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 \91L\92 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 \930x\94.  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 \93mm/dd/yyyy  hh:mm\94, 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, hexidecimal, 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 Hexidecimal 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 a Null-terminated
 241   Unicode format string and variable 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 based on the contents of the format string.
 247   The number of Unicode characters in the produced output buffer is returned not including
 248   the Null-terminator.
 249   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 250
 251   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 252   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 253   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 254   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 255   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 256   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 257   ASSERT().
 258   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 259   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 260   Null-terminator, then ASSERT().
 261
 262   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 263                           Unicode string.
 264   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 265   @param  FormatString    Null-terminated Unicode format string.
 266   @param  ...             Variable argument list whose contents are accessed based on the
 267                           format string specified by FormatString.
 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 UnicodeSPrint (
 276   OUT CHAR16        *StartOfBuffer,
 277   IN  UINTN         BufferSize,
 278   IN  CONST CHAR16  *FormatString,
 279   ...
 280   );
 281
 282 /**
 283   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 284   ASCII format string and a VA_LIST 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 specified by Marker based on the
 290   contents of the format string.
 291   The number of Unicode characters in the produced output buffer is returned not including
 292   the Null-terminator.
 293   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 294
 295   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 296   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 297   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 298   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 299   PcdMaximumAsciiStringLength ASCII 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 ASCII format string.
 309   @param  Marker          VA_LIST marker for the variable argument list.
 310
 311   @return The number of Unicode characters in the produced output buffer not including the
 312           Null-terminator.
 313
 314 **/
 315 UINTN
 316 EFIAPI
 317 UnicodeVSPrintAsciiFormat (
 318   OUT CHAR16       *StartOfBuffer,
 319   IN  UINTN        BufferSize,
 320   IN  CONST CHAR8  *FormatString,
 321   IN  VA_LIST      Marker
 322   );
 323
 324 /**
 325   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 326   ASCII format string and  variable argument list.
 327
 328   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 329   and BufferSize.
 330   The Unicode string is produced by parsing the format string specified by FormatString.
 331   Arguments are pulled from the variable argument list based on the contents of the
 332   format string.
 333   The number of Unicode characters in the produced output buffer is returned not including
 334   the Null-terminator.
 335   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 336
 337   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 338   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 339   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 340   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 341   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 342   ASSERT().
 343   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 344   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 345   Null-terminator, then ASSERT().
 346
 347   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 348                           Unicode string.
 349   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 350   @param  FormatString    Null-terminated ASCII format string.
 351   @param  ...             Variable argument list whose contents are accessed based on the
 352                           format string specified by FormatString.
 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 UnicodeSPrintAsciiFormat (
 361   OUT CHAR16       *StartOfBuffer,
 362   IN  UINTN        BufferSize,
 363   IN  CONST CHAR8  *FormatString,
 364   ...
 365   );
 366
 367 /**
 368   Converts a decimal value to a Null-terminated Unicode string.
 369
 370   Converts the decimal number specified by Value to a Null-terminated Unicode
 371   string specified by Buffer containing at most Width characters. No padding of spaces
 372   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 373   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 374   If the conversion contains more than Width characters, then only the first
 375   Width characters are returned, and the total number of characters
 376   required to perform the conversion is returned.
 377   Additional conversion parameters are specified in Flags.
 378
 379   The Flags bit LEFT_JUSTIFY is always ignored.
 380   All conversions are left justified in Buffer.
 381   If Width is 0, PREFIX_ZERO is ignored in Flags.
 382   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 383   are inserted every 3rd digit starting from the right.
 384   If HEX_RADIX is set in Flags, then the output buffer will be
 385   formatted in hexadecimal format.
 386   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 387   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 388   then Buffer is padded with '0' characters so the combination of the optional '-'
 389   sign character, '0' characters, digit characters for Value, and the Null-terminator
 390   add up to Width characters.
 391   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 392   If Buffer is NULL, then ASSERT().
 393   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 394   If unsupported bits are set in Flags, then ASSERT().
 395   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 396   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 397
 398   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 399                   Unicode string.
 400   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 401   @param  Value   The 64-bit signed value to convert to a string.
 402   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 403                   the Null-terminator.
 404
 405   @return The number of Unicode characters in Buffer not including the Null-terminator.
 406
 407 **/
 408 UINTN
 409 EFIAPI
 410 UnicodeValueToString (
 411   IN OUT CHAR16  *Buffer,
 412   IN UINTN       Flags,
 413   IN INT64       Value,
 414   IN UINTN       Width
 415   );
 416
 417 /**
 418   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 419   ASCII format string and a VA_LIST argument list.
 420
 421   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 422   and BufferSize.
 423   The ASCII string is produced by parsing the format string specified by FormatString.
 424   Arguments are pulled from the variable argument list specified by Marker based on
 425   the contents of the format string.
 426   The number of ASCII characters in the produced output buffer is returned not including
 427   the Null-terminator.
 428   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 429
 430   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 431   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 432   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 433   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 434   ASSERT().
 435   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 436   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 437   Null-terminator, then ASSERT().
 438
 439   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 440                           ASCII string.
 441   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 442   @param  FormatString    Null-terminated ASCII format string.
 443   @param  Marker          VA_LIST marker for the variable argument list.
 444
 445   @return The number of ASCII characters in the produced output buffer not including the
 446           Null-terminator.
 447
 448 **/
 449 UINTN
 450 EFIAPI
 451 AsciiVSPrint (
 452   OUT CHAR8         *StartOfBuffer,
 453   IN  UINTN         BufferSize,
 454   IN  CONST CHAR8   *FormatString,
 455   IN  VA_LIST       Marker
 456   );
 457
 458 /**
 459   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 460   ASCII format string and  variable argument list.
 461
 462   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 463   and BufferSize.
 464   The ASCII string is produced by parsing the format string specified by FormatString.
 465   Arguments are pulled from the variable argument list based on the contents of the
 466   format string.
 467   The number of ASCII characters in the produced output buffer is returned not including
 468   the Null-terminator.
 469   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 470
 471   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 472   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 473   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 474   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 475   ASSERT().
 476   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 477   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 478   Null-terminator, then ASSERT().
 479
 480   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 481                           ASCII string.
 482   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 483   @param  FormatString    Null-terminated ASCII format string.
 484   @param  ...             Variable argument list whose contents are accessed based on the
 485                           format string specified by FormatString.
 486
 487   @return The number of ASCII characters in the produced output buffer not including the
 488           Null-terminator.
 489
 490 **/
 491 UINTN
 492 EFIAPI
 493 AsciiSPrint (
 494   OUT CHAR8        *StartOfBuffer,
 495   IN  UINTN        BufferSize,
 496   IN  CONST CHAR8  *FormatString,
 497   ...
 498   );
 499
 500 /**
 501   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 502   Unicode format string and a VA_LIST argument list.
 503
 504   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 505   and BufferSize.
 506   The ASCII string is produced by parsing the format string specified by FormatString.
 507   Arguments are pulled from the variable argument list specified by Marker based on
 508   the contents of the format string.
 509   The number of ASCII characters in the produced output buffer is returned not including
 510   the Null-terminator.
 511   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 512
 513   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 514   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 515   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 516   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 517   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 518   ASSERT().
 519   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 520   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 521   Null-terminator, then ASSERT().
 522
 523   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 524                           ASCII string.
 525   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 526   @param  FormatString    Null-terminated Unicode format string.
 527   @param  Marker          VA_LIST marker for the variable argument list.
 528
 529   @return The number of ASCII characters in the produced output buffer not including the
 530           Null-terminator.
 531
 532 **/
 533 UINTN
 534 EFIAPI
 535 AsciiVSPrintUnicodeFormat (
 536   OUT CHAR8         *StartOfBuffer,
 537   IN  UINTN         BufferSize,
 538   IN  CONST CHAR16  *FormatString,
 539   IN  VA_LIST       Marker
 540   );
 541
 542 /**
 543   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 544   Unicode format string and  variable argument list.
 545
 546   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 547   and BufferSize.
 548   The ASCII string is produced by parsing the format string specified by FormatString.
 549   Arguments are pulled from the variable argument list based on the contents of the
 550   format string.
 551   The number of ASCII characters in the produced output buffer is returned not including
 552   the Null-terminator.
 553   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 554
 555   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 556   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 557   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 558   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 559   PcdMaximumUnicodeStringLength Unicode 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 Unicode format string.
 569   @param  ...             Variable argument list whose contents are accessed based on the
 570                           format string specified by FormatString.
 571
 572   @return The number of ASCII characters in the produced output buffer not including the
 573           Null-terminator.
 574
 575 **/
 576 UINTN
 577 EFIAPI
 578 AsciiSPrintUnicodeFormat (
 579   OUT CHAR8         *StartOfBuffer,
 580   IN  UINTN         BufferSize,
 581   IN  CONST CHAR16  *FormatString,
 582   ...
 583   );
 584
 585 /**
 586   Converts a decimal value to a Null-terminated ASCII string.
 587
 588   Converts the decimal number specified by Value to a Null-terminated ASCII string
 589   specified by Buffer containing at most Width characters. No padding of spaces
 590   is ever performed.
 591   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 592   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 593   If the conversion contains more than Width characters, then only the first Width
 594   characters are returned, and the total number of characters required to perform
 595   the conversion is returned.
 596   Additional conversion parameters are specified in Flags.
 597   The Flags bit LEFT_JUSTIFY is always ignored.
 598   All conversions are left justified in Buffer.
 599   If Width is 0, PREFIX_ZERO is ignored in Flags.
 600   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 601   are inserted every 3rd digit starting from the right.
 602   If HEX_RADIX is set in Flags, then the output buffer will be
 603   formatted in hexadecimal format.
 604   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 605   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 606   then Buffer is padded with '0' characters so the combination of the optional '-'
 607   sign character, '0' characters, digit characters for Value, and the Null-terminator
 608   add up to Width characters.
 609
 610   If Buffer is NULL, then ASSERT().
 611   If unsupported bits are set in Flags, then ASSERT().
 612   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 613   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 614
 615   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 616                   ASCII string.
 617   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 618   @param  Value   The 64-bit signed value to convert to a string.
 619   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 620                   the Null-terminator.
 621
 622   @return The number of ASCII characters in Buffer not including the Null-terminator.
 623
 624 **/
 625 UINTN
 626 EFIAPI
 627 AsciiValueToString (
 628   OUT CHAR8      *Buffer,
 629   IN  UINTN      Flags,
 630   IN  INT64      Value,
 631   IN  UINTN      Width
 632   );
 633
 634 #endif