A typo in comments that alignment should be 8 for IPF
[mirror_edk2.git] / EdkModulePkg / Library / EdkUefiDebugLibStdErr / DebugLib.c
CommitLineData
add13dc2 1/** @file\r
2 UEFI Debug Library that uses PrintLib to send messages to STDERR.\r
878ddf1f 3\r
add13dc2 4 Copyright (c) 2006, Intel Corporation<BR>\r
5 All rights reserved. This program and the accompanying materials\r
6 are licensed and made available under the terms and conditions of the BSD License\r
7 which accompanies this distribution. The full text of the license may be found at\r
8 http://opensource.org/licenses/bsd-license.php\r
878ddf1f 9\r
add13dc2 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
878ddf1f 12\r
add13dc2 13**/\r
878ddf1f 14\r
add13dc2 15//\r
16// Define the maximum debug and assert message length that this library supports. \r
17//\r
18#define MAX_DEBUG_MESSAGE_LENGTH 0x100\r
878ddf1f 19\r
add13dc2 20STATIC BOOLEAN mDebugLevelInstalled = FALSE;\r
21STATIC EFI_DEBUG_LEVEL_PROTOCOL mDebugLevel = { 0 };\r
878ddf1f 22\r
add13dc2 23/**\r
24 Installs Debug Level Protocol.\r
25 \r
26 The constructor function installs Debug Level Protocol on the ImageHandle.\r
27 It will ASSERT() if the installation fails and will always return EFI_SUCCESS. \r
878ddf1f 28\r
add13dc2 29 @param ImageHandle The firmware allocated handle for the EFI image.\r
30 @param SystemTable A pointer to the EFI System Table.\r
31 \r
32 @retval EFI_SUCCESS The constructor always returns EFI_SUCCESS.\r
878ddf1f 33\r
add13dc2 34**/\r
878ddf1f 35EFI_STATUS\r
add13dc2 36EFIAPI\r
878ddf1f 37DebugLibConstructor (\r
38 IN EFI_HANDLE ImageHandle,\r
39 IN EFI_SYSTEM_TABLE *SystemTable\r
40 )\r
878ddf1f 41{\r
add13dc2 42 EFI_STATUS Status;\r
878ddf1f 43\r
44 //\r
add13dc2 45 // Initialize Debug Level Protocol.\r
878ddf1f 46 //\r
47 mDebugLevel.DebugLevel = PcdGet32(PcdDebugPrintErrorLevel);\r
48\r
49 //\r
add13dc2 50 // Install Debug Level Protocol. \r
878ddf1f 51 //\r
52 Status = gBS->InstallMultipleProtocolInterfaces (\r
53 &ImageHandle,\r
add13dc2 54 &gEfiDebugLevelProtocolGuid,\r
55 &mDebugLevel,\r
878ddf1f 56 NULL\r
57 );\r
58 ASSERT_EFI_ERROR (Status);\r
59\r
60 //\r
add13dc2 61 // Set flag to show that the Debug Level Protocol has been installed.\r
878ddf1f 62 //\r
63 mDebugLevelInstalled = TRUE;\r
64\r
add13dc2 65 return Status;\r
878ddf1f 66}\r
67\r
add13dc2 68/**\r
878ddf1f 69\r
add13dc2 70 Prints a debug message to the debug output device if the specified error level is enabled.\r
878ddf1f 71\r
add13dc2 72 If any bit in ErrorLevel is also set in PcdDebugPrintErrorLevel, then print \r
73 the message specified by Format and the associated variable argument list to \r
74 the debug output device.\r
878ddf1f 75\r
add13dc2 76 If Format is NULL, then ASSERT().\r
878ddf1f 77\r
add13dc2 78 @param ErrorLevel The error level of the debug message.\r
79 @param Format Format string for the debug message to print.\r
878ddf1f 80\r
add13dc2 81**/\r
82VOID\r
83EFIAPI\r
84DebugPrint (\r
85 IN UINTN ErrorLevel,\r
86 IN CONST CHAR8 *Format,\r
87 ...\r
88 )\r
878ddf1f 89{\r
add13dc2 90 CHAR16 Buffer[MAX_DEBUG_MESSAGE_LENGTH];\r
878ddf1f 91 VA_LIST Marker;\r
92\r
93 //\r
add13dc2 94 // If Format is NULL, then ASSERT().\r
878ddf1f 95 //\r
add13dc2 96 ASSERT (Format != NULL);\r
878ddf1f 97\r
98 //\r
99 // Check driver Debug Level value and global debug level\r
100 //\r
101 if (mDebugLevelInstalled) {\r
102 if ((ErrorLevel & mDebugLevel.DebugLevel) == 0) {\r
103 return;\r
104 }\r
105 } else {\r
106 if ((ErrorLevel & PcdGet32(PcdDebugPrintErrorLevel)) == 0) {\r
107 return;\r
108 }\r
109 }\r
110\r
878ddf1f 111 //\r
112 // Convert the DEBUG() message to a Unicode String\r
113 //\r
114 VA_START (Marker, Format);\r
add13dc2 115 UnicodeVSPrintAsciiFormat (Buffer, sizeof (Buffer), Format, Marker);\r
878ddf1f 116 VA_END (Marker);\r
117\r
118 //\r
add13dc2 119 // Send the print string to the Standard Error device if STDERR is available.\r
878ddf1f 120 //\r
add13dc2 121 if (gST->StdErr != NULL) {\r
122 gST->StdErr->OutputString (gST->StdErr, Buffer);\r
123 }\r
878ddf1f 124}\r
125\r
878ddf1f 126\r
add13dc2 127/**\r
878ddf1f 128\r
add13dc2 129 Prints an assert message containing a filename, line number, and description. \r
130 This may be followed by a breakpoint or a dead loop.\r
878ddf1f 131\r
add13dc2 132 Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n" \r
133 to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of \r
134 PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if \r
135 DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then \r
136 CpuDeadLoop() is called. If neither of these bits are set, then this function \r
137 returns immediately after the message is printed to the debug output device.\r
138 DebugAssert() must actively prevent recusrsion. If DebugAssert() is called while\r
139 processing another DebugAssert(), then DebugAssert() must return immediately.\r
878ddf1f 140\r
add13dc2 141 If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.\r
878ddf1f 142\r
add13dc2 143 If Description is NULL, then a <Description> string of "(NULL) Description" is printed.\r
878ddf1f 144\r
add13dc2 145 @param FileName Pointer to the name of the source file that generated the assert condition.\r
146 @param LineNumber The line number in the source file that generated the assert condition\r
147 @param Description Pointer to the description of the assert condition.\r
878ddf1f 148\r
add13dc2 149**/\r
150VOID\r
151EFIAPI\r
152DebugAssert (\r
153 IN CONST CHAR8 *FileName,\r
154 IN UINTN LineNumber,\r
155 IN CONST CHAR8 *Description\r
156 )\r
878ddf1f 157{\r
add13dc2 158 CHAR16 Buffer[MAX_DEBUG_MESSAGE_LENGTH];\r
878ddf1f 159\r
160 //\r
161 // Generate the ASSERT() message in Unicode format\r
162 //\r
add13dc2 163 UnicodeSPrintAsciiFormat (Buffer, sizeof (Buffer), "ASSERT %s(%d): %s\n", FileName, LineNumber, Description);\r
878ddf1f 164\r
165 //\r
add13dc2 166 // Send the print string to the Standard Error device if STDERR is available.\r
878ddf1f 167 //\r
add13dc2 168 if (gST->StdErr != NULL) {\r
169 gST->StdErr->OutputString (gST->StdErr, Buffer);\r
170 }\r
878ddf1f 171\r
172 //\r
add13dc2 173 // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings\r
878ddf1f 174 //\r
add13dc2 175 if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {\r
176 CpuBreakpoint ();\r
177 } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {\r
178 CpuDeadLoop ();\r
179 }\r
878ddf1f 180}\r
181\r
add13dc2 182\r
878ddf1f 183/**\r
add13dc2 184\r
878ddf1f 185 Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.\r
186\r
187 This function fills Length bytes of Buffer with the value specified by \r
188 PcdDebugClearMemoryValue, and returns Buffer.\r
189\r
190 If Buffer is NULL, then ASSERT().\r
191\r
511710d6 192 If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). \r
878ddf1f 193\r
add13dc2 194 @param Buffer Pointer to the target buffer to fill with PcdDebugClearMemoryValue.\r
195 @param Length Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. \r
878ddf1f 196\r
197 @return Buffer\r
198\r
199**/\r
200VOID *\r
201EFIAPI\r
202DebugClearMemory (\r
203 OUT VOID *Buffer,\r
204 IN UINTN Length\r
205 )\r
206{\r
add13dc2 207 //\r
208 // If Buffer is NULL, then ASSERT().\r
209 //\r
210 ASSERT (Buffer != NULL);\r
211\r
212 //\r
213 // SetMem() checks for the the ASSERT() condition on Length and returns Buffer\r
214 //\r
215 return SetMem (Buffer, Length, PcdGet8(PcdDebugClearMemoryValue));\r
878ddf1f 216}\r
217\r
add13dc2 218\r
219/**\r
220 \r
221 Returns TRUE if ASSERT() macros are enabled.\r
222\r
223 This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of \r
224 PcdDebugProperyMask is set. Otherwise FALSE is returned.\r
225\r
226 @retval TRUE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.\r
227 @retval FALSE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.\r
228\r
229**/\r
878ddf1f 230BOOLEAN\r
231EFIAPI\r
232DebugAssertEnabled (\r
233 VOID\r
234 )\r
235{\r
236 return ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);\r
237}\r
238\r
add13dc2 239\r
240/**\r
241 \r
242 Returns TRUE if DEBUG()macros are enabled.\r
243\r
244 This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of \r
245 PcdDebugProperyMask is set. Otherwise FALSE is returned.\r
246\r
247 @retval TRUE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.\r
248 @retval FALSE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.\r
249\r
250**/\r
878ddf1f 251BOOLEAN\r
252EFIAPI\r
253DebugPrintEnabled (\r
254 VOID\r
255 )\r
256{\r
257 return ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);\r
258}\r
259\r
add13dc2 260\r
261/**\r
262 \r
263 Returns TRUE if DEBUG_CODE()macros are enabled.\r
264\r
265 This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of \r
266 PcdDebugProperyMask is set. Otherwise FALSE is returned.\r
267\r
268 @retval TRUE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.\r
269 @retval FALSE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.\r
270\r
271**/\r
878ddf1f 272BOOLEAN\r
273EFIAPI\r
274DebugCodeEnabled (\r
275 VOID\r
276 )\r
277{\r
278 return ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);\r
279}\r
280\r
add13dc2 281\r
282/**\r
283 \r
284 Returns TRUE if DEBUG_CLEAR_MEMORY()macro is enabled.\r
285\r
286 This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of \r
287 PcdDebugProperyMask is set. Otherwise FALSE is returned.\r
288\r
289 @retval TRUE The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.\r
290 @retval FALSE The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.\r
291\r
292**/\r
878ddf1f 293BOOLEAN\r
294EFIAPI\r
295DebugClearMemoryEnabled (\r
296 VOID\r
297 )\r
298{\r
299 return ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED) != 0);\r
300}\r