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