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