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