ArmPkg/Library/SemiHostingDebugLib/DebugLib.c

   1 /** @file
   2   UEFI Debug Library that uses PrintLib to send messages to STDERR.
   3
   4   Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
   5   Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #include <Uefi.h>
  11 #include <Library/DebugLib.h>
  12 #include <Library/PrintLib.h>
  13 #include <Library/PcdLib.h>
  14 #include <Library/BaseLib.h>
  15 #include <Library/BaseMemoryLib.h>
  16 #include <Library/SemihostLib.h>
  17
  18 //
  19 // Define the maximum debug and assert message length that this library supports
  20 //
  21 #define MAX_DEBUG_MESSAGE_LENGTH  0x100
  22
  23 //
  24 // VA_LIST can not initialize to NULL for all compiler, so we use this to
  25 // indicate a null VA_LIST
  26 //
  27 VA_LIST  mVaListNull;
  28
  29 /**
  30
  31   Prints a debug message to the debug output device if the specified error level is enabled.
  32
  33   If any bit in ErrorLevel is also set in PcdDebugPrintErrorLevel, then print
  34   the message specified by Format and the associated variable argument list to
  35   the debug output device.
  36
  37   If Format is NULL, then ASSERT().
  38
  39   @param  ErrorLevel  The error level of the debug message.
  40   @param  Format      Format string for the debug message to print.
  41
  42 **/
  43 VOID
  44 EFIAPI
  45 DebugPrint (
  46   IN  UINTN        ErrorLevel,
  47   IN  CONST CHAR8  *Format,
  48   ...
  49   )
  50 {
  51   VA_LIST  Marker;
  52
  53   VA_START (Marker, Format);
  54   DebugVPrint (ErrorLevel, Format, Marker);
  55   VA_END (Marker);
  56 }
  57
  58 /**
  59   Prints a debug message to the debug output device if the specified
  60   error level is enabled base on Null-terminated format string and a
  61   VA_LIST argument list or a BASE_LIST argument list.
  62
  63   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
  64   GetDebugPrintErrorLevel (), then print the message specified by Format and
  65   the associated variable argument list to the debug output device.
  66
  67   If Format is NULL, then ASSERT().
  68
  69   @param  ErrorLevel      The error level of the debug message.
  70   @param  Format          Format string for the debug message to print.
  71   @param  VaListMarker    VA_LIST marker for the variable argument list.
  72   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
  73
  74 **/
  75 VOID
  76 DebugPrintMarker (
  77   IN  UINTN        ErrorLevel,
  78   IN  CONST CHAR8  *Format,
  79   IN  VA_LIST      VaListMarker,
  80   IN  BASE_LIST    BaseListMarker
  81   )
  82 {
  83   CHAR8  AsciiBuffer[MAX_DEBUG_MESSAGE_LENGTH];
  84
  85   //
  86   // If Format is NULL, then ASSERT().
  87   //
  88   ASSERT (Format != NULL);
  89
  90   //
  91   // Check driver debug mask value and global mask
  92   //
  93   if ((ErrorLevel & PcdGet32 (PcdDebugPrintErrorLevel)) == 0) {
  94     return;
  95   }
  96
  97   //
  98   // Convert the DEBUG() message to a Unicode String
  99   //
 100   if (BaseListMarker == NULL) {
 101     AsciiVSPrint (AsciiBuffer, sizeof (AsciiBuffer), Format, VaListMarker);
 102   } else {
 103     AsciiBSPrint (AsciiBuffer, sizeof (AsciiBuffer), Format, BaseListMarker);
 104   }
 105
 106   SemihostWriteString (AsciiBuffer);
 107 }
 108
 109 /**
 110   Prints a debug message to the debug output device if the specified
 111   error level is enabled.
 112
 113   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 114   GetDebugPrintErrorLevel (), then print the message specified by Format and
 115   the associated variable argument list to the debug output device.
 116
 117   If Format is NULL, then ASSERT().
 118
 119   @param  ErrorLevel    The error level of the debug message.
 120   @param  Format        Format string for the debug message to print.
 121   @param  VaListMarker  VA_LIST marker for the variable argument list.
 122
 123 **/
 124 VOID
 125 EFIAPI
 126 DebugVPrint (
 127   IN  UINTN        ErrorLevel,
 128   IN  CONST CHAR8  *Format,
 129   IN  VA_LIST      VaListMarker
 130   )
 131 {
 132   DebugPrintMarker (ErrorLevel, Format, VaListMarker, NULL);
 133 }
 134
 135 /**
 136   Prints a debug message to the debug output device if the specified
 137   error level is enabled.
 138   This function use BASE_LIST which would provide a more compatible
 139   service than VA_LIST.
 140
 141   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 142   GetDebugPrintErrorLevel (), then print the message specified by Format and
 143   the associated variable argument list to the debug output device.
 144
 145   If Format is NULL, then ASSERT().
 146
 147   @param  ErrorLevel      The error level of the debug message.
 148   @param  Format          Format string for the debug message to print.
 149   @param  BaseListMarker  BASE_LIST marker for the variable argument list.
 150
 151 **/
 152 VOID
 153 EFIAPI
 154 DebugBPrint (
 155   IN  UINTN        ErrorLevel,
 156   IN  CONST CHAR8  *Format,
 157   IN  BASE_LIST    BaseListMarker
 158   )
 159 {
 160   DebugPrintMarker (ErrorLevel, Format, mVaListNull, BaseListMarker);
 161 }
 162
 163 /**
 164
 165   Prints an assert message containing a filename, line number, and description.
 166   This may be followed by a breakpoint or a dead loop.
 167
 168   Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n"
 169   to the debug output device.  If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of
 170   PcdDebugPropertyMask is set then CpuBreakpoint() is called. Otherwise, if
 171   DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugPropertyMask is set then
 172   CpuDeadLoop() is called.  If neither of these bits are set, then this function
 173   returns immediately after the message is printed to the debug output device.
 174   DebugAssert() must actively prevent recursion.  If DebugAssert() is called while
 175   processing another DebugAssert(), then DebugAssert() must return immediately.
 176
 177   If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
 178
 179   If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
 180
 181   @param  FileName     Pointer to the name of the source file that generated the assert condition.
 182   @param  LineNumber   The line number in the source file that generated the assert condition
 183   @param  Description  Pointer to the description of the assert condition.
 184
 185 **/
 186 VOID
 187 EFIAPI
 188 DebugAssert (
 189   IN CONST CHAR8  *FileName,
 190   IN UINTN        LineNumber,
 191   IN CONST CHAR8  *Description
 192   )
 193 {
 194   CHAR8  AsciiBuffer[MAX_DEBUG_MESSAGE_LENGTH];
 195
 196   //
 197   // Generate the ASSERT() message in Unicode format
 198   //
 199   AsciiSPrint (AsciiBuffer, sizeof (AsciiBuffer), "ASSERT %a(%d): %a\n", FileName, LineNumber, Description);
 200
 201   SemihostWriteString (AsciiBuffer);
 202
 203   //
 204   // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
 205   //
 206   if ((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
 207     CpuBreakpoint ();
 208   } else if ((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
 209     CpuDeadLoop ();
 210   }
 211 }
 212
 213 /**
 214
 215   Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.
 216
 217   This function fills Length bytes of Buffer with the value specified by
 218   PcdDebugClearMemoryValue, and returns Buffer.
 219
 220   If Buffer is NULL, then ASSERT().
 221
 222   If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
 223
 224   @param   Buffer  Pointer to the target buffer to fill with PcdDebugClearMemoryValue.
 225   @param   Length  Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue.
 226
 227   @return  Buffer
 228
 229 **/
 230 VOID *
 231 EFIAPI
 232 DebugClearMemory (
 233   OUT VOID  *Buffer,
 234   IN UINTN  Length
 235   )
 236 {
 237   //
 238   // If Buffer is NULL, then ASSERT().
 239   //
 240   ASSERT (Buffer != NULL);
 241
 242   //
 243   // SetMem() checks for the ASSERT() condition on Length and returns Buffer
 244   //
 245   return SetMem (Buffer, Length, PcdGet8 (PcdDebugClearMemoryValue));
 246 }
 247
 248 /**
 249
 250   Returns TRUE if ASSERT() macros are enabled.
 251
 252   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of
 253   PcdDebugPropertyMask is set.  Otherwise FALSE is returned.
 254
 255   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugPropertyMask is set.
 256   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugPropertyMask is clear.
 257
 258 **/
 259 BOOLEAN
 260 EFIAPI
 261 DebugAssertEnabled (
 262   VOID
 263   )
 264 {
 265   return (BOOLEAN)((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);
 266 }
 267
 268 /**
 269
 270   Returns TRUE if DEBUG()macros are enabled.
 271
 272   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of
 273   PcdDebugPropertyMask is set.  Otherwise FALSE is returned.
 274
 275   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugPropertyMask is set.
 276   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugPropertyMask is clear.
 277
 278 **/
 279 BOOLEAN
 280 EFIAPI
 281 DebugPrintEnabled (
 282   VOID
 283   )
 284 {
 285   return (BOOLEAN)((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);
 286 }
 287
 288 /**
 289
 290   Returns TRUE if DEBUG_CODE()macros are enabled.
 291
 292   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of
 293   PcdDebugPropertyMask is set.  Otherwise FALSE is returned.
 294
 295   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugPropertyMask is set.
 296   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugPropertyMask is clear.
 297
 298 **/
 299 BOOLEAN
 300 EFIAPI
 301 DebugCodeEnabled (
 302   VOID
 303   )
 304 {
 305   return (BOOLEAN)((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);
 306 }
 307
 308 /**
 309
 310   Returns TRUE if DEBUG_CLEAR_MEMORY()macro is enabled.
 311
 312   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of
 313   PcdDebugPropertyMask is set.  Otherwise FALSE is returned.
 314
 315   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugPropertyMask is set.
 316   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugPropertyMask is clear.
 317
 318 **/
 319 BOOLEAN
 320 EFIAPI
 321 DebugClearMemoryEnabled (
 322   VOID
 323   )
 324 {
 325   return (BOOLEAN)((PcdGet8 (PcdDebugPropertyMask) & DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED) != 0);
 326 }