-/*++\r
+/** @file\r
+ UEFI Debug Library that uses PrintLib to send messages to STDERR.\r
\r
-Copyright (c) 2006, Intel Corporation \r
-All rights reserved. This program and the accompanying materials \r
-are licensed and made available under the terms and conditions of the BSD License \r
-which accompanies this distribution. The full text of the license may be found at \r
-http://opensource.org/licenses/bsd-license.php \r
- \r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+ Copyright (c) 2006, Intel Corporation<BR>\r
+ All rights reserved. This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD License\r
+ which accompanies this distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php\r
\r
-Module Name:\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
- DebugLib.c\r
+**/\r
\r
-Abstract:\r
+//\r
+// Define the maximum debug and assert message length that this library supports. \r
+//\r
+#define MAX_DEBUG_MESSAGE_LENGTH 0x100\r
\r
- UEFI Debug Library that uses PrintLib to send messages to STDERR\r
+STATIC BOOLEAN mDebugLevelInstalled = FALSE;\r
+STATIC EFI_DEBUG_LEVEL_PROTOCOL mDebugLevel = { 0 };\r
\r
---*/\r
+/**\r
+ Installs Debug Level Protocol.\r
+ \r
+ The constructor function installs Debug Level Protocol on the ImageHandle.\r
+ It will ASSERT() if the installation fails and will always return EFI_SUCCESS. \r
\r
-static BOOLEAN mDebugLevelInstalled = FALSE;\r
-static EFI_DEBUG_LEVEL_PROTOCOL mDebugLevel = { 0 };\r
+ @param ImageHandle The firmware allocated handle for the EFI image.\r
+ @param SystemTable A pointer to the EFI System Table.\r
+ \r
+ @retval EFI_SUCCESS The constructor always returns EFI_SUCCESS.\r
\r
+**/\r
EFI_STATUS\r
+EFIAPI\r
DebugLibConstructor (\r
IN EFI_HANDLE ImageHandle,\r
IN EFI_SYSTEM_TABLE *SystemTable\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
-Arguments:\r
-\r
-Returns:\r
-\r
---*/\r
{\r
- EFI_STATUS Status;\r
+ EFI_STATUS Status;\r
\r
//\r
- // Initialize Debug Level Protocol\r
+ // Initialize Debug Level Protocol.\r
//\r
mDebugLevel.DebugLevel = PcdGet32(PcdDebugPrintErrorLevel);\r
\r
//\r
- // Install Debug Level Protocol \r
+ // Install Debug Level Protocol. \r
//\r
Status = gBS->InstallMultipleProtocolInterfaces (\r
&ImageHandle,\r
- &gEfiDebugLevelProtocolGuid, &mDebugLevel,\r
+ &gEfiDebugLevelProtocolGuid,\r
+ &mDebugLevel,\r
NULL\r
);\r
ASSERT_EFI_ERROR (Status);\r
\r
//\r
- // Set flag to show that the Debug Level Protocol has been installed\r
+ // Set flag to show that the Debug Level Protocol has been installed.\r
//\r
mDebugLevelInstalled = TRUE;\r
\r
- return EFI_SUCCESS;\r
+ return Status;\r
}\r
\r
-VOID\r
-EFIAPI\r
-DebugPrint (\r
- IN UINTN ErrorLevel,\r
- IN CHAR8 *Format,\r
- ...\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Wrapper for DebugVPrint ()\r
- \r
-Arguments:\r
+/**\r
\r
- ErrorLevel - If error level is set do the debug print.\r
+ Prints a debug message to the debug output device if the specified error level is enabled.\r
\r
- Format - String to use for the print, followed by Print arguments.\r
+ If any bit in ErrorLevel is also set in PcdDebugPrintErrorLevel, then print \r
+ the message specified by Format and the associated variable argument list to \r
+ the debug output device.\r
\r
- ... - Print arguments.\r
+ If Format is NULL, then ASSERT().\r
\r
-Returns:\r
- \r
- None\r
+ @param ErrorLevel The error level of the debug message.\r
+ @param Format Format string for the debug message to print.\r
\r
---*/\r
+**/\r
+VOID\r
+EFIAPI\r
+DebugPrint (\r
+ IN UINTN ErrorLevel,\r
+ IN CONST CHAR8 *Format,\r
+ ...\r
+ )\r
{\r
- CHAR16 Buffer[0x100];\r
- CHAR16 UnicodeBuffer[0x100];\r
- UINT32 Index;\r
+ CHAR16 Buffer[MAX_DEBUG_MESSAGE_LENGTH];\r
VA_LIST Marker;\r
\r
//\r
- // Check to see if STDERR is avilable\r
+ // If Format is NULL, then ASSERT().\r
//\r
- if (gST->StdErr == NULL) {\r
- return;\r
- }\r
+ ASSERT (Format != NULL);\r
\r
//\r
// Check driver Debug Level value and global debug level\r
}\r
}\r
\r
- //\r
- // BUGBUG: Need print that take CHAR8 Format and returns CHAR16 Buffer\r
- //\r
- for (Index = 0; Format[Index] != 0; Index++) {\r
- UnicodeBuffer[Index] = Format[Index];\r
- }\r
- UnicodeBuffer[Index] = Format[Index];\r
-\r
//\r
// Convert the DEBUG() message to a Unicode String\r
//\r
VA_START (Marker, Format);\r
- UnicodeVSPrint (Buffer, sizeof (Buffer), UnicodeBuffer, Marker);\r
+ UnicodeVSPrintAsciiFormat (Buffer, sizeof (Buffer), Format, Marker);\r
VA_END (Marker);\r
\r
//\r
- // Send the print string to the Standard Error device\r
+ // Send the print string to the Standard Error device if STDERR is available.\r
//\r
- gST->StdErr->OutputString (gST->StdErr, Buffer);\r
+ if (gST->StdErr != NULL) {\r
+ gST->StdErr->OutputString (gST->StdErr, Buffer);\r
+ }\r
}\r
\r
-VOID\r
-EFIAPI\r
-DebugAssert (\r
- IN CHAR8 *FileName,\r
- IN UINTN LineNumber,\r
- IN CHAR8 *Description\r
- )\r
-/*++\r
\r
-Routine Description:\r
-\r
- Worker function for ASSERT(). If Error Logging hub is loaded log ASSERT\r
- information. If Error Logging hub is not loaded CpuBreakpoint ().\r
+/**\r
\r
- We use UINT64 buffers due to IPF alignment concerns.\r
+ Prints an assert message containing a filename, line number, and description. \r
+ This may be followed by a breakpoint or a dead loop.\r
\r
-Arguments:\r
+ Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n" \r
+ to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of \r
+ PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if \r
+ DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then \r
+ CpuDeadLoop() is called. If neither of these bits are set, then this function \r
+ returns immediately after the message is printed to the debug output device.\r
+ DebugAssert() must actively prevent recusrsion. If DebugAssert() is called while\r
+ processing another DebugAssert(), then DebugAssert() must return immediately.\r
\r
- FileName - File name of failing routine.\r
+ If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.\r
\r
- LineNumber - Line number of failing ASSERT().\r
+ If Description is NULL, then a <Description> string of "(NULL) Description" is printed.\r
\r
- Description - Descritption, usally the assertion,\r
- \r
-Returns:\r
- \r
- None\r
+ @param FileName Pointer to the name of the source file that generated the assert condition.\r
+ @param LineNumber The line number in the source file that generated the assert condition\r
+ @param Description Pointer to the description of the assert condition.\r
\r
---*/\r
+**/\r
+VOID\r
+EFIAPI\r
+DebugAssert (\r
+ IN CONST CHAR8 *FileName,\r
+ IN UINTN LineNumber,\r
+ IN CONST CHAR8 *Description\r
+ )\r
{\r
- CHAR16 Buffer[0x100];\r
-\r
- //\r
- // Check to see if STDERR is avilable\r
- //\r
- if (gST->StdErr == NULL) {\r
- return;\r
- }\r
+ CHAR16 Buffer[MAX_DEBUG_MESSAGE_LENGTH];\r
\r
//\r
// Generate the ASSERT() message in Unicode format\r
//\r
- UnicodeSPrint (Buffer, sizeof (Buffer), (CHAR16 *)L"ASSERT %s(%d): %s\n", FileName, LineNumber, Description);\r
+ UnicodeSPrintAsciiFormat (Buffer, sizeof (Buffer), "ASSERT %s(%d): %s\n", FileName, LineNumber, Description);\r
\r
//\r
- // Send the print string to the Standard Error device\r
+ // Send the print string to the Standard Error device if STDERR is available.\r
//\r
- gST->StdErr->OutputString (gST->StdErr, Buffer);\r
+ if (gST->StdErr != NULL) {\r
+ gST->StdErr->OutputString (gST->StdErr, Buffer);\r
+ }\r
\r
//\r
- // Put break point in module that contained the error.\r
+ // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings\r
//\r
- CpuBreakpoint ();\r
+ if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {\r
+ CpuBreakpoint ();\r
+ } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {\r
+ CpuDeadLoop ();\r
+ }\r
}\r
\r
+\r
/**\r
+\r
Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.\r
\r
This function fills Length bytes of Buffer with the value specified by \r
\r
If Length is greater than (MAX_ADDRESS \96 Buffer + 1), then ASSERT(). \r
\r
- @param Buffer Pointer to the target buffer to fill with PcdDebugClearMemoryValue.\r
- @param Length Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. \r
+ @param Buffer Pointer to the target buffer to fill with PcdDebugClearMemoryValue.\r
+ @param Length Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. \r
\r
@return Buffer\r
\r
IN UINTN Length\r
)\r
{\r
-// SetMem (Buffer, Length, PcdGet8(PcdDebugClearMemoryValue));\r
- SetMem (Buffer, Length, 0xAF);\r
- return Buffer;\r
+ //\r
+ // If Buffer is NULL, then ASSERT().\r
+ //\r
+ ASSERT (Buffer != NULL);\r
+\r
+ //\r
+ // SetMem() checks for the the ASSERT() condition on Length and returns Buffer\r
+ //\r
+ return SetMem (Buffer, Length, PcdGet8(PcdDebugClearMemoryValue));\r
}\r
\r
+\r
+/**\r
+ \r
+ Returns TRUE if ASSERT() macros are enabled.\r
+\r
+ This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of \r
+ PcdDebugProperyMask is set. Otherwise FALSE is returned.\r
+\r
+ @retval TRUE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.\r
+ @retval FALSE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.\r
+\r
+**/\r
BOOLEAN\r
EFIAPI\r
DebugAssertEnabled (\r
return ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);\r
}\r
\r
+\r
+/**\r
+ \r
+ Returns TRUE if DEBUG()macros are enabled.\r
+\r
+ This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of \r
+ PcdDebugProperyMask is set. Otherwise FALSE is returned.\r
+\r
+ @retval TRUE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.\r
+ @retval FALSE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.\r
+\r
+**/\r
BOOLEAN\r
EFIAPI\r
DebugPrintEnabled (\r
return ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);\r
}\r
\r
+\r
+/**\r
+ \r
+ Returns TRUE if DEBUG_CODE()macros are enabled.\r
+\r
+ This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of \r
+ PcdDebugProperyMask is set. Otherwise FALSE is returned.\r
+\r
+ @retval TRUE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.\r
+ @retval FALSE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.\r
+\r
+**/\r
BOOLEAN\r
EFIAPI\r
DebugCodeEnabled (\r
return ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);\r
}\r
\r
+\r
+/**\r
+ \r
+ Returns TRUE if DEBUG_CLEAR_MEMORY()macro is enabled.\r
+\r
+ This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of \r
+ PcdDebugProperyMask is set. Otherwise FALSE is returned.\r
+\r
+ @retval TRUE The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.\r
+ @retval FALSE The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.\r
+\r
+**/\r
BOOLEAN\r
EFIAPI\r
DebugClearMemoryEnabled (\r