OvmfPkg/Library/PlatformDebugLibIoPort/DebugLib.c

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