TianoCore EDK2 master
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_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
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
124VOID
125EFIAPI
126DebugPrint (
127 IN UINTN ErrorLevel,
128 IN CONST CHAR8 *Format,
129 ...
130 );
131
147VOID
148EFIAPI
149DebugVPrint (
150 IN UINTN ErrorLevel,
151 IN CONST CHAR8 *Format,
152 IN VA_LIST VaListMarker
153 );
154
172VOID
173EFIAPI
174DebugBPrint (
175 IN UINTN ErrorLevel,
176 IN CONST CHAR8 *Format,
177 IN BASE_LIST BaseListMarker
178 );
179
201VOID
202EFIAPI
203DebugAssert (
204 IN CONST CHAR8 *FileName,
205 IN UINTN LineNumber,
206 IN CONST CHAR8 *Description
207 );
208
224VOID *
225EFIAPI
226DebugClearMemory (
227 OUT VOID *Buffer,
228 IN UINTN Length
229 );
230
241BOOLEAN
242EFIAPI
243DebugAssertEnabled (
244 VOID
245 );
246
257BOOLEAN
258EFIAPI
259DebugPrintEnabled (
260 VOID
261 );
262
273BOOLEAN
274EFIAPI
275DebugCodeEnabled (
276 VOID
277 );
278
289BOOLEAN
290EFIAPI
291DebugClearMemoryEnabled (
292 VOID
293 );
294
304BOOLEAN
305EFIAPI
306DebugPrintLevelEnabled (
307 IN CONST UINTN ErrorLevel
308 );
309
319#if defined (EDKII_UNIT_TEST_FRAMEWORK_ENABLED)
320
332VOID
333EFIAPI
334UnitTestDebugAssert (
335 IN CONST CHAR8 *FileName,
336 IN UINTN LineNumber,
337 IN CONST CHAR8 *Description
338 );
339
340 #if defined (__clang__) && defined (__FILE_NAME__)
341#define _ASSERT(Expression) UnitTestDebugAssert (__FILE_NAME__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
342 #else
343#define _ASSERT(Expression) UnitTestDebugAssert (__FILE__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
344 #endif
345#else
346 #if defined (__clang__) && defined (__FILE_NAME__)
347#define _ASSERT(Expression) DebugAssert (__FILE_NAME__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
348 #else
349#define _ASSERT(Expression) DebugAssert (__FILE__, DEBUG_LINE_NUMBER, DEBUG_EXPRESSION_STRING (Expression))
350 #endif
351#endif
352
366#if !defined (MDE_CPU_EBC) && (!defined (_MSC_VER) || _MSC_VER > 1400)
367#define _DEBUG_PRINT(PrintLevel, ...) \
368 do { \
369 if (DebugPrintLevelEnabled (PrintLevel)) { \
370 DebugPrint (PrintLevel, ##__VA_ARGS__); \
371 } \
372 } while (FALSE)
373#define _DEBUG(Expression) _DEBUG_PRINT Expression
374#else
375#define _DEBUG(Expression) DebugPrint Expression
376#endif
377
390#if !defined (MDEPKG_NDEBUG)
391#define ASSERT(Expression) \
392 do { \
393 if (DebugAssertEnabled ()) { \
394 if (!(Expression)) { \
395 _ASSERT (Expression); \
396 ANALYZER_UNREACHABLE (); \
397 } \
398 } \
399 } while (FALSE)
400#else
401#define ASSERT(Expression)
402#endif
403
416#if !defined (MDEPKG_NDEBUG)
417#define DEBUG(Expression) \
418 do { \
419 if (DebugPrintEnabled ()) { \
420 _DEBUG (Expression); \
421 } \
422 } while (FALSE)
423#else
424#define DEBUG(Expression)
425#endif
426
439#if !defined (MDEPKG_NDEBUG)
440#define ASSERT_EFI_ERROR(StatusParameter) \
441 do { \
442 if (DebugAssertEnabled ()) { \
443 if (EFI_ERROR (StatusParameter)) { \
444 DEBUG ((DEBUG_ERROR, "\nASSERT_EFI_ERROR (Status = %r)\n", StatusParameter)); \
445 _ASSERT (!EFI_ERROR (StatusParameter)); \
446 } \
447 } \
448 } while (FALSE)
449#else
450#define ASSERT_EFI_ERROR(StatusParameter)
451#endif
452
465#if !defined (MDEPKG_NDEBUG)
466#define ASSERT_RETURN_ERROR(StatusParameter) \
467 do { \
468 if (DebugAssertEnabled ()) { \
469 if (RETURN_ERROR (StatusParameter)) { \
470 DEBUG ((DEBUG_ERROR, "\nASSERT_RETURN_ERROR (Status = %r)\n", \
471 StatusParameter)); \
472 _ASSERT (!RETURN_ERROR (StatusParameter)); \
473 } \
474 } \
475 } while (FALSE)
476#else
477#define ASSERT_RETURN_ERROR(StatusParameter)
478#endif
479
502#if !defined (MDEPKG_NDEBUG)
503#define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid) \
504 do { \
505 if (DebugAssertEnabled ()) { \
506 VOID *Instance; \
507 ASSERT (Guid != NULL); \
508 if (Handle == NULL) { \
509 if (!EFI_ERROR (gBS->LocateProtocol ((EFI_GUID *)Guid, NULL, &Instance))) { \
510 _ASSERT (Guid already installed in database); \
511 } \
512 } else { \
513 if (!EFI_ERROR (gBS->HandleProtocol (Handle, (EFI_GUID *)Guid, &Instance))) { \
514 _ASSERT (Guid already installed on Handle); \
515 } \
516 } \
517 } \
518 } while (FALSE)
519#else
520#define ASSERT_PROTOCOL_ALREADY_INSTALLED(Handle, Guid)
521#endif
522
532#define DEBUG_CODE_BEGIN() do { if (DebugCodeEnabled ()) { UINT8 __DebugCodeLocal
533
543#define DEBUG_CODE_END() __DebugCodeLocal = 0; __DebugCodeLocal++; } } while (FALSE)
544
553#define DEBUG_CODE(Expression) \
554 DEBUG_CODE_BEGIN (); \
555 Expression \
556 DEBUG_CODE_END ()
557
568#define DEBUG_CLEAR_MEMORY(Address, Length) \
569 do { \
570 if (DebugClearMemoryEnabled ()) { \
571 DebugClearMemory (Address, Length); \
572 } \
573 } while (FALSE)
574
617#if !defined (MDEPKG_NDEBUG)
618#define CR(Record, TYPE, Field, TestSignature) \
619 (DebugAssertEnabled () && (BASE_CR (Record, TYPE, Field)->Signature != TestSignature)) ? \
620 (TYPE *) (_ASSERT (CR has Bad Signature), Record) : \
621 BASE_CR (Record, TYPE, Field)
622#else
623#define CR(Record, TYPE, Field, TestSignature) \
624 BASE_CR (Record, TYPE, Field)
625#endif
626
627#endif
UINTN
UINT64 UINTN
Definition: ProcessorBind.h:112
CONST
#define CONST
Definition: Base.h:259
VA_LIST
CHAR8 * VA_LIST
Definition: Base.h:635
IN
#define IN
Definition: Base.h:279
BASE_LIST
UINTN * BASE_LIST
Definition: Base.h:703
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:415
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