EdkModulePkg/Library/EdkUefiDebugLibConOut/DebugLib.c

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