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 (EVT_SIGNAL_EXIT_BOOT_SERVICES,
  81                                       TPL_NOTIFY, ExitBootServicesEvent, NULL,
  82                                       &mEfiExitBootServicesEvent);
  83 }
  84
  85 /**
  86   If a runtime driver exits with an error, it must call this routine
  87   to free the allocated resource before the exiting.
  88
  89   @param[in]  ImageHandle   The firmware allocated handle for the EFI image.
  90   @param[in]  SystemTable   A pointer to the EFI System Table.
  91
  92   @retval     EFI_SUCCESS       The Runtime Driver Lib shutdown successfully.
  93   @retval     EFI_UNSUPPORTED   Runtime Driver lib was not initialized.
  94 **/
  95 EFI_STATUS
  96 EFIAPI
  97 DxeRuntimeDebugLibSerialPortDestructor (
  98   IN EFI_HANDLE        ImageHandle,
  99   IN EFI_SYSTEM_TABLE  *SystemTable
 100   )
 101 {
 102   return SystemTable->BootServices->CloseEvent (mEfiExitBootServicesEvent);
 103 }
 104
 105 /**
 106   Prints a debug message to the debug output device if the specified error level is enabled.
 107
 108   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 109   GetDebugPrintErrorLevel (), then print the message specified by Format and the
 110   associated variable argument list to the debug output device.
 111
 112   If Format is NULL, then ASSERT().
 113
 114   @param  ErrorLevel  The error level of the debug message.
 115   @param  Format      Format string for the debug message to print.
 116   @param  ...         Variable argument list whose contents are accessed
 117                       based on the format string specified by Format.
 118
 119 **/
 120 VOID
 121 EFIAPI
 122 DebugPrint (
 123   IN  UINTN        ErrorLevel,
 124   IN  CONST CHAR8  *Format,
 125   ...
 126   )
 127 {
 128   VA_LIST         Marker;
 129
 130   VA_START (Marker, Format);
 131   DebugVPrint (ErrorLevel, Format, Marker);
 132   VA_END (Marker);
 133 }
 134
 135
 136 /**
 137   Prints a debug message to the debug output device if the specified
 138   error level is enabled base on Null-terminated format string and a
 139   VA_LIST argument list or a BASE_LIST argument list.
 140
 141   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 142   GetDebugPrintErrorLevel (), then print the message specified by Format and
 143   the associated variable argument list to the debug output device.
 144
 145   If Format is NULL, then ASSERT().
 146
 147   @param  ErrorLevel      The error level of the debug message.
 148   @param  Format          Format string for the debug message to print.
 149   @param  VaListMarker    VA_LIST marker for the variable argument list.
 150   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
 151
 152 **/
 153 VOID
 154 DebugPrintMarker (
 155   IN  UINTN         ErrorLevel,
 156   IN  CONST CHAR8   *Format,
 157   IN  VA_LIST       VaListMarker,
 158   IN  BASE_LIST     BaseListMarker
 159   )
 160 {
 161   CHAR8    Buffer[MAX_DEBUG_MESSAGE_LENGTH];
 162
 163   if (mEfiAtRuntime) {
 164     return;
 165   }
 166
 167   //
 168   // If Format is NULL, then ASSERT().
 169   //
 170   ASSERT (Format != NULL);
 171
 172   //
 173   // Check driver debug mask value and global mask
 174   //
 175   if ((ErrorLevel & GetDebugPrintErrorLevel ()) == 0) {
 176     return;
 177   }
 178
 179   //
 180   // Convert the DEBUG() message to an ASCII String
 181   //
 182   if (BaseListMarker == NULL) {
 183     AsciiVSPrint (Buffer, sizeof (Buffer), Format, VaListMarker);
 184   } else {
 185     AsciiBSPrint (Buffer, sizeof (Buffer), Format, BaseListMarker);
 186   }
 187
 188   //
 189   // Send the print string to a Serial Port
 190   //
 191   SerialPortWrite ((UINT8 *)Buffer, AsciiStrLen (Buffer));
 192 }
 193
 194
 195 /**
 196   Prints a debug message to the debug output device if the specified
 197   error level is enabled.
 198
 199   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 200   GetDebugPrintErrorLevel (), then print the message specified by Format and
 201   the associated variable argument list to the debug output device.
 202
 203   If Format is NULL, then ASSERT().
 204
 205   @param  ErrorLevel    The error level of the debug message.
 206   @param  Format        Format string for the debug message to print.
 207   @param  VaListMarker  VA_LIST marker for the variable argument list.
 208
 209 **/
 210 VOID
 211 EFIAPI
 212 DebugVPrint (
 213   IN  UINTN         ErrorLevel,
 214   IN  CONST CHAR8   *Format,
 215   IN  VA_LIST       VaListMarker
 216   )
 217 {
 218   DebugPrintMarker (ErrorLevel, Format, VaListMarker, NULL);
 219 }
 220
 221
 222 /**
 223   Prints a debug message to the debug output device if the specified
 224   error level is enabled.
 225   This function use BASE_LIST which would provide a more compatible
 226   service than VA_LIST.
 227
 228   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 229   GetDebugPrintErrorLevel (), then print the message specified by Format and
 230   the associated variable argument list to the debug output device.
 231
 232   If Format is NULL, then ASSERT().
 233
 234   @param  ErrorLevel      The error level of the debug message.
 235   @param  Format          Format string for the debug message to print.
 236   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
 237
 238 **/
 239 VOID
 240 EFIAPI
 241 DebugBPrint (
 242   IN  UINTN         ErrorLevel,
 243   IN  CONST CHAR8   *Format,
 244   IN  BASE_LIST     BaseListMarker
 245   )
 246 {
 247   DebugPrintMarker (ErrorLevel, Format, mVaListNull, BaseListMarker);
 248 }
 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 (Buffer, sizeof (Buffer), "ASSERT [%a] %a(%d): %a\n",
 286     gEfiCallerBaseName, FileName, LineNumber, Description);
 287
 288   if (!mEfiAtRuntime) {
 289     //
 290     // Send the print string to the Console Output device
 291     //
 292     SerialPortWrite ((UINT8 *)Buffer, AsciiStrLen (Buffer));
 293   }
 294
 295   //
 296   // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
 297   //
 298   if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
 299     CpuBreakpoint ();
 300   } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
 301     CpuDeadLoop ();
 302   }
 303 }
 304
 305
 306 /**
 307   Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.
 308
 309   This function fills Length bytes of Buffer with the value specified by
 310   PcdDebugClearMemoryValue, and returns Buffer.
 311
 312   If Buffer is NULL, then ASSERT().
 313   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 314
 315   @param   Buffer  The pointer to the target buffer to be filled with PcdDebugClearMemoryValue.
 316   @param   Length  The number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue.
 317
 318   @return  Buffer  The pointer to the target buffer filled with PcdDebugClearMemoryValue.
 319
 320 **/
 321 VOID *
 322 EFIAPI
 323 DebugClearMemory (
 324   OUT VOID  *Buffer,
 325   IN UINTN  Length
 326   )
 327 {
 328   //
 329   // If Buffer is NULL, then ASSERT().
 330   //
 331   ASSERT (Buffer != NULL);
 332
 333   //
 334   // SetMem() checks for the the ASSERT() condition on Length and returns Buffer
 335   //
 336   return SetMem (Buffer, Length, PcdGet8(PcdDebugClearMemoryValue));
 337 }
 338
 339
 340 /**
 341   Returns TRUE if ASSERT() macros are enabled.
 342
 343   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of
 344   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 345
 346   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.
 347   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.
 348
 349 **/
 350 BOOLEAN
 351 EFIAPI
 352 DebugAssertEnabled (
 353   VOID
 354   )
 355 {
 356   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);
 357 }
 358
 359
 360 /**
 361   Returns TRUE if DEBUG() macros are enabled.
 362
 363   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of
 364   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 365
 366   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.
 367   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.
 368
 369 **/
 370 BOOLEAN
 371 EFIAPI
 372 DebugPrintEnabled (
 373   VOID
 374   )
 375 {
 376   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);
 377 }
 378
 379
 380 /**
 381   Returns TRUE if DEBUG_CODE() macros are enabled.
 382
 383   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of
 384   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 385
 386   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.
 387   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.
 388
 389 **/
 390 BOOLEAN
 391 EFIAPI
 392 DebugCodeEnabled (
 393   VOID
 394   )
 395 {
 396   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);
 397 }
 398
 399
 400 /**
 401   Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled.
 402
 403   This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of
 404   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 405
 406   @retval  TRUE    The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.
 407   @retval  FALSE   The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.
 408
 409 **/
 410 BOOLEAN
 411 EFIAPI
 412 DebugClearMemoryEnabled (
 413   VOID
 414   )
 415 {
 416   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED) != 0);
 417 }
 418
 419 /**
 420   Returns TRUE if any one of the bit is set both in ErrorLevel and PcdFixedDebugPrintErrorLevel.
 421
 422   This function compares the bit mask of ErrorLevel and PcdFixedDebugPrintErrorLevel.
 423
 424   @retval  TRUE    Current ErrorLevel is supported.
 425   @retval  FALSE   Current ErrorLevel is not supported.
 426
 427 **/
 428 BOOLEAN
 429 EFIAPI
 430 DebugPrintLevelEnabled (
 431   IN  CONST UINTN        ErrorLevel
 432   )
 433 {
 434   return (BOOLEAN) ((ErrorLevel & PcdGet32(PcdFixedDebugPrintErrorLevel)) != 0);
 435 }