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