Subrata Banik | 20fe24b | 2021-12-09 02:46:38 +0530 | [diff] [blame] | 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 | // Source file line number. |
| 76 | // Default is use the to compiler provided __LINE__ macro value. The __LINE__ |
| 77 | // mapping can be overriden by predefining DEBUG_LINE_NUMBER |
| 78 | // |
| 79 | // Defining DEBUG_LINE_NUMBER to a fixed value is useful when comparing builds |
| 80 | // across source code formatting changes that may add/remove lines in a source |
| 81 | // file. |
| 82 | // |
| 83 | #ifdef DEBUG_LINE_NUMBER |
| 84 | #else |
| 85 | #define DEBUG_LINE_NUMBER __LINE__ |
| 86 | #endif |
| 87 | |
| 88 | /** |
| 89 | Macro that converts a Boolean expression to a Null-terminated ASCII string. |
| 90 | |
| 91 | The default is to use the C pre-processor stringizing operator '#' to add |
| 92 | quotes around the C expression. If DEBUG_EXPRESSION_STRING_VALUE is defined |
| 93 | then the C expression is converted to the fixed string value. |
| 94 | |
| 95 | Defining DEBUG_EXPRESSION_STRING_VALUE to a fixed value is useful when |
| 96 | comparing builds across source code formatting changes that may make |
| 97 | changes to spaces or parenthesis in a Boolean expression. |
| 98 | |
| 99 | @param Expression Boolean expression. |
| 100 | |
| 101 | **/ |
| 102 | |
| 103 | #ifdef DEBUG_EXPRESSION_STRING_VALUE |
| 104 | #define DEBUG_EXPRESSION_STRING(Expression) DEBUG_EXPRESSION_STRING_VALUE |
| 105 | #else |
| 106 | #define DEBUG_EXPRESSION_STRING(Expression) #Expression |
| 107 | #endif |
| 108 | |
| 109 | /** |
| 110 | Prints a debug message to the debug output device if the specified error level is enabled. |
| 111 | |
| 112 | If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function |
| 113 | GetDebugPrintErrorLevel (), then print the message specified by Format and the |
| 114 | associated variable argument list to the debug output device. |
| 115 | |
| 116 | If Format is NULL, then ASSERT(). |
| 117 | |
| 118 | @param ErrorLevel The error level of the debug message. |
| 119 | @param Format The format string for the debug message to print. |
| 120 | @param ... The variable argument list whose contents are accessed |
| 121 | based on the format string specified by Format. |
| 122 | |
| 123 | **/ |
| 124 | VOID |
| 125 | EFIAPI |
| 126 | DebugPrint ( |
| 127 | IN UINTN ErrorLevel, |
| 128 | IN CONST CHAR8 *Format, |
| 129 | ... |
| 130 | ); |
| 131 | |
| 132 | |
| 133 | /** |
| 134 | Prints a debug message to the debug output device if the specified |
| 135 | error level is enabled. |
| 136 | |
| 137 | If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function |
| 138 | GetDebugPrintErrorLevel (), then print the message specified by Format and |
| 139 | the associated variable argument list to the debug output device. |
| 140 | |
| 141 | If Format is NULL, then ASSERT(). |
| 142 | |
| 143 | @param ErrorLevel The error level of the debug message. |
| 144 | @param Format Format string for the debug message to print. |
| 145 | @param VaListMarker VA_LIST marker for the variable argument list. |
| 146 | |
| 147 | **/ |
| 148 | VOID |
| 149 | EFIAPI |
| 150 | DebugVPrint ( |
| 151 | IN UINTN ErrorLevel, |
| 152 | IN CONST CHAR8 *Format, |
| 153 | IN VA_LIST VaListMarker |
| 154 | ); |
| 155 | |
| 156 | |
| 157 | /** |
| 158 | Prints a debug message to the debug output device if the specified |
| 159 | error level is enabled. |
| 160 | This function use BASE_LIST which would provide a more compatible |
| 161 | service than VA_LIST. |
| 162 | |
| 163 | If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function |
| 164 | GetDebugPrintErrorLevel (), then print the message specified by Format and |
| 165 | the associated variable argument list to the debug output device. |
| 166 | |
| 167 | If Format is NULL, then ASSERT(). |
| 168 | |
| 169 | @param ErrorLevel The error level of the debug message. |
| 170 | @param Format Format string for the debug message to print. |
| 171 | @param BaseListMarker BASE_LIST marker for the variable argument list. |
| 172 | |
| 173 | **/ |
| 174 | VOID |
| 175 | EFIAPI |
| 176 | DebugBPrint ( |
| 177 | IN UINTN ErrorLevel, |
| 178 | IN CONST CHAR8 *Format, |
| 179 | IN BASE_LIST BaseListMarker |
| 180 | ); |
| 181 | |
| 182 | |
| 183 | /** |
| 184 | Prints an assert message containing a filename, line number, and description. |
| 185 | This may be followed by a breakpoint or a dead loop. |
| 186 | |
| 187 | Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n" |
| 188 | to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of |
| 189 | PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if |
| 190 | DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then |
| 191 | CpuDeadLoop() is called. If neither of these bits are set, then this function |
| 192 | returns immediately after the message is printed to the debug output device. |
| 193 | DebugAssert() must actively prevent recursion. If DebugAssert() is called while |
| 194 | processing another DebugAssert(), then DebugAssert() must return immediately. |
| 195 | |
| 196 | If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed. |
| 197 | If Description is NULL, then a <Description> string of "(NULL) Description" is printed. |
| 198 | |
| 199 | @param FileName The pointer to the name of the source file that generated the assert condition. |
| 200 | @param LineNumber The line number in the source file that generated the assert condition |
| 201 | @param Description The pointer to the description of the assert condition. |
| 202 | |
| 203 | **/ |
| 204 | VOID |
| 205 | EFIAPI |
| 206 | DebugAssert ( |
| 207 | IN CONST CHAR8 *FileName, |
| 208 | IN UINTN LineNumber, |
| 209 | IN CONST CHAR8 *Description |
| 210 | ); |
| 211 | |
| 212 | |
| 213 | /** |
| 214 | Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer. |
| 215 | |
| 216 | This function fills Length bytes of Buffer with the value specified by |
| 217 | PcdDebugClearMemoryValue, and returns Buffer. |
| 218 | |
| 219 | If Buffer is NULL, then ASSERT(). |
| 220 | If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). |
| 221 | |
| 222 | @param Buffer The pointer to the target buffer to be filled with PcdDebugClearMemoryValue. |
| 223 | @param Length The number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. |
| 224 | |
| 225 | @return Buffer The pointer to the target buffer filled with PcdDebugClearMemoryValue. |
| 226 | |
| 227 | **/ |
| 228 | VOID * |
| 229 | EFIAPI |
| 230 | DebugClearMemory ( |
| 231 | OUT VOID *Buffer, |
| 232 | IN UINTN Length |
| 233 | ); |
| 234 | |
| 235 | |
| 236 | /** |
| 237 | Returns TRUE if ASSERT() macros are enabled. |
| 238 | |
| 239 | This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of |
| 240 | PcdDebugProperyMask is set. Otherwise, FALSE is returned. |
| 241 | |
| 242 | @retval TRUE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set. |
| 243 | @retval FALSE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear. |
| 244 | |
| 245 | **/ |
| 246 | BOOLEAN |
| 247 | EFIAPI |
| 248 | DebugAssertEnabled ( |
| 249 | VOID |
| 250 | ); |
| 251 | |
| 252 | |
| 253 | /** |
| 254 | Returns TRUE if DEBUG() macros are enabled. |
| 255 | |
| 256 | This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of |
| 257 | PcdDebugProperyMask is set. Otherwise, FALSE is returned. |
| 258 | |
| 259 | @retval TRUE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set. |
| 260 | @retval FALSE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear. |
| 261 | |
| 262 | **/ |
| 263 | BOOLEAN |
| 264 | EFIAPI |
| 265 | DebugPrintEnabled ( |
| 266 | VOID |
| 267 | ); |
| 268 | |
| 269 | |
| 270 | /** |
| 271 | Returns TRUE if DEBUG_CODE() macros are enabled. |
| 272 | |
| 273 | This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of |
| 274 | PcdDebugProperyMask is set. Otherwise, FALSE is returned. |
| 275 | |
| 276 | @retval TRUE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set. |
| 277 | @retval FALSE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear. |
| 278 | |
| 279 | **/ |
| 280 | BOOLEAN |
| 281 | EFIAPI |
| 282 | DebugCodeEnabled ( |
| 283 | VOID |
| 284 | ); |
| 285 | |
| 286 | |
| 287 | /** |
| 288 | Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled. |
| 289 | |
| 290 | This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of |
| 291 | PcdDebugProperyMask is set. Otherwise, FALSE is returned. |
| 292 | |
| 293 | @retval TRUE The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set. |
| 294 | @retval FALSE The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear. |
| 295 | |
| 296 | **/ |
| 297 | BOOLEAN |
| 298 | EFIAPI |
| 299 | DebugClearMemoryEnabled ( |
| 300 | VOID |
| 301 | ); |
| 302 | |
| 303 | /** |
| 304 | Returns TRUE if any one of the bit is set both in ErrorLevel and PcdFixedDebugPrintErrorLevel. |
| 305 | |
| 306 | This function compares the bit mask of ErrorLevel and PcdFixedDebugPrintErrorLevel. |
| 307 | |
| 308 | @retval TRUE Current ErrorLevel is supported. |
| 309 | @retval FALSE Current ErrorLevel is not supported. |
| 310 | |
| 311 | **/ |
| 312 | BOOLEAN |
| 313 | EFIAPI |
| 314 | DebugPrintLevelEnabled ( |
| 315 | IN CONST UINTN ErrorLevel |
| 316 | ); |
| 317 | |
| 318 | /** |
| 319 | Internal worker macro that calls DebugAssert(). |
| 320 | |
| 321 | This macro calls DebugAssert(), passing in the filename, line number, and an |
| 322 | expression that evaluated to FALSE. |
| 323 | |
| 324 | @param Expression Boolean expression that evaluated to FALSE |
| 325 | |
| 326 | **/ |
| 327 | #if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED) |
| 328 | /** |
| 329 | Unit test library replacement for DebugAssert() in DebugLib. |
| 330 | |
| 331 | If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed. |
| 332 | If Description is NULL, then a <Description> string of "(NULL) Description" is printed. |
| 333 | |
| 334 | @param FileName The pointer to the name of the source file that generated the assert condition. |
| 335 | @param LineNumber The line number in the source file that generated the assert condition |
| 336 | @param Description The pointer to the description of the assert condition. |
| 337 | |
| 338 | **/ |
| 339 | VOID |
| 340 | EFIAPI |
| 341 | UnitTestDebugAssert ( |
| 342 | IN CONST CHAR8 *FileName, |
| 343 | IN UINTN LineNumber, |
| 344 | IN CONST CHAR8 *Description |
| 345 | ); |
| 346 | |
| 347 | #if defined(__clang__) && defined(__FILE_NAME__) |
| 348 | #define _ASSERT(Expression) UnitTestDebugAssert (__FILE_NAME__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression)) |
| 349 | #else |
| 350 | #define _ASSERT(Expression) UnitTestDebugAssert (__FILE__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression)) |
| 351 | #endif |
| 352 | #else |
| 353 | #if defined(__clang__) && defined(__FILE_NAME__) |
| 354 | #define _ASSERT(Expression) DebugAssert (__FILE_NAME__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression)) |
| 355 | #else |
| 356 | #define _ASSERT(Expression) DebugAssert (__FILE__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression)) |
| 357 | #endif |
| 358 | #endif |
| 359 | |
| 360 | /** |
| 361 | Internal worker macro that calls DebugPrint(). |
| 362 | |
| 363 | This macro calls DebugPrint() passing in the debug error level, a format |
| 364 | string, and a variable argument list. |
| 365 | __VA_ARGS__ is not supported by EBC compiler, Microsoft Visual Studio .NET 2003 |
| 366 | and Microsoft Windows Server 2003 Driver Development Kit (Microsoft WINDDK) version 3790.1830. |
| 367 | |
| 368 | @param Expression Expression containing an error level, a format string, |
| 369 | and a variable argument list based on the format string. |
| 370 | |
| 371 | **/ |
| 372 | |
| 373 | #if !defined(MDE_CPU_EBC) && (!defined (_MSC_VER) || _MSC_VER > 1400) |
| 374 | #define _DEBUG_PRINT(PrintLevel, ...) \ |
| 375 | do { \ |
| 376 | if (DebugPrintLevelEnabled (PrintLevel)) { \ |
| 377 | DebugPrint (PrintLevel, ##__VA_ARGS__); \ |
| 378 | } \ |
| 379 | } while (FALSE) |
| 380 | #define _DEBUG(Expression) _DEBUG_PRINT Expression |
| 381 | #else |
| 382 | #define _DEBUG(Expression) DebugPrint Expression |
| 383 | #endif |
| 384 | |
| 385 | /** |
| 386 | Macro that calls DebugAssert() if an expression evaluates to FALSE. |
| 387 | |
| 388 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED |
| 389 | bit of PcdDebugProperyMask is set, then this macro evaluates the Boolean |
| 390 | expression specified by Expression. If Expression evaluates to FALSE, then |
| 391 | DebugAssert() is called passing in the source filename, source line number, |
| 392 | and Expression. |
| 393 | |
| 394 | @param Expression Boolean expression. |
| 395 | |
| 396 | **/ |
| 397 | #if !defined(MDEPKG_NDEBUG) |
| 398 | #define ASSERT(Expression) \ |
| 399 | do { \ |
| 400 | if (DebugAssertEnabled ()) { \ |
| 401 | if (!(Expression)) { \ |
| 402 | _ASSERT (Expression); \ |
| 403 | ANALYZER_UNREACHABLE (); \ |
| 404 | } \ |
| 405 | } \ |
| 406 | } while (FALSE) |
| 407 | #else |
| 408 | #define ASSERT(Expression) |
| 409 | #endif |
| 410 | |
| 411 | /** |
| 412 | Macro that calls DebugPrint(). |
| 413 | |
| 414 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED |
| 415 | bit of PcdDebugProperyMask is set, then this macro passes Expression to |
| 416 | DebugPrint(). |
| 417 | |
| 418 | @param Expression Expression containing an error level, a format string, |
| 419 | and a variable argument list based on the format string. |
| 420 | |
| 421 | |
| 422 | **/ |
| 423 | #if !defined(MDEPKG_NDEBUG) |
| 424 | #define DEBUG(Expression) \ |
| 425 | do { \ |
| 426 | if (DebugPrintEnabled ()) { \ |
| 427 | _DEBUG (Expression); \ |
| 428 | } \ |
| 429 | } while (FALSE) |
| 430 | #else |
| 431 | #define DEBUG(Expression) |
| 432 | #endif |
| 433 | |
| 434 | /** |
| 435 | Macro that calls DebugAssert() if an EFI_STATUS evaluates to an error code. |
| 436 | |
| 437 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED |
| 438 | bit of PcdDebugProperyMask is set, then this macro evaluates the EFI_STATUS |
| 439 | value specified by StatusParameter. If StatusParameter is an error code, |
| 440 | then DebugAssert() is called passing in the source filename, source line |
| 441 | number, and StatusParameter. |
| 442 | |
| 443 | @param StatusParameter EFI_STATUS value to evaluate. |
| 444 | |
| 445 | **/ |
| 446 | #if !defined(MDEPKG_NDEBUG) |
| 447 | #define ASSERT_EFI_ERROR(StatusParameter) \ |
| 448 | do { \ |
| 449 | if (DebugAssertEnabled ()) { \ |
| 450 | if (EFI_ERROR (StatusParameter)) { \ |
| 451 | DEBUG ((EFI_D_ERROR, "\nASSERT_EFI_ERROR (Status = %r)\n", StatusParameter)); \ |
| 452 | _ASSERT (!EFI_ERROR (StatusParameter)); \ |
| 453 | } \ |
| 454 | } \ |
| 455 | } while (FALSE) |
| 456 | #else |
| 457 | #define ASSERT_EFI_ERROR(StatusParameter) |
| 458 | #endif |
| 459 | |
| 460 | /** |
| 461 | Macro that calls DebugAssert() if a RETURN_STATUS evaluates to an error code. |
| 462 | |
| 463 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED |
| 464 | bit of PcdDebugProperyMask is set, then this macro evaluates the |
| 465 | RETURN_STATUS value specified by StatusParameter. If StatusParameter is an |
| 466 | error code, then DebugAssert() is called passing in the source filename, |
| 467 | source line number, and StatusParameter. |
| 468 | |
| 469 | @param StatusParameter RETURN_STATUS value to evaluate. |
| 470 | |
| 471 | **/ |
| 472 | #if !defined(MDEPKG_NDEBUG) |
| 473 | #define ASSERT_RETURN_ERROR(StatusParameter) \ |
| 474 | do { \ |
| 475 | if (DebugAssertEnabled ()) { \ |
| 476 | if (RETURN_ERROR (StatusParameter)) { \ |
| 477 | DEBUG ((DEBUG_ERROR, "\nASSERT_RETURN_ERROR (Status = %r)\n", \ |
| 478 | StatusParameter)); \ |
| 479 | _ASSERT (!RETURN_ERROR (StatusParameter)); \ |
| 480 | } \ |
| 481 | } \ |
| 482 | } while (FALSE) |
| 483 | #else |
| 484 | #define ASSERT_RETURN_ERROR(StatusParameter) |
| 485 | #endif |
| 486 | |
| 487 | /** |
| 488 | Macro that calls DebugAssert() if a protocol is already installed in the |
| 489 | handle database. |
| 490 | |
| 491 | If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit |
| 492 | of PcdDebugProperyMask is clear, then return. |
| 493 | |
| 494 | If Handle is NULL, then a check is made to see if the protocol specified by Guid |
| 495 | is present on any handle in the handle database. If Handle is not NULL, then |
| 496 | a check is made to see if the protocol specified by Guid is present on the |
| 497 | handle specified by Handle. If the check finds the protocol, then DebugAssert() |
| 498 | is called passing in the source filename, source line number, and Guid. |
| 499 | |
| 500 | If Guid is NULL, then ASSERT(). |
| 501 | |
| 502 | @param Handle The handle to check for the protocol. This is an optional |
| 503 | parameter that may be NULL. If it is NULL, then the entire |
| 504 | handle database is searched. |
| 505 | |
| 506 | @param Guid The pointer to a protocol GUID. |
| 507 | |
| 508 | **/ |
| 509 | #if !defined(MDEPKG_NDEBUG) |
| 510 | #define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid) \ |
| 511 | do { \ |
| 512 | if (DebugAssertEnabled ()) { \ |
| 513 | VOID *Instance; \ |
| 514 | ASSERT (Guid != NULL); \ |
| 515 | if (Handle == NULL) { \ |
| 516 | if (!EFI_ERROR (gBS->LocateProtocol ((EFI_GUID *)Guid, NULL, &Instance))) { \ |
| 517 | _ASSERT (Guid already installed in database); \ |
| 518 | } \ |
| 519 | } else { \ |
| 520 | if (!EFI_ERROR (gBS->HandleProtocol (Handle, (EFI_GUID *)Guid, &Instance))) { \ |
| 521 | _ASSERT (Guid already installed on Handle); \ |
| 522 | } \ |
| 523 | } \ |
| 524 | } \ |
| 525 | } while (FALSE) |
| 526 | #else |
| 527 | #define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid) |
| 528 | #endif |
| 529 | |
| 530 | /** |
| 531 | Macro that marks the beginning of debug source code. |
| 532 | |
| 533 | If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, |
| 534 | then this macro marks the beginning of source code that is included in a module. |
| 535 | Otherwise, the source lines between DEBUG_CODE_BEGIN() and DEBUG_CODE_END() |
| 536 | are not included in a module. |
| 537 | |
| 538 | **/ |
| 539 | #define DEBUG_CODE_BEGIN() do { if (DebugCodeEnabled ()) { UINT8 __DebugCodeLocal |
| 540 | |
| 541 | |
| 542 | /** |
| 543 | The macro that marks the end of debug source code. |
| 544 | |
| 545 | If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, |
| 546 | then this macro marks the end of source code that is included in a module. |
| 547 | Otherwise, the source lines between DEBUG_CODE_BEGIN() and DEBUG_CODE_END() |
| 548 | are not included in a module. |
| 549 | |
| 550 | **/ |
| 551 | #define DEBUG_CODE_END() __DebugCodeLocal = 0; __DebugCodeLocal++; } } while (FALSE) |
| 552 | |
| 553 | |
| 554 | /** |
| 555 | The macro that declares a section of debug source code. |
| 556 | |
| 557 | If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, |
| 558 | then the source code specified by Expression is included in a module. |
| 559 | Otherwise, the source specified by Expression is not included in a module. |
| 560 | |
| 561 | **/ |
| 562 | #define DEBUG_CODE(Expression) \ |
| 563 | DEBUG_CODE_BEGIN (); \ |
| 564 | Expression \ |
| 565 | DEBUG_CODE_END () |
| 566 | |
| 567 | |
| 568 | /** |
| 569 | The macro that calls DebugClearMemory() to clear a buffer to a default value. |
| 570 | |
| 571 | If the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set, |
| 572 | then this macro calls DebugClearMemory() passing in Address and Length. |
| 573 | |
| 574 | @param Address The pointer to a buffer. |
| 575 | @param Length The number of bytes in the buffer to set. |
| 576 | |
| 577 | **/ |
| 578 | #define DEBUG_CLEAR_MEMORY(Address, Length) \ |
| 579 | do { \ |
| 580 | if (DebugClearMemoryEnabled ()) { \ |
| 581 | DebugClearMemory (Address, Length); \ |
| 582 | } \ |
| 583 | } while (FALSE) |
| 584 | |
| 585 | |
| 586 | /** |
| 587 | Macro that calls DebugAssert() if the containing record does not have a |
| 588 | matching signature. If the signatures matches, then a pointer to the data |
| 589 | structure that contains a specified field of that data structure is returned. |
| 590 | This is a lightweight method hide information by placing a public data |
| 591 | structure inside a larger private data structure and using a pointer to the |
| 592 | public data structure to retrieve a pointer to the private data structure. |
| 593 | |
| 594 | If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit |
| 595 | of PcdDebugProperyMask is clear, then this macro computes the offset, in bytes, |
| 596 | of the field specified by Field from the beginning of the data structure specified |
| 597 | by TYPE. This offset is subtracted from Record, and is used to return a pointer |
| 598 | to a data structure of the type specified by TYPE. |
| 599 | |
| 600 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit |
| 601 | of PcdDebugProperyMask is set, then this macro computes the offset, in bytes, |
| 602 | of field specified by Field from the beginning of the data structure specified |
| 603 | by TYPE. This offset is subtracted from Record, and is used to compute a pointer |
| 604 | to a data structure of the type specified by TYPE. The Signature field of the |
| 605 | data structure specified by TYPE is compared to TestSignature. If the signatures |
| 606 | match, then a pointer to the pointer to a data structure of the type specified by |
| 607 | TYPE is returned. If the signatures do not match, then DebugAssert() is called |
| 608 | with a description of "CR has a bad signature" and Record is returned. |
| 609 | |
| 610 | If the data type specified by TYPE does not contain the field specified by Field, |
| 611 | then the module will not compile. |
| 612 | |
| 613 | If TYPE does not contain a field called Signature, then the module will not |
| 614 | compile. |
| 615 | |
| 616 | @param Record The pointer to the field specified by Field within a data |
| 617 | structure of type TYPE. |
| 618 | |
| 619 | @param TYPE The name of the data structure type to return This |
| 620 | data structure must contain the field specified by Field. |
| 621 | |
| 622 | @param Field The name of the field in the data structure specified |
| 623 | by TYPE to which Record points. |
| 624 | |
| 625 | @param TestSignature The 32-bit signature value to match. |
| 626 | |
| 627 | **/ |
| 628 | #if !defined(MDEPKG_NDEBUG) |
| 629 | #define CR(Record, TYPE, Field, TestSignature) \ |
| 630 | (DebugAssertEnabled () && (BASE_CR (Record, TYPE, Field)->Signature != TestSignature)) ? \ |
| 631 | (TYPE *) (_ASSERT (CR has Bad Signature), Record) : \ |
| 632 | BASE_CR (Record, TYPE, Field) |
| 633 | #else |
| 634 | #define CR(Record, TYPE, Field, TestSignature) \ |
| 635 | BASE_CR (Record, TYPE, Field) |
| 636 | #endif |
| 637 | |
| 638 | #endif |