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