1 /** @file
2 UEFI Debug Library that uses PrintLib to send messages to STDERR.
3
4 Copyright (c) 2006 - 2007, Intel Corporation. All rights reserved.<BR>
5 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
10
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14 **/
15
16
17 #include <Uefi.h>
18 #include <Library/DebugLib.h>
19 #include <Library/PrintLib.h>
20 #include <Library/PcdLib.h>
21 #include <Library/BaseLib.h>
22 #include <Library/BaseMemoryLib.h>
23 #include <Library/SemihostLib.h>
24
25 //
26 // Define the maximum debug and assert message length that this library supports
27 //
28 #define MAX_DEBUG_MESSAGE_LENGTH 0x100
29
30 /**
31
32 Prints a debug message to the debug output device if the specified error level is enabled.
33
34 If any bit in ErrorLevel is also set in PcdDebugPrintErrorLevel, then print
35 the message specified by Format and the associated variable argument list to
36 the debug output device.
37
38 If Format is NULL, then ASSERT().
39
40 @param ErrorLevel The error level of the debug message.
41 @param Format Format string for the debug message to print.
42
43 **/
44 VOID
45 EFIAPI
DebugPrint(IN UINTN ErrorLevel,IN CONST CHAR8 * Format,...)46 DebugPrint (
47 IN UINTN ErrorLevel,
48 IN CONST CHAR8 *Format,
49 ...
50 )
51 {
52 CHAR8 AsciiBuffer[MAX_DEBUG_MESSAGE_LENGTH];
53 VA_LIST Marker;
54
55 //
56 // If Format is NULL, then ASSERT().
57 //
58 ASSERT (Format != NULL);
59
60 //
61 // Check driver debug mask value and global mask
62 //
63 if ((ErrorLevel & PcdGet32(PcdDebugPrintErrorLevel)) == 0) {
64 return;
65 }
66
67 //
68 // Convert the DEBUG() message to a Unicode String
69 //
70 VA_START (Marker, Format);
71 AsciiVSPrint (AsciiBuffer, sizeof (AsciiBuffer), Format, Marker);
72 VA_END (Marker);
73
74 SemihostWriteString (AsciiBuffer);
75 }
76
77
78 /**
79
80 Prints an assert message containing a filename, line number, and description.
81 This may be followed by a breakpoint or a dead loop.
82
83 Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n"
84 to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of
85 PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if
86 DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then
87 CpuDeadLoop() is called. If neither of these bits are set, then this function
88 returns immediately after the message is printed to the debug output device.
89 DebugAssert() must actively prevent recusrsion. If DebugAssert() is called while
90 processing another DebugAssert(), then DebugAssert() must return immediately.
91
92 If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
93
94 If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
95
96 @param FileName Pointer to the name of the source file that generated the assert condition.
97 @param LineNumber The line number in the source file that generated the assert condition
98 @param Description Pointer to the description of the assert condition.
99
100 **/
101 VOID
102 EFIAPI
DebugAssert(IN CONST CHAR8 * FileName,IN UINTN LineNumber,IN CONST CHAR8 * Description)103 DebugAssert (
104 IN CONST CHAR8 *FileName,
105 IN UINTN LineNumber,
106 IN CONST CHAR8 *Description
107 )
108 {
109 CHAR8 AsciiBuffer[MAX_DEBUG_MESSAGE_LENGTH];
110
111 //
112 // Generate the ASSERT() message in Unicode format
113 //
114 AsciiSPrint (AsciiBuffer, sizeof (AsciiBuffer), "ASSERT %a(%d): %a\n", FileName, LineNumber, Description);
115
116 SemihostWriteString (AsciiBuffer);
117
118 //
119 // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
120 //
121 if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
122 CpuBreakpoint ();
123 } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
124 CpuDeadLoop ();
125 }
126 }
127
128
129 /**
130
131 Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.
132
133 This function fills Length bytes of Buffer with the value specified by
134 PcdDebugClearMemoryValue, and returns Buffer.
135
136 If Buffer is NULL, then ASSERT().
137
138 If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
139
140 @param Buffer Pointer to the target buffer to fill with PcdDebugClearMemoryValue.
141 @param Length Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue.
142
143 @return Buffer
144
145 **/
146 VOID *
147 EFIAPI
DebugClearMemory(OUT VOID * Buffer,IN UINTN Length)148 DebugClearMemory (
149 OUT VOID *Buffer,
150 IN UINTN Length
151 )
152 {
153 //
154 // If Buffer is NULL, then ASSERT().
155 //
156 ASSERT (Buffer != NULL);
157
158 //
159 // SetMem() checks for the the ASSERT() condition on Length and returns Buffer
160 //
161 return SetMem (Buffer, Length, PcdGet8(PcdDebugClearMemoryValue));
162 }
163
164
165 /**
166
167 Returns TRUE if ASSERT() macros are enabled.
168
169 This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of
170 PcdDebugProperyMask is set. Otherwise FALSE is returned.
171
172 @retval TRUE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.
173 @retval FALSE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.
174
175 **/
176 BOOLEAN
177 EFIAPI
DebugAssertEnabled(VOID)178 DebugAssertEnabled (
179 VOID
180 )
181 {
182 return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);
183 }
184
185
186 /**
187
188 Returns TRUE if DEBUG()macros are enabled.
189
190 This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of
191 PcdDebugProperyMask is set. Otherwise FALSE is returned.
192
193 @retval TRUE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.
194 @retval FALSE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.
195
196 **/
197 BOOLEAN
198 EFIAPI
DebugPrintEnabled(VOID)199 DebugPrintEnabled (
200 VOID
201 )
202 {
203 return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);
204 }
205
206
207 /**
208
209 Returns TRUE if DEBUG_CODE()macros are enabled.
210
211 This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of
212 PcdDebugProperyMask is set. Otherwise FALSE is returned.
213
214 @retval TRUE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.
215 @retval FALSE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.
216
217 **/
218 BOOLEAN
219 EFIAPI
DebugCodeEnabled(VOID)220 DebugCodeEnabled (
221 VOID
222 )
223 {
224 return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);
225 }
226
227
228 /**
229
230 Returns TRUE if DEBUG_CLEAR_MEMORY()macro is enabled.
231
232 This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of
233 PcdDebugProperyMask is set. Otherwise FALSE is returned.
234
235 @retval TRUE The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.
236 @retval FALSE The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.
237
238 **/
239 BOOLEAN
240 EFIAPI
DebugClearMemoryEnabled(VOID)241 DebugClearMemoryEnabled (
242 VOID
243 )
244 {
245 return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED) != 0);
246 }
247