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