TianoCore EDK2 master
Loading...
Searching...
No Matches
DebugLib.h
Go to the documentation of this file.
1
23#ifndef __DEBUG_LIB_H__
24#define __DEBUG_LIB_H__
25
26//
27// Declare bits for PcdDebugPropertyMask
28//
29#define DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED 0x01
30#define DEBUG_PROPERTY_DEBUG_PRINT_ENABLED 0x02
31#define DEBUG_PROPERTY_DEBUG_CODE_ENABLED 0x04
32#define DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED 0x08
33#define DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED 0x10
34#define DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED 0x20
35
36//
37// Declare bits for PcdDebugPrintErrorLevel and the ErrorLevel parameter of DebugPrint()
38//
39#define DEBUG_INIT 0x00000001 // Initialization
40#define DEBUG_WARN 0x00000002 // Warnings
41#define DEBUG_LOAD 0x00000004 // Load events
42#define DEBUG_FS 0x00000008 // EFI File system
43#define DEBUG_POOL 0x00000010 // Alloc & Free (pool)
44#define DEBUG_PAGE 0x00000020 // Alloc & Free (page)
45#define DEBUG_INFO 0x00000040 // Informational debug messages
46#define DEBUG_DISPATCH 0x00000080 // PEI/DXE/SMM Dispatchers
47#define DEBUG_VARIABLE 0x00000100 // Variable
48#define DEBUG_BM 0x00000400 // Boot Manager
49#define DEBUG_BLKIO 0x00001000 // BlkIo Driver
50#define DEBUG_NET 0x00004000 // Network Io Driver
51#define DEBUG_UNDI 0x00010000 // UNDI Driver
52#define DEBUG_LOADFILE 0x00020000 // LoadFile
53#define DEBUG_EVENT 0x00080000 // Event messages
54#define DEBUG_GCD 0x00100000 // Global Coherency Database changes
55#define DEBUG_CACHE 0x00200000 // Memory range cachability changes
56#define DEBUG_VERBOSE 0x00400000 // Detailed debug messages that may
57 // significantly impact boot performance
58#define DEBUG_MANAGEABILITY 0x00800000 // Detailed debug and payload manageability messages
59 // related to modules such as Redfish, IPMI, MCTP etc.
60#define DEBUG_ERROR 0x80000000 // Error
61
62//
63// Aliases of debug message mask bits
64//
65#define EFI_D_INIT DEBUG_INIT
66#define EFI_D_WARN DEBUG_WARN
67#define EFI_D_LOAD DEBUG_LOAD
68#define EFI_D_FS DEBUG_FS
69#define EFI_D_POOL DEBUG_POOL
70#define EFI_D_PAGE DEBUG_PAGE
71#define EFI_D_INFO DEBUG_INFO
72#define EFI_D_DISPATCH DEBUG_DISPATCH
73#define EFI_D_VARIABLE DEBUG_VARIABLE
74#define EFI_D_BM DEBUG_BM
75#define EFI_D_BLKIO DEBUG_BLKIO
76#define EFI_D_NET DEBUG_NET
77#define EFI_D_UNDI DEBUG_UNDI
78#define EFI_D_LOADFILE DEBUG_LOADFILE
79#define EFI_D_EVENT DEBUG_EVENT
80#define EFI_D_VERBOSE DEBUG_VERBOSE
81#define EFI_D_ERROR DEBUG_ERROR
82
83//
84// Source file line number.
85// Default is use the to compiler provided __LINE__ macro value. The __LINE__
86// mapping can be overriden by predefining DEBUG_LINE_NUMBER
87//
88// Defining DEBUG_LINE_NUMBER to a fixed value is useful when comparing builds
89// across source code formatting changes that may add/remove lines in a source
90// file.
91//
92#ifdef DEBUG_LINE_NUMBER
93#else
94#define DEBUG_LINE_NUMBER __LINE__
95#endif
96
112#ifdef DEBUG_EXPRESSION_STRING_VALUE
113#define DEBUG_EXPRESSION_STRING(Expression) DEBUG_EXPRESSION_STRING_VALUE
114#else
115#define DEBUG_EXPRESSION_STRING(Expression) #Expression
116#endif
117
133VOID
134EFIAPI
135DebugPrint (
136 IN UINTN ErrorLevel,
137 IN CONST CHAR8 *Format,
138 ...
139 );
140
156VOID
157EFIAPI
158DebugVPrint (
159 IN UINTN ErrorLevel,
160 IN CONST CHAR8 *Format,
161 IN VA_LIST VaListMarker
162 );
163
181VOID
182EFIAPI
183DebugBPrint (
184 IN UINTN ErrorLevel,
185 IN CONST CHAR8 *Format,
186 IN BASE_LIST BaseListMarker
187 );
188
210VOID
211EFIAPI
212DebugAssert (
213 IN CONST CHAR8 *FileName,
214 IN UINTN LineNumber,
215 IN CONST CHAR8 *Description
216 );
217
233VOID *
234EFIAPI
235DebugClearMemory (
236 OUT VOID *Buffer,
237 IN UINTN Length
238 );
239
250BOOLEAN
251EFIAPI
252DebugAssertEnabled (
253 VOID
254 );
255
266BOOLEAN
267EFIAPI
268DebugPrintEnabled (
269 VOID
270 );
271
282BOOLEAN
283EFIAPI
284DebugCodeEnabled (
285 VOID
286 );
287
298BOOLEAN
299EFIAPI
300DebugClearMemoryEnabled (
301 VOID
302 );
303
313BOOLEAN
314EFIAPI
315DebugPrintLevelEnabled (
316 IN CONST UINTN ErrorLevel
317 );
318
328#if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED)
329
341VOID
342EFIAPI
343UnitTestDebugAssert (
344 IN CONST CHAR8 *FileName,
345 IN UINTN LineNumber,
346 IN CONST CHAR8 *Description
347 );
348
349 #if defined (_ASSERT)
350 #undef _ASSERT
351 #endif
352 #if defined (__FILE_NAME__)
353#define _ASSERT(Expression) UnitTestDebugAssert (__FILE_NAME__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
354 #else
355#define _ASSERT(Expression) UnitTestDebugAssert (__FILE__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
356 #endif
357#else
358 #if defined (__FILE_NAME__)
359#define _ASSERT(Expression) DebugAssert (__FILE_NAME__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
360 #else
361#define _ASSERT(Expression) DebugAssert (__FILE__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
362 #endif
363#endif
364
378#if !defined (MDE_CPU_EBC) && (!defined (_MSC_VER) || _MSC_VER > 1400)
379#define _DEBUG_PRINT(PrintLevel, ...) \
380 do { \
381 if (DebugPrintLevelEnabled (PrintLevel)) { \
382 DebugPrint (PrintLevel, ##__VA_ARGS__); \
383 } \
384 } while (FALSE)
385#define _DEBUGLIB_DEBUG(Expression) _DEBUG_PRINT Expression
386#else
387#define _DEBUGLIB_DEBUG(Expression) DebugPrint Expression
388#endif
389
402#if !defined (MDEPKG_NDEBUG)
403#define ASSERT(Expression) \
404 do { \
405 if (DebugAssertEnabled ()) { \
406 if (!(Expression)) { \
407 _ASSERT (Expression); \
408 ANALYZER_UNREACHABLE (); \
409 } \
410 } \
411 } while (FALSE)
412#else
413#define ASSERT(Expression) \
414 do { \
415 if (FALSE) { \
416 (VOID) (Expression); \
417 } \
418 } while (FALSE)
419#endif
420
433#if !defined (MDEPKG_NDEBUG)
434#define DEBUG(Expression) \
435 do { \
436 if (DebugPrintEnabled ()) { \
437 _DEBUGLIB_DEBUG (Expression); \
438 } \
439 } while (FALSE)
440#else
441#define DEBUG(Expression) \
442 do { \
443 if (FALSE) { \
444 _DEBUGLIB_DEBUG (Expression); \
445 } \
446 } while (FALSE)
447#endif
448
461#if !defined (MDEPKG_NDEBUG)
462#define ASSERT_EFI_ERROR(StatusParameter) \
463 do { \
464 if (DebugAssertEnabled ()) { \
465 if (EFI_ERROR (StatusParameter)) { \
466 DEBUG ((DEBUG_ERROR, "\nASSERT_EFI_ERROR (Status = %r)\n", StatusParameter)); \
467 _ASSERT (!EFI_ERROR (StatusParameter)); \
468 } \
469 } \
470 } while (FALSE)
471#else
472#define ASSERT_EFI_ERROR(StatusParameter) \
473 do { \
474 if (FALSE) { \
475 (VOID) (StatusParameter); \
476 } \
477 } while (FALSE)
478#endif
479
492#if !defined (MDEPKG_NDEBUG)
493#define ASSERT_RETURN_ERROR(StatusParameter) \
494 do { \
495 if (DebugAssertEnabled ()) { \
496 if (RETURN_ERROR (StatusParameter)) { \
497 DEBUG ((DEBUG_ERROR, "\nASSERT_RETURN_ERROR (Status = %r)\n", \
498 StatusParameter)); \
499 _ASSERT (!RETURN_ERROR (StatusParameter)); \
500 } \
501 } \
502 } while (FALSE)
503#else
504#define ASSERT_RETURN_ERROR(StatusParameter) \
505 do { \
506 if (FALSE) { \
507 (VOID) (StatusParameter); \
508 } \
509 } while (FALSE)
510#endif
511
534#if !defined (MDEPKG_NDEBUG)
535#define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid) \
536 do { \
537 if (DebugAssertEnabled ()) { \
538 VOID *Instance; \
539 ASSERT (Guid != NULL); \
540 if (Handle == NULL) { \
541 if (!EFI_ERROR (gBS->LocateProtocol ((EFI_GUID *)Guid, NULL, &Instance))) { \
542 _ASSERT (Guid already installed in database); \
543 } \
544 } else { \
545 if (!EFI_ERROR (gBS->HandleProtocol (Handle, (EFI_GUID *)Guid, &Instance))) { \
546 _ASSERT (Guid already installed on Handle); \
547 } \
548 } \
549 } \
550 } while (FALSE)
551#else
552#define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid)
553#endif
554
564#define DEBUG_CODE_BEGIN() \
565 do { \
566 if (DebugCodeEnabled ()) { \
567 do { } while (FALSE)
568
578#define DEBUG_CODE_END() \
579 } \
580 } while (FALSE)
581
590#define DEBUG_CODE(Expression) \
591 DEBUG_CODE_BEGIN (); \
592 Expression \
593 DEBUG_CODE_END ()
594
605#define DEBUG_CLEAR_MEMORY(Address, Length) \
606 do { \
607 if (DebugClearMemoryEnabled ()) { \
608 DebugClearMemory (Address, Length); \
609 } \
610 } while (FALSE)
611
658#if !defined (MDEPKG_NDEBUG)
659#define CR(Record, TYPE, Field, TestSignature) \
660 (DebugAssertEnabled () && (BASE_CR (Record, TYPE, Field)->Signature != TestSignature)) ? \
661 (TYPE *) (_ASSERT (CR has Bad Signature), Record) : \
662 (BASE_CR (Record, TYPE, Field)->Signature != TestSignature) ? \
663 NULL : \
664 BASE_CR (Record, TYPE, Field)
665#else
666#define CR(Record, TYPE, Field, TestSignature) \
667 (BASE_CR (Record, TYPE, Field)->Signature != TestSignature) ? \
668 NULL : \
669 BASE_CR (Record, TYPE, Field)
670#endif
671
672#endif
UINTN
UINT64 UINTN
Definition: ProcessorBind.h:112
CONST
#define CONST
Definition: Base.h:259
VA_LIST
CHAR8 * VA_LIST
Definition: Base.h:643
IN
#define IN
Definition: Base.h:279
BASE_LIST
UINTN * BASE_LIST
Definition: Base.h:711
OUT
#define OUT
Definition: Base.h:284
DebugAssert
VOID EFIAPI DebugAssert(IN CONST CHAR8 *FileName, IN UINTN LineNumber, IN CONST CHAR8 *Description)
Definition: DebugLib.c:188
DebugVPrint
VOID EFIAPI DebugVPrint(IN UINTN ErrorLevel, IN CONST CHAR8 *Format, IN VA_LIST VaListMarker)
Definition: DebugLib.c:126
DebugPrintLevelEnabled
BOOLEAN EFIAPI DebugPrintLevelEnabled(IN CONST UINTN ErrorLevel)
Definition: DebugLib.c:350
DebugBPrint
VOID EFIAPI DebugBPrint(IN UINTN ErrorLevel, IN CONST CHAR8 *Format, IN BASE_LIST BaseListMarker)
Definition: DebugLib.c:154
DebugClearMemory
VOID *EFIAPI DebugClearMemory(OUT VOID *Buffer, IN UINTN Length)
Definition: DebugLib.c:232
DebugPrint
VOID EFIAPI DebugPrint(IN UINTN ErrorLevel, IN CONST CHAR8 *Format,...)
Definition: DebugLib.c:45
DebugCodeEnabled
BOOLEAN EFIAPI DebugCodeEnabled(VOID)
Definition: DebugLib.c:301
DebugClearMemoryEnabled
BOOLEAN EFIAPI DebugClearMemoryEnabled(VOID)
Definition: DebugLib.c:321
DebugPrintEnabled
BOOLEAN EFIAPI DebugPrintEnabled(VOID)
Definition: DebugLib.c:281
DebugAssertEnabled
BOOLEAN EFIAPI DebugAssertEnabled(VOID)
Definition: DebugLib.c:261
UnitTestDebugAssert
VOID EFIAPI UnitTestDebugAssert(IN CONST CHAR8 *FileName, IN UINTN LineNumber, IN CONST CHAR8 *Description)
Definition: UnitTestDebugAssertLib.c:32