MdePkg/Library/BasePrintLib/PrintLib.c

   1 /** @file
   2   Print Library.
   3
   4   Copyright (c) 2006 - 2007, 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   Module Name:  PrintLib.c
  14
  15 **/
  16
  17 #include "PrintLibInternal.h"
  18
  19 #define WARNING_STATUS_NUMBER          4
  20 #define ERROR_STATUS_NUMBER            24
  21
  22 GLOBAL_REMOVE_IF_UNREFERENCED CONST CHAR8 *StatusString [] = {
  23   "Success",                      //  RETURN_SUCCESS                = 0
  24   "Warning Unknown Glyph",        //  RETURN_WARN_UNKNOWN_GLYPH     = 1
  25   "Warning Delete Failure",       //  RETURN_WARN_DELETE_FAILURE    = 2
  26   "Warning Write Failure",        //  RETURN_WARN_WRITE_FAILURE     = 3
  27   "Warning Buffer Too Small",     //  RETURN_WARN_BUFFER_TOO_SMALL  = 4
  28   "Load Error",                   //  RETURN_LOAD_ERROR             = 1  | MAX_BIT
  29   "Invalid Parameter",            //  RETURN_INVALID_PARAMETER      = 2  | MAX_BIT
  30   "Unsupported",                  //  RETURN_UNSUPPORTED            = 3  | MAX_BIT
  31   "Bad Buffer Size",              //  RETURN_BAD_BUFFER_SIZE        = 4  | MAX_BIT
  32   "Buffer Too Small",             //  RETURN_BUFFER_TOO_SMALL,      = 5  | MAX_BIT
  33   "Not Ready",                    //  RETURN_NOT_READY              = 6  | MAX_BIT
  34   "Device Error",                 //  RETURN_DEVICE_ERROR           = 7  | MAX_BIT
  35   "Write Protected",              //  RETURN_WRITE_PROTECTED        = 8  | MAX_BIT
  36   "Out of Resources",             //  RETURN_OUT_OF_RESOURCES       = 9  | MAX_BIT
  37   "Volume Corrupt",               //  RETURN_VOLUME_CORRUPTED       = 10 | MAX_BIT
  38   "Volume Full",                  //  RETURN_VOLUME_FULL            = 11 | MAX_BIT
  39   "No Media",                     //  RETURN_NO_MEDIA               = 12 | MAX_BIT
  40   "Media changed",                //  RETURN_MEDIA_CHANGED          = 13 | MAX_BIT
  41   "Not Found",                    //  RETURN_NOT_FOUND              = 14 | MAX_BIT
  42   "Access Denied",                //  RETURN_ACCESS_DENIED          = 15 | MAX_BIT
  43   "No Response",                  //  RETURN_NO_RESPONSE            = 16 | MAX_BIT
  44   "No mapping",                   //  RETURN_NO_MAPPING             = 17 | MAX_BIT
  45   "Time out",                     //  RETURN_TIMEOUT                = 18 | MAX_BIT
  46   "Not started",                  //  RETURN_NOT_STARTED            = 19 | MAX_BIT
  47   "Already started",              //  RETURN_ALREADY_STARTED        = 20 | MAX_BIT
  48   "Aborted",                      //  RETURN_ABORTED                = 21 | MAX_BIT
  49   "ICMP Error",                   //  RETURN_ICMP_ERROR             = 22 | MAX_BIT
  50   "TFTP Error",                   //  RETURN_TFTP_ERROR             = 23 | MAX_BIT
  51   "Protocol Error"                //  RETURN_PROTOCOL_ERROR         = 24 | MAX_BIT
  52 };
  53
  54 /**
  55   Worker function that produces a Null-terminated string in an output buffer
  56   based on a Null-terminated format string and a VA_LIST argument list.
  57
  58   VSPrint function to process format and place the results in Buffer. Since a
  59   VA_LIST is used this rountine allows the nesting of Vararg routines. Thus
  60   this is the main print working routine.
  61
  62   @param  Buffer      Character buffer to print the results of the parsing
  63                       of Format into.
  64   @param  BufferSize  Maximum number of characters to put into buffer.
  65   @param  Flags       Intial flags value.
  66                       Can only have FORMAT_UNICODE and OUTPUT_UNICODE set.
  67   @param  Format      Null-terminated format string.
  68   @param  Marker      Vararg list consumed by processing Format.
  69
  70   @return Number of characters printed not including the Null-terminator.
  71
  72 **/
  73 UINTN
  74 BasePrintLibVSPrint (
  75   OUT CHAR8        *Buffer,
  76   IN  UINTN        BufferSize,
  77   IN  UINTN        Flags,
  78   IN  CONST CHAR8  *Format,
  79   IN  VA_LIST      Marker
  80   )
  81 {
  82   CHAR8           *OriginalBuffer;
  83   CHAR8           *EndBuffer;
  84   CHAR8           ValueBuffer[MAXIMUM_VALUE_CHARACTERS];
  85   UINTN           BytesPerOutputCharacter;
  86   UINTN           BytesPerFormatCharacter;
  87   UINTN           FormatMask;
  88   UINTN           FormatCharacter;
  89   UINTN           Width;
  90   UINTN           Precision;
  91   INT64           Value;
  92   CONST CHAR8     *ArgumentString;
  93   UINTN           Character;
  94   GUID            *TmpGuid;
  95   TIME            *TmpTime;
  96   UINTN           Count;
  97   UINTN           ArgumentMask;
  98   INTN            BytesPerArgumentCharacter;
  99   UINTN           ArgumentCharacter;
 100   BOOLEAN         Done;
 101   UINTN           Index;
 102   CHAR8           Prefix;
 103   BOOLEAN         ZeroPad;
 104   BOOLEAN         Comma;
 105   UINTN           Digits;
 106   UINTN           Radix;
 107   RETURN_STATUS   Status;
 108
 109   if (BufferSize == 0) {
 110     return 0;
 111   }
 112   ASSERT (Buffer != NULL);
 113
 114   if ((Flags & OUTPUT_UNICODE) != 0) {
 115     BytesPerOutputCharacter = 2;
 116   } else {
 117     BytesPerOutputCharacter = 1;
 118   }
 119
 120   //
 121   // Reserve space for the Null terminator.
 122   //
 123   BufferSize--;
 124   OriginalBuffer = Buffer;
 125   //
 126   // Set the tag for the end of the input Buffer.
 127   //
 128   EndBuffer      = Buffer + BufferSize * BytesPerOutputCharacter;
 129
 130   if ((Flags & FORMAT_UNICODE) != 0) {
 131     //
 132     // Make sure format string cannot contain more than PcdMaximumUnicodeStringLength
 133     // Unicode characters if PcdMaximumUnicodeStringLength is not zero.
 134     //
 135     ASSERT (StrSize ((CHAR16 *) Format) != 0);
 136     BytesPerFormatCharacter = 2;
 137     FormatMask = 0xffff;
 138   } else {
 139     //
 140     // Make sure format string cannot contain more than PcdMaximumAsciiStringLength
 141     // Ascii characters if PcdMaximumAsciiStringLength is not zero.
 142     //
 143     ASSERT (AsciiStrSize (Format) != 0);
 144     BytesPerFormatCharacter = 1;
 145     FormatMask = 0xff;
 146   }
 147
 148
 149
 150   //
 151   // Get the first character from the format string
 152   //
 153   FormatCharacter = (*Format | (*(Format + 1) << 8)) & FormatMask;
 154
 155   //
 156   // Loop until the end of the format string is reached or the output buffer is full
 157   //
 158   while (FormatCharacter != 0 && Buffer < EndBuffer) {
 159     //
 160     // Clear all the flag bits except those that may have been passed in
 161     //
 162     Flags &= (OUTPUT_UNICODE | FORMAT_UNICODE);
 163
 164     //
 165     // Set the default width to zero, and the default precision to 1
 166     //
 167     Width     = 0;
 168     Precision = 1;
 169     Prefix    = 0;
 170     Comma     = FALSE;
 171     ZeroPad   = FALSE;
 172     Count     = 0;
 173     Digits    = 0;
 174
 175     switch (FormatCharacter) {
 176     case '%':
 177       //
 178       // Parse Flags and Width
 179       //
 180       for (Done = FALSE; !Done; ) {
 181         Format += BytesPerFormatCharacter;
 182         FormatCharacter = (*Format | (*(Format + 1) << 8)) & FormatMask;
 183         switch (FormatCharacter) {
 184         case '.':
 185           Flags |= PRECISION;
 186           break;
 187         case '-':
 188           Flags |= LEFT_JUSTIFY;
 189           break;
 190         case '+':
 191           Flags |= PREFIX_SIGN;
 192           break;
 193         case ' ':
 194           Flags |= PREFIX_BLANK;
 195           break;
 196         case ',':
 197           Flags |= COMMA_TYPE;
 198           break;
 199         case 'L':
 200         case 'l':
 201           Flags |= LONG_TYPE;
 202           break;
 203         case '*':
 204           if ((Flags & PRECISION) == 0) {
 205             Flags |= PAD_TO_WIDTH;
 206             Width = VA_ARG (Marker, UINTN);
 207           } else {
 208             Precision = VA_ARG (Marker, UINTN);
 209           }
 210           break;
 211         case '0':
 212           if ((Flags & PRECISION) == 0) {
 213             Flags |= PREFIX_ZERO;
 214           }
 215         case '1':
 216         case '2':
 217         case '3':
 218         case '4':
 219         case '5':
 220         case '6':
 221         case '7':
 222         case '8':
 223         case '9':
 224           for (Count = 0; ((FormatCharacter >= '0') &&  (FormatCharacter <= '9')); ){
 225             Count = (Count * 10) + FormatCharacter - '0';
 226             Format += BytesPerFormatCharacter;
 227             FormatCharacter = (*Format | (*(Format + 1) << 8)) & FormatMask;
 228           }
 229           Format -= BytesPerFormatCharacter;
 230           if ((Flags & PRECISION) == 0) {
 231             Flags |= PAD_TO_WIDTH;
 232             Width = Count;
 233           } else {
 234             Precision = Count;
 235           }
 236           break;
 237
 238         case '\0':
 239           //
 240           // Make no output if Format string terminates unexpectedly when
 241           // looking up for flag, width, precision and type.
 242           //
 243           Format   -= BytesPerFormatCharacter;
 244           Precision = 0;
 245           //
 246           // break skipped on purpose.
 247           //
 248         default:
 249           Done = TRUE;
 250           break;
 251         }
 252       }
 253
 254       //
 255       // Handle each argument type
 256       //
 257       switch (FormatCharacter) {
 258       case 'p':
 259         //
 260         // Flag space, +, 0, L & l are invalid for type p.
 261         //
 262         Flags &= ~(PREFIX_BLANK | PREFIX_SIGN | PREFIX_ZERO | LONG_TYPE);
 263         if (sizeof (VOID *) > 4) {
 264           Flags |= LONG_TYPE;
 265         }
 266       case 'X':
 267         Flags |= PREFIX_ZERO;
 268         //
 269         // break skipped on purpose
 270         //
 271       case 'x':
 272         Flags |= RADIX_HEX;
 273         //
 274         // break skipped on purpose
 275         //
 276       case 'd':
 277         if ((Flags & LONG_TYPE) == 0) {
 278           Value = (VA_ARG (Marker, int));
 279         } else {
 280           Value = VA_ARG (Marker, INT64);
 281         }
 282         if ((Flags & PREFIX_BLANK) != 0) {
 283           Prefix = ' ';
 284         }
 285         if ((Flags & PREFIX_SIGN) != 0) {
 286           Prefix = '+';
 287         }
 288         if ((Flags & COMMA_TYPE) != 0) {
 289           Comma = TRUE;
 290         }
 291         if ((Flags & RADIX_HEX) == 0) {
 292           Radix = 10;
 293           if (Comma) {
 294             Flags &= (~PREFIX_ZERO);
 295             Precision = 1;
 296           }
 297           if (Value < 0) {
 298             Flags |= PREFIX_SIGN;
 299             Prefix = '-';
 300             Value = -Value;
 301           }
 302         } else {
 303           Radix = 16;
 304           Comma = FALSE;
 305           if ((Flags & LONG_TYPE) == 0 && Value < 0) {
 306             Value = (unsigned int)Value;
 307           }
 308         }
 309         //
 310         // Convert Value to a reversed string
 311         //
 312         Count = BasePrintLibValueToString (ValueBuffer, Value, Radix);
 313         if (Value == 0 && Precision == 0) {
 314           Count = 0;
 315         }
 316         ArgumentString = (CHAR8 *)ValueBuffer + Count;
 317
 318         Digits = Count % 3;
 319         if (Digits != 0) {
 320           Digits = 3 - Digits;
 321         }
 322         if (Comma && Count != 0) {
 323           Count += ((Count - 1) / 3);
 324         }
 325         if (Prefix != 0) {
 326           Count++;
 327           Precision++;
 328         }
 329         Flags |= ARGUMENT_REVERSED;
 330         ZeroPad = TRUE;
 331         if ((Flags & PREFIX_ZERO) != 0) {
 332           if ((Flags & LEFT_JUSTIFY) == 0) {
 333             if ((Flags & PAD_TO_WIDTH) != 0) {
 334               if ((Flags & PRECISION) == 0) {
 335                 Precision = Width;
 336               }
 337             }
 338           }
 339         }
 340         break;
 341
 342       case 's':
 343       case 'S':
 344         Flags |= ARGUMENT_UNICODE;
 345         //
 346         // break skipped on purpose
 347         //
 348       case 'a':
 349         ArgumentString = (CHAR8 *)VA_ARG (Marker, CHAR8 *);
 350         if (ArgumentString == NULL) {
 351           Flags &= (~ARGUMENT_UNICODE);
 352           ArgumentString = "<null string>";
 353         }
 354         break;
 355
 356       case 'c':
 357         Character = VA_ARG (Marker, UINTN) & 0xffff;
 358         ArgumentString = (CHAR8 *)&Character;
 359         Flags |= ARGUMENT_UNICODE;
 360         break;
 361
 362       case 'g':
 363         TmpGuid = VA_ARG (Marker, GUID *);
 364         if (TmpGuid == NULL) {
 365           ArgumentString = "<null guid>";
 366         } else {
 367           BasePrintLibSPrint (
 368             ValueBuffer,
 369             MAXIMUM_VALUE_CHARACTERS,
 370             0,
 371             "%08x-%04x-%04x-%02x%02x-%02x%02x%02x%02x%02x%02x",
 372             TmpGuid->Data1,
 373             TmpGuid->Data2,
 374             TmpGuid->Data3,
 375             TmpGuid->Data4[0],
 376             TmpGuid->Data4[1],
 377             TmpGuid->Data4[2],
 378             TmpGuid->Data4[3],
 379             TmpGuid->Data4[4],
 380             TmpGuid->Data4[5],
 381             TmpGuid->Data4[6],
 382             TmpGuid->Data4[7]
 383             );
 384           ArgumentString = ValueBuffer;
 385         }
 386         break;
 387
 388       case 't':
 389         TmpTime = VA_ARG (Marker, TIME *);
 390         if (TmpTime == NULL) {
 391           ArgumentString = "<null time>";
 392         } else {
 393           BasePrintLibSPrint (
 394             ValueBuffer,
 395             MAXIMUM_VALUE_CHARACTERS,
 396             0,
 397             "%02d/%02d/%04d  %02d:%02d",
 398             TmpTime->Month,
 399             TmpTime->Day,
 400             TmpTime->Year,
 401             TmpTime->Hour,
 402             TmpTime->Minute
 403             );
 404           ArgumentString = ValueBuffer;
 405         }
 406         break;
 407
 408       case 'r':
 409         Status = VA_ARG (Marker, RETURN_STATUS);
 410         ArgumentString = ValueBuffer;
 411         if (RETURN_ERROR (Status)) {
 412           //
 413           // Clear error bit
 414           //
 415           Index = Status & ~MAX_BIT;
 416           if (Index > 0 && Index <= ERROR_STATUS_NUMBER) {
 417             ArgumentString = StatusString [Index + WARNING_STATUS_NUMBER];
 418           }
 419         } else {
 420           Index = Status;
 421           if (Index <= WARNING_STATUS_NUMBER) {
 422             ArgumentString = StatusString [Index];
 423           }
 424         }
 425         if (ArgumentString == ValueBuffer) {
 426           BasePrintLibSPrint ((CHAR8 *) ValueBuffer, MAXIMUM_VALUE_CHARACTERS, 0, "%08X", Status);
 427         }
 428         break;
 429
 430       case '\n':
 431         ArgumentString = "\n\r";
 432         break;
 433
 434       case '%':
 435       default:
 436         //
 437         // if the type is '%' or unknown, then print it to the screen
 438         //
 439         ArgumentString = (CHAR8 *)&FormatCharacter;
 440         Flags |= ARGUMENT_UNICODE;
 441         break;
 442       }
 443       break;
 444
 445     case '\n':
 446       ArgumentString = "\n\r";
 447       break;
 448
 449     default:
 450       ArgumentString = (CHAR8 *)&FormatCharacter;
 451       Flags |= ARGUMENT_UNICODE;
 452       break;
 453     }
 454
 455     //
 456     // Retrieve the ArgumentString attriubutes
 457     //
 458     if ((Flags & ARGUMENT_UNICODE) != 0) {
 459       ArgumentMask = 0xffff;
 460       BytesPerArgumentCharacter = 2;
 461     } else {
 462       ArgumentMask = 0xff;
 463       BytesPerArgumentCharacter = 1;
 464     }
 465     if ((Flags & ARGUMENT_REVERSED) != 0) {
 466       BytesPerArgumentCharacter = -BytesPerArgumentCharacter;
 467     } else {
 468       //
 469       // Compute the number of characters in ArgumentString and store it in Count
 470       // ArgumentString is either null-terminated, or it contains Precision characters
 471       //
 472       for (Count = 0; Count < Precision || ((Flags & PRECISION) == 0); Count++) {
 473         ArgumentCharacter = ((ArgumentString[Count * BytesPerArgumentCharacter] & 0xff) | ((ArgumentString[Count * BytesPerArgumentCharacter + 1]) << 8)) & ArgumentMask;
 474         if (ArgumentCharacter == 0) {
 475           break;
 476         }
 477       }
 478     }
 479
 480     if (Precision < Count) {
 481       Precision = Count;
 482     }
 483
 484     //
 485     // Pad before the string
 486     //
 487     if ((Flags & (PAD_TO_WIDTH | LEFT_JUSTIFY)) == (PAD_TO_WIDTH)) {
 488       Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, Width - Precision, ' ', BytesPerOutputCharacter);
 489     }
 490
 491     if (ZeroPad) {
 492       if (Prefix != 0) {
 493         Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, 1, Prefix, BytesPerOutputCharacter);
 494       }
 495       Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, Precision - Count, '0', BytesPerOutputCharacter);
 496     } else {
 497       Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, Precision - Count, ' ', BytesPerOutputCharacter);
 498       if (Prefix != 0) {
 499         Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, 1, Prefix, BytesPerOutputCharacter);
 500       }
 501     }
 502
 503     //
 504     // Output the Prefix character if it is present
 505     //
 506     Index = 0;
 507     if (Prefix != 0) {
 508       Index++;
 509     }
 510
 511     //
 512     // Copy the string into the output buffer performing the required type conversions
 513     //
 514     while (Index < Count) {
 515       ArgumentCharacter = ((*ArgumentString & 0xff) | (*(ArgumentString + 1) << 8)) & ArgumentMask;
 516
 517       Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, 1, ArgumentCharacter, BytesPerOutputCharacter);
 518       ArgumentString    += BytesPerArgumentCharacter;
 519       Index++;
 520       if (Comma) {
 521         Digits++;
 522         if (Digits == 3) {
 523           Digits = 0;
 524           Index++;
 525           if (Index < Count) {
 526             Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, 1, ',', BytesPerOutputCharacter);
 527           }
 528         }
 529       }
 530     }
 531
 532     //
 533     // Pad after the string
 534     //
 535     if ((Flags & (PAD_TO_WIDTH | LEFT_JUSTIFY)) == (PAD_TO_WIDTH | LEFT_JUSTIFY)) {
 536       Buffer = BasePrintLibFillBuffer (Buffer, EndBuffer, Width - Precision, ' ', BytesPerOutputCharacter);
 537     }
 538
 539     //
 540     // Get the next character from the format string
 541     //
 542     Format += BytesPerFormatCharacter;
 543
 544     //
 545     // Get the next character from the format string
 546     //
 547     FormatCharacter = (*Format | (*(Format + 1) << 8)) & FormatMask;
 548   }
 549
 550   //
 551   // Null terminate the Unicode or ASCII string
 552   //
 553   BasePrintLibFillBuffer (Buffer, EndBuffer + BytesPerOutputCharacter, 1, 0, BytesPerOutputCharacter);
 554   //
 555   // Make sure output buffer cannot contain more than PcdMaximumUnicodeStringLength
 556   // Unicode characters if PcdMaximumUnicodeStringLength is not zero.
 557   //
 558   ASSERT ((((Flags & OUTPUT_UNICODE) == 0)) || (StrSize ((CHAR16 *) OriginalBuffer) != 0));
 559   //
 560   // Make sure output buffer cannot contain more than PcdMaximumAsciiStringLength
 561   // ASCII characters if PcdMaximumAsciiStringLength is not zero.
 562   //
 563   ASSERT ((((Flags & OUTPUT_UNICODE) != 0)) || (AsciiStrSize (OriginalBuffer) != 0));
 564
 565   return ((Buffer - OriginalBuffer) / BytesPerOutputCharacter);
 566 }
 567
 568 /**
 569   Worker function that produces a Null-terminated string in an output buffer
 570   based on a Null-terminated format string and variable argument list.
 571
 572   VSPrint function to process format and place the results in Buffer. Since a
 573   VA_LIST is used this rountine allows the nesting of Vararg routines. Thus
 574   this is the main print working routine.
 575
 576   @param  Buffer        Character buffer to print the results of the parsing
 577                         of Format into.
 578   @param  BufferSize    Maximum number of characters to put into buffer.
 579                         Zero means no limit.
 580   @param  Flags         Intial flags value.
 581                         Can only have FORMAT_UNICODE and OUTPUT_UNICODE set
 582   @param  FormatString  Null-terminated format string.
 583
 584   @return Number of characters printed not including the Null-terminator.
 585
 586 **/
 587 UINTN
 588 BasePrintLibSPrint (
 589   OUT CHAR8        *StartOfBuffer,
 590   IN  UINTN        BufferSize,
 591   IN  UINTN        Flags,
 592   IN  CONST CHAR8  *FormatString,
 593   ...
 594   )
 595 {
 596   VA_LIST  Marker;
 597
 598   VA_START (Marker, FormatString);
 599   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, Flags, FormatString, Marker);
 600 }
 601
 602 /**
 603   Produces a Null-terminated Unicode string in an output buffer based on
 604   a Null-terminated Unicode format string and a VA_LIST argument list
 605
 606   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 607   and BufferSize.
 608   The Unicode string is produced by parsing the format string specified by FormatString.
 609   Arguments are pulled from the variable argument list specified by Marker based on the
 610   contents of the format string.
 611   The number of Unicode characters in the produced output buffer is returned not including
 612   the Null-terminator.
 613   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 614
 615   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 616   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 617   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 618   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 619   ASSERT().
 620   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 621   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 622   Null-terminator, then ASSERT().
 623
 624   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 625                           Unicode string.
 626   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 627   @param  FormatString    Null-terminated Unicode format string.
 628   @param  Marker          VA_LIST marker for the variable argument list.
 629
 630   @return The number of Unicode characters in the produced output buffer not including the
 631           Null-terminator.
 632
 633 **/
 634 UINTN
 635 EFIAPI
 636 UnicodeVSPrint (
 637   OUT CHAR16        *StartOfBuffer,
 638   IN  UINTN         BufferSize,
 639   IN  CONST CHAR16  *FormatString,
 640   IN  VA_LIST       Marker
 641   )
 642 {
 643   return BasePrintLibVSPrint ((CHAR8 *)StartOfBuffer, BufferSize >> 1, FORMAT_UNICODE | OUTPUT_UNICODE, (CHAR8 *)FormatString, Marker);
 644 }
 645
 646 /**
 647   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 648   Unicode format string and variable argument list.
 649
 650   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 651   and BufferSize.
 652   The Unicode string is produced by parsing the format string specified by FormatString.
 653   Arguments are pulled from the variable argument list based on the contents of the format string.
 654   The number of Unicode characters in the produced output buffer is returned not including
 655   the Null-terminator.
 656   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 657
 658   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 659   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 660   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 661   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 662   ASSERT().
 663   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 664   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 665   Null-terminator, then ASSERT().
 666
 667   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 668                           Unicode string.
 669   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 670   @param  FormatString    Null-terminated Unicode format string.
 671
 672   @return The number of Unicode characters in the produced output buffer not including the
 673           Null-terminator.
 674
 675 **/
 676 UINTN
 677 EFIAPI
 678 UnicodeSPrint (
 679   OUT CHAR16        *StartOfBuffer,
 680   IN  UINTN         BufferSize,
 681   IN  CONST CHAR16  *FormatString,
 682   ...
 683   )
 684 {
 685   VA_LIST Marker;
 686
 687   VA_START (Marker, FormatString);
 688   return UnicodeVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
 689 }
 690
 691 /**
 692   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 693   ASCII format string and a VA_LIST argument list
 694
 695   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 696   and BufferSize.
 697   The Unicode string is produced by parsing the format string specified by FormatString.
 698   Arguments are pulled from the variable argument list specified by Marker based on the
 699   contents of the format string.
 700   The number of Unicode characters in the produced output buffer is returned not including
 701   the Null-terminator.
 702   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 703
 704   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 705   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 706   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 707   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 708   ASSERT().
 709   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 710   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 711   Null-terminator, then ASSERT().
 712
 713   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 714                           Unicode string.
 715   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 716   @param  FormatString    Null-terminated Unicode format string.
 717   @param  Marker          VA_LIST marker for the variable argument list.
 718
 719   @return The number of Unicode characters in the produced output buffer not including the
 720           Null-terminator.
 721
 722 **/
 723 UINTN
 724 EFIAPI
 725 UnicodeVSPrintAsciiFormat (
 726   OUT CHAR16       *StartOfBuffer,
 727   IN  UINTN        BufferSize,
 728   IN  CONST CHAR8  *FormatString,
 729   IN  VA_LIST      Marker
 730   )
 731 {
 732   return BasePrintLibVSPrint ((CHAR8 *)StartOfBuffer, BufferSize >> 1, OUTPUT_UNICODE,FormatString, Marker);
 733 }
 734
 735 /**
 736   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
 737   ASCII format string and  variable argument list.
 738
 739   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
 740   and BufferSize.
 741   The Unicode string is produced by parsing the format string specified by FormatString.
 742   Arguments are pulled from the variable argument list based on the contents of the
 743   format string.
 744   The number of Unicode characters in the produced output buffer is returned not including
 745   the Null-terminator.
 746   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
 747
 748   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
 749   If BufferSize > 1 and FormatString is NULL, then ASSERT().
 750   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 751   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 752   ASSERT().
 753   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
 754   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
 755   Null-terminator, then ASSERT().
 756
 757   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 758                           Unicode string.
 759   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 760   @param  FormatString    Null-terminated Unicode format string.
 761
 762   @return The number of Unicode characters in the produced output buffer not including the
 763           Null-terminator.
 764
 765 **/
 766 UINTN
 767 EFIAPI
 768 UnicodeSPrintAsciiFormat (
 769   OUT CHAR16       *StartOfBuffer,
 770   IN  UINTN        BufferSize,
 771   IN  CONST CHAR8  *FormatString,
 772   ...
 773   )
 774 {
 775   VA_LIST Marker;
 776
 777   VA_START (Marker, FormatString);
 778   return UnicodeVSPrintAsciiFormat (StartOfBuffer, BufferSize, FormatString, Marker);
 779 }
 780
 781 /**
 782   Converts a decimal value to a Null-terminated Unicode string.
 783
 784   Converts the decimal number specified by Value to a Null-terminated Unicode
 785   string specified by Buffer containing at most Width characters. No padding of spaces
 786   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
 787   The number of Unicode characters in Buffer is returned not including the Null-terminator.
 788   If the conversion contains more than Width characters, then only the first
 789   Width characters are returned, and the total number of characters
 790   required to perform the conversion is returned.
 791   Additional conversion parameters are specified in Flags.
 792
 793   The Flags bit LEFT_JUSTIFY is always ignored.
 794   All conversions are left justified in Buffer.
 795   If Width is 0, PREFIX_ZERO is ignored in Flags.
 796   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 797   are inserted every 3rd digit starting from the right.
 798   If HEX_RADIX is set in Flags, then the output buffer will be
 799   formatted in hexadecimal format.
 800   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
 801   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 802   then Buffer is padded with '0' characters so the combination of the optional '-'
 803   sign character, '0' characters, digit characters for Value, and the Null-terminator
 804   add up to Width characters.
 805   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 806   If Buffer is NULL, then ASSERT().
 807   If unsupported bits are set in Flags, then ASSERT().
 808   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
 809   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 810
 811   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
 812                   Unicode string.
 813   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
 814   @param  Value   The 64-bit signed value to convert to a string.
 815   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
 816                   the Null-terminator.
 817
 818   @return The number of Unicode characters in Buffer not including the Null-terminator.
 819
 820 **/
 821 UINTN
 822 EFIAPI
 823 UnicodeValueToString (
 824   IN OUT CHAR16  *Buffer,
 825   IN UINTN       Flags,
 826   IN INT64       Value,
 827   IN UINTN       Width
 828   )
 829 {
 830   return BasePrintLibConvertValueToString ((CHAR8 *)Buffer, Flags, Value, Width, 2);
 831 }
 832
 833 /**
 834   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 835   ASCII format string and a VA_LIST argument list.
 836
 837   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 838   and BufferSize.
 839   The ASCII string is produced by parsing the format string specified by FormatString.
 840   Arguments are pulled from the variable argument list specified by Marker based on
 841   the contents of the format string.
 842   The number of ASCII characters in the produced output buffer is returned not including
 843   the Null-terminator.
 844   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 845
 846   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 847   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 848   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 849   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 850   ASSERT().
 851   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 852   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 853   Null-terminator, then ASSERT().
 854
 855   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 856                           ASCII string.
 857   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 858   @param  FormatString    Null-terminated Unicode format string.
 859   @param  Marker          VA_LIST marker for the variable argument list.
 860
 861   @return The number of ASCII characters in the produced output buffer not including the
 862           Null-terminator.
 863
 864 **/
 865 UINTN
 866 EFIAPI
 867 AsciiVSPrint (
 868   OUT CHAR8         *StartOfBuffer,
 869   IN  UINTN         BufferSize,
 870   IN  CONST CHAR8   *FormatString,
 871   IN  VA_LIST       Marker
 872   )
 873 {
 874   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, 0, FormatString, Marker);
 875 }
 876
 877 /**
 878   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 879   ASCII format string and  variable argument list.
 880
 881   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 882   and BufferSize.
 883   The ASCII string is produced by parsing the format string specified by FormatString.
 884   Arguments are pulled from the variable argument list based on the contents of the
 885   format string.
 886   The number of ASCII characters in the produced output buffer is returned not including
 887   the Null-terminator.
 888   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 889
 890   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 891   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 892   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
 893   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
 894   ASSERT().
 895   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 896   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 897   Null-terminator, then ASSERT().
 898
 899   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 900                           ASCII string.
 901   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 902   @param  FormatString    Null-terminated Unicode format string.
 903
 904   @return The number of ASCII characters in the produced output buffer not including the
 905           Null-terminator.
 906
 907 **/
 908 UINTN
 909 EFIAPI
 910 AsciiSPrint (
 911   OUT CHAR8        *StartOfBuffer,
 912   IN  UINTN        BufferSize,
 913   IN  CONST CHAR8  *FormatString,
 914   ...
 915   )
 916 {
 917   VA_LIST Marker;
 918
 919   VA_START (Marker, FormatString);
 920   return AsciiVSPrint (StartOfBuffer, BufferSize, FormatString, Marker);
 921 }
 922
 923 /**
 924   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 925   ASCII format string and a VA_LIST argument list.
 926
 927   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 928   and BufferSize.
 929   The ASCII string is produced by parsing the format string specified by FormatString.
 930   Arguments are pulled from the variable argument list specified by Marker based on
 931   the contents of the format string.
 932   The number of ASCII characters in the produced output buffer is returned not including
 933   the Null-terminator.
 934   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 935
 936   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 937   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 938   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 939   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 940   ASSERT().
 941   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 942   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 943   Null-terminator, then ASSERT().
 944
 945   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 946                           ASCII string.
 947   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 948   @param  FormatString    Null-terminated Unicode format string.
 949   @param  Marker          VA_LIST marker for the variable argument list.
 950
 951   @return The number of ASCII characters in the produced output buffer not including the
 952           Null-terminator.
 953
 954 **/
 955 UINTN
 956 EFIAPI
 957 AsciiVSPrintUnicodeFormat (
 958   OUT CHAR8         *StartOfBuffer,
 959   IN  UINTN         BufferSize,
 960   IN  CONST CHAR16  *FormatString,
 961   IN  VA_LIST       Marker
 962   )
 963 {
 964   return BasePrintLibVSPrint (StartOfBuffer, BufferSize, FORMAT_UNICODE, (CHAR8 *)FormatString, Marker);
 965 }
 966
 967 /**
 968   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
 969   ASCII format string and  variable argument list.
 970
 971   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
 972   and BufferSize.
 973   The ASCII string is produced by parsing the format string specified by FormatString.
 974   Arguments are pulled from the variable argument list based on the contents of the
 975   format string.
 976   The number of ASCII characters in the produced output buffer is returned not including
 977   the Null-terminator.
 978   If BufferSize is 0, then no output buffer is produced and 0 is returned.
 979
 980   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
 981   If BufferSize > 0 and FormatString is NULL, then ASSERT().
 982   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
 983   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
 984   ASSERT().
 985   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
 986   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
 987   Null-terminator, then ASSERT().
 988
 989   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
 990                           ASCII string.
 991   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
 992   @param  FormatString    Null-terminated Unicode format string.
 993
 994   @return The number of ASCII characters in the produced output buffer not including the
 995           Null-terminator.
 996
 997 **/
 998 UINTN
 999 EFIAPI
1000 AsciiSPrintUnicodeFormat (
1001   OUT CHAR8         *StartOfBuffer,
1002   IN  UINTN         BufferSize,
1003   IN  CONST CHAR16  *FormatString,
1004   ...
1005   )
1006 {
1007   VA_LIST Marker;
1008
1009   VA_START (Marker, FormatString);
1010   return AsciiVSPrintUnicodeFormat (StartOfBuffer, BufferSize, FormatString, Marker);
1011 }
1012
1013
1014 /**
1015   Converts a decimal value to a Null-terminated ASCII string.
1016
1017   Converts the decimal number specified by Value to a Null-terminated ASCII string
1018   specified by Buffer containing at most Width characters. No padding of spaces
1019   is ever performed.
1020   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
1021   The number of ASCII characters in Buffer is returned not including the Null-terminator.
1022   If the conversion contains more than Width characters, then only the first Width
1023   characters are returned, and the total number of characters required to perform
1024   the conversion is returned.
1025   Additional conversion parameters are specified in Flags.
1026   The Flags bit LEFT_JUSTIFY is always ignored.
1027   All conversions are left justified in Buffer.
1028   If Width is 0, PREFIX_ZERO is ignored in Flags.
1029   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
1030   are inserted every 3rd digit starting from the right.
1031   If HEX_RADIX is set in Flags, then the output buffer will be
1032   formatted in hexadecimal format.
1033   If Value is < 0 and HEX_RADIX is not set in Flags, then the fist character in Buffer is a '-'.
1034   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
1035   then Buffer is padded with '0' characters so the combination of the optional '-'
1036   sign character, '0' characters, digit characters for Value, and the Null-terminator
1037   add up to Width characters.
1038
1039   If Buffer is NULL, then ASSERT().
1040   If unsupported bits are set in Flags, then ASSERT().
1041   If both COMMA_TYPE and HEX_RADIX are set in Flags, then ASSERT().
1042   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
1043
1044   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
1045                   ASCII string.
1046   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
1047   @param  Value   The 64-bit signed value to convert to a string.
1048   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
1049                   the Null-terminator.
1050
1051   @return The number of ASCII characters in Buffer not including the Null-terminator.
1052
1053 **/
1054 UINTN
1055 EFIAPI
1056 AsciiValueToString (
1057   IN OUT CHAR8  *Buffer,
1058   IN UINTN      Flags,
1059   IN INT64      Value,
1060   IN UINTN      Width
1061   )
1062 {
1063   return BasePrintLibConvertValueToString ((CHAR8 *)Buffer, Flags, Value, Width, 1);
1064 }
1065