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   @return The number of Unicode characters in the produced output buffer not including the
  97           Null-terminator.
  98
  99 **/
 100 UINTN
 101 EFIAPI
 102 UnicodeSPrint (
 103   OUT CHAR16        *StartOfBuffer,
 104   IN  UINTN         BufferSize,
 105   IN  CONST CHAR16  *FormatString,
 106   ...
 107   )
 108 {
 109   VA_LIST Marker;
 110
 111   VA_START (Marker, FormatString);
 112   return UnicodeVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
 113 }
 114
 115 /**
 116   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 117   ASCII format string and a VA_LIST argument list
 118
 119   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 120   and BufferSize.
 121   The Unicode string is produced by parsing the format string specified by FormatString.
 122   Arguments are pulled from the variable argument list specified by Marker based on the
 123   contents of the format string.
 124   The number of Unicode characters in the produced output buffer is returned not including
 125   the Null-terminator.
 126   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 127
 128   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 129   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 130   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 131   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 132   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 133   ASSERT().
 134   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 135   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 136   Null-terminator, then ASSERT().
 137
 138   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 139                           Unicode string.
 140   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 141   @param  FormatString    Null-terminated ASCII format string.
 142   @param  Marker          VA_LIST marker for the variable argument list.
 143
 144   @return The number of Unicode characters in the produced output buffer not including the
 145           Null-terminator.
 146
 147 **/
 148 UINTN
 149 EFIAPI
 150 UnicodeVSPrintAsciiFormat (
 151   OUT CHAR16       *StartOfBuffer,
 152   IN  UINTN        BufferSize,
 153   IN  CONST CHAR8  *FormatString,
 154   IN  VA_LIST      Marker
 155   )
 156 {
 157   ASSERT_UNICODE_BUFFER(StartOfBuffer);
 158   return BasePrintLibVSPrint ((CHAR8 *)StartOfBuffer, BufferSize >> 1, OUTPUT_UNICODE,FormatString, Marker);
 159 }
 160
 161 /**
 162   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 163   ASCII format string and  variable argument list.
 164
 165   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 166   and BufferSize.
 167   The Unicode string is produced by parsing the format string specified by FormatString.
 168   Arguments are pulled from the variable argument list based on the contents of the
 169   format string.
 170   The number of Unicode characters in the produced output buffer is returned not including
 171   the Null-terminator.
 172   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 173
 174   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 175   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
 176   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 177   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 178   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 179   ASSERT().
 180   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 181   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 182   Null-terminator, then ASSERT().
 183
 184   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 185                           Unicode string.
 186   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 187   @param  FormatString    Null-terminated ASCII format string.
 188   @param  ...             Variable argument list whose contents are accessed based on the
 189                           format string specified by FormatString.
 190
 191   @return The number of Unicode characters in the produced output buffer not including the
 192           Null-terminator.
 193
 194 **/
 195 UINTN
 196 EFIAPI
 197 UnicodeSPrintAsciiFormat (
 198   OUT CHAR16       *StartOfBuffer,
 199   IN  UINTN        BufferSize,
 200   IN  CONST CHAR8  *FormatString,
 201   ...
 202   )
 203 {
 204   VA_LIST Marker;
 205
 206   VA_START (Marker, FormatString);
 207   return UnicodeVSPrintAsciiFormat (StartOfBuffer, BufferSize, FormatString, Marker);
 208 }
 209
 210 /**
 211   Converts a decimal value to a Null-terminated Unicode string.
 212
 213   Converts the decimal number specified by Value to a Null-terminated Unicode
 214   string specified by Buffer containing at most Width characters. No padding of spaces
 215   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 216   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 217   If the conversion contains more than Width characters, then only the first
 218   Width characters are returned, and the total number of characters
 219   required to perform the conversion is returned.
 220   Additional conversion parameters are specified in Flags.
 221
 222   The Flags bit LEFT_JUSTIFY is always ignored.
 223   All conversions are left justified in Buffer.
 224   If Width is 0, PREFIX_ZERO is ignored in Flags.
 225   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 226   are inserted every 3rd digit starting from the right.
 227   If HEX_RADIX is set in Flags, then the output buffer will be
 228   formatted in hexadecimal format.
 229   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 230   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 231   then Buffer is padded with '0' characters so the combination of the optional '-'
 232   sign character, '0' characters, digit characters for Value, and the Null-terminator
 233   add up to Width characters.
 234   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 235   If Buffer is NULL, then ASSERT().
 236   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 237   If unsupported bits are set in Flags, then ASSERT().
 238   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 239   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 240
 241   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 242                   Unicode string.
 243   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 244   @param  Value   The 64-bit signed value to convert to a string.
 245   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 246                   the Null-terminator.
 247
 248   @return The number of Unicode characters in Buffer not including the Null-terminator.
 249
 250 **/
 251 UINTN
 252 EFIAPI
 253 UnicodeValueToString (
 254   IN OUT CHAR16  *Buffer,
 255   IN UINTN       Flags,
 256   IN INT64       Value,
 257   IN UINTN       Width
 258   )
 259 {
 260   ASSERT_UNICODE_BUFFER(Buffer);
 261   return BasePrintLibConvertValueToString ((CHAR8 *)Buffer, Flags, Value, Width, 2);
 262 }
 263
 264 /**
 265   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 266   ASCII format string and a VA_LIST argument list.
 267
 268   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 269   and BufferSize.
 270   The ASCII string is produced by parsing the format string specified by FormatString.
 271   Arguments are pulled from the variable argument list specified by Marker based on
 272   the contents of the format string.
 273   The number of ASCII characters in the produced output buffer is returned not including
 274   the Null-terminator.
 275   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 276
 277   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 278   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 279   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 280   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 281   ASSERT().
 282   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 283   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 284   Null-terminator, then ASSERT().
 285
 286   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 287                           ASCII string.
 288   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 289   @param  FormatString    Null-terminated ASCII format string.
 290   @param  Marker          VA_LIST marker for the variable argument list.
 291
 292   @return The number of ASCII characters in the produced output buffer not including the
 293           Null-terminator.
 294
 295 **/
 296 UINTN
 297 EFIAPI
 298 AsciiVSPrint (
 299   OUT CHAR8         *StartOfBuffer,
 300   IN  UINTN         BufferSize,
 301   IN  CONST CHAR8   *FormatString,
 302   IN  VA_LIST       Marker
 303   )
 304 {
 305   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, 0, FormatString, Marker);
 306 }
 307
 308 /**
 309   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 310   ASCII format string and  variable argument list.
 311
 312   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 313   and BufferSize.
 314   The ASCII string is produced by parsing the format string specified by FormatString.
 315   Arguments are pulled from the variable argument list based on the contents of the
 316   format string.
 317   The number of ASCII characters in the produced output buffer is returned not including
 318   the Null-terminator.
 319   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 320
 321   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 322   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 323   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 324   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 325   ASSERT().
 326   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 327   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 328   Null-terminator, then ASSERT().
 329
 330   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 331                           ASCII string.
 332   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 333   @param  FormatString    Null-terminated ASCII format string.
 334   @param  ...             Variable argument list whose contents are accessed based on the
 335                           format string specified by FormatString.
 336
 337   @return The number of ASCII characters in the produced output buffer not including the
 338           Null-terminator.
 339
 340 **/
 341 UINTN
 342 EFIAPI
 343 AsciiSPrint (
 344   OUT CHAR8        *StartOfBuffer,
 345   IN  UINTN        BufferSize,
 346   IN  CONST CHAR8  *FormatString,
 347   ...
 348   )
 349 {
 350   VA_LIST Marker;
 351
 352   VA_START (Marker, FormatString);
 353   return AsciiVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
 354 }
 355
 356 /**
 357   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 358   Unicode format string and a VA_LIST argument list.
 359
 360   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 361   and BufferSize.
 362   The ASCII string is produced by parsing the format string specified by FormatString.
 363   Arguments are pulled from the variable argument list specified by Marker based on
 364   the contents of the format string.
 365   The number of ASCII characters in the produced output buffer is returned not including
 366   the Null-terminator.
 367   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 368
 369   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 370   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 371   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 372   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 373   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 374   ASSERT().
 375   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 376   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 377   Null-terminator, then ASSERT().
 378
 379   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 380                           ASCII string.
 381   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 382   @param  FormatString    Null-terminated Unicode format string.
 383   @param  Marker          VA_LIST marker for the variable argument list.
 384
 385   @return The number of ASCII characters in the produced output buffer not including the
 386           Null-terminator.
 387
 388 **/
 389 UINTN
 390 EFIAPI
 391 AsciiVSPrintUnicodeFormat (
 392   OUT CHAR8         *StartOfBuffer,
 393   IN  UINTN         BufferSize,
 394   IN  CONST CHAR16  *FormatString,
 395   IN  VA_LIST       Marker
 396   )
 397 {
 398   ASSERT_UNICODE_BUFFER (FormatString);
 399   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, Marker);
 400 }
 401
 402 /**
 403   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 404   Unicode format string and  variable argument list.
 405
 406   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 407   and BufferSize.
 408   The ASCII string is produced by parsing the format string specified by FormatString.
 409   Arguments are pulled from the variable argument list based on the contents of the
 410   format string.
 411   The number of ASCII characters in the produced output buffer is returned not including
 412   the Null-terminator.
 413   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 414
 415   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 416   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 417   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
 418   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 419   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 420   ASSERT().
 421   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 422   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 423   Null-terminator, then ASSERT().
 424
 425   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 426                           ASCII string.
 427   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 428   @param  FormatString    Null-terminated Unicode format string.
 429   @param  ...             Variable argument list whose contents are accessed based on the
 430                           format string specified by FormatString.
 431
 432   @return The number of ASCII characters in the produced output buffer not including the
 433           Null-terminator.
 434
 435 **/
 436 UINTN
 437 EFIAPI
 438 AsciiSPrintUnicodeFormat (
 439   OUT CHAR8         *StartOfBuffer,
 440   IN  UINTN         BufferSize,
 441   IN  CONST CHAR16  *FormatString,
 442   ...
 443   )
 444 {
 445   VA_LIST Marker;
 446
 447   VA_START (Marker, FormatString);
 448   return AsciiVSPrintUnicodeFormat (StartOfBuffer, BufferSize, FormatString, Marker);
 449 }
 450
 451
 452 /**
 453   Converts a decimal value to a Null-terminated ASCII string.
 454
 455   Converts the decimal number specified by Value to a Null-terminated ASCII string
 456   specified by Buffer containing at most Width characters. No padding of spaces
 457   is ever performed.
 458   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 459   The number of ASCII characters in Buffer is returned not including the Null-terminator.
 460   If the conversion contains more than Width characters, then only the first Width
 461   characters are returned, and the total number of characters required to perform
 462   the conversion is returned.
 463   Additional conversion parameters are specified in Flags.
 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
 477   If Buffer is NULL, then ASSERT().
 478   If unsupported bits are set in Flags, then ASSERT().
 479   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 480   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 481
 482   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 483                   ASCII string.
 484   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 485   @param  Value   The 64-bit signed value to convert to a string.
 486   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
 487                   the Null-terminator.
 488
 489   @return The number of ASCII characters in Buffer not including the Null-terminator.
 490
 491 **/
 492 UINTN
 493 EFIAPI
 494 AsciiValueToString (
 495   OUT CHAR8      *Buffer,
 496   IN  UINTN      Flags,
 497   IN  INT64      Value,
 498   IN  UINTN      Width
 499   )
 500 {
 501   return BasePrintLibConvertValueToString (Buffer, Flags, Value, Width, 1);
 502 }
 503