MdePkg/Library/BaseDebugLibSerialPort/DebugLib.c

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