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