MdePkg/Include/Library/DebugLib.h

   1 /** @file
   2   Provides services to print debug and assert messages to a debug output device.
   3
   4   The Debug library supports debug print and asserts based on a combination of macros and code.
   5   The debug library can be turned on and off so that the debug code does not increase the size of an image.
   6
   7   Note that a reserved macro named MDEPKG_NDEBUG is introduced for the intention
   8   of size reduction when compiler optimization is disabled. If MDEPKG_NDEBUG is
   9   defined, then debug and assert related macros wrapped by it are the NULL implementations.
  10
  11 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
  12 This program and the accompanying materials are licensed and made available under
  13 the terms and conditions of the BSD License that accompanies this distribution.
  14 The full text of the license may be found at
  15 http://opensource.org/licenses/bsd-license.php.
  16
  17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  19
  20 **/
  21
  22 #ifndef __DEBUG_LIB_H__
  23 #define __DEBUG_LIB_H__
  24
  25 //
  26 // Declare bits for PcdDebugPropertyMask
  27 //
  28 #define DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED       0x01
  29 #define DEBUG_PROPERTY_DEBUG_PRINT_ENABLED        0x02
  30 #define DEBUG_PROPERTY_DEBUG_CODE_ENABLED         0x04
  31 #define DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED       0x08
  32 #define DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED  0x10
  33 #define DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED    0x20
  34
  35 //
  36 // Declare bits for PcdDebugPrintErrorLevel and the ErrorLevel parameter of DebugPrint()
  37 //
  38 #define DEBUG_INIT      0x00000001  // Initialization
  39 #define DEBUG_WARN      0x00000002  // Warnings
  40 #define DEBUG_LOAD      0x00000004  // Load events
  41 #define DEBUG_FS        0x00000008  // EFI File system
  42 #define DEBUG_POOL      0x00000010  // Alloc & Free's
  43 #define DEBUG_PAGE      0x00000020  // Alloc & Free's
  44 #define DEBUG_INFO      0x00000040  // Verbose
  45 #define DEBUG_DISPATCH  0x00000080  // PEI/DXE/SMM Dispatchers
  46 #define DEBUG_VARIABLE  0x00000100  // Variable
  47 #define DEBUG_BM        0x00000400  // Boot Manager
  48 #define DEBUG_BLKIO     0x00001000  // BlkIo Driver
  49 #define DEBUG_NET       0x00004000  // SNI Driver
  50 #define DEBUG_UNDI      0x00010000  // UNDI Driver
  51 #define DEBUG_LOADFILE  0x00020000  // UNDI Driver
  52 #define DEBUG_EVENT     0x00080000  // Event messages
  53 #define DEBUG_GCD       0x00100000  // Global Coherency Database changes
  54 #define DEBUG_CACHE     0x00200000  // Memory range cachability changes
  55 #define DEBUG_ERROR     0x80000000  // Error
  56
  57 //
  58 // Aliases of debug message mask bits
  59 //
  60 #define EFI_D_INIT      DEBUG_INIT
  61 #define EFI_D_WARN      DEBUG_WARN
  62 #define EFI_D_LOAD      DEBUG_LOAD
  63 #define EFI_D_FS        DEBUG_FS
  64 #define EFI_D_POOL      DEBUG_POOL
  65 #define EFI_D_PAGE      DEBUG_PAGE
  66 #define EFI_D_INFO      DEBUG_INFO
  67 #define EFI_D_DISPATCH  DEBUG_DISPATCH
  68 #define EFI_D_VARIABLE  DEBUG_VARIABLE
  69 #define EFI_D_BM        DEBUG_BM
  70 #define EFI_D_BLKIO     DEBUG_BLKIO
  71 #define EFI_D_NET       DEBUG_NET
  72 #define EFI_D_UNDI      DEBUG_UNDI
  73 #define EFI_D_LOADFILE  DEBUG_LOADFILE
  74 #define EFI_D_EVENT     DEBUG_EVENT
  75 #define EFI_D_ERROR     DEBUG_ERROR
  76
  77 /**
  78   Prints a debug message to the debug output device if the specified error level is enabled.
  79
  80   If any bit in ErrorLevel is also set in PcdDebugPrintErrorLevel, then print
  81   the message specified by Format and the associated variable argument list to
  82   the debug output device.
  83
  84   If Format is NULL, then ASSERT().
  85
  86   @param  ErrorLevel  The error level of the debug message.
  87   @param  Format      The format string for the debug message to print.
  88   @param  ...         The variable argument list whose contents are accessed
  89                       based on the format string specified by Format.
  90
  91 **/
  92 VOID
  93 EFIAPI
  94 DebugPrint (
  95   IN  UINTN        ErrorLevel,
  96   IN  CONST CHAR8  *Format,
  97   ...
  98   );
  99
 100
 101 /**
 102   Prints an assert message containing a filename, line number, and description.
 103   This may be followed by a breakpoint or a dead loop.
 104
 105   Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n"
 106   to the debug output device.  If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of
 107   PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if
 108   DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then
 109   CpuDeadLoop() is called.  If neither of these bits are set, then this function
 110   returns immediately after the message is printed to the debug output device.
 111   DebugAssert() must actively prevent recursion.  If DebugAssert() is called while
 112   processing another DebugAssert(), then DebugAssert() must return immediately.
 113
 114   If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
 115   If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
 116
 117   @param  FileName     The pointer to the name of the source file that generated the assert condition.
 118   @param  LineNumber   The line number in the source file that generated the assert condition
 119   @param  Description  The pointer to the description of the assert condition.
 120
 121 **/
 122 VOID
 123 EFIAPI
 124 DebugAssert (
 125   IN CONST CHAR8  *FileName,
 126   IN UINTN        LineNumber,
 127   IN CONST CHAR8  *Description
 128   );
 129
 130
 131 /**
 132   Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.
 133
 134   This function fills Length bytes of Buffer with the value specified by
 135   PcdDebugClearMemoryValue, and returns Buffer.
 136
 137   If Buffer is NULL, then ASSERT().
 138   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 139
 140   @param   Buffer  The pointer to the target buffer to be filled with PcdDebugClearMemoryValue.
 141   @param   Length  The number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue.
 142
 143   @return  Buffer  The pointer to the target buffer filled with PcdDebugClearMemoryValue.
 144
 145 **/
 146 VOID *
 147 EFIAPI
 148 DebugClearMemory (
 149   OUT VOID  *Buffer,
 150   IN UINTN  Length
 151   );
 152
 153
 154 /**
 155   Returns TRUE if ASSERT() macros are enabled.
 156
 157   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of
 158   PcdDebugProperyMask is set.  Otherwise, FALSE is returned.
 159
 160   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.
 161   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.
 162
 163 **/
 164 BOOLEAN
 165 EFIAPI
 166 DebugAssertEnabled (
 167   VOID
 168   );
 169
 170
 171 /**
 172   Returns TRUE if DEBUG() macros are enabled.
 173
 174   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of
 175   PcdDebugProperyMask is set.  Otherwise, FALSE is returned.
 176
 177   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.
 178   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.
 179
 180 **/
 181 BOOLEAN
 182 EFIAPI
 183 DebugPrintEnabled (
 184   VOID
 185   );
 186
 187
 188 /**
 189   Returns TRUE if DEBUG_CODE() macros are enabled.
 190
 191   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of
 192   PcdDebugProperyMask is set.  Otherwise, FALSE is returned.
 193
 194   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.
 195   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.
 196
 197 **/
 198 BOOLEAN
 199 EFIAPI
 200 DebugCodeEnabled (
 201   VOID
 202   );
 203
 204
 205 /**
 206   Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled.
 207
 208   This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of
 209   PcdDebugProperyMask is set.  Otherwise, FALSE is returned.
 210
 211   @retval  TRUE    The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.
 212   @retval  FALSE   The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.
 213
 214 **/
 215 BOOLEAN
 216 EFIAPI
 217 DebugClearMemoryEnabled (
 218   VOID
 219   );
 220
 221
 222 /**
 223   Internal worker macro that calls DebugAssert().
 224
 225   This macro calls DebugAssert(), passing in the filename, line number, and an
 226   expression that evaluated to FALSE.
 227
 228   @param  Expression  Boolean expression that evaluated to FALSE
 229
 230 **/
 231 #define _ASSERT(Expression)  DebugAssert (__FILE__, __LINE__, #Expression)
 232
 233
 234 /**
 235   Internal worker macro that calls DebugPrint().
 236
 237   This macro calls DebugPrint() passing in the debug error level, a format
 238   string, and a variable argument list.
 239
 240   @param  Expression  Expression containing an error level, a format string,
 241                       and a variable argument list based on the format string.
 242
 243 **/
 244 #define _DEBUG(Expression)   DebugPrint Expression
 245
 246
 247 /**
 248   Macro that calls DebugAssert() if an expression evaluates to FALSE.
 249
 250   If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED
 251   bit of PcdDebugProperyMask is set, then this macro evaluates the Boolean
 252   expression specified by Expression.  If Expression evaluates to FALSE, then
 253   DebugAssert() is called passing in the source filename, source line number,
 254   and Expression.
 255
 256   @param  Expression  Boolean expression.
 257
 258 **/
 259 #if !defined(MDEPKG_NDEBUG)
 260   #define ASSERT(Expression)        \
 261     do {                            \
 262       if (DebugAssertEnabled ()) {  \
 263         if (!(Expression)) {        \
 264           _ASSERT (Expression);     \
 265         }                           \
 266       }                             \
 267     } while (FALSE)
 268 #else
 269   #define ASSERT(Expression)
 270 #endif
 271
 272 /**
 273   Macro that calls DebugPrint().
 274
 275   If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED
 276   bit of PcdDebugProperyMask is set, then this macro passes Expression to
 277   DebugPrint().
 278
 279   @param  Expression  Expression containing an error level, a format string,
 280                       and a variable argument list based on the format string.
 281
 282
 283 **/
 284 #if !defined(MDEPKG_NDEBUG)
 285   #define DEBUG(Expression)        \
 286     do {                           \
 287       if (DebugPrintEnabled ()) {  \
 288         _DEBUG (Expression);       \
 289       }                            \
 290     } while (FALSE)
 291 #else
 292   #define DEBUG(Expression)
 293 #endif
 294
 295 /**
 296   Macro that calls DebugAssert() if an EFI_STATUS evaluates to an error code.
 297
 298   If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED
 299   bit of PcdDebugProperyMask is set, then this macro evaluates the EFI_STATUS
 300   value specified by StatusParameter.  If StatusParameter is an error code,
 301   then DebugAssert() is called passing in the source filename, source line
 302   number, and StatusParameter.
 303
 304   @param  StatusParameter  EFI_STATUS value to evaluate.
 305
 306 **/
 307 #if !defined(MDEPKG_NDEBUG)
 308   #define ASSERT_EFI_ERROR(StatusParameter)                                              \
 309     do {                                                                                 \
 310       if (DebugAssertEnabled ()) {                                                       \
 311         if (EFI_ERROR (StatusParameter)) {                                               \
 312           DEBUG ((EFI_D_ERROR, "\nASSERT_EFI_ERROR (Status = %r)\n", StatusParameter));  \
 313           _ASSERT (!EFI_ERROR (StatusParameter));                                        \
 314         }                                                                                \
 315       }                                                                                  \
 316     } while (FALSE)
 317 #else
 318   #define ASSERT_EFI_ERROR(StatusParameter)
 319 #endif
 320
 321 /**
 322   Macro that calls DebugAssert() if a protocol is already installed in the
 323   handle database.
 324
 325   If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit
 326   of PcdDebugProperyMask is clear, then return.
 327
 328   If Handle is NULL, then a check is made to see if the protocol specified by Guid
 329   is present on any handle in the handle database.  If Handle is not NULL, then
 330   a check is made to see if the protocol specified by Guid is present on the
 331   handle specified by Handle.  If the check finds the protocol, then DebugAssert()
 332   is called passing in the source filename, source line number, and Guid.
 333
 334   If Guid is NULL, then ASSERT().
 335
 336   @param  Handle  The handle to check for the protocol.  This is an optional
 337                   parameter that may be NULL.  If it is NULL, then the entire
 338                   handle database is searched.
 339
 340   @param  Guid    The pointer to a protocol GUID.
 341
 342 **/
 343 #if !defined(MDEPKG_NDEBUG)
 344   #define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid)                               \
 345     do {                                                                                \
 346       if (DebugAssertEnabled ()) {                                                      \
 347         VOID  *Instance;                                                                \
 348         ASSERT (Guid != NULL);                                                          \
 349         if (Handle == NULL) {                                                           \
 350           if (!EFI_ERROR (gBS->LocateProtocol ((EFI_GUID *)Guid, NULL, &Instance))) {   \
 351             _ASSERT (Guid already installed in database);                               \
 352           }                                                                             \
 353         } else {                                                                        \
 354           if (!EFI_ERROR (gBS->HandleProtocol (Handle, (EFI_GUID *)Guid, &Instance))) { \
 355             _ASSERT (Guid already installed on Handle);                                 \
 356           }                                                                             \
 357         }                                                                               \
 358       }                                                                                 \
 359     } while (FALSE)
 360 #else
 361   #define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid)
 362 #endif
 363
 364 /**
 365   Macro that marks the beginning of debug source code.
 366
 367   If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set,
 368   then this macro marks the beginning of source code that is included in a module.
 369   Otherwise, the source lines between DEBUG_CODE_BEGIN() and DEBUG_CODE_END()
 370   are not included in a module.
 371
 372 **/
 373 #define DEBUG_CODE_BEGIN()  do { if (DebugCodeEnabled ()) { UINT8  __DebugCodeLocal
 374
 375
 376 /**
 377   The macro that marks the end of debug source code.
 378
 379   If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set,
 380   then this macro marks the end of source code that is included in a module.
 381   Otherwise, the source lines between DEBUG_CODE_BEGIN() and DEBUG_CODE_END()
 382   are not included in a module.
 383
 384 **/
 385 #define DEBUG_CODE_END()    __DebugCodeLocal = 0; __DebugCodeLocal++; } } while (FALSE)
 386
 387
 388 /**
 389   The macro that declares a section of debug source code.
 390
 391   If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set,
 392   then the source code specified by Expression is included in a module.
 393   Otherwise, the source specified by Expression is not included in a module.
 394
 395 **/
 396 #define DEBUG_CODE(Expression)  \
 397   DEBUG_CODE_BEGIN ();          \
 398   Expression                    \
 399   DEBUG_CODE_END ()
 400
 401
 402 /**
 403   The macro that calls DebugClearMemory() to clear a buffer to a default value.
 404
 405   If the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set,
 406   then this macro calls DebugClearMemory() passing in Address and Length.
 407
 408   @param  Address  The pointer to a buffer.
 409   @param  Length   The number of bytes in the buffer to set.
 410
 411 **/
 412 #define DEBUG_CLEAR_MEMORY(Address, Length)  \
 413   do {                                       \
 414     if (DebugClearMemoryEnabled ()) {        \
 415       DebugClearMemory (Address, Length);    \
 416     }                                        \
 417   } while (FALSE)
 418
 419
 420 /**
 421   Macro that calls DebugAssert() if the containing record does not have a
 422   matching signature.  If the signatures matches, then a pointer to the data
 423   structure that contains a specified field of that data structure is returned.
 424   This is a lightweight method hide information by placing a public data
 425   structure inside a larger private data structure and using a pointer to the
 426   public data structure to retrieve a pointer to the private data structure.
 427
 428   If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit
 429   of PcdDebugProperyMask is clear, then this macro computes the offset, in bytes,
 430   of the field specified by Field from the beginning of the data structure specified
 431   by TYPE.  This offset is subtracted from Record, and is used to return a pointer
 432   to a data structure of the type specified by TYPE.
 433
 434   If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit
 435   of PcdDebugProperyMask is set, then this macro computes the offset, in bytes,
 436   of field specified by Field from the beginning of the data structure specified
 437   by TYPE.  This offset is subtracted from Record, and is used to compute a pointer
 438   to a data structure of the type specified by TYPE.  The Signature field of the
 439   data structure specified by TYPE is compared to TestSignature.  If the signatures
 440   match, then a pointer to the pointer to a data structure of the type specified by
 441   TYPE is returned.  If the signatures do not match, then DebugAssert() is called
 442   with a description of "CR has a bad signature" and Record is returned.
 443
 444   If the data type specified by TYPE does not contain the field specified by Field,
 445   then the module will not compile.
 446
 447   If TYPE does not contain a field called Signature, then the module will not
 448   compile.
 449
 450   @param  Record         The pointer to the field specified by Field within a data
 451                          structure of type TYPE.
 452
 453   @param  TYPE           The name of the data structure type to return  This
 454                          data structure must contain the field specified by Field.
 455
 456   @param  Field          The name of the field in the data structure specified
 457                          by TYPE to which Record points.
 458
 459   @param  TestSignature  The 32-bit signature value to match.
 460
 461 **/
 462 #if !defined(MDEPKG_NDEBUG)
 463   #define CR(Record, TYPE, Field, TestSignature)                                              \
 464     (DebugAssertEnabled () && (BASE_CR (Record, TYPE, Field)->Signature != TestSignature)) ?  \
 465     (TYPE *) (_ASSERT (CR has Bad Signature), Record) :                                       \
 466     BASE_CR (Record, TYPE, Field)
 467 #else
 468   #define CR(Record, TYPE, Field, TestSignature)                                              \
 469     BASE_CR (Record, TYPE, Field)
 470 #endif
 471
 472 #endif