MdePkg/Library/BasePrintLib/PrintLibInternal.h

   1 /** @file
   2   Base Print Library instance Internal Functions definition.
   3
   4   Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
   5   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 #ifndef __PRINT_LIB_INTERNAL_H__
  16 #define __PRINT_LIB_INTERNAL_H__
  17
  18 #include <Base.h>
  19 #include <Library/PrintLib.h>
  20 #include <Library/BaseLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/PcdLib.h>
  23
  24
  25 //
  26 // Print primitives
  27 //
  28 #define PREFIX_SIGN           BIT1
  29 #define PREFIX_BLANK          BIT2
  30 #define LONG_TYPE             BIT4
  31 #define OUTPUT_UNICODE        BIT6
  32 #define FORMAT_UNICODE        BIT8
  33 #define PAD_TO_WIDTH          BIT9
  34 #define ARGUMENT_UNICODE      BIT10
  35 #define PRECISION             BIT11
  36 #define ARGUMENT_REVERSED     BIT12
  37 #define COUNT_ONLY_NO_PRINT   BIT13
  38 #define UNSIGNED_TYPE         BIT14
  39
  40 //
  41 // Record date and time information
  42 //
  43 typedef struct {
  44   UINT16  Year;
  45   UINT8   Month;
  46   UINT8   Day;
  47   UINT8   Hour;
  48   UINT8   Minute;
  49   UINT8   Second;
  50   UINT8   Pad1;
  51   UINT32  Nanosecond;
  52   INT16   TimeZone;
  53   UINT8   Daylight;
  54   UINT8   Pad2;
  55 } TIME;
  56
  57 /**
  58   Worker function that produces a Null-terminated string in an output buffer
  59   based on a Null-terminated format string and a VA_LIST argument list.
  60
  61   VSPrint function to process format and place the results in Buffer. Since a
  62   VA_LIST is used this routine allows the nesting of Vararg routines. Thus
  63   this is the main print working routine.
  64
  65   If COUNT_ONLY_NO_PRINT is set in Flags, Buffer will not be modified at all.
  66
  67   @param[out] Buffer          The character buffer to print the results of the
  68                               parsing of Format into.
  69   @param[in]  BufferSize      The maximum number of characters to put into
  70                               buffer.
  71   @param[in]  Flags           Initial flags value.
  72                               Can only have FORMAT_UNICODE, OUTPUT_UNICODE,
  73                               and COUNT_ONLY_NO_PRINT set.
  74   @param[in]  Format          A Null-terminated format string.
  75   @param[in]  VaListMarker    VA_LIST style variable argument list consumed by
  76                               processing Format.
  77   @param[in]  BaseListMarker  BASE_LIST style variable argument list consumed
  78                               by processing Format.
  79
  80   @return The number of characters printed not including the Null-terminator.
  81           If COUNT_ONLY_NO_PRINT was set returns the same, but without any
  82           modification to Buffer.
  83
  84 **/
  85 UINTN
  86 BasePrintLibSPrintMarker (
  87   OUT CHAR8        *Buffer,
  88   IN  UINTN        BufferSize,
  89   IN  UINTN        Flags,
  90   IN  CONST CHAR8  *Format,
  91   IN  VA_LIST      VaListMarker,   OPTIONAL
  92   IN  BASE_LIST    BaseListMarker  OPTIONAL
  93   );
  94
  95 /**
  96   Worker function that produces a Null-terminated string in an output buffer
  97   based on a Null-terminated format string and variable argument list.
  98
  99   VSPrint function to process format and place the results in Buffer. Since a
 100   VA_LIST is used this routine allows the nesting of Vararg routines. Thus
 101   this is the main print working routine
 102
 103   @param  StartOfBuffer The character buffer to print the results of the parsing
 104                         of Format into.
 105   @param  BufferSize    The maximum number of characters to put into buffer.
 106                         Zero means no limit.
 107   @param  Flags         Initial flags value.
 108                         Can only have FORMAT_UNICODE and OUTPUT_UNICODE set
 109   @param  FormatString  Null-terminated format string.
 110   @param  ...           The variable argument list.
 111
 112   @return The number of characters printed.
 113
 114 **/
 115 UINTN
 116 EFIAPI
 117 BasePrintLibSPrint (
 118   OUT CHAR8        *StartOfBuffer,
 119   IN  UINTN        BufferSize,
 120   IN  UINTN        Flags,
 121   IN  CONST CHAR8  *FormatString,
 122   ...
 123   );
 124
 125 /**
 126   Internal function that places the character into the Buffer.
 127
 128   Internal function that places ASCII or Unicode character into the Buffer.
 129
 130   @param  Buffer      Buffer to place the Unicode or ASCII string.
 131   @param  EndBuffer   The end of the input Buffer. No characters will be
 132                       placed after that.
 133   @param  Length      The count of character to be placed into Buffer.
 134                       (Negative value indicates no buffer fill.)
 135   @param  Character   The character to be placed into Buffer.
 136   @param  Increment   The character increment in Buffer.
 137
 138   @return Buffer      Buffer filled with the input Character.
 139
 140 **/
 141 CHAR8 *
 142 BasePrintLibFillBuffer (
 143   OUT CHAR8   *Buffer,
 144   IN  CHAR8   *EndBuffer,
 145   IN  INTN    Length,
 146   IN  UINTN   Character,
 147   IN  INTN    Increment
 148   );
 149
 150 /**
 151   Internal function that convert a number to a string in Buffer.
 152
 153   Print worker function that converts a decimal or hexadecimal number to an ASCII string in Buffer.
 154
 155   @param  Buffer    Location to place the ASCII string of Value.
 156   @param  Value     The value to convert to a Decimal or Hexadecimal string in Buffer.
 157   @param  Radix     Radix of the value
 158
 159   @return A pointer to the end of buffer filled with ASCII string.
 160
 161 **/
 162 CHAR8 *
 163 BasePrintLibValueToString (
 164   IN OUT CHAR8  *Buffer,
 165   IN INT64      Value,
 166   IN UINTN      Radix
 167   );
 168
 169 /**
 170   Internal function that converts a decimal value to a Null-terminated string.
 171
 172   Converts the decimal number specified by Value to a Null-terminated
 173   string specified by Buffer containing at most Width characters.
 174   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
 175   The total number of characters placed in Buffer is returned.
 176   If the conversion contains more than Width characters, then only the first
 177   Width characters are returned, and the total number of characters
 178   required to perform the conversion is returned.
 179   Additional conversion parameters are specified in Flags.
 180   The Flags bit LEFT_JUSTIFY is always ignored.
 181   All conversions are left justified in Buffer.
 182   If Width is 0, PREFIX_ZERO is ignored in Flags.
 183   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
 184   are inserted every 3rd digit starting from the right.
 185   If Value is < 0, then the fist character in Buffer is a '-'.
 186   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
 187   then Buffer is padded with '0' characters so the combination of the optional '-'
 188   sign character, '0' characters, digit characters for Value, and the Null-terminator
 189   add up to Width characters.
 190
 191   If Buffer is NULL, then ASSERT().
 192   If unsupported bits are set in Flags, then ASSERT().
 193   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
 194
 195   @param  Buffer    The pointer to the output buffer for the produced Null-terminated
 196                     string.
 197   @param  Flags     The bitmask of flags that specify left justification, zero pad,
 198                     and commas.
 199   @param  Value     The 64-bit signed value to convert to a string.
 200   @param  Width     The maximum number of characters to place in Buffer, not including
 201                     the Null-terminator.
 202   @param  Increment Character increment in Buffer.
 203
 204   @return Total number of characters required to perform the conversion.
 205
 206 **/
 207 UINTN
 208 BasePrintLibConvertValueToString (
 209   IN OUT CHAR8   *Buffer,
 210   IN UINTN       Flags,
 211   IN INT64       Value,
 212   IN UINTN       Width,
 213   IN UINTN       Increment
 214   );
 215
 216 /**
 217   Internal function that converts a decimal value to a Null-terminated string.
 218
 219   Converts the decimal number specified by Value to a Null-terminated string
 220   specified by Buffer containing at most Width characters. If Width is 0 then a
 221   width of MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more
 222   than Width characters, then only the first Width characters are placed in
 223   Buffer. Additional conversion parameters are specified in Flags.
 224   The Flags bit LEFT_JUSTIFY is always ignored.
 225   All conversions are left justified in Buffer.
 226   If Width is 0, PREFIX_ZERO is ignored in Flags.
 227   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
 228   commas are inserted every 3rd digit starting from the right.
 229   If Value is < 0, 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
 233   Null-terminator add up to Width characters.
 234
 235   If an error would be returned, the function will ASSERT().
 236
 237   @param  Buffer      The pointer to the output buffer for the produced
 238                       Null-terminated string.
 239   @param  BufferSize  The size of Buffer in bytes, including the
 240                       Null-terminator.
 241   @param  Flags       The bitmask of flags that specify left justification,
 242                       zero pad, and commas.
 243   @param  Value       The 64-bit signed value to convert to a string.
 244   @param  Width       The maximum number of characters to place in Buffer,
 245                       not including the Null-terminator.
 246   @param  Increment   The character increment in Buffer.
 247
 248   @retval RETURN_SUCCESS           The decimal value is converted.
 249   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
 250                                    value.
 251   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
 252                                    If Increment is 1 and
 253                                    PcdMaximumAsciiStringLength is not zero,
 254                                    BufferSize is greater than
 255                                    PcdMaximumAsciiStringLength.
 256                                    If Increment is not 1 and
 257                                    PcdMaximumUnicodeStringLength is not zero,
 258                                    BufferSize is greater than
 259                                    (PcdMaximumUnicodeStringLength *
 260                                    sizeof (CHAR16) + 1).
 261                                    If unsupported bits are set in Flags.
 262                                    If both COMMA_TYPE and RADIX_HEX are set in
 263                                    Flags.
 264                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
 265
 266 **/
 267 RETURN_STATUS
 268 BasePrintLibConvertValueToStringS (
 269   IN OUT CHAR8   *Buffer,
 270   IN UINTN       BufferSize,
 271   IN UINTN       Flags,
 272   IN INT64       Value,
 273   IN UINTN       Width,
 274   IN UINTN       Increment
 275   );
 276
 277 #endif