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   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 //
  26 // Define the maximum debug and assert message length that this library supports
  27 //
  28 #define MAX_DEBUG_MESSAGE_LENGTH  0x100
  29
  30 //
  31 // VA_LIST can not initialize to NULL for all compiler, so we use this to
  32 // indicate a null VA_LIST
  33 //
  34 VA_LIST     mVaListNull;
  35
  36 /**
  37   Prints a debug message to the debug output device if the specified error level is enabled.
  38
  39   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
  40   GetDebugPrintErrorLevel (), then print the message specified by Format and the
  41   associated variable argument list to the debug output device.
  42
  43   If Format is NULL, then ASSERT().
  44
  45   @param  ErrorLevel  The error level of the debug message.
  46   @param  Format      Format string for the debug message to print.
  47   @param  ...         A variable argument list whose contents are accessed
  48                       based on the format string specified by Format.
  49
  50 **/
  51 VOID
  52 EFIAPI
  53 DebugPrint (
  54   IN  UINTN        ErrorLevel,
  55   IN  CONST CHAR8  *Format,
  56   ...
  57   )
  58 {
  59   VA_LIST  Marker;
  60
  61   VA_START (Marker, Format);
  62   DebugVPrint (ErrorLevel, Format, Marker);
  63   VA_END (Marker);
  64 }
  65
  66
  67 /**
  68   Prints a debug message to the debug output device if the specified
  69   error level is enabled base on Null-terminated format string and a
  70   VA_LIST argument list or a BASE_LIST argument list.
  71
  72   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
  73   GetDebugPrintErrorLevel (), then print the message specified by Format and
  74   the associated variable argument list to the debug output device.
  75
  76   If Format is NULL, then ASSERT().
  77
  78   @param  ErrorLevel      The error level of the debug message.
  79   @param  Format          Format string for the debug message to print.
  80   @param  VaListMarker    VA_LIST marker for the variable argument list.
  81   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
  82
  83 **/
  84 VOID
  85 DebugPrintMarker (
  86   IN  UINTN         ErrorLevel,
  87   IN  CONST CHAR8   *Format,
  88   IN  VA_LIST       VaListMarker,
  89   IN  BASE_LIST     BaseListMarker
  90   )
  91 {
  92   CHAR16   Buffer[MAX_DEBUG_MESSAGE_LENGTH];
  93
  94   //
  95   // If Format is NULL, then ASSERT().
  96   //
  97   ASSERT (Format != NULL);
  98
  99   //
 100   // Check driver debug mask value and global mask
 101   //
 102   if ((ErrorLevel & GetDebugPrintErrorLevel ()) == 0) {
 103     return;
 104   }
 105
 106   //
 107   // Convert the DEBUG() message to a Unicode String
 108   //
 109   if (BaseListMarker == NULL) {
 110     UnicodeVSPrintAsciiFormat (Buffer, MAX_DEBUG_MESSAGE_LENGTH,  Format, VaListMarker);
 111   } else {
 112     UnicodeBSPrintAsciiFormat (Buffer, MAX_DEBUG_MESSAGE_LENGTH,  Format, BaseListMarker);
 113   }
 114
 115
 116   //
 117   // Send the print string to the Console Output device
 118   //
 119   if ((gST != NULL) && (gST->ConOut != NULL)) {
 120     gST->ConOut->OutputString (gST->ConOut, Buffer);
 121   }
 122 }
 123
 124
 125 /**
 126   Prints a debug message to the debug output device if the specified
 127   error level is enabled.
 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
 139 **/
 140 VOID
 141 EFIAPI
 142 DebugVPrint (
 143   IN  UINTN         ErrorLevel,
 144   IN  CONST CHAR8   *Format,
 145   IN  VA_LIST       VaListMarker
 146   )
 147 {
 148   DebugPrintMarker (ErrorLevel, Format, VaListMarker, NULL);
 149 }
 150
 151
 152 /**
 153   Prints a debug message to the debug output device if the specified
 154   error level is enabled.
 155   This function use BASE_LIST which would provide a more compatible
 156   service than VA_LIST.
 157
 158   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 159   GetDebugPrintErrorLevel (), then print the message specified by Format and
 160   the associated variable argument list to the debug output device.
 161
 162   If Format is NULL, then ASSERT().
 163
 164   @param  ErrorLevel      The error level of the debug message.
 165   @param  Format          Format string for the debug message to print.
 166   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
 167
 168 **/
 169 VOID
 170 EFIAPI
 171 DebugBPrint (
 172   IN  UINTN         ErrorLevel,
 173   IN  CONST CHAR8   *Format,
 174   IN  BASE_LIST     BaseListMarker
 175   )
 176 {
 177   DebugPrintMarker (ErrorLevel, Format, mVaListNull, BaseListMarker);
 178 }
 179
 180
 181 /**
 182   Prints an assert message containing a filename, line number, and description.
 183   This may be followed by a breakpoint or a dead loop.
 184
 185   Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n"
 186   to the debug output device.  If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of
 187   PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if
 188   DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then
 189   CpuDeadLoop() is called.  If neither of these bits are set, then this function
 190   returns immediately after the message is printed to the debug output device.
 191   DebugAssert() must actively prevent recursion.  If DebugAssert() is called while
 192   processing another DebugAssert(), then DebugAssert() must return immediately.
 193
 194   If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
 195   If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
 196
 197   @param  FileName     The pointer to the name of the source file that generated
 198                        the assert condition.
 199   @param  LineNumber   The line number in the source file that generated the
 200                        assert condition
 201   @param  Description  The pointer to the description of the assert condition.
 202
 203 **/
 204 VOID
 205 EFIAPI
 206 DebugAssert (
 207   IN CONST CHAR8  *FileName,
 208   IN UINTN        LineNumber,
 209   IN CONST CHAR8  *Description
 210   )
 211 {
 212   CHAR16  Buffer[MAX_DEBUG_MESSAGE_LENGTH];
 213
 214   //
 215   // Generate the ASSERT() message in Unicode format
 216   //
 217   UnicodeSPrintAsciiFormat (
 218     Buffer,
 219     sizeof (Buffer),
 220     "ASSERT [%a] %a(%d): %a\n",
 221     gEfiCallerBaseName,
 222     FileName,
 223     LineNumber,
 224     Description
 225     );
 226
 227   //
 228   // Send the print string to the Console Output device
 229   //
 230   if ((gST != NULL) && (gST->ConOut != NULL)) {
 231     gST->ConOut->OutputString (gST->ConOut, Buffer);
 232   }
 233
 234   //
 235   // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
 236   //
 237   if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
 238     CpuBreakpoint ();
 239   } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
 240     CpuDeadLoop ();
 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 }