EdkCompatibilityPkg/Foundation/Library/EdkIIGlueLib/Include/Library/EdkIIGlueDebugLib.h

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