MdePkg/Include/Library/PrintLib.h

   1 /** @file
   2   Provides services to print a formatted string to a buffer. All combinations of
   3   Unicode and ASCII strings are supported.
   4
   5 Copyright (c) 2006 - 2008, Intel Corporation
   6 All rights reserved. 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   The Print Library functions provide a simple means to produce formatted output
  15   strings.  Many of the output functions use a format string to describe how to
  16   format the output of variable arguments.  The format string consists of normal
  17   text and argument descriptors.  There are no restrictions for how the normal
  18   text and argument descriptors can be mixed.  A normal text character '\n' must
  19   always be converted to '\n\r'.  This does not follow the ANSI C standard for
  20   sprint().  The format of argument descriptors is described below.  The ANSI C
  21   standard for sprint() has been followed for some of the format types, and has
  22   not been followed for others.  The exceptions are noted below.
  23
  24     %[flags][width][.precision]type
  25
  26   [flags]:
  27     - -
  28       - The field is left justified.  If not flag is not specified, then the
  29         field is right justified.
  30     - space
  31       - Prefix a space character to a number.  Only valid for types X, x, and d.
  32     - +
  33       - Prefix a plus character to a number.  Only valid for types X, x, and d.
  34         If both space and + are specified, then space is ignored.
  35     - 0
  36       - Pad with 0 characters to the left of a number.  Only valid for types
  37         X, x, and d.
  38     - ,
  39       - Place a comma every 3rd digit of the number.  Only valid for type d.
  40         If 0 is also specified, then 0 is ignored.
  41     - L, l
  42       - The number being printed is a UINT64.  Only valid for types X, x, and d.
  43         If this flag is not specified, then the number being printed is a int.
  44     - NOTE: All invalid flags are ignored.
  45
  46   [width]:
  47
  48     - *
  49       - The width of the field is specified by a UINTN argument in the
  50         argument list.
  51     - number
  52       - The number specified as a decimal value represents the width of
  53         the field.
  54     - NOTE: If [width] is not specified, then a field width of 0 is assumed.
  55
  56   [.precision]:
  57
  58     - *
  59       - The prevision of the field is specified by a UINTN argument in the
  60         argument list.
  61     - number
  62       - The number specified as a decimal value represents the precision of
  63         the field.
  64     - NOTE: If [.precision] is not specified, then a precision of 0 is assumed.
  65
  66   type:
  67
  68     - %
  69       - Print a %%.
  70     - c
  71       - The argument is a Unicode character.  ASCII characters can be printed
  72         using this type too by making sure bits 8..15 of the argument are set to 0.
  73     - x
  74       - The argument is a hexadecimal number.  The characters used are 0..9 and
  75         A..F.  If the flag 'L' is not specified, then the argument is assumed
  76         to be an int.  This does not follow ANSI C.
  77     - X
  78       - The argument is a hexadecimal number and the number is padded with
  79         zeros.  This is equivalent to a format string of "0x". If the flag
  80         'L' is not specified, then the argument is assumed to be an int.
  81         This does not follow ANSI C.
  82     - d
  83       - The argument is a decimal number.  If the flag 'L' is not specified,
  84         then the argument is assumed to be an int.
  85     - p
  86       - The argument is a pointer that is a (VOID *), and it is printed as a
  87         hexadecimal number  The characters used are 0..9 and A..F.
  88     - a
  89       - The argument is a pointer to an ASCII string.
  90         This does not follow ANSI C.
  91     - S, s
  92       - The argument is a pointer to a Unicode string.
  93         This does not follow ANSI C.
  94     - g
  95       - The argument is a pointer to a GUID structure.  The GUID is printed
  96         in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
  97         This does not follow ANSI C.
  98     - t
  99       - The argument is a pointer to an EFI_TIME structure.  The time and
 100         date are printed in the format "mm/dd/yyyy hh:mm" where mm is the
 101         month zero padded, dd is the day zero padded, yyyy is the year zero
 102         padded, hh is the hour zero padded, and mm is minutes zero padded.
 103         This does not follow ANSI C.
 104     - r
 105       - The argument is a RETURN_STATUS value.  This value is converted to
 106         a string following the table below.  This does not follow ANSI C.
 107       - RETURN_SUCCESS
 108         - "Success"
 109       - RETURN_LOAD_ERROR
 110         - "Load Error"
 111       - RETURN_INVALID_PARAMETER
 112         - "Invalid Parameter"
 113       - RETURN_UNSUPPORTED
 114         - "Unsupported"
 115       - RETURN_BAD_BUFFER_SIZE
 116         - "Bad Buffer Size"
 117       - RETURN_BUFFER_TOO_SMALL
 118         - "Buffer Too Small"
 119       - RETURN_NOT_READY
 120         - "Not Ready"
 121       - RETURN_DEVICE_ERROR
 122         - "Device Error"
 123       - RETURN_WRITE_PROTECTED
 124         - "Write Protected"
 125       - RETURN_OUT_OF_RESOURCES
 126         - "Out of Resources"
 127       - RETURN_VOLUME_CORRUPTED
 128         - "Volume Corrupt"
 129       - RETURN_VOLUME_FULL
 130         - "Volume Full"
 131       - RETURN_NO_MEDIA
 132         - "No Media"
 133       - RETURN_MEDIA_CHANGED
 134         - "Media changed"
 135       - RETURN_NOT_FOUND
 136         - "Not Found"
 137       - RETURN_ACCESS_DENIED
 138         - "Access Denied"
 139       - RETURN_NO_RESPONSE
 140         - "No Response"
 141       - RETURN_NO_MAPPING
 142         - "No mapping"
 143       - RETURN_TIMEOUT
 144         - "Time out"
 145       - RETURN_NOT_STARTED
 146         - "Not started"
 147       - RETURN_ALREADY_STARTED
 148         - "Already started"
 149       - RETURN_ABORTED
 150         - "Aborted"
 151       - RETURN_ICMP_ERROR
 152         - "ICMP Error"
 153       - RETURN_TFTP_ERROR
 154         - "TFTP Error"
 155       - RETURN_PROTOCOL_ERROR
 156         - "Protocol Error"
 157       - RETURN_WARN_UNKNOWN_GLYPH
 158         - "Warning Unknown Glyph"
 159       - RETURN_WARN_DELETE_FAILURE
 160         - "Warning Delete Failure"
 161       - RETURN_WARN_WRITE_FAILURE
 162         - "Warning Write Failure"
 163       - RETURN_WARN_BUFFER_TOO_SMALL
 164         - "Warning Buffer Too Small"
 165
 166 **/
 167
 168 #ifndef __PRINT_LIB_H__
 169 #define __PRINT_LIB_H__
 170
 171 ///
 172 /// Define the maximum number of characters that are required to
 173 /// encode a decimal, hexadecimal, GUID, or TIME value with a NULL
 174 /// terminator.
 175 ///
 176 ///  Maximum Length Decimal String     = 28
 177 ///    "-9,223,372,036,854,775,808"
 178 ///  Maximum Length Hexadecimal String = 17
 179 ///    "FFFFFFFFFFFFFFFF"
 180 ///  Maximum Length GUID               = 37
 181 ///    "00000000-0000-0000-0000-000000000000"
 182 ///  Maximum Length TIME               = 18
 183 ///    "12/12/2006  12:12"
 184 ///
 185 #define MAXIMUM_VALUE_CHARACTERS  38
 186
 187 ///
 188 /// Flags bitmask values use in UnicodeValueToString() and
 189 /// AsciiValueToString()
 190 ///
 191 #define LEFT_JUSTIFY      0x01
 192 #define COMMA_TYPE        0x08
 193 #define PREFIX_ZERO       0x20
 194 #define RADIX_HEX         0x80
 195
 196 /**
 197   Produces a Null-terminated Unicode string in an output buffer based on
 198   a Null-terminated Unicode format string and a VA_LIST argument list
 199
 200   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 201   and BufferSize.
 202   The Unicode string is produced by parsing the format string specified by FormatString.
 203   Arguments are pulled from the variable argument list specified by Marker based on the
 204   contents of the format string.
 205   The number of Unicode characters in the produced output buffer is returned not including
 206   the Null-terminator.
 207   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 208
 209   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 210   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 211   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 212   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 213   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 214   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 215   ASSERT().
 216   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 217   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 218   Null-terminator, then ASSERT().
 219
 220   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 221                           Unicode string.
 222   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 223   @param  FormatString    Null-terminated Unicode format string.
 224   @param  Marker          VA_LIST marker for the variable argument list.
 225
 226   @return The number of Unicode characters in the produced output buffer not including the
 227           Null-terminator.
 228
 229 **/
 230 UINTN
 231 EFIAPI
 232 UnicodeVSPrint (
 233   OUT CHAR16        *StartOfBuffer,
 234   IN  UINTN         BufferSize,
 235   IN  CONST CHAR16  *FormatString,
 236   IN  VA_LIST       Marker
 237   );
 238
 239 /**
 240   Produces a Null-terminated Unicode string in an output buffer based on
 241   a Null-terminated Unicode format string and a BASE_LIST argument list
 242
 243   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 244   and BufferSize.
 245   The Unicode string is produced by parsing the format string specified by FormatString.
 246   Arguments are pulled from the variable argument list specified by Marker based on the
 247   contents of the format string.
 248   The number of Unicode characters in the produced output buffer is returned not including
 249   the Null-terminator.
 250   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 251
 252   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 253   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 254   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 255   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 256   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 257   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 258   ASSERT().
 259   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 260   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 261   Null-terminator, then ASSERT().
 262
 263   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 264                           Unicode string.
 265   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 266   @param  FormatString    Null-terminated Unicode format string.
 267   @param  Marker          BASE_LIST marker for the variable argument list.
 268
 269   @return The number of Unicode characters in the produced output buffer not including the
 270           Null-terminator.
 271
 272 **/
 273 UINTN
 274 EFIAPI
 275 UnicodeBSPrint (
 276   OUT CHAR16        *StartOfBuffer,
 277   IN  UINTN         BufferSize,
 278   IN  CONST CHAR16  *FormatString,
 279   IN  BASE_LIST     Marker
 280   );
 281
 282 /**
 283   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 284   Unicode format string and variable argument list.
 285
 286   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 287   and BufferSize.
 288   The Unicode string is produced by parsing the format string specified by FormatString.
 289   Arguments are pulled from the variable argument list based on the contents of the format string.
 290   The number of Unicode characters in the produced output buffer is returned not including
 291   the Null-terminator.
 292   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 293
 294   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 295   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 296   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 297   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 298   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 299   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 300   ASSERT().
 301   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 302   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 303   Null-terminator, then ASSERT().
 304
 305   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 306                           Unicode string.
 307   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 308   @param  FormatString    Null-terminated Unicode format string.
 309   @param  ...             Variable argument list whose contents are accessed based on the
 310                           format string specified by FormatString.
 311
 312   @return The number of Unicode characters in the produced output buffer not including the
 313           Null-terminator.
 314
 315 **/
 316 UINTN
 317 EFIAPI
 318 UnicodeSPrint (
 319   OUT CHAR16        *StartOfBuffer,
 320   IN  UINTN         BufferSize,
 321   IN  CONST CHAR16  *FormatString,
 322   ...
 323   );
 324
 325 /**
 326   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 327   ASCII format string and a VA_LIST argument list
 328
 329   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 330   and BufferSize.
 331   The Unicode string is produced by parsing the format string specified by FormatString.
 332   Arguments are pulled from the variable argument list specified by Marker based on the
 333   contents of the format string.
 334   The number of Unicode characters in the produced output buffer is returned not including
 335   the Null-terminator.
 336   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 337
 338   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 339   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 340   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 341   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 342   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 343   ASSERT().
 344   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 345   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 346   Null-terminator, then ASSERT().
 347
 348   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 349                           Unicode string.
 350   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 351   @param  FormatString    Null-terminated ASCII format string.
 352   @param  Marker          VA_LIST marker for the variable argument list.
 353
 354   @return The number of Unicode characters in the produced output buffer not including the
 355           Null-terminator.
 356
 357 **/
 358 UINTN
 359 EFIAPI
 360 UnicodeVSPrintAsciiFormat (
 361   OUT CHAR16       *StartOfBuffer,
 362   IN  UINTN        BufferSize,
 363   IN  CONST CHAR8  *FormatString,
 364   IN  VA_LIST      Marker
 365   );
 366
 367 /**
 368   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 369   ASCII format string and a BASE_LIST argument list
 370
 371   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 372   and BufferSize.
 373   The Unicode string is produced by parsing the format string specified by FormatString.
 374   Arguments are pulled from the variable argument list specified by Marker based on the
 375   contents of the format string.
 376   The number of Unicode characters in the produced output buffer is returned not including
 377   the Null-terminator.
 378   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 379
 380   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 381   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 382   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 383   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 384   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 385   ASSERT().
 386   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 387   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 388   Null-terminator, then ASSERT().
 389
 390   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 391                           Unicode string.
 392   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 393   @param  FormatString    Null-terminated ASCII format string.
 394   @param  Marker          BASE_LIST marker for the variable argument list.
 395
 396   @return The number of Unicode characters in the produced output buffer not including the
 397           Null-terminator.
 398
 399 **/
 400 UINTN
 401 EFIAPI
 402 UnicodeBSPrintAsciiFormat (
 403   OUT CHAR16       *StartOfBuffer,
 404   IN  UINTN        BufferSize,
 405   IN  CONST CHAR8  *FormatString,
 406   IN  BASE_LIST    Marker
 407   );
 408
 409 /**
 410   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 411   ASCII format string and  variable argument list.
 412
 413   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 414   and BufferSize.
 415   The Unicode string is produced by parsing the format string specified by FormatString.
 416   Arguments are pulled from the variable argument list based on the contents of the
 417   format string.
 418   The number of Unicode characters in the produced output buffer is returned not including
 419   the Null-terminator.
 420   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 421
 422   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 423   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 424   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 425   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 426   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 427   ASSERT().
 428   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 429   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 430   Null-terminator, then ASSERT().
 431
 432   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 433                           Unicode string.
 434   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 435   @param  FormatString    Null-terminated ASCII format string.
 436   @param  ...             Variable argument list whose contents are accessed based on the
 437                           format string specified by FormatString.
 438
 439   @return The number of Unicode characters in the produced output buffer not including the
 440           Null-terminator.
 441
 442 **/
 443 UINTN
 444 EFIAPI
 445 UnicodeSPrintAsciiFormat (
 446   OUT CHAR16       *StartOfBuffer,
 447   IN  UINTN        BufferSize,
 448   IN  CONST CHAR8  *FormatString,
 449   ...
 450   );
 451
 452 /**
 453   Converts a decimal value to a Null-terminated Unicode string.
 454
 455   Converts the decimal number specified by Value to a Null-terminated Unicode
 456   string specified by Buffer containing at most Width characters. No padding of spaces
 457   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 458   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 459   If the conversion contains more than Width characters, then only the first
 460   Width characters are returned, and the total number of characters
 461   required to perform the conversion is returned.
 462   Additional conversion parameters are specified in Flags.
 463
 464   The Flags bit LEFT_JUSTIFY is always ignored.
 465   All conversions are left justified in Buffer.
 466   If Width is 0, PREFIX_ZERO is ignored in Flags.
 467   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 468   are inserted every 3rd digit starting from the right.
 469   If HEX_RADIX is set in Flags, then the output buffer will be
 470   formatted in hexadecimal format.
 471   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 472   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 473   then Buffer is padded with '0' characters so the combination of the optional '-'
 474   sign character, '0' characters, digit characters for Value, and the Null-terminator
 475   add up to Width characters.
 476   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 477   If Buffer is NULL, then ASSERT().
 478   If Buffer is not aligned on a 16-bit boundary, 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                   Unicode 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 Unicode characters to place in Buffer, not including
 488                   the Null-terminator.
 489
 490   @return The number of Unicode characters in Buffer not including the Null-terminator.
 491
 492 **/
 493 UINTN
 494 EFIAPI
 495 UnicodeValueToString (
 496   IN OUT CHAR16  *Buffer,
 497   IN UINTN       Flags,
 498   IN INT64       Value,
 499   IN UINTN       Width
 500   );
 501
 502 /**
 503   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 504   ASCII format string and a VA_LIST argument list.
 505
 506   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 507   and BufferSize.
 508   The ASCII string is produced by parsing the format string specified by FormatString.
 509   Arguments are pulled from the variable argument list specified by Marker based on
 510   the contents of the format string.
 511   The number of ASCII characters in the produced output buffer is returned not including
 512   the Null-terminator.
 513   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 514
 515   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 516   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 517   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 518   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 519   ASSERT().
 520   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 521   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 522   Null-terminator, then ASSERT().
 523
 524   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 525                           ASCII string.
 526   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 527   @param  FormatString    Null-terminated ASCII format string.
 528   @param  Marker          VA_LIST marker for the variable argument list.
 529
 530   @return The number of ASCII characters in the produced output buffer not including the
 531           Null-terminator.
 532
 533 **/
 534 UINTN
 535 EFIAPI
 536 AsciiVSPrint (
 537   OUT CHAR8         *StartOfBuffer,
 538   IN  UINTN         BufferSize,
 539   IN  CONST CHAR8   *FormatString,
 540   IN  VA_LIST       Marker
 541   );
 542
 543 /**
 544   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 545   ASCII format string and a BASE_LIST argument list.
 546
 547   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 548   and BufferSize.
 549   The ASCII string is produced by parsing the format string specified by FormatString.
 550   Arguments are pulled from the variable argument list specified by Marker based on
 551   the contents of the format string.
 552   The number of ASCII characters in the produced output buffer is returned not including
 553   the Null-terminator.
 554   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 555
 556   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 557   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 558   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 559   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 560   ASSERT().
 561   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 562   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 563   Null-terminator, then ASSERT().
 564
 565   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 566                           ASCII string.
 567   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 568   @param  FormatString    Null-terminated ASCII format string.
 569   @param  Marker          BASE_LIST marker for the variable argument list.
 570
 571   @return The number of ASCII characters in the produced output buffer not including the
 572           Null-terminator.
 573
 574 **/
 575 UINTN
 576 EFIAPI
 577 AsciiBSPrint (
 578   OUT CHAR8         *StartOfBuffer,
 579   IN  UINTN         BufferSize,
 580   IN  CONST CHAR8   *FormatString,
 581   IN  BASE_LIST     Marker
 582   );
 583
 584 /**
 585   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 586   ASCII format string and  variable argument list.
 587
 588   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 589   and BufferSize.
 590   The ASCII string is produced by parsing the format string specified by FormatString.
 591   Arguments are pulled from the variable argument list based on the contents of the
 592   format string.
 593   The number of ASCII characters in the produced output buffer is returned not including
 594   the Null-terminator.
 595   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 596
 597   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 598   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 599   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 600   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 601   ASSERT().
 602   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 603   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 604   Null-terminator, then ASSERT().
 605
 606   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 607                           ASCII string.
 608   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 609   @param  FormatString    Null-terminated ASCII format string.
 610   @param  ...             Variable argument list whose contents are accessed based on the
 611                           format string specified by FormatString.
 612
 613   @return The number of ASCII characters in the produced output buffer not including the
 614           Null-terminator.
 615
 616 **/
 617 UINTN
 618 EFIAPI
 619 AsciiSPrint (
 620   OUT CHAR8        *StartOfBuffer,
 621   IN  UINTN        BufferSize,
 622   IN  CONST CHAR8  *FormatString,
 623   ...
 624   );
 625
 626 /**
 627   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 628   Unicode format string and a VA_LIST argument list.
 629
 630   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 631   and BufferSize.
 632   The ASCII string is produced by parsing the format string specified by FormatString.
 633   Arguments are pulled from the variable argument list specified by Marker based on
 634   the contents of the format string.
 635   The number of ASCII characters in the produced output buffer is returned not including
 636   the Null-terminator.
 637   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 638
 639   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 640   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 641   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 642   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 643   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 644   ASSERT().
 645   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 646   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 647   Null-terminator, then ASSERT().
 648
 649   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 650                           ASCII string.
 651   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 652   @param  FormatString    Null-terminated Unicode format string.
 653   @param  Marker          VA_LIST marker for the variable argument list.
 654
 655   @return The number of ASCII characters in the produced output buffer not including the
 656           Null-terminator.
 657
 658 **/
 659 UINTN
 660 EFIAPI
 661 AsciiVSPrintUnicodeFormat (
 662   OUT CHAR8         *StartOfBuffer,
 663   IN  UINTN         BufferSize,
 664   IN  CONST CHAR16  *FormatString,
 665   IN  VA_LIST       Marker
 666   );
 667
 668 /**
 669   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 670   Unicode format string and a BASE_LIST argument list.
 671
 672   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 673   and BufferSize.
 674   The ASCII string is produced by parsing the format string specified by FormatString.
 675   Arguments are pulled from the variable argument list specified by Marker based on
 676   the contents of the format string.
 677   The number of ASCII characters in the produced output buffer is returned not including
 678   the Null-terminator.
 679   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 680
 681   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 682   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 683   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 684   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 685   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 686   ASSERT().
 687   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 688   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 689   Null-terminator, then ASSERT().
 690
 691   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 692                           ASCII string.
 693   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 694   @param  FormatString    Null-terminated Unicode format string.
 695   @param  Marker          BASE_LIST marker for the variable argument list.
 696
 697   @return The number of ASCII characters in the produced output buffer not including the
 698           Null-terminator.
 699
 700 **/
 701 UINTN
 702 EFIAPI
 703 AsciiBSPrintUnicodeFormat (
 704   OUT CHAR8         *StartOfBuffer,
 705   IN  UINTN         BufferSize,
 706   IN  CONST CHAR16  *FormatString,
 707   IN  BASE_LIST     Marker
 708   );
 709
 710 /**
 711   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 712   Unicode format string and  variable argument list.
 713
 714   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 715   and BufferSize.
 716   The ASCII string is produced by parsing the format string specified by FormatString.
 717   Arguments are pulled from the variable argument list based on the contents of the
 718   format string.
 719   The number of ASCII characters in the produced output buffer is returned not including
 720   the Null-terminator.
 721   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 722
 723   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 724   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 725   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 726   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 727   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 728   ASSERT().
 729   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 730   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 731   Null-terminator, then ASSERT().
 732
 733   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 734                           ASCII string.
 735   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 736   @param  FormatString    Null-terminated Unicode format string.
 737   @param  ...             Variable argument list whose contents are accessed based on the
 738                           format string specified by FormatString.
 739
 740   @return The number of ASCII characters in the produced output buffer not including the
 741           Null-terminator.
 742
 743 **/
 744 UINTN
 745 EFIAPI
 746 AsciiSPrintUnicodeFormat (
 747   OUT CHAR8         *StartOfBuffer,
 748   IN  UINTN         BufferSize,
 749   IN  CONST CHAR16  *FormatString,
 750   ...
 751   );
 752
 753 /**
 754   Converts a decimal value to a Null-terminated ASCII string.
 755
 756   Converts the decimal number specified by Value to a Null-terminated ASCII string
 757   specified by Buffer containing at most Width characters. No padding of spaces
 758   is ever performed.
 759   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 760   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 761   If the conversion contains more than Width characters, then only the first Width
 762   characters are returned, and the total number of characters required to perform
 763   the conversion is returned.
 764   Additional conversion parameters are specified in Flags.
 765   The Flags bit LEFT_JUSTIFY is always ignored.
 766   All conversions are left justified in Buffer.
 767   If Width is 0, PREFIX_ZERO is ignored in Flags.
 768   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 769   are inserted every 3rd digit starting from the right.
 770   If HEX_RADIX is set in Flags, then the output buffer will be
 771   formatted in hexadecimal format.
 772   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 773   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 774   then Buffer is padded with '0' characters so the combination of the optional '-'
 775   sign character, '0' characters, digit characters for Value, and the Null-terminator
 776   add up to Width characters.
 777
 778   If Buffer is NULL, then ASSERT().
 779   If unsupported bits are set in Flags, then ASSERT().
 780   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 781   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 782
 783   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 784                   ASCII string.
 785   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 786   @param  Value   The 64-bit signed value to convert to a string.
 787   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 788                   the Null-terminator.
 789
 790   @return The number of ASCII characters in Buffer not including the Null-terminator.
 791
 792 **/
 793 UINTN
 794 EFIAPI
 795 AsciiValueToString (
 796   OUT CHAR8      *Buffer,
 797   IN  UINTN      Flags,
 798   IN  INT64      Value,
 799   IN  UINTN      Width
 800   );
 801
 802 #endif