MdePkg/Include/Library/DebugLib.h

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