MdePkg/Library/DxeRuntimeDebugLibSerialPort/DebugLib.c

   1 /** @file
   2   DXE runtime Debug library instance based on Serial Port library.
   3   It takes care not to call into SerialPortLib after ExitBootServices() has
   4   been called, to prevent touching hardware that is no longer owned by the
   5   firmware.
   6
   7   Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
   8   Copyright (c) 2018, Linaro, Ltd. All rights reserved.<BR>
   9
  10   SPDX-License-Identifier: BSD-2-Clause-Patent
  11
  12 **/
  13
  14 #include <Base.h>
  15 #include <Library/DebugLib.h>
  16 #include <Library/DebugPrintErrorLevelLib.h>
  17 #include <Library/BaseLib.h>
  18 #include <Library/PrintLib.h>
  19 #include <Library/PcdLib.h>
  20 #include <Library/BaseMemoryLib.h>
  21 #include <Library/SerialPortLib.h>
  22
  23 STATIC EFI_EVENT  mEfiExitBootServicesEvent;
  24 STATIC BOOLEAN    mEfiAtRuntime = FALSE;
  25
  26 //
  27 // Define the maximum debug and assert message length that this library supports
  28 //
  29 #define MAX_DEBUG_MESSAGE_LENGTH  0x100
  30
  31 //
  32 // VA_LIST can not initialize to NULL for all compiler, so we use this to
  33 // indicate a null VA_LIST
  34 //
  35 VA_LIST  mVaListNull;
  36
  37 /**
  38   Set AtRuntime flag as TRUE after ExitBootServices.
  39
  40   @param[in]  Event   The Event that is being processed.
  41   @param[in]  Context The Event Context.
  42
  43 **/
  44 STATIC
  45 VOID
  46 EFIAPI
  47 ExitBootServicesEvent (
  48   IN EFI_EVENT  Event,
  49   IN VOID       *Context
  50   )
  51 {
  52   mEfiAtRuntime = TRUE;
  53 }
  54
  55 /**
  56   The constructor function to initialize the Serial Port library and
  57   register a callback for the ExitBootServices event.
  58
  59   @param[in]  ImageHandle   The firmware allocated handle for the EFI image.
  60   @param[in]  SystemTable   A pointer to the EFI System Table.
  61
  62   @retval EFI_SUCCESS   The operation completed successfully.
  63   @retval other         Either the serial port failed to initialize or the
  64                         ExitBootServices event callback registration failed.
  65 **/
  66 EFI_STATUS
  67 EFIAPI
  68 DxeRuntimeDebugLibSerialPortConstructor (
  69   IN EFI_HANDLE        ImageHandle,
  70   IN EFI_SYSTEM_TABLE  *SystemTable
  71   )
  72 {
  73   EFI_STATUS  Status;
  74
  75   Status = SerialPortInitialize ();
  76   if (EFI_ERROR (Status)) {
  77     return Status;
  78   }
  79
  80   return SystemTable->BootServices->CreateEvent (
  81                                       EVT_SIGNAL_EXIT_BOOT_SERVICES,
  82                                       TPL_NOTIFY,
  83                                       ExitBootServicesEvent,
  84                                       NULL,
  85                                       &mEfiExitBootServicesEvent
  86                                       );
  87 }
  88
  89 /**
  90   If a runtime driver exits with an error, it must call this routine
  91   to free the allocated resource before the exiting.
  92
  93   @param[in]  ImageHandle   The firmware allocated handle for the EFI image.
  94   @param[in]  SystemTable   A pointer to the EFI System Table.
  95
  96   @retval     EFI_SUCCESS       The Runtime Driver Lib shutdown successfully.
  97   @retval     EFI_UNSUPPORTED   Runtime Driver lib was not initialized.
  98 **/
  99 EFI_STATUS
 100 EFIAPI
 101 DxeRuntimeDebugLibSerialPortDestructor (
 102   IN EFI_HANDLE        ImageHandle,
 103   IN EFI_SYSTEM_TABLE  *SystemTable
 104   )
 105 {
 106   return SystemTable->BootServices->CloseEvent (mEfiExitBootServicesEvent);
 107 }
 108
 109 /**
 110   Prints a debug message to the debug output device if the specified error level is enabled.
 111
 112   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 113   GetDebugPrintErrorLevel (), then print the message specified by Format and the
 114   associated variable argument list to the debug output device.
 115
 116   If Format is NULL, then ASSERT().
 117
 118   @param  ErrorLevel  The error level of the debug message.
 119   @param  Format      Format string for the debug message to print.
 120   @param  ...         Variable argument list whose contents are accessed
 121                       based on the format string specified by Format.
 122
 123 **/
 124 VOID
 125 EFIAPI
 126 DebugPrint (
 127   IN  UINTN        ErrorLevel,
 128   IN  CONST CHAR8  *Format,
 129   ...
 130   )
 131 {
 132   VA_LIST  Marker;
 133
 134   VA_START (Marker, Format);
 135   DebugVPrint (ErrorLevel, Format, Marker);
 136   VA_END (Marker);
 137 }
 138
 139 /**
 140   Prints a debug message to the debug output device if the specified
 141   error level is enabled base on Null-terminated format string and a
 142   VA_LIST argument list or a BASE_LIST argument list.
 143
 144   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 145   GetDebugPrintErrorLevel (), then print the message specified by Format and
 146   the associated variable argument list to the debug output device.
 147
 148   If Format is NULL, then ASSERT().
 149
 150   @param  ErrorLevel      The error level of the debug message.
 151   @param  Format          Format string for the debug message to print.
 152   @param  VaListMarker    VA_LIST marker for the variable argument list.
 153   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
 154
 155 **/
 156 VOID
 157 DebugPrintMarker (
 158   IN  UINTN        ErrorLevel,
 159   IN  CONST CHAR8  *Format,
 160   IN  VA_LIST      VaListMarker,
 161   IN  BASE_LIST    BaseListMarker
 162   )
 163 {
 164   CHAR8  Buffer[MAX_DEBUG_MESSAGE_LENGTH];
 165
 166   if (mEfiAtRuntime) {
 167     return;
 168   }
 169
 170   //
 171   // If Format is NULL, then ASSERT().
 172   //
 173   ASSERT (Format != NULL);
 174
 175   //
 176   // Check driver debug mask value and global mask
 177   //
 178   if ((ErrorLevel & GetDebugPrintErrorLevel ()) == 0) {
 179     return;
 180   }
 181
 182   //
 183   // Convert the DEBUG() message to an ASCII String
 184   //
 185   if (BaseListMarker == NULL) {
 186     AsciiVSPrint (Buffer, sizeof (Buffer), Format, VaListMarker);
 187   } else {
 188     AsciiBSPrint (Buffer, sizeof (Buffer), Format, BaseListMarker);
 189   }
 190
 191   //
 192   // Send the print string to a Serial Port
 193   //
 194   SerialPortWrite ((UINT8 *)Buffer, AsciiStrLen (Buffer));
 195 }
 196
 197 /**
 198   Prints a debug message to the debug output device if the specified
 199   error level is enabled.
 200
 201   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 202   GetDebugPrintErrorLevel (), then print the message specified by Format and
 203   the associated variable argument list to the debug output device.
 204
 205   If Format is NULL, then ASSERT().
 206
 207   @param  ErrorLevel    The error level of the debug message.
 208   @param  Format        Format string for the debug message to print.
 209   @param  VaListMarker  VA_LIST marker for the variable argument list.
 210
 211 **/
 212 VOID
 213 EFIAPI
 214 DebugVPrint (
 215   IN  UINTN        ErrorLevel,
 216   IN  CONST CHAR8  *Format,
 217   IN  VA_LIST      VaListMarker
 218   )
 219 {
 220   DebugPrintMarker (ErrorLevel, Format, VaListMarker, NULL);
 221 }
 222
 223 /**
 224   Prints a debug message to the debug output device if the specified
 225   error level is enabled.
 226   This function use BASE_LIST which would provide a more compatible
 227   service than VA_LIST.
 228
 229   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 230   GetDebugPrintErrorLevel (), then print the message specified by Format and
 231   the associated variable argument list to the debug output device.
 232
 233   If Format is NULL, then ASSERT().
 234
 235   @param  ErrorLevel      The error level of the debug message.
 236   @param  Format          Format string for the debug message to print.
 237   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
 238
 239 **/
 240 VOID
 241 EFIAPI
 242 DebugBPrint (
 243   IN  UINTN        ErrorLevel,
 244   IN  CONST CHAR8  *Format,
 245   IN  BASE_LIST    BaseListMarker
 246   )
 247 {
 248   DebugPrintMarker (ErrorLevel, Format, mVaListNull, BaseListMarker);
 249 }
 250
 251 /**
 252   Prints an assert message containing a filename, line number, and description.
 253   This may be followed by a breakpoint or a dead loop.
 254
 255   Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n"
 256   to the debug output device.  If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of
 257   PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if
 258   DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then
 259   CpuDeadLoop() is called.  If neither of these bits are set, then this function
 260   returns immediately after the message is printed to the debug output device.
 261   DebugAssert() must actively prevent recursion.  If DebugAssert() is called while
 262   processing another DebugAssert(), then DebugAssert() must return immediately.
 263
 264   If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
 265   If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
 266
 267   @param  FileName     The pointer to the name of the source file that generated the assert condition.
 268   @param  LineNumber   The line number in the source file that generated the assert condition
 269   @param  Description  The pointer to the description of the assert condition.
 270
 271 **/
 272 VOID
 273 EFIAPI
 274 DebugAssert (
 275   IN CONST CHAR8  *FileName,
 276   IN UINTN        LineNumber,
 277   IN CONST CHAR8  *Description
 278   )
 279 {
 280   CHAR8  Buffer[MAX_DEBUG_MESSAGE_LENGTH];
 281
 282   //
 283   // Generate the ASSERT() message in Ascii format
 284   //
 285   AsciiSPrint (
 286     Buffer,
 287     sizeof (Buffer),
 288     "ASSERT [%a] %a(%d): %a\n",
 289     gEfiCallerBaseName,
 290     FileName,
 291     LineNumber,
 292     Description
 293     );
 294
 295   if (!mEfiAtRuntime) {
 296     //
 297     // Send the print string to the Console Output device
 298     //
 299     SerialPortWrite ((UINT8 *)Buffer, AsciiStrLen (Buffer));
 300   }
 301
 302   //
 303   // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
 304   //
 305   if ((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
 306     CpuBreakpoint ();
 307   } else if ((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
 308     CpuDeadLoop ();
 309   }
 310 }
 311
 312 /**
 313   Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.
 314
 315   This function fills Length bytes of Buffer with the value specified by
 316   PcdDebugClearMemoryValue, and returns Buffer.
 317
 318   If Buffer is NULL, then ASSERT().
 319   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 320
 321   @param   Buffer  The pointer to the target buffer to be filled with PcdDebugClearMemoryValue.
 322   @param   Length  The number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue.
 323
 324   @return  Buffer  The pointer to the target buffer filled with PcdDebugClearMemoryValue.
 325
 326 **/
 327 VOID *
 328 EFIAPI
 329 DebugClearMemory (
 330   OUT VOID  *Buffer,
 331   IN UINTN  Length
 332   )
 333 {
 334   //
 335   // If Buffer is NULL, then ASSERT().
 336   //
 337   ASSERT (Buffer != NULL);
 338
 339   //
 340   // SetMem() checks for the the ASSERT() condition on Length and returns Buffer
 341   //
 342   return SetMem (Buffer, Length, PcdGet8 (PcdDebugClearMemoryValue));
 343 }
 344
 345 /**
 346   Returns TRUE if ASSERT() macros are enabled.
 347
 348   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of
 349   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 350
 351   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.
 352   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.
 353
 354 **/
 355 BOOLEAN
 356 EFIAPI
 357 DebugAssertEnabled (
 358   VOID
 359   )
 360 {
 361   return (BOOLEAN)((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);
 362 }
 363
 364 /**
 365   Returns TRUE if DEBUG() macros are enabled.
 366
 367   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of
 368   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 369
 370   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.
 371   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.
 372
 373 **/
 374 BOOLEAN
 375 EFIAPI
 376 DebugPrintEnabled (
 377   VOID
 378   )
 379 {
 380   return (BOOLEAN)((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);
 381 }
 382
 383 /**
 384   Returns TRUE if DEBUG_CODE() macros are enabled.
 385
 386   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of
 387   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 388
 389   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.
 390   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.
 391
 392 **/
 393 BOOLEAN
 394 EFIAPI
 395 DebugCodeEnabled (
 396   VOID
 397   )
 398 {
 399   return (BOOLEAN)((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);
 400 }
 401
 402 /**
 403   Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled.
 404
 405   This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of
 406   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 407
 408   @retval  TRUE    The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.
 409   @retval  FALSE   The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.
 410
 411 **/
 412 BOOLEAN
 413 EFIAPI
 414 DebugClearMemoryEnabled (
 415   VOID
 416   )
 417 {
 418   return (BOOLEAN)((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED) != 0);
 419 }
 420
 421 /**
 422   Returns TRUE if any one of the bit is set both in ErrorLevel and PcdFixedDebugPrintErrorLevel.
 423
 424   This function compares the bit mask of ErrorLevel and PcdFixedDebugPrintErrorLevel.
 425
 426   @retval  TRUE    Current ErrorLevel is supported.
 427   @retval  FALSE   Current ErrorLevel is not supported.
 428
 429 **/
 430 BOOLEAN
 431 EFIAPI
 432 DebugPrintLevelEnabled (
 433   IN  CONST UINTN  ErrorLevel
 434   )
 435 {
 436   return (BOOLEAN)((ErrorLevel & PcdGet32 (PcdFixedDebugPrintErrorLevel)) != 0);
 437 }