MdePkg/Library/UefiDebugLibDebugPortProtocol/DebugLib.c

   1 /** @file
   2   UEFI Debug Library that sends messages to EFI_DEBUGPORT_PROTOCOL.Write.
   3
   4   Copyright (c) 2015 - 2019, 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 // VA_LIST can not initialize to NULL for all compiler, so we use this to
  42 // indicate a null VA_LIST
  43 //
  44 VA_LIST     mVaListNull;
  45
  46 /**
  47   Send message to DebugPort Protocol.
  48
  49   If mDebugPort is NULL, i.e. EFI_DEBUGPORT_PROTOCOL is not located,
  50   EFI_DEBUGPORT_PROTOCOL is located first.
  51   Then, Buffer is sent via EFI_DEBUGPORT_PROTOCOL.Write.
  52
  53   @param  Buffer         The message to be sent.
  54   @param  BufferLength   The byte length of Buffer.
  55 **/
  56 VOID
  57 UefiDebugLibDebugPortProtocolWrite (
  58   IN  CONST CHAR8  *Buffer,
  59   IN        UINTN  BufferLength
  60   )
  61 {
  62   UINTN      Length;
  63   EFI_STATUS Status;
  64
  65   //
  66   // If mDebugPort is NULL, initialize first.
  67   //
  68   if (mDebugPort == NULL) {
  69       Status = gBS->LocateProtocol (&gEfiDebugPortProtocolGuid, NULL, (VOID **)&mDebugPort);
  70       if (EFI_ERROR (Status)) {
  71           return;
  72       }
  73
  74       mDebugPort->Reset (mDebugPort);
  75   }
  76
  77   //
  78   // EFI_DEBUGPORT_PROTOCOL.Write is called until all message is sent.
  79   //
  80   while (BufferLength > 0) {
  81     Length = BufferLength;
  82
  83     Status = mDebugPort->Write (mDebugPort, WRITE_TIMEOUT, &Length, (VOID *) Buffer);
  84     if (EFI_ERROR (Status) || BufferLength < Length) {
  85       break;
  86     }
  87
  88     Buffer += Length;
  89     BufferLength -= Length;
  90   }
  91 }
  92
  93 /**
  94   Prints a debug message to the debug output device if the specified error level is enabled.
  95
  96   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
  97   GetDebugPrintErrorLevel (), then print the message specified by Format and the
  98   associated variable argument list to the debug output device.
  99
 100   If Format is NULL, then ASSERT().
 101
 102   @param  ErrorLevel  The error level of the debug message.
 103   @param  Format      Format string for the debug message to print.
 104   @param  ...         A variable argument list whose contents are accessed
 105                       based on the format string specified by Format.
 106
 107 **/
 108 VOID
 109 EFIAPI
 110 DebugPrint (
 111   IN  UINTN        ErrorLevel,
 112   IN  CONST CHAR8  *Format,
 113   ...
 114   )
 115 {
 116   VA_LIST         Marker;
 117
 118   VA_START (Marker, Format);
 119   DebugVPrint (ErrorLevel, Format, Marker);
 120   VA_END (Marker);
 121 }
 122
 123
 124 /**
 125   Prints a debug message to the debug output device if the specified
 126   error level is enabled base on Null-terminated format string and a
 127   VA_LIST argument list or a BASE_LIST argument list.
 128
 129   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 130   GetDebugPrintErrorLevel (), then print the message specified by Format and
 131   the associated variable argument list to the debug output device.
 132
 133   If Format is NULL, then ASSERT().
 134
 135   @param  ErrorLevel      The error level of the debug message.
 136   @param  Format          Format string for the debug message to print.
 137   @param  VaListMarker    VA_LIST marker for the variable argument list.
 138   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
 139
 140 **/
 141 VOID
 142 DebugPrintMarker (
 143   IN  UINTN         ErrorLevel,
 144   IN  CONST CHAR8   *Format,
 145   IN  VA_LIST       VaListMarker,
 146   IN  BASE_LIST     BaseListMarker
 147   )
 148 {
 149   CHAR8      Buffer[MAX_DEBUG_MESSAGE_LENGTH];
 150
 151   //
 152   // If Format is NULL, then ASSERT().
 153   //
 154   ASSERT (Format != NULL);
 155
 156   //
 157   // Check driver debug mask value and global mask
 158   //
 159   if ((ErrorLevel & GetDebugPrintErrorLevel ()) == 0) {
 160     return;
 161   }
 162
 163   //
 164   // Convert the DEBUG() message to an ASCII String
 165   //
 166   if (BaseListMarker == NULL) {
 167     AsciiVSPrint (Buffer, sizeof (Buffer), Format, VaListMarker);
 168   } else {
 169     AsciiBSPrint (Buffer, sizeof (Buffer), Format, BaseListMarker);
 170   }
 171
 172   //
 173   // Send the print string to EFI_DEBUGPORT_PROTOCOL.Write.
 174   //
 175   UefiDebugLibDebugPortProtocolWrite (Buffer, AsciiStrLen (Buffer));
 176 }
 177
 178
 179 /**
 180   Prints a debug message to the debug output device if the specified
 181   error level is enabled.
 182
 183   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 184   GetDebugPrintErrorLevel (), then print the message specified by Format and
 185   the associated variable argument list to the debug output device.
 186
 187   If Format is NULL, then ASSERT().
 188
 189   @param  ErrorLevel    The error level of the debug message.
 190   @param  Format        Format string for the debug message to print.
 191   @param  VaListMarker  VA_LIST marker for the variable argument list.
 192
 193 **/
 194 VOID
 195 EFIAPI
 196 DebugVPrint (
 197   IN  UINTN         ErrorLevel,
 198   IN  CONST CHAR8   *Format,
 199   IN  VA_LIST       VaListMarker
 200   )
 201 {
 202   DebugPrintMarker (ErrorLevel, Format, VaListMarker, NULL);
 203 }
 204
 205
 206 /**
 207   Prints a debug message to the debug output device if the specified
 208   error level is enabled.
 209   This function use BASE_LIST which would provide a more compatible
 210   service than VA_LIST.
 211
 212   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 213   GetDebugPrintErrorLevel (), then print the message specified by Format and
 214   the associated variable argument list to the debug output device.
 215
 216   If Format is NULL, then ASSERT().
 217
 218   @param  ErrorLevel      The error level of the debug message.
 219   @param  Format          Format string for the debug message to print.
 220   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
 221
 222 **/
 223 VOID
 224 EFIAPI
 225 DebugBPrint (
 226   IN  UINTN         ErrorLevel,
 227   IN  CONST CHAR8   *Format,
 228   IN  BASE_LIST     BaseListMarker
 229   )
 230 {
 231   DebugPrintMarker (ErrorLevel, Format, mVaListNull, BaseListMarker);
 232 }
 233
 234
 235 /**
 236   Prints an assert message containing a filename, line number, and description.
 237   This may be followed by a breakpoint or a dead loop.
 238
 239   Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n"
 240   to the debug output device.  If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of
 241   PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if
 242   DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then
 243   CpuDeadLoop() is called.  If neither of these bits are set, then this function
 244   returns immediately after the message is printed to the debug output device.
 245   DebugAssert() must actively prevent recursion.  If DebugAssert() is called while
 246   processing another DebugAssert(), then DebugAssert() must return immediately.
 247
 248   If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
 249   If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
 250
 251   @param  FileName     The pointer to the name of the source file that generated
 252                        the assert condition.
 253   @param  LineNumber   The line number in the source file that generated the
 254                        assert condition
 255   @param  Description  The pointer to the description of the assert condition.
 256
 257 **/
 258 VOID
 259 EFIAPI
 260 DebugAssert (
 261   IN CONST CHAR8  *FileName,
 262   IN UINTN        LineNumber,
 263   IN CONST CHAR8  *Description
 264   )
 265 {
 266   CHAR8  Buffer[MAX_DEBUG_MESSAGE_LENGTH];
 267
 268   //
 269   // Generate the ASSERT() message in ASCII format
 270   //
 271   AsciiSPrint (
 272     Buffer,
 273     sizeof (Buffer),
 274     "ASSERT [%a] %a(%d): %a\n",
 275     gEfiCallerBaseName,
 276     FileName,
 277     LineNumber,
 278     Description
 279     );
 280
 281   //
 282   // Send the print string to EFI_DEBUGPORT_PROTOCOL.Write.
 283   //
 284   UefiDebugLibDebugPortProtocolWrite (Buffer, AsciiStrLen (Buffer));
 285
 286   //
 287   // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
 288   //
 289   if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
 290     CpuBreakpoint ();
 291   } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
 292     CpuDeadLoop ();
 293   }
 294 }
 295
 296
 297 /**
 298   Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.
 299
 300   This function fills Length bytes of Buffer with the value specified by
 301   PcdDebugClearMemoryValue, and returns Buffer.
 302
 303   If Buffer is NULL, then ASSERT().
 304   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 305
 306   @param   Buffer  The pointer to the target buffer to be filled with PcdDebugClearMemoryValue.
 307   @param   Length  The number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue.
 308
 309   @return  Buffer  The pointer to the target buffer filled with PcdDebugClearMemoryValue.
 310
 311 **/
 312 VOID *
 313 EFIAPI
 314 DebugClearMemory (
 315   OUT VOID  *Buffer,
 316   IN UINTN  Length
 317   )
 318 {
 319   //
 320   // If Buffer is NULL, then ASSERT().
 321   //
 322   ASSERT (Buffer != NULL);
 323
 324   //
 325   // SetMem() checks for the the ASSERT() condition on Length and returns Buffer
 326   //
 327   return SetMem (Buffer, Length, PcdGet8(PcdDebugClearMemoryValue));
 328 }
 329
 330
 331 /**
 332   Returns TRUE if ASSERT() macros are enabled.
 333
 334   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of
 335   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 336
 337   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.
 338   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.
 339
 340 **/
 341 BOOLEAN
 342 EFIAPI
 343 DebugAssertEnabled (
 344   VOID
 345   )
 346 {
 347   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);
 348 }
 349
 350
 351 /**
 352   Returns TRUE if DEBUG() macros are enabled.
 353
 354   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of
 355   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 356
 357   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.
 358   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.
 359
 360 **/
 361 BOOLEAN
 362 EFIAPI
 363 DebugPrintEnabled (
 364   VOID
 365   )
 366 {
 367   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);
 368 }
 369
 370
 371 /**
 372   Returns TRUE if DEBUG_CODE() macros are enabled.
 373
 374   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of
 375   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 376
 377   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.
 378   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.
 379
 380 **/
 381 BOOLEAN
 382 EFIAPI
 383 DebugCodeEnabled (
 384   VOID
 385   )
 386 {
 387   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);
 388 }
 389
 390
 391 /**
 392   Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled.
 393
 394   This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of
 395   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 396
 397   @retval  TRUE    The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.
 398   @retval  FALSE   The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.
 399
 400 **/
 401 BOOLEAN
 402 EFIAPI
 403 DebugClearMemoryEnabled (
 404   VOID
 405   )
 406 {
 407   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED) != 0);
 408 }
 409
 410 /**
 411   Returns TRUE if any one of the bit is set both in ErrorLevel and PcdFixedDebugPrintErrorLevel.
 412
 413   This function compares the bit mask of ErrorLevel and PcdFixedDebugPrintErrorLevel.
 414
 415   @retval  TRUE    Current ErrorLevel is supported.
 416   @retval  FALSE   Current ErrorLevel is not supported.
 417
 418 **/
 419 BOOLEAN
 420 EFIAPI
 421 DebugPrintLevelEnabled (
 422   IN  CONST UINTN        ErrorLevel
 423   )
 424 {
 425   return (BOOLEAN) ((ErrorLevel & PcdGet32(PcdFixedDebugPrintErrorLevel)) != 0);
 426 }
 427