| 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 - 2019, 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 | #define _ASSERT(Expression) DebugAssert (__FILE__, __LINE__, #Expression)
|
|---|
| 293 |
|
|---|
| 294 |
|
|---|
| 295 | /**
|
|---|
| 296 | Internal worker macro that calls DebugPrint().
|
|---|
| 297 |
|
|---|
| 298 | This macro calls DebugPrint() passing in the debug error level, a format
|
|---|
| 299 | string, and a variable argument list.
|
|---|
| 300 | __VA_ARGS__ is not supported by EBC compiler, Microsoft Visual Studio .NET 2003
|
|---|
| 301 | and Microsoft Windows Server 2003 Driver Development Kit (Microsoft WINDDK) version 3790.1830.
|
|---|
| 302 |
|
|---|
| 303 | @param Expression Expression containing an error level, a format string,
|
|---|
| 304 | and a variable argument list based on the format string.
|
|---|
| 305 |
|
|---|
| 306 | **/
|
|---|
| 307 |
|
|---|
| 308 | #if !defined(MDE_CPU_EBC) && (!defined (_MSC_VER) || _MSC_VER > 1400)
|
|---|
| 309 | #define _DEBUG_PRINT(PrintLevel, ...) \
|
|---|
| 310 | do { \
|
|---|
| 311 | if (DebugPrintLevelEnabled (PrintLevel)) { \
|
|---|
| 312 | DebugPrint (PrintLevel, ##__VA_ARGS__); \
|
|---|
| 313 | } \
|
|---|
| 314 | } while (FALSE)
|
|---|
| 315 | #define _DEBUG(Expression) _DEBUG_PRINT Expression
|
|---|
| 316 | #else
|
|---|
| 317 | #define _DEBUG(Expression) DebugPrint Expression
|
|---|
| 318 | #endif
|
|---|
| 319 |
|
|---|
| 320 | /**
|
|---|
| 321 | Macro that calls DebugAssert() if an expression evaluates to FALSE.
|
|---|
| 322 |
|
|---|
| 323 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED
|
|---|
| 324 | bit of PcdDebugProperyMask is set, then this macro evaluates the Boolean
|
|---|
| 325 | expression specified by Expression. If Expression evaluates to FALSE, then
|
|---|
| 326 | DebugAssert() is called passing in the source filename, source line number,
|
|---|
| 327 | and Expression.
|
|---|
| 328 |
|
|---|
| 329 | @param Expression Boolean expression.
|
|---|
| 330 |
|
|---|
| 331 | **/
|
|---|
| 332 | #if !defined(MDEPKG_NDEBUG)
|
|---|
| 333 | #define ASSERT(Expression) \
|
|---|
| 334 | do { \
|
|---|
| 335 | if (DebugAssertEnabled ()) { \
|
|---|
| 336 | if (!(Expression)) { \
|
|---|
| 337 | _ASSERT (Expression); \
|
|---|
| 338 | ANALYZER_UNREACHABLE (); \
|
|---|
| 339 | } \
|
|---|
| 340 | } \
|
|---|
| 341 | } while (FALSE)
|
|---|
| 342 | #else
|
|---|
| 343 | #define ASSERT(Expression)
|
|---|
| 344 | #endif
|
|---|
| 345 |
|
|---|
| 346 | /**
|
|---|
| 347 | Macro that calls DebugPrint().
|
|---|
| 348 |
|
|---|
| 349 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED
|
|---|
| 350 | bit of PcdDebugProperyMask is set, then this macro passes Expression to
|
|---|
| 351 | DebugPrint().
|
|---|
| 352 |
|
|---|
| 353 | @param Expression Expression containing an error level, a format string,
|
|---|
| 354 | and a variable argument list based on the format string.
|
|---|
| 355 |
|
|---|
| 356 |
|
|---|
| 357 | **/
|
|---|
| 358 | #if !defined(MDEPKG_NDEBUG)
|
|---|
| 359 | #define DEBUG(Expression) \
|
|---|
| 360 | do { \
|
|---|
| 361 | if (DebugPrintEnabled ()) { \
|
|---|
| 362 | _DEBUG (Expression); \
|
|---|
| 363 | } \
|
|---|
| 364 | } while (FALSE)
|
|---|
| 365 | #else
|
|---|
| 366 | #define DEBUG(Expression)
|
|---|
| 367 | #endif
|
|---|
| 368 |
|
|---|
| 369 | /**
|
|---|
| 370 | Macro that calls DebugAssert() if an EFI_STATUS evaluates to an error code.
|
|---|
| 371 |
|
|---|
| 372 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED
|
|---|
| 373 | bit of PcdDebugProperyMask is set, then this macro evaluates the EFI_STATUS
|
|---|
| 374 | value specified by StatusParameter. If StatusParameter is an error code,
|
|---|
| 375 | then DebugAssert() is called passing in the source filename, source line
|
|---|
| 376 | number, and StatusParameter.
|
|---|
| 377 |
|
|---|
| 378 | @param StatusParameter EFI_STATUS value to evaluate.
|
|---|
| 379 |
|
|---|
| 380 | **/
|
|---|
| 381 | #if !defined(MDEPKG_NDEBUG)
|
|---|
| 382 | #define ASSERT_EFI_ERROR(StatusParameter) \
|
|---|
| 383 | do { \
|
|---|
| 384 | if (DebugAssertEnabled ()) { \
|
|---|
| 385 | if (EFI_ERROR (StatusParameter)) { \
|
|---|
| 386 | DEBUG ((EFI_D_ERROR, "\nASSERT_EFI_ERROR (Status = %r)\n", StatusParameter)); \
|
|---|
| 387 | _ASSERT (!EFI_ERROR (StatusParameter)); \
|
|---|
| 388 | } \
|
|---|
| 389 | } \
|
|---|
| 390 | } while (FALSE)
|
|---|
| 391 | #else
|
|---|
| 392 | #define ASSERT_EFI_ERROR(StatusParameter)
|
|---|
| 393 | #endif
|
|---|
| 394 |
|
|---|
| 395 | /**
|
|---|
| 396 | Macro that calls DebugAssert() if a RETURN_STATUS evaluates to an error code.
|
|---|
| 397 |
|
|---|
| 398 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED
|
|---|
| 399 | bit of PcdDebugProperyMask is set, then this macro evaluates the
|
|---|
| 400 | RETURN_STATUS value specified by StatusParameter. If StatusParameter is an
|
|---|
| 401 | error code, then DebugAssert() is called passing in the source filename,
|
|---|
| 402 | source line number, and StatusParameter.
|
|---|
| 403 |
|
|---|
| 404 | @param StatusParameter RETURN_STATUS value to evaluate.
|
|---|
| 405 |
|
|---|
| 406 | **/
|
|---|
| 407 | #if !defined(MDEPKG_NDEBUG)
|
|---|
| 408 | #define ASSERT_RETURN_ERROR(StatusParameter) \
|
|---|
| 409 | do { \
|
|---|
| 410 | if (DebugAssertEnabled ()) { \
|
|---|
| 411 | if (RETURN_ERROR (StatusParameter)) { \
|
|---|
| 412 | DEBUG ((DEBUG_ERROR, "\nASSERT_RETURN_ERROR (Status = %r)\n", \
|
|---|
| 413 | StatusParameter)); \
|
|---|
| 414 | _ASSERT (!RETURN_ERROR (StatusParameter)); \
|
|---|
| 415 | } \
|
|---|
| 416 | } \
|
|---|
| 417 | } while (FALSE)
|
|---|
| 418 | #else
|
|---|
| 419 | #define ASSERT_RETURN_ERROR(StatusParameter)
|
|---|
| 420 | #endif
|
|---|
| 421 |
|
|---|
| 422 | /**
|
|---|
| 423 | Macro that calls DebugAssert() if a protocol is already installed in the
|
|---|
| 424 | handle database.
|
|---|
| 425 |
|
|---|
| 426 | If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit
|
|---|
| 427 | of PcdDebugProperyMask is clear, then return.
|
|---|
| 428 |
|
|---|
| 429 | If Handle is NULL, then a check is made to see if the protocol specified by Guid
|
|---|
| 430 | is present on any handle in the handle database. If Handle is not NULL, then
|
|---|
| 431 | a check is made to see if the protocol specified by Guid is present on the
|
|---|
| 432 | handle specified by Handle. If the check finds the protocol, then DebugAssert()
|
|---|
| 433 | is called passing in the source filename, source line number, and Guid.
|
|---|
| 434 |
|
|---|
| 435 | If Guid is NULL, then ASSERT().
|
|---|
| 436 |
|
|---|
| 437 | @param Handle The handle to check for the protocol. This is an optional
|
|---|
| 438 | parameter that may be NULL. If it is NULL, then the entire
|
|---|
| 439 | handle database is searched.
|
|---|
| 440 |
|
|---|
| 441 | @param Guid The pointer to a protocol GUID.
|
|---|
| 442 |
|
|---|
| 443 | **/
|
|---|
| 444 | #if !defined(MDEPKG_NDEBUG)
|
|---|
| 445 | #define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid) \
|
|---|
| 446 | do { \
|
|---|
| 447 | if (DebugAssertEnabled ()) { \
|
|---|
| 448 | VOID *Instance; \
|
|---|
| 449 | ASSERT (Guid != NULL); \
|
|---|
| 450 | if (Handle == NULL) { \
|
|---|
| 451 | if (!EFI_ERROR (gBS->LocateProtocol ((EFI_GUID *)Guid, NULL, &Instance))) { \
|
|---|
| 452 | _ASSERT (Guid already installed in database); \
|
|---|
| 453 | } \
|
|---|
| 454 | } else { \
|
|---|
| 455 | if (!EFI_ERROR (gBS->HandleProtocol (Handle, (EFI_GUID *)Guid, &Instance))) { \
|
|---|
| 456 | _ASSERT (Guid already installed on Handle); \
|
|---|
| 457 | } \
|
|---|
| 458 | } \
|
|---|
| 459 | } \
|
|---|
| 460 | } while (FALSE)
|
|---|
| 461 | #else
|
|---|
| 462 | #define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid)
|
|---|
| 463 | #endif
|
|---|
| 464 |
|
|---|
| 465 | /**
|
|---|
| 466 | Macro that marks the beginning of debug source code.
|
|---|
| 467 |
|
|---|
| 468 | If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set,
|
|---|
| 469 | then this macro marks the beginning of source code that is included in a module.
|
|---|
| 470 | Otherwise, the source lines between DEBUG_CODE_BEGIN() and DEBUG_CODE_END()
|
|---|
| 471 | are not included in a module.
|
|---|
| 472 |
|
|---|
| 473 | **/
|
|---|
| 474 | #define DEBUG_CODE_BEGIN() do { if (DebugCodeEnabled ()) { UINT8 __DebugCodeLocal
|
|---|
| 475 |
|
|---|
| 476 |
|
|---|
| 477 | /**
|
|---|
| 478 | The 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 | The macro that declares a section of debug source code.
|
|---|
| 491 |
|
|---|
| 492 | If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set,
|
|---|
| 493 | then the source code specified by Expression is included in a module.
|
|---|
| 494 | Otherwise, the source specified by Expression is not included in a module.
|
|---|
| 495 |
|
|---|
| 496 | **/
|
|---|
| 497 | #define DEBUG_CODE(Expression) \
|
|---|
| 498 | DEBUG_CODE_BEGIN (); \
|
|---|
| 499 | Expression \
|
|---|
| 500 | DEBUG_CODE_END ()
|
|---|
| 501 |
|
|---|
| 502 |
|
|---|
| 503 | /**
|
|---|
| 504 | The macro that calls DebugClearMemory() to clear a buffer to a default value.
|
|---|
| 505 |
|
|---|
| 506 | If the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set,
|
|---|
| 507 | then this macro calls DebugClearMemory() passing in Address and Length.
|
|---|
| 508 |
|
|---|
| 509 | @param Address The pointer to a buffer.
|
|---|
| 510 | @param Length The number of bytes in the buffer to set.
|
|---|
| 511 |
|
|---|
| 512 | **/
|
|---|
| 513 | #define DEBUG_CLEAR_MEMORY(Address, Length) \
|
|---|
| 514 | do { \
|
|---|
| 515 | if (DebugClearMemoryEnabled ()) { \
|
|---|
| 516 | DebugClearMemory (Address, Length); \
|
|---|
| 517 | } \
|
|---|
| 518 | } while (FALSE)
|
|---|
| 519 |
|
|---|
| 520 |
|
|---|
| 521 | /**
|
|---|
| 522 | Macro that calls DebugAssert() if the containing record does not have a
|
|---|
| 523 | matching signature. If the signatures matches, then a pointer to the data
|
|---|
| 524 | structure that contains a specified field of that data structure is returned.
|
|---|
| 525 | This is a lightweight method hide information by placing a public data
|
|---|
| 526 | structure inside a larger private data structure and using a pointer to the
|
|---|
| 527 | public data structure to retrieve a pointer to the private data structure.
|
|---|
| 528 |
|
|---|
| 529 | If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit
|
|---|
| 530 | of PcdDebugProperyMask is clear, then this macro computes the offset, in bytes,
|
|---|
| 531 | of the field specified by Field from the beginning of the data structure specified
|
|---|
| 532 | by TYPE. This offset is subtracted from Record, and is used to return a pointer
|
|---|
| 533 | to a data structure of the type specified by TYPE.
|
|---|
| 534 |
|
|---|
| 535 | If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit
|
|---|
| 536 | of PcdDebugProperyMask is set, then this macro computes the offset, in bytes,
|
|---|
| 537 | of field specified by Field from the beginning of the data structure specified
|
|---|
| 538 | by TYPE. This offset is subtracted from Record, and is used to compute a pointer
|
|---|
| 539 | to a data structure of the type specified by TYPE. The Signature field of the
|
|---|
| 540 | data structure specified by TYPE is compared to TestSignature. If the signatures
|
|---|
| 541 | match, then a pointer to the pointer to a data structure of the type specified by
|
|---|
| 542 | TYPE is returned. If the signatures do not match, then DebugAssert() is called
|
|---|
| 543 | with a description of "CR has a bad signature" and Record is returned.
|
|---|
| 544 |
|
|---|
| 545 | If the data type specified by TYPE does not contain the field specified by Field,
|
|---|
| 546 | then the module will not compile.
|
|---|
| 547 |
|
|---|
| 548 | If TYPE does not contain a field called Signature, then the module will not
|
|---|
| 549 | compile.
|
|---|
| 550 |
|
|---|
| 551 | @param Record The pointer to the field specified by Field within a data
|
|---|
| 552 | structure of type TYPE.
|
|---|
| 553 |
|
|---|
| 554 | @param TYPE The name of the data structure type to return This
|
|---|
| 555 | data structure must contain the field specified by Field.
|
|---|
| 556 |
|
|---|
| 557 | @param Field The name of the field in the data structure specified
|
|---|
| 558 | by TYPE to which Record points.
|
|---|
| 559 |
|
|---|
| 560 | @param TestSignature The 32-bit signature value to match.
|
|---|
| 561 |
|
|---|
| 562 | **/
|
|---|
| 563 | #if !defined(MDEPKG_NDEBUG)
|
|---|
| 564 | #define CR(Record, TYPE, Field, TestSignature) \
|
|---|
| 565 | (DebugAssertEnabled () && (BASE_CR (Record, TYPE, Field)->Signature != TestSignature)) ? \
|
|---|
| 566 | (TYPE *) (_ASSERT (CR has Bad Signature), Record) : \
|
|---|
| 567 | BASE_CR (Record, TYPE, Field)
|
|---|
| 568 | #else
|
|---|
| 569 | #define CR(Record, TYPE, Field, TestSignature) \
|
|---|
| 570 | BASE_CR (Record, TYPE, Field)
|
|---|
| 571 | #endif
|
|---|
| 572 |
|
|---|
| 573 | #if defined(VBOX)
|
|---|
| 574 | VOID EFIAPI VBoxLogWorker(const char *pszFormat, ...);
|
|---|
| 575 |
|
|---|
| 576 | /** See RT_XSTR */
|
|---|
| 577 | # define VBOX_XSTR(str) VBOX_STR(str)
|
|---|
| 578 | /** See RT_STR */
|
|---|
| 579 | # define VBOX_STR(str) #str
|
|---|
| 580 | # if defined(EFI_LOG_ENABLED)
|
|---|
| 581 | # define VBoxLogFlowFuncEnter() DEBUG((DEBUG_INFO, "%a:" VBOX_XSTR(__LINE__) ": ENTER\n", __FUNCTION__))
|
|---|
| 582 | # define VBoxLogFlowFuncLeave() DEBUG((DEBUG_INFO, "%a:" VBOX_XSTR(__LINE__) ": LEAVE\n", __FUNCTION__))
|
|---|
| 583 | # define VBoxLogFlowFuncMark() DEBUG((DEBUG_INFO, "%a:" VBOX_XSTR(__LINE__) "\n", __FUNCTION__))
|
|---|
| 584 | # define VBoxLogFlowFuncLeaveRC(rc) \
|
|---|
| 585 | do { \
|
|---|
| 586 | EFI_STATUS rcLog = (rc); \
|
|---|
| 587 | VBoxLog(("%a:" VBOX_XSTR(__LINE__) ": LEAVE " #rc "=0x%x (%r)\n", __FUNCTION__, rcLog, rcLog)); \
|
|---|
| 588 | } while (0)
|
|---|
| 589 | # define VBoxLogFlowFuncMarkVar(var, varfmt) \
|
|---|
| 590 | DEBUG((DEBUG_INFO, "%a:" VBOX_XSTR(__LINE__) ": " #var "=" varfmt "\n", __FUNCTION__, (var)))
|
|---|
| 591 | # define VBoxLogFlowFuncMarkRC(rc) \
|
|---|
| 592 | do { \
|
|---|
| 593 | EFI_STATUS rcLog = (rc); \
|
|---|
| 594 | VBoxLog(("%a:" VBOX_XSTR(__LINE__) ": " #rc "=0x%x (%r)\n", __FUNCTION__, rcLog, rcLog)); \
|
|---|
| 595 | } while (0)
|
|---|
| 596 | # define VBoxLog(a) VBoxLogWorker a
|
|---|
| 597 | # else /* !EFI_LOG_ENABLED */
|
|---|
| 598 | # define VBoxLogFlowFuncEnter() do {} while (0)
|
|---|
| 599 | # define VBoxLogFlowFuncLeave() do {} while (0)
|
|---|
| 600 | # define VBoxLogFlowFuncLeaveRC(rc) do {} while (0)
|
|---|
| 601 | # define VBoxLogFlowFuncMark() do {} while (0)
|
|---|
| 602 | # define VBoxLogFlowFuncMarkVar(var, varfmt) do {} while (0)
|
|---|
| 603 | # define VBoxLogFlowFuncMarkRC(rc) do {} while (0)
|
|---|
| 604 | # define VBoxLog(a) do {} while (0)
|
|---|
| 605 | # endif /* !EFI_LOG_ENABLED */
|
|---|
| 606 | #endif /* VBOX */
|
|---|
| 607 | #endif
|
|---|
