MdePkg/Library/UefiDebugLibDebugPortProtocol/DebugLib.c

   1 /** @file
   2   UEFI Debug Library that sends messages to EFI_DEBUGPORT_PROTOCOL.Write.
   3
   4   Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php.
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #include <Uefi.h>
  16
  17 #include <Library/DebugLib.h>
  18 #include <Library/UefiBootServicesTableLib.h>
  19 #include <Library/PrintLib.h>
  20 #include <Library/PcdLib.h>
  21 #include <Library/BaseLib.h>
  22 #include <Library/BaseMemoryLib.h>
  23 #include <Library/DebugPrintErrorLevelLib.h>
  24
  25 #include <Protocol/DebugPort.h>
  26
  27 //
  28 // Define the maximum debug and assert message length that this library supports
  29 //
  30 #define MAX_DEBUG_MESSAGE_LENGTH  0x100
  31
  32 //
  33 // Define the timeout for EFI_DEBUGPORT_PROTOCOL.Write
  34 //
  35 #define WRITE_TIMEOUT 1000
  36
  37
  38 EFI_DEBUGPORT_PROTOCOL *mDebugPort = NULL;
  39
  40 /**
  41   Send message to DebugPort Protocol.
  42
  43   If mDebugPort is NULL, i.e. EFI_DEBUGPORT_PROTOCOL is not located,
  44   EFI_DEBUGPORT_PROTOCOL is located first.
  45   Then, Buffer is sent via EFI_DEBUGPORT_PROTOCOL.Write.
  46
  47   @param  Buffer         The message to be sent.
  48   @param  BufferLength   The byte length of Buffer.
  49 **/
  50 VOID
  51 UefiDebugLibDebugPortProtocolWrite (
  52   IN  CONST CHAR8  *Buffer,
  53   IN        UINTN  BufferLength
  54   )
  55 {
  56   UINTN      Length;
  57   EFI_STATUS Status;
  58
  59   //
  60   // If mDebugPort is NULL, initialize first.
  61   //
  62   if (mDebugPort == NULL) {
  63       Status = gBS->LocateProtocol (&gEfiDebugPortProtocolGuid, NULL, (VOID **)&mDebugPort);
  64       if (EFI_ERROR (Status)) {
  65           return;
  66       }
  67
  68       mDebugPort->Reset (mDebugPort);
  69   }
  70
  71   //
  72   // EFI_DEBUGPORT_PROTOCOL.Write is called until all message is sent.
  73   //
  74   while (BufferLength > 0) {
  75     Length = BufferLength;
  76
  77     Status = mDebugPort->Write (mDebugPort, WRITE_TIMEOUT, &Length, (VOID *) Buffer);
  78     if (EFI_ERROR (Status) || BufferLength < Length) {
  79       break;
  80     }
  81
  82     Buffer += Length;
  83     BufferLength -= Length;
  84   }
  85 }
  86
  87 /**
  88   Prints a debug message to the debug output device if the specified error level is enabled.
  89
  90   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
  91   GetDebugPrintErrorLevel (), then print the message specified by Format and the
  92   associated variable argument list to the debug output device.
  93
  94   If Format is NULL, then ASSERT().
  95
  96   @param  ErrorLevel  The error level of the debug message.
  97   @param  Format      Format string for the debug message to print.
  98   @param  ...         A variable argument list whose contents are accessed
  99                       based on the format string specified by Format.
 100
 101 **/
 102 VOID
 103 EFIAPI
 104 DebugPrint (
 105   IN  UINTN        ErrorLevel,
 106   IN  CONST CHAR8  *Format,
 107   ...
 108   )
 109 {
 110   CHAR8      Buffer[MAX_DEBUG_MESSAGE_LENGTH];
 111   VA_LIST    Marker;
 112
 113   //
 114   // If Format is NULL, then ASSERT().
 115   //
 116   ASSERT (Format != NULL);
 117
 118   //
 119   // Check driver debug mask value and global mask
 120   //
 121   if ((ErrorLevel & GetDebugPrintErrorLevel ()) == 0) {
 122     return;
 123   }
 124
 125   //
 126   // Convert the DEBUG() message to an ASCII String
 127   //
 128   VA_START (Marker, Format);
 129   AsciiVSPrint (Buffer, sizeof (Buffer), Format, Marker);
 130   VA_END (Marker);
 131
 132   //
 133   // Send the print string to EFI_DEBUGPORT_PROTOCOL.Write.
 134   //
 135   UefiDebugLibDebugPortProtocolWrite (Buffer, AsciiStrLen (Buffer));
 136 }
 137
 138
 139 /**
 140   Prints an assert message containing a filename, line number, and description.
 141   This may be followed by a breakpoint or a dead loop.
 142
 143   Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n"
 144   to the debug output device.  If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of
 145   PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if
 146   DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then
 147   CpuDeadLoop() is called.  If neither of these bits are set, then this function
 148   returns immediately after the message is printed to the debug output device.
 149   DebugAssert() must actively prevent recursion.  If DebugAssert() is called while
 150   processing another DebugAssert(), then DebugAssert() must return immediately.
 151
 152   If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
 153   If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
 154
 155   @param  FileName     The pointer to the name of the source file that generated
 156                        the assert condition.
 157   @param  LineNumber   The line number in the source file that generated the
 158                        assert condition
 159   @param  Description  The pointer to the description of the assert condition.
 160
 161 **/
 162 VOID
 163 EFIAPI
 164 DebugAssert (
 165   IN CONST CHAR8  *FileName,
 166   IN UINTN        LineNumber,
 167   IN CONST CHAR8  *Description
 168   )
 169 {
 170   CHAR8  Buffer[MAX_DEBUG_MESSAGE_LENGTH];
 171
 172   //
 173   // Generate the ASSERT() message in ASCII format
 174   //
 175   AsciiSPrint (
 176     Buffer,
 177     sizeof (Buffer),
 178     "ASSERT %a(%d): %a\n",
 179     FileName,
 180     LineNumber,
 181     Description
 182     );
 183
 184   //
 185   // Send the print string to EFI_DEBUGPORT_PROTOCOL.Write.
 186   //
 187   UefiDebugLibDebugPortProtocolWrite (Buffer, AsciiStrLen (Buffer));
 188
 189   //
 190   // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
 191   //
 192   if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
 193     CpuBreakpoint ();
 194   } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
 195     CpuDeadLoop ();
 196   }
 197 }
 198
 199
 200 /**
 201   Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.
 202
 203   This function fills Length bytes of Buffer with the value specified by
 204   PcdDebugClearMemoryValue, and returns Buffer.
 205
 206   If Buffer is NULL, then ASSERT().
 207   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 208
 209   @param   Buffer  The pointer to the target buffer to be filled with PcdDebugClearMemoryValue.
 210   @param   Length  The number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue.
 211
 212   @return  Buffer  The pointer to the target buffer filled with PcdDebugClearMemoryValue.
 213
 214 **/
 215 VOID *
 216 EFIAPI
 217 DebugClearMemory (
 218   OUT VOID  *Buffer,
 219   IN UINTN  Length
 220   )
 221 {
 222   //
 223   // If Buffer is NULL, then ASSERT().
 224   //
 225   ASSERT (Buffer != NULL);
 226
 227   //
 228   // SetMem() checks for the the ASSERT() condition on Length and returns Buffer
 229   //
 230   return SetMem (Buffer, Length, PcdGet8(PcdDebugClearMemoryValue));
 231 }
 232
 233
 234 /**
 235   Returns TRUE if ASSERT() macros are enabled.
 236
 237   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of
 238   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 239
 240   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.
 241   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.
 242
 243 **/
 244 BOOLEAN
 245 EFIAPI
 246 DebugAssertEnabled (
 247   VOID
 248   )
 249 {
 250   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);
 251 }
 252
 253
 254 /**
 255   Returns TRUE if DEBUG() macros are enabled.
 256
 257   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of
 258   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 259
 260   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.
 261   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.
 262
 263 **/
 264 BOOLEAN
 265 EFIAPI
 266 DebugPrintEnabled (
 267   VOID
 268   )
 269 {
 270   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);
 271 }
 272
 273
 274 /**
 275   Returns TRUE if DEBUG_CODE() macros are enabled.
 276
 277   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of
 278   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 279
 280   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.
 281   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.
 282
 283 **/
 284 BOOLEAN
 285 EFIAPI
 286 DebugCodeEnabled (
 287   VOID
 288   )
 289 {
 290   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);
 291 }
 292
 293
 294 /**
 295   Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled.
 296
 297   This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of
 298   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 299
 300   @retval  TRUE    The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.
 301   @retval  FALSE   The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.
 302
 303 **/
 304 BOOLEAN
 305 EFIAPI
 306 DebugClearMemoryEnabled (
 307   VOID
 308   )
 309 {
 310   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED) != 0);
 311 }
 312
 313 /**
 314   Returns TRUE if any one of the bit is set both in ErrorLevel and PcdFixedDebugPrintErrorLevel.
 315
 316   This function compares the bit mask of ErrorLevel and PcdFixedDebugPrintErrorLevel.
 317
 318   @retval  TRUE    Current ErrorLevel is supported.
 319   @retval  FALSE   Current ErrorLevel is not supported.
 320
 321 **/
 322 BOOLEAN
 323 EFIAPI
 324 DebugPrintLevelEnabled (
 325   IN  CONST UINTN        ErrorLevel
 326   )
 327 {
 328   return (BOOLEAN) ((ErrorLevel & PcdGet32(PcdFixedDebugPrintErrorLevel)) != 0);
 329 }
 330