MdePkg/Library/BasePrintLib/PrintLib.c

   1 /** @file
   2   Base Print Library instance implementation.
   3
   4   Copyright (c) 2006 - 2008, Intel Corporation<BR>
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #include "PrintLibInternal.h"
  16
  17 #define ASSERT_UNICODE_BUFFER(Buffer) ASSERT ((((UINTN) (Buffer)) & 0x01) == 0)
  18
  19 /**
  20   Produces a Null-terminated Unicode string in an output buffer based on
  21   a Null-terminated Unicode format string and a VA_LIST argument list
  22
  23   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  24   and BufferSize.
  25   The Unicode string is produced by parsing the format string specified by FormatString.
  26   Arguments are pulled from the variable argument list specified by Marker based on the
  27   contents of the format string.
  28   The number of Unicode characters in the produced output buffer is returned not including
  29   the Null-terminator.
  30   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  31
  32   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
  33   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  34   If BufferSize > 1 and FormatString is NULL, then ASSERT().
  35   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
  36   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  37   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
  38   ASSERT().
  39   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  40   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
  41   Null-terminator, then ASSERT().
  42
  43   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  44                           Unicode string.
  45   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  46   @param  FormatString    Null-terminated Unicode format string.
  47   @param  Marker          VA_LIST marker for the variable argument list.
  48
  49   @return The number of Unicode characters in the produced output buffer not including the
  50           Null-terminator.
  51
  52 **/
  53 UINTN
  54 EFIAPI
  55 UnicodeVSPrint (
  56   OUT CHAR16        *StartOfBuffer,
  57   IN  UINTN         BufferSize,
  58   IN  CONST CHAR16  *FormatString,
  59   IN  VA_LIST       Marker
  60   )
  61 {
  62   ASSERT_UNICODE_BUFFER(StartOfBuffer);
  63   ASSERT_UNICODE_BUFFER(FormatString);
  64   return BasePrintLibVSPrint ((CHAR8 *)StartOfBuffer, BufferSize >> 1, FORMAT_UNICODE | OUTPUT_UNICODE, (CHAR8 *)FormatString, Marker);
  65 }
  66
  67 /**
  68   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
  69   Unicode format string and variable argument list.
  70
  71   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
  72   and BufferSize.
  73   The Unicode string is produced by parsing the format string specified by FormatString.
  74   Arguments are pulled from the variable argument list based on the contents of the format string.
  75   The number of Unicode characters in the produced output buffer is returned not including
  76   the Null-terminator.
  77   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
  78
  79   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
  80   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
  81   If BufferSize > 1 and FormatString is NULL, then ASSERT().
  82   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
  83   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
  84   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
  85   ASSERT().
  86   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
  87   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
  88   Null-terminator, then ASSERT().
  89
  90   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
  91                           Unicode string.
  92   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
  93   @param  FormatString    Null-terminated Unicode format string.
  94   @param  ...             Variable argument list whose contents are accessed based on the
  95                           format string specified by FormatString.
  96
  97   @return The number of Unicode characters in the produced output buffer not including the
  98           Null-terminator.
  99
 100 **/
 101 UINTN
 102 EFIAPI
 103 UnicodeSPrint (
 104   OUT CHAR16        *StartOfBuffer,
 105   IN  UINTN         BufferSize,
 106   IN  CONST CHAR16  *FormatString,
 107   ...
 108   )
 109 {
 110   VA_LIST Marker;
 111
 112   VA_START (Marker, FormatString);
 113   return UnicodeVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
 114 }
 115
 116 /**
 117   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 118   ASCII format string and a VA_LIST argument list
 119
 120   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 121   and BufferSize.
 122   The Unicode string is produced by parsing the format string specified by FormatString.
 123   Arguments are pulled from the variable argument list specified by Marker based on the
 124   contents of the format string.
 125   The number of Unicode characters in the produced output buffer is returned not including
 126   the Null-terminator.
 127   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 128
 129   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 130   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 131   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 132   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 133   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 134   ASSERT().
 135   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 136   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 137   Null-terminator, then ASSERT().
 138
 139   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 140                           Unicode string.
 141   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 142   @param  FormatString    Null-terminated ASCII format string.
 143   @param  Marker          VA_LIST marker for the variable argument list.
 144
 145   @return The number of Unicode characters in the produced output buffer not including the
 146           Null-terminator.
 147
 148 **/
 149 UINTN
 150 EFIAPI
 151 UnicodeVSPrintAsciiFormat (
 152   OUT CHAR16       *StartOfBuffer,
 153   IN  UINTN        BufferSize,
 154   IN  CONST CHAR8  *FormatString,
 155   IN  VA_LIST      Marker
 156   )
 157 {
 158   ASSERT_UNICODE_BUFFER(StartOfBuffer);
 159   return BasePrintLibVSPrint ((CHAR8 *)StartOfBuffer, BufferSize >> 1, OUTPUT_UNICODE,FormatString, Marker);
 160 }
 161
 162 /**
 163   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 164   ASCII format string and  variable argument list.
 165
 166   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 167   and BufferSize.
 168   The Unicode string is produced by parsing the format string specified by FormatString.
 169   Arguments are pulled from the variable argument list based on the contents of the
 170   format string.
 171   The number of Unicode characters in the produced output buffer is returned not including
 172   the Null-terminator.
 173   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 174
 175   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 176   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 177   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 178   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 179   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 180   ASSERT().
 181   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 182   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 183   Null-terminator, then ASSERT().
 184
 185   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 186                           Unicode string.
 187   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 188   @param  FormatString    Null-terminated ASCII format string.
 189   @param  ...             Variable argument list whose contents are accessed based on the
 190                           format string specified by FormatString.
 191
 192   @return The number of Unicode characters in the produced output buffer not including the
 193           Null-terminator.
 194
 195 **/
 196 UINTN
 197 EFIAPI
 198 UnicodeSPrintAsciiFormat (
 199   OUT CHAR16       *StartOfBuffer,
 200   IN  UINTN        BufferSize,
 201   IN  CONST CHAR8  *FormatString,
 202   ...
 203   )
 204 {
 205   VA_LIST Marker;
 206
 207   VA_START (Marker, FormatString);
 208   return UnicodeVSPrintAsciiFormat (StartOfBuffer, BufferSize, FormatString, Marker);
 209 }
 210
 211 /**
 212   Converts a decimal value to a Null-terminated Unicode string.
 213
 214   Converts the decimal number specified by Value to a Null-terminated Unicode
 215   string specified by Buffer containing at most Width characters. No padding of spaces
 216   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 217   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 218   If the conversion contains more than Width characters, then only the first
 219   Width characters are returned, and the total number of characters
 220   required to perform the conversion is returned.
 221   Additional conversion parameters are specified in Flags.
 222
 223   The Flags bit LEFT_JUSTIFY is always ignored.
 224   All conversions are left justified in Buffer.
 225   If Width is 0, PREFIX_ZERO is ignored in Flags.
 226   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 227   are inserted every 3rd digit starting from the right.
 228   If HEX_RADIX is set in Flags, then the output buffer will be
 229   formatted in hexadecimal format.
 230   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 231   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 232   then Buffer is padded with '0' characters so the combination of the optional '-'
 233   sign character, '0' characters, digit characters for Value, and the Null-terminator
 234   add up to Width characters.
 235   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 236   If Buffer is NULL, then ASSERT().
 237   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 238   If unsupported bits are set in Flags, then ASSERT().
 239   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 240   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 241
 242   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 243                   Unicode string.
 244   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 245   @param  Value   The 64-bit signed value to convert to a string.
 246   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 247                   the Null-terminator.
 248
 249   @return The number of Unicode characters in Buffer not including the Null-terminator.
 250
 251 **/
 252 UINTN
 253 EFIAPI
 254 UnicodeValueToString (
 255   IN OUT CHAR16  *Buffer,
 256   IN UINTN       Flags,
 257   IN INT64       Value,
 258   IN UINTN       Width
 259   )
 260 {
 261   ASSERT_UNICODE_BUFFER(Buffer);
 262   return BasePrintLibConvertValueToString ((CHAR8 *)Buffer, Flags, Value, Width, 2);
 263 }
 264
 265 /**
 266   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 267   ASCII format string and a VA_LIST argument list.
 268
 269   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 270   and BufferSize.
 271   The ASCII string is produced by parsing the format string specified by FormatString.
 272   Arguments are pulled from the variable argument list specified by Marker based on
 273   the contents of the format string.
 274   The number of ASCII characters in the produced output buffer is returned not including
 275   the Null-terminator.
 276   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 277
 278   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 279   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 280   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 281   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 282   ASSERT().
 283   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 284   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 285   Null-terminator, then ASSERT().
 286
 287   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 288                           ASCII string.
 289   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 290   @param  FormatString    Null-terminated ASCII format string.
 291   @param  Marker          VA_LIST marker for the variable argument list.
 292
 293   @return The number of ASCII characters in the produced output buffer not including the
 294           Null-terminator.
 295
 296 **/
 297 UINTN
 298 EFIAPI
 299 AsciiVSPrint (
 300   OUT CHAR8         *StartOfBuffer,
 301   IN  UINTN         BufferSize,
 302   IN  CONST CHAR8   *FormatString,
 303   IN  VA_LIST       Marker
 304   )
 305 {
 306   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, 0, FormatString, Marker);
 307 }
 308
 309 /**
 310   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 311   ASCII format string and  variable argument list.
 312
 313   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 314   and BufferSize.
 315   The ASCII string is produced by parsing the format string specified by FormatString.
 316   Arguments are pulled from the variable argument list based on the contents of the
 317   format string.
 318   The number of ASCII characters in the produced output buffer is returned not including
 319   the Null-terminator.
 320   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 321
 322   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 323   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 324   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 325   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 326   ASSERT().
 327   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 328   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 329   Null-terminator, then ASSERT().
 330
 331   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 332                           ASCII string.
 333   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 334   @param  FormatString    Null-terminated ASCII format string.
 335   @param  ...             Variable argument list whose contents are accessed based on the
 336                           format string specified by FormatString.
 337
 338   @return The number of ASCII characters in the produced output buffer not including the
 339           Null-terminator.
 340
 341 **/
 342 UINTN
 343 EFIAPI
 344 AsciiSPrint (
 345   OUT CHAR8        *StartOfBuffer,
 346   IN  UINTN        BufferSize,
 347   IN  CONST CHAR8  *FormatString,
 348   ...
 349   )
 350 {
 351   VA_LIST Marker;
 352
 353   VA_START (Marker, FormatString);
 354   return AsciiVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
 355 }
 356
 357 /**
 358   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 359   Unicode format string and a VA_LIST argument list.
 360
 361   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 362   and BufferSize.
 363   The ASCII string is produced by parsing the format string specified by FormatString.
 364   Arguments are pulled from the variable argument list specified by Marker based on
 365   the contents of the format string.
 366   The number of ASCII characters in the produced output buffer is returned not including
 367   the Null-terminator.
 368   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 369
 370   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 371   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 372   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 373   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 374   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 375   ASSERT().
 376   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 377   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 378   Null-terminator, then ASSERT().
 379
 380   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 381                           ASCII string.
 382   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 383   @param  FormatString    Null-terminated Unicode format string.
 384   @param  Marker          VA_LIST marker for the variable argument list.
 385
 386   @return The number of ASCII characters in the produced output buffer not including the
 387           Null-terminator.
 388
 389 **/
 390 UINTN
 391 EFIAPI
 392 AsciiVSPrintUnicodeFormat (
 393   OUT CHAR8         *StartOfBuffer,
 394   IN  UINTN         BufferSize,
 395   IN  CONST CHAR16  *FormatString,
 396   IN  VA_LIST       Marker
 397   )
 398 {
 399   ASSERT_UNICODE_BUFFER (FormatString);
 400   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, Marker);
 401 }
 402
 403 /**
 404   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 405   Unicode format string and  variable argument list.
 406
 407   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 408   and BufferSize.
 409   The ASCII string is produced by parsing the format string specified by FormatString.
 410   Arguments are pulled from the variable argument list based on the contents of the
 411   format string.
 412   The number of ASCII characters in the produced output buffer is returned not including
 413   the Null-terminator.
 414   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 415
 416   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 417   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 418   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 419   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 420   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 421   ASSERT().
 422   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 423   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 424   Null-terminator, then ASSERT().
 425
 426   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 427                           ASCII string.
 428   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 429   @param  FormatString    Null-terminated Unicode format string.
 430   @param  ...             Variable argument list whose contents are accessed based on the
 431                           format string specified by FormatString.
 432
 433   @return The number of ASCII characters in the produced output buffer not including the
 434           Null-terminator.
 435
 436 **/
 437 UINTN
 438 EFIAPI
 439 AsciiSPrintUnicodeFormat (
 440   OUT CHAR8         *StartOfBuffer,
 441   IN  UINTN         BufferSize,
 442   IN  CONST CHAR16  *FormatString,
 443   ...
 444   )
 445 {
 446   VA_LIST Marker;
 447
 448   VA_START (Marker, FormatString);
 449   return AsciiVSPrintUnicodeFormat (StartOfBuffer, BufferSize, FormatString, Marker);
 450 }
 451
 452
 453 /**
 454   Converts a decimal value to a Null-terminated ASCII string.
 455
 456   Converts the decimal number specified by Value to a Null-terminated ASCII string
 457   specified by Buffer containing at most Width characters. No padding of spaces
 458   is ever performed.
 459   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 460   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 461   If the conversion contains more than Width characters, then only the first Width
 462   characters are returned, and the total number of characters required to perform
 463   the conversion is returned.
 464   Additional conversion parameters are specified in Flags.
 465   The Flags bit LEFT_JUSTIFY is always ignored.
 466   All conversions are left justified in Buffer.
 467   If Width is 0, PREFIX_ZERO is ignored in Flags.
 468   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 469   are inserted every 3rd digit starting from the right.
 470   If HEX_RADIX is set in Flags, then the output buffer will be
 471   formatted in hexadecimal format.
 472   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 473   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 474   then Buffer is padded with '0' characters so the combination of the optional '-'
 475   sign character, '0' characters, digit characters for Value, and the Null-terminator
 476   add up to Width characters.
 477
 478   If Buffer is NULL, then ASSERT().
 479   If unsupported bits are set in Flags, then ASSERT().
 480   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 481   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 482
 483   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 484                   ASCII string.
 485   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 486   @param  Value   The 64-bit signed value to convert to a string.
 487   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 488                   the Null-terminator.
 489
 490   @return The number of ASCII characters in Buffer not including the Null-terminator.
 491
 492 **/
 493 UINTN
 494 EFIAPI
 495 AsciiValueToString (
 496   OUT CHAR8      *Buffer,
 497   IN  UINTN      Flags,
 498   IN  INT64      Value,
 499   IN  UINTN      Width
 500   )
 501 {
 502   return BasePrintLibConvertValueToString (Buffer, Flags, Value, Width, 1);
 503 }
 504