MdePkg/Library/UefiDebugLibConOut/DebugLib.c

   1 /** @file
   2   UEFI Debug Library that sends messages to the Console Output Device in the EFI System Table.
   3
   4   Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #include <Uefi.h>
  10
  11 #include <Library/DebugLib.h>
  12 #include <Library/PrintLib.h>
  13 #include <Library/PcdLib.h>
  14 #include <Library/BaseLib.h>
  15 #include <Library/BaseMemoryLib.h>
  16 #include <Library/DebugPrintErrorLevelLib.h>
  17
  18 //
  19 // Define the maximum debug and assert message length that this library supports
  20 //
  21 #define MAX_DEBUG_MESSAGE_LENGTH  0x100
  22
  23 //
  24 // VA_LIST can not initialize to NULL for all compiler, so we use this to
  25 // indicate a null VA_LIST
  26 //
  27 VA_LIST     mVaListNull;
  28
  29 extern BOOLEAN                mPostEBS;
  30 extern EFI_SYSTEM_TABLE       *mDebugST;
  31
  32 /**
  33   Prints a debug message to the debug output device if the specified error level is enabled.
  34
  35   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
  36   GetDebugPrintErrorLevel (), then print the message specified by Format and the
  37   associated variable argument list to the debug output device.
  38
  39   If Format is NULL, then ASSERT().
  40
  41   @param  ErrorLevel  The error level of the debug message.
  42   @param  Format      Format string for the debug message to print.
  43   @param  ...         A variable argument list whose contents are accessed
  44                       based on the format string specified by Format.
  45
  46 **/
  47 VOID
  48 EFIAPI
  49 DebugPrint (
  50   IN  UINTN        ErrorLevel,
  51   IN  CONST CHAR8  *Format,
  52   ...
  53   )
  54 {
  55   VA_LIST  Marker;
  56
  57   VA_START (Marker, Format);
  58   DebugVPrint (ErrorLevel, Format, Marker);
  59   VA_END (Marker);
  60 }
  61
  62
  63 /**
  64   Prints a debug message to the debug output device if the specified
  65   error level is enabled base on Null-terminated format string and a
  66   VA_LIST argument list or a BASE_LIST argument list.
  67
  68   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
  69   GetDebugPrintErrorLevel (), then print the message specified by Format and
  70   the associated variable argument list to the debug output device.
  71
  72   If Format is NULL, then ASSERT().
  73
  74   @param  ErrorLevel      The error level of the debug message.
  75   @param  Format          Format string for the debug message to print.
  76   @param  VaListMarker    VA_LIST marker for the variable argument list.
  77   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
  78
  79 **/
  80 VOID
  81 DebugPrintMarker (
  82   IN  UINTN         ErrorLevel,
  83   IN  CONST CHAR8   *Format,
  84   IN  VA_LIST       VaListMarker,
  85   IN  BASE_LIST     BaseListMarker
  86   )
  87 {
  88   CHAR16   Buffer[MAX_DEBUG_MESSAGE_LENGTH];
  89
  90   if (!mPostEBS) {
  91     //
  92     // If Format is NULL, then ASSERT().
  93     //
  94     ASSERT (Format != NULL);
  95
  96     //
  97     // Check driver debug mask value and global mask
  98     //
  99     if ((ErrorLevel & GetDebugPrintErrorLevel ()) == 0) {
 100       return;
 101     }
 102
 103     //
 104     // Convert the DEBUG() message to a Unicode String
 105     //
 106     if (BaseListMarker == NULL) {
 107       UnicodeVSPrintAsciiFormat (Buffer, sizeof (Buffer), Format, VaListMarker);
 108     } else {
 109       UnicodeBSPrintAsciiFormat (Buffer, sizeof (Buffer), Format, BaseListMarker);
 110     }
 111
 112
 113     //
 114     // Send the print string to the Console Output device
 115     //
 116     if ((mDebugST != NULL) && (mDebugST->ConOut != NULL)) {
 117       mDebugST->ConOut->OutputString (mDebugST->ConOut, Buffer);
 118     }
 119   }
 120 }
 121
 122
 123 /**
 124   Prints a debug message to the debug output device if the specified
 125   error level is enabled.
 126
 127   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 128   GetDebugPrintErrorLevel (), then print the message specified by Format and
 129   the associated variable argument list to the debug output device.
 130
 131   If Format is NULL, then ASSERT().
 132
 133   @param  ErrorLevel    The error level of the debug message.
 134   @param  Format        Format string for the debug message to print.
 135   @param  VaListMarker  VA_LIST marker for the variable argument list.
 136
 137 **/
 138 VOID
 139 EFIAPI
 140 DebugVPrint (
 141   IN  UINTN         ErrorLevel,
 142   IN  CONST CHAR8   *Format,
 143   IN  VA_LIST       VaListMarker
 144   )
 145 {
 146   DebugPrintMarker (ErrorLevel, Format, VaListMarker, NULL);
 147 }
 148
 149
 150 /**
 151   Prints a debug message to the debug output device if the specified
 152   error level is enabled.
 153   This function use BASE_LIST which would provide a more compatible
 154   service than VA_LIST.
 155
 156   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 157   GetDebugPrintErrorLevel (), then print the message specified by Format and
 158   the associated variable argument list to the debug output device.
 159
 160   If Format is NULL, then ASSERT().
 161
 162   @param  ErrorLevel      The error level of the debug message.
 163   @param  Format          Format string for the debug message to print.
 164   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
 165
 166 **/
 167 VOID
 168 EFIAPI
 169 DebugBPrint (
 170   IN  UINTN         ErrorLevel,
 171   IN  CONST CHAR8   *Format,
 172   IN  BASE_LIST     BaseListMarker
 173   )
 174 {
 175   DebugPrintMarker (ErrorLevel, Format, mVaListNull, BaseListMarker);
 176 }
 177
 178
 179 /**
 180   Prints an assert message containing a filename, line number, and description.
 181   This may be followed by a breakpoint or a dead loop.
 182
 183   Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n"
 184   to the debug output device.  If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of
 185   PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if
 186   DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then
 187   CpuDeadLoop() is called.  If neither of these bits are set, then this function
 188   returns immediately after the message is printed to the debug output device.
 189   DebugAssert() must actively prevent recursion.  If DebugAssert() is called while
 190   processing another DebugAssert(), then DebugAssert() must return immediately.
 191
 192   If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
 193   If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
 194
 195   @param  FileName     The pointer to the name of the source file that generated
 196                        the assert condition.
 197   @param  LineNumber   The line number in the source file that generated the
 198                        assert condition
 199   @param  Description  The pointer to the description of the assert condition.
 200
 201 **/
 202 VOID
 203 EFIAPI
 204 DebugAssert (
 205   IN CONST CHAR8  *FileName,
 206   IN UINTN        LineNumber,
 207   IN CONST CHAR8  *Description
 208   )
 209 {
 210   CHAR16  Buffer[MAX_DEBUG_MESSAGE_LENGTH];
 211
 212   if (!mPostEBS) {
 213     //
 214     // Generate the ASSERT() message in Unicode format
 215     //
 216     UnicodeSPrintAsciiFormat (
 217       Buffer,
 218       sizeof (Buffer),
 219       "ASSERT [%a] %a(%d): %a\n",
 220       gEfiCallerBaseName,
 221       FileName,
 222       LineNumber,
 223       Description
 224       );
 225
 226     //
 227     // Send the print string to the Console Output device
 228     //
 229     if ((mDebugST != NULL) && (mDebugST->ConOut != NULL)) {
 230       mDebugST->ConOut->OutputString (mDebugST->ConOut, Buffer);
 231     }
 232
 233     //
 234     // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
 235     //
 236     if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
 237       CpuBreakpoint ();
 238     } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
 239       CpuDeadLoop ();
 240     }
 241   }
 242 }
 243
 244
 245 /**
 246   Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.
 247
 248   This function fills Length bytes of Buffer with the value specified by
 249   PcdDebugClearMemoryValue, and returns Buffer.
 250
 251   If Buffer is NULL, then ASSERT().
 252   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 253
 254   @param   Buffer  The pointer to the target buffer to be filled with PcdDebugClearMemoryValue.
 255   @param   Length  The number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue.
 256
 257   @return  Buffer  The pointer to the target buffer filled with PcdDebugClearMemoryValue.
 258
 259 **/
 260 VOID *
 261 EFIAPI
 262 DebugClearMemory (
 263   OUT VOID  *Buffer,
 264   IN UINTN  Length
 265   )
 266 {
 267   //
 268   // If Buffer is NULL, then ASSERT().
 269   //
 270   ASSERT (Buffer != NULL);
 271
 272   //
 273   // SetMem() checks for the the ASSERT() condition on Length and returns Buffer
 274   //
 275   return SetMem (Buffer, Length, PcdGet8(PcdDebugClearMemoryValue));
 276 }
 277
 278
 279 /**
 280   Returns TRUE if ASSERT() macros are enabled.
 281
 282   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of
 283   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 284
 285   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.
 286   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.
 287
 288 **/
 289 BOOLEAN
 290 EFIAPI
 291 DebugAssertEnabled (
 292   VOID
 293   )
 294 {
 295   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);
 296 }
 297
 298
 299 /**
 300   Returns TRUE if DEBUG() macros are enabled.
 301
 302   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of
 303   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 304
 305   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.
 306   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.
 307
 308 **/
 309 BOOLEAN
 310 EFIAPI
 311 DebugPrintEnabled (
 312   VOID
 313   )
 314 {
 315   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);
 316 }
 317
 318
 319 /**
 320   Returns TRUE if DEBUG_CODE() macros are enabled.
 321
 322   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of
 323   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 324
 325   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.
 326   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.
 327
 328 **/
 329 BOOLEAN
 330 EFIAPI
 331 DebugCodeEnabled (
 332   VOID
 333   )
 334 {
 335   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);
 336 }
 337
 338
 339 /**
 340   Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled.
 341
 342   This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of
 343   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 344
 345   @retval  TRUE    The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.
 346   @retval  FALSE   The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.
 347
 348 **/
 349 BOOLEAN
 350 EFIAPI
 351 DebugClearMemoryEnabled (
 352   VOID
 353   )
 354 {
 355   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED) != 0);
 356 }
 357
 358 /**
 359   Returns TRUE if any one of the bit is set both in ErrorLevel and PcdFixedDebugPrintErrorLevel.
 360
 361   This function compares the bit mask of ErrorLevel and PcdFixedDebugPrintErrorLevel.
 362
 363   @retval  TRUE    Current ErrorLevel is supported.
 364   @retval  FALSE   Current ErrorLevel is not supported.
 365
 366 **/
 367 BOOLEAN
 368 EFIAPI
 369 DebugPrintLevelEnabled (
 370   IN  CONST UINTN        ErrorLevel
 371   )
 372 {
 373   return (BOOLEAN) ((ErrorLevel & PcdGet32(PcdFixedDebugPrintErrorLevel)) != 0);
 374 }