ArmPkg/Library/SemiHostingDebugLib/DebugLib.c

   1 /** @file
   2   UEFI Debug Library that uses PrintLib to send messages to STDERR.
   3
   4   Copyright (c) 2006 - 2007, 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
  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   CHAR8    AsciiBuffer[MAX_DEBUG_MESSAGE_LENGTH];
  53   VA_LIST  Marker;
  54
  55   //
  56   // If Format is NULL, then ASSERT().
  57   //
  58   ASSERT (Format != NULL);
  59
  60   //
  61   // Check driver debug mask value and global mask
  62   //
  63   if ((ErrorLevel & PcdGet32(PcdDebugPrintErrorLevel)) == 0) {
  64     return;
  65   }
  66
  67   //
  68   // Convert the DEBUG() message to a Unicode String
  69   //
  70   VA_START (Marker, Format);
  71   AsciiVSPrint (AsciiBuffer, sizeof (AsciiBuffer), Format, Marker);
  72   VA_END (Marker);
  73
  74   SemihostWriteString (AsciiBuffer);
  75 }
  76
  77
  78 /**
  79
  80   Prints an assert message containing a filename, line number, and description.
  81   This may be followed by a breakpoint or a dead loop.
  82
  83   Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n"
  84   to the debug output device.  If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of
  85   PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if
  86   DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then
  87   CpuDeadLoop() is called.  If neither of these bits are set, then this function
  88   returns immediately after the message is printed to the debug output device.
  89   DebugAssert() must actively prevent recusrsion.  If DebugAssert() is called while
  90   processing another DebugAssert(), then DebugAssert() must return immediately.
  91
  92   If FileName is NULL, then a <FileName> string of "(NULL) Filename" is printed.
  93
  94   If Description is NULL, then a <Description> string of "(NULL) Description" is printed.
  95
  96   @param  FileName     Pointer to the name of the source file that generated the assert condition.
  97   @param  LineNumber   The line number in the source file that generated the assert condition
  98   @param  Description  Pointer to the description of the assert condition.
  99
 100 **/
 101 VOID
 102 EFIAPI
 103 DebugAssert (
 104   IN CONST CHAR8  *FileName,
 105   IN UINTN        LineNumber,
 106   IN CONST CHAR8  *Description
 107   )
 108 {
 109   CHAR8   AsciiBuffer[MAX_DEBUG_MESSAGE_LENGTH];
 110
 111   //
 112   // Generate the ASSERT() message in Unicode format
 113   //
 114   AsciiSPrint (AsciiBuffer, sizeof (AsciiBuffer), "ASSERT %a(%d): %a\n", FileName, LineNumber, Description);
 115
 116   SemihostWriteString (AsciiBuffer);
 117
 118   //
 119   // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
 120   //
 121   if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
 122     CpuBreakpoint ();
 123   } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
 124     CpuDeadLoop ();
 125   }
 126 }
 127
 128
 129 /**
 130
 131   Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer.
 132
 133   This function fills Length bytes of Buffer with the value specified by
 134   PcdDebugClearMemoryValue, and returns Buffer.
 135
 136   If Buffer is NULL, then ASSERT().
 137
 138   If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
 139
 140   @param   Buffer  Pointer to the target buffer to fill with PcdDebugClearMemoryValue.
 141   @param   Length  Number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue.
 142
 143   @return  Buffer
 144
 145 **/
 146 VOID *
 147 EFIAPI
 148 DebugClearMemory (
 149   OUT VOID  *Buffer,
 150   IN UINTN  Length
 151   )
 152 {
 153   //
 154   // If Buffer is NULL, then ASSERT().
 155   //
 156   ASSERT (Buffer != NULL);
 157
 158   //
 159   // SetMem() checks for the the ASSERT() condition on Length and returns Buffer
 160   //
 161   return SetMem (Buffer, Length, PcdGet8(PcdDebugClearMemoryValue));
 162 }
 163
 164
 165 /**
 166
 167   Returns TRUE if ASSERT() macros are enabled.
 168
 169   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of
 170   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 171
 172   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set.
 173   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear.
 174
 175 **/
 176 BOOLEAN
 177 EFIAPI
 178 DebugAssertEnabled (
 179   VOID
 180   )
 181 {
 182   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED) != 0);
 183 }
 184
 185
 186 /**
 187
 188   Returns TRUE if DEBUG()macros are enabled.
 189
 190   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of
 191   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 192
 193   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set.
 194   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is clear.
 195
 196 **/
 197 BOOLEAN
 198 EFIAPI
 199 DebugPrintEnabled (
 200   VOID
 201   )
 202 {
 203   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);
 204 }
 205
 206
 207 /**
 208
 209   Returns TRUE if DEBUG_CODE()macros are enabled.
 210
 211   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of
 212   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 213
 214   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set.
 215   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is clear.
 216
 217 **/
 218 BOOLEAN
 219 EFIAPI
 220 DebugCodeEnabled (
 221   VOID
 222   )
 223 {
 224   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_CODE_ENABLED) != 0);
 225 }
 226
 227
 228 /**
 229
 230   Returns TRUE if DEBUG_CLEAR_MEMORY()macro is enabled.
 231
 232   This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of
 233   PcdDebugProperyMask is set.  Otherwise FALSE is returned.
 234
 235   @retval  TRUE    The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set.
 236   @retval  FALSE   The DEBUG_PROPERTY_DEBUG_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is clear.
 237
 238 **/
 239 BOOLEAN
 240 EFIAPI
 241 DebugClearMemoryEnabled (
 242   VOID
 243   )
 244 {
 245   return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED) != 0);
 246 }