TianoCore EDK2 master
Loading...
Searching...
No Matches
DebugLib.h
Go to the documentation of this file.
1
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_MANAGEABILITY 0x00800000 // Detailed debug and payload message of manageability
52 // related modules, such Redfish, IPMI, MCTP and etc.
53#define DEBUG_ERROR 0x80000000 // Error
54
55//
56// Aliases of debug message mask bits
57//
58#define EFI_D_INIT DEBUG_INIT
59#define EFI_D_WARN DEBUG_WARN
60#define EFI_D_LOAD DEBUG_LOAD
61#define EFI_D_FS DEBUG_FS
62#define EFI_D_POOL DEBUG_POOL
63#define EFI_D_PAGE DEBUG_PAGE
64#define EFI_D_INFO DEBUG_INFO
65#define EFI_D_DISPATCH DEBUG_DISPATCH
66#define EFI_D_VARIABLE DEBUG_VARIABLE
67#define EFI_D_BM DEBUG_BM
68#define EFI_D_BLKIO DEBUG_BLKIO
69#define EFI_D_NET DEBUG_NET
70#define EFI_D_UNDI DEBUG_UNDI
71#define EFI_D_LOADFILE DEBUG_LOADFILE
72#define EFI_D_EVENT DEBUG_EVENT
73#define EFI_D_VERBOSE DEBUG_VERBOSE
74#define EFI_D_ERROR DEBUG_ERROR
75
76//
77// Source file line number.
78// Default is use the to compiler provided __LINE__ macro value. The __LINE__
79// mapping can be overriden by predefining DEBUG_LINE_NUMBER
80//
81// Defining DEBUG_LINE_NUMBER to a fixed value is useful when comparing builds
82// across source code formatting changes that may add/remove lines in a source
83// file.
84//
85#ifdef DEBUG_LINE_NUMBER
86#else
87#define DEBUG_LINE_NUMBER __LINE__
88#endif
89
105#ifdef DEBUG_EXPRESSION_STRING_VALUE
106#define DEBUG_EXPRESSION_STRING(Expression) DEBUG_EXPRESSION_STRING_VALUE
107#else
108#define DEBUG_EXPRESSION_STRING(Expression) #Expression
109#endif
110
126VOID
127EFIAPI
128DebugPrint (
129 IN UINTN ErrorLevel,
130 IN CONST CHAR8 *Format,
131 ...
132 );
133
149VOID
150EFIAPI
151DebugVPrint (
152 IN UINTN ErrorLevel,
153 IN CONST CHAR8 *Format,
154 IN VA_LIST VaListMarker
155 );
156
174VOID
175EFIAPI
176DebugBPrint (
177 IN UINTN ErrorLevel,
178 IN CONST CHAR8 *Format,
179 IN BASE_LIST BaseListMarker
180 );
181
203VOID
204EFIAPI
205DebugAssert (
206 IN CONST CHAR8 *FileName,
207 IN UINTN LineNumber,
208 IN CONST CHAR8 *Description
209 );
210
226VOID *
227EFIAPI
228DebugClearMemory (
229 OUT VOID *Buffer,
230 IN UINTN Length
231 );
232
243BOOLEAN
244EFIAPI
245DebugAssertEnabled (
246 VOID
247 );
248
259BOOLEAN
260EFIAPI
261DebugPrintEnabled (
262 VOID
263 );
264
275BOOLEAN
276EFIAPI
277DebugCodeEnabled (
278 VOID
279 );
280
291BOOLEAN
292EFIAPI
293DebugClearMemoryEnabled (
294 VOID
295 );
296
306BOOLEAN
307EFIAPI
308DebugPrintLevelEnabled (
309 IN CONST UINTN ErrorLevel
310 );
311
321#if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED)
322
334VOID
335EFIAPI
336UnitTestDebugAssert (
337 IN CONST CHAR8 *FileName,
338 IN UINTN LineNumber,
339 IN CONST CHAR8 *Description
340 );
341
342 #if defined (_ASSERT)
343 #undef _ASSERT
344 #endif
345 #if defined (__clang__) && defined (__FILE_NAME__)
346#define _ASSERT(Expression) UnitTestDebugAssert (__FILE_NAME__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
347 #else
348#define _ASSERT(Expression) UnitTestDebugAssert (__FILE__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
349 #endif
350#else
351 #if defined (__clang__) && defined (__FILE_NAME__)
352#define _ASSERT(Expression) DebugAssert (__FILE_NAME__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
353 #else
354#define _ASSERT(Expression) DebugAssert (__FILE__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
355 #endif
356#endif
357
371#if !defined (MDE_CPU_EBC) && (!defined (_MSC_VER) || _MSC_VER > 1400)
372#define _DEBUG_PRINT(PrintLevel, ...) \
373 do { \
374 if (DebugPrintLevelEnabled (PrintLevel)) { \
375 DebugPrint (PrintLevel, ##__VA_ARGS__); \
376 } \
377 } while (FALSE)
378#define _DEBUG(Expression) _DEBUG_PRINT Expression
379#else
380#define _DEBUG(Expression) DebugPrint Expression
381#endif
382
395#if !defined (MDEPKG_NDEBUG)
396#define ASSERT(Expression) \
397 do { \
398 if (DebugAssertEnabled ()) { \
399 if (!(Expression)) { \
400 _ASSERT (Expression); \
401 ANALYZER_UNREACHABLE (); \
402 } \
403 } \
404 } while (FALSE)
405#else
406#define ASSERT(Expression)
407#endif
408
421#if !defined (MDEPKG_NDEBUG)
422#define DEBUG(Expression) \
423 do { \
424 if (DebugPrintEnabled ()) { \
425 _DEBUG (Expression); \
426 } \
427 } while (FALSE)
428#else
429#define DEBUG(Expression)
430#endif
431
444#if !defined (MDEPKG_NDEBUG)
445#define ASSERT_EFI_ERROR(StatusParameter) \
446 do { \
447 if (DebugAssertEnabled ()) { \
448 if (EFI_ERROR (StatusParameter)) { \
449 DEBUG ((DEBUG_ERROR, "\nASSERT_EFI_ERROR (Status = %r)\n", StatusParameter)); \
450 _ASSERT (!EFI_ERROR (StatusParameter)); \
451 } \
452 } \
453 } while (FALSE)
454#else
455#define ASSERT_EFI_ERROR(StatusParameter)
456#endif
457
470#if !defined (MDEPKG_NDEBUG)
471#define ASSERT_RETURN_ERROR(StatusParameter) \
472 do { \
473 if (DebugAssertEnabled ()) { \
474 if (RETURN_ERROR (StatusParameter)) { \
475 DEBUG ((DEBUG_ERROR, "\nASSERT_RETURN_ERROR (Status = %r)\n", \
476 StatusParameter)); \
477 _ASSERT (!RETURN_ERROR (StatusParameter)); \
478 } \
479 } \
480 } while (FALSE)
481#else
482#define ASSERT_RETURN_ERROR(StatusParameter)
483#endif
484
507#if !defined (MDEPKG_NDEBUG)
508#define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid) \
509 do { \
510 if (DebugAssertEnabled ()) { \
511 VOID *Instance; \
512 ASSERT (Guid != NULL); \
513 if (Handle == NULL) { \
514 if (!EFI_ERROR (gBS->LocateProtocol ((EFI_GUID *)Guid, NULL, &Instance))) { \
515 _ASSERT (Guid already installed in database); \
516 } \
517 } else { \
518 if (!EFI_ERROR (gBS->HandleProtocol (Handle, (EFI_GUID *)Guid, &Instance))) { \
519 _ASSERT (Guid already installed on Handle); \
520 } \
521 } \
522 } \
523 } while (FALSE)
524#else
525#define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid)
526#endif
527
537#define DEBUG_CODE_BEGIN() do { if (DebugCodeEnabled ()) { UINT8 __DebugCodeLocal
538
548#define DEBUG_CODE_END() __DebugCodeLocal = 0; __DebugCodeLocal++; } } while (FALSE)
549
558#define DEBUG_CODE(Expression) \
559 DEBUG_CODE_BEGIN (); \
560 Expression \
561 DEBUG_CODE_END ()
562
573#define DEBUG_CLEAR_MEMORY(Address, Length) \
574 do { \
575 if (DebugClearMemoryEnabled ()) { \
576 DebugClearMemory (Address, Length); \
577 } \
578 } while (FALSE)
579
622#if !defined (MDEPKG_NDEBUG)
623#define CR(Record, TYPE, Field, TestSignature) \
624 (DebugAssertEnabled () && (BASE_CR (Record, TYPE, Field)->Signature != TestSignature)) ? \
625 (TYPE *) (_ASSERT (CR has Bad Signature), Record) : \
626 BASE_CR (Record, TYPE, Field)
627#else
628#define CR(Record, TYPE, Field, TestSignature) \
629 BASE_CR (Record, TYPE, Field)
630#endif
631
632#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:416
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