1 /*++
2 
3 Copyright (c) 2004 - 2009, Intel Corporation. All rights reserved.<BR>
4 This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution.  The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
8 
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
11 
12 
13 Module Name:
14 
15   EdkIIGluePrintLib.h
16 
17 Abstract:
18 
19   Public header file Print Lib
20 
21 --*/
22 
23 #ifndef __EDKII_GLUE_PRINT_LIB_H__
24 #define __EDKII_GLUE_PRINT_LIB_H__
25 
26 ///
27 /// Define the maximum number of characters that are required to
28 /// encode a decimal, hexidecimal, GUID, or TIME value with a NULL
29 /// terminator.
30 ///
31 ///  Maximum Length Decimal String     = 28
32 ///    "-9,223,372,036,854,775,808"
33 ///  Maximum Length Hexidecimal String = 17
34 ///    "FFFFFFFFFFFFFFFF"
35 ///  Maximum Length GUID               = 37
36 ///    "00000000-0000-0000-0000-000000000000"
37 ///  Maximum Length TIME               = 18
38 ///    "12/12/2006  12:12"
39 ///
40 #define MAXIMUM_VALUE_CHARACTERS  38
41 
42 ///
43 /// Flags bitmask values use in UnicodeValueToString() and
44 /// AsciiValueToString()
45 ///
46 #define LEFT_JUSTIFY      0x01
47 #define COMMA_TYPE        0x08
48 #define PREFIX_ZERO       0x20
49 #define RADIX_HEX         0x80
50 
51 /**
52   Produces a Null-terminated Unicode string in an output buffer based on
53   a Null-terminated Unicode format string and a VA_LIST argument list
54 
55   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
56   and BufferSize.
57   The Unicode string is produced by parsing the format string specified by FormatString.
58   Arguments are pulled from the variable argument list specified by Marker based on the
59   contents of the format string.
60   The number of Unicode characters in the produced output buffer is returned not including
61   the Null-terminator.
62   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
63 
64   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
65   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
66   If BufferSize > 1 and FormatString is NULL, then ASSERT().
67   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
68   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
69   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
70   ASSERT().
71   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
72   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
73   Null-terminator, then ASSERT().
74 
75   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
76                           Unicode string.
77   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
78   @param  FormatString    Null-terminated Unicode format string.
79   @param  Marker          VA_LIST marker for the variable argument list.
80 
81   @return The number of Unicode characters in the produced output buffer not including the
82           Null-terminator.
83 
84 **/
85 UINTN
86 EFIAPI
87 UnicodeVSPrint (
88   OUT CHAR16        *StartOfBuffer,
89   IN  UINTN         BufferSize,
90   IN  CONST CHAR16  *FormatString,
91   IN  VA_LIST       Marker
92   );
93 
94 /**
95   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
96   Unicode format string and variable argument list.
97 
98   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
99   and BufferSize.
100   The Unicode string is produced by parsing the format string specified by FormatString.
101   Arguments are pulled from the variable argument list based on the contents of the format string.
102   The number of Unicode characters in the produced output buffer is returned not including
103   the Null-terminator.
104   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
105 
106   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
107   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
108   If BufferSize > 1 and FormatString is NULL, then ASSERT().
109   If BufferSize > 1 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
110   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
111   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
112   ASSERT().
113   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
114   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
115   Null-terminator, then ASSERT().
116 
117   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
118                           Unicode string.
119   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
120   @param  FormatString    Null-terminated Unicode format string.
121 
122   @return The number of Unicode characters in the produced output buffer not including the
123           Null-terminator.
124 
125 **/
126 UINTN
127 EFIAPI
128 UnicodeSPrint (
129   OUT CHAR16        *StartOfBuffer,
130   IN  UINTN         BufferSize,
131   IN  CONST CHAR16  *FormatString,
132   ...
133   );
134 
135 /**
136   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
137   ASCII format string and a VA_LIST argument list
138 
139   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
140   and BufferSize.
141   The Unicode string is produced by parsing the format string specified by FormatString.
142   Arguments are pulled from the variable argument list specified by Marker based on the
143   contents of the format string.
144   The number of Unicode characters in the produced output buffer is returned not including
145   the Null-terminator.
146   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
147 
148   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
149   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
150   If BufferSize > 1 and FormatString is NULL, then ASSERT().
151   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
152   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
153   ASSERT().
154   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
155   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
156   Null-terminator, then ASSERT().
157 
158   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
159                           Unicode string.
160   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
161   @param  FormatString    Null-terminated Unicode format string.
162   @param  Marker          VA_LIST marker for the variable argument list.
163 
164   @return The number of Unicode characters in the produced output buffer not including the
165           Null-terminator.
166 
167 **/
168 UINTN
169 EFIAPI
170 UnicodeVSPrintAsciiFormat (
171   OUT CHAR16       *StartOfBuffer,
172   IN  UINTN        BufferSize,
173   IN  CONST CHAR8  *FormatString,
174   IN  VA_LIST      Marker
175   );
176 
177 /**
178   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
179   ASCII format string and  variable argument list.
180 
181   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
182   and BufferSize.
183   The Unicode string is produced by parsing the format string specified by FormatString.
184   Arguments are pulled from the variable argument list based on the contents of the
185   format string.
186   The number of Unicode characters in the produced output buffer is returned not including
187   the Null-terminator.
188   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
189 
190   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT().
191   If BufferSize > 1 and StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
192   If BufferSize > 1 and FormatString is NULL, then ASSERT().
193   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
194   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
195   ASSERT().
196   If PcdMaximumUnicodeStringLength is not zero, and produced Null-terminated Unicode string
197   contains more than PcdMaximumUnicodeStringLength Unicode characters not including the
198   Null-terminator, then ASSERT().
199 
200   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
201                           Unicode string.
202   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
203   @param  FormatString    Null-terminated Unicode format string.
204 
205   @return The number of Unicode characters in the produced output buffer not including the
206           Null-terminator.
207 
208 **/
209 UINTN
210 EFIAPI
211 UnicodeSPrintAsciiFormat (
212   OUT CHAR16       *StartOfBuffer,
213   IN  UINTN        BufferSize,
214   IN  CONST CHAR8  *FormatString,
215   ...
216   );
217 
218 /**
219   Converts a decimal value to a Null-terminated Unicode string.
220 
221   Converts the decimal number specified by Value to a Null-terminated Unicode
222   string specified by Buffer containing at most Width characters. No padding of spaces
223   is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
224   The number of Unicode characters in Buffer is returned not including the Null-terminator.
225   If the conversion contains more than Width characters, then only the first
226   Width characters are returned, and the total number of characters
227   required to perform the conversion is returned.
228   Additional conversion parameters are specified in Flags.
229 
230   The Flags bit LEFT_JUSTIFY is always ignored.
231   All conversions are left justified in Buffer.
232   If Width is 0, PREFIX_ZERO is ignored in Flags.
233   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
234   are inserted every 3rd digit starting from the right.
235   If RADIX_HEX is set in Flags, then the output buffer will be
236   formatted in hexadecimal format.
237   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
238   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
239   then Buffer is padded with '0' characters so the combination of the optional '-'
240   sign character, '0' characters, digit characters for Value, and the Null-terminator
241   add up to Width characters.
242   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
243   If Buffer is NULL, then ASSERT().
244   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
245   If unsupported bits are set in Flags, then ASSERT().
246   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
247   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
248 
249   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
250                   Unicode string.
251   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
252   @param  Value   The 64-bit signed value to convert to a string.
253   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
254                   the Null-terminator.
255 
256   @return The number of Unicode characters in Buffer not including the Null-terminator.
257 
258 **/
259 UINTN
260 EFIAPI
261 UnicodeValueToString (
262   IN OUT CHAR16  *Buffer,
263   IN UINTN       Flags,
264   IN INT64       Value,
265   IN UINTN       Width
266   );
267 
268 /**
269   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
270   ASCII format string and a VA_LIST argument list.
271 
272   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
273   and BufferSize.
274   The ASCII string is produced by parsing the format string specified by FormatString.
275   Arguments are pulled from the variable argument list specified by Marker based on
276   the contents of the format string.
277   The number of ASCII characters in the produced output buffer is returned not including
278   the Null-terminator.
279   If BufferSize is 0, then no output buffer is produced and 0 is returned.
280 
281   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
282   If BufferSize > 0 and FormatString is NULL, then ASSERT().
283   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
284   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
285   ASSERT().
286   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
287   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
288   Null-terminator, then ASSERT().
289 
290   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
291                           ASCII string.
292   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
293   @param  FormatString    Null-terminated Unicode format string.
294   @param  Marker          VA_LIST marker for the variable argument list.
295 
296   @return The number of ASCII characters in the produced output buffer not including the
297           Null-terminator.
298 
299 **/
300 UINTN
301 EFIAPI
302 AsciiVSPrint (
303   OUT CHAR8         *StartOfBuffer,
304   IN  UINTN         BufferSize,
305   IN  CONST CHAR8   *FormatString,
306   IN  VA_LIST       Marker
307   );
308 
309 /**
310   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
311   ASCII format string and  variable argument list.
312 
313   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
314   and BufferSize.
315   The ASCII string is produced by parsing the format string specified by FormatString.
316   Arguments are pulled from the variable argument list based on the contents of the
317   format string.
318   The number of ASCII characters in the produced output buffer is returned not including
319   the Null-terminator.
320   If BufferSize is 0, then no output buffer is produced and 0 is returned.
321 
322   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
323   If BufferSize > 0 and FormatString is NULL, then ASSERT().
324   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
325   PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, then
326   ASSERT().
327   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
328   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
329   Null-terminator, then ASSERT().
330 
331   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
332                           ASCII string.
333   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
334   @param  FormatString    Null-terminated Unicode format string.
335 
336   @return The number of ASCII characters in the produced output buffer not including the
337           Null-terminator.
338 
339 **/
340 UINTN
341 EFIAPI
342 AsciiSPrint (
343   OUT CHAR8        *StartOfBuffer,
344   IN  UINTN        BufferSize,
345   IN  CONST CHAR8  *FormatString,
346   ...
347   );
348 
349 /**
350   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
351   ASCII format string and a VA_LIST argument list.
352 
353   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
354   and BufferSize.
355   The ASCII string is produced by parsing the format string specified by FormatString.
356   Arguments are pulled from the variable argument list specified by Marker based on
357   the contents of the format string.
358   The number of ASCII characters in the produced output buffer is returned not including
359   the Null-terminator.
360   If BufferSize is 0, then no output buffer is produced and 0 is returned.
361 
362   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
363   If BufferSize > 0 and FormatString is NULL, then ASSERT().
364   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
365   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
366   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
367   ASSERT().
368   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
369   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
370   Null-terminator, then ASSERT().
371 
372   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
373                           ASCII string.
374   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
375   @param  FormatString    Null-terminated Unicode format string.
376   @param  Marker          VA_LIST marker for the variable argument list.
377 
378   @return The number of ASCII characters in the produced output buffer not including the
379           Null-terminator.
380 
381 **/
382 UINTN
383 EFIAPI
384 AsciiVSPrintUnicodeFormat (
385   OUT CHAR8         *StartOfBuffer,
386   IN  UINTN         BufferSize,
387   IN  CONST CHAR16  *FormatString,
388   IN  VA_LIST       Marker
389   );
390 
391 /**
392   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
393   ASCII format string and  variable argument list.
394 
395   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
396   and BufferSize.
397   The ASCII string is produced by parsing the format string specified by FormatString.
398   Arguments are pulled from the variable argument list based on the contents of the
399   format string.
400   The number of ASCII characters in the produced output buffer is returned not including
401   the Null-terminator.
402   If BufferSize is 0, then no output buffer is produced and 0 is returned.
403 
404   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT().
405   If BufferSize > 0 and FormatString is NULL, then ASSERT().
406   If BufferSize > 0 and FormatString is not aligned on a 16-bit boundary, then ASSERT().
407   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
408   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
409   ASSERT().
410   If PcdMaximumAsciiStringLength is not zero, and produced Null-terminated ASCII string
411   contains more than PcdMaximumAsciiStringLength ASCII characters not including the
412   Null-terminator, then ASSERT().
413 
414   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
415                           ASCII string.
416   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
417   @param  FormatString    Null-terminated Unicode format string.
418 
419   @return The number of ASCII characters in the produced output buffer not including the
420           Null-terminator.
421 
422 **/
423 UINTN
424 EFIAPI
425 AsciiSPrintUnicodeFormat (
426   OUT CHAR8         *StartOfBuffer,
427   IN  UINTN         BufferSize,
428   IN  CONST CHAR16  *FormatString,
429   ...
430   );
431 
432 /**
433   Converts a decimal value to a Null-terminated ASCII string.
434 
435   Converts the decimal number specified by Value to a Null-terminated ASCII string
436   specified by Buffer containing at most Width characters. No padding of spaces
437   is ever performed.
438   If Width is 0 then a width of  MAXIMUM_VALUE_CHARACTERS is assumed.
439   The number of ASCII characters in Buffer is returned not including the Null-terminator.
440   If the conversion contains more than Width characters, then only the first Width
441   characters are returned, and the total number of characters required to perform
442   the conversion is returned.
443   Additional conversion parameters are specified in Flags.
444   The Flags bit LEFT_JUSTIFY is always ignored.
445   All conversions are left justified in Buffer.
446   If Width is 0, PREFIX_ZERO is ignored in Flags.
447   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
448   are inserted every 3rd digit starting from the right.
449   If RADIX_HEX is set in Flags, then the output buffer will be
450   formatted in hexadecimal format.
451   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
452   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
453   then Buffer is padded with '0' characters so the combination of the optional '-'
454   sign character, '0' characters, digit characters for Value, and the Null-terminator
455   add up to Width characters.
456 
457   If Buffer is NULL, then ASSERT().
458   If unsupported bits are set in Flags, then ASSERT().
459   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
460   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
461 
462   @param  Buffer  Pointer to the output buffer for the produced Null-terminated
463                   ASCII string.
464   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
465   @param  Value   The 64-bit signed value to convert to a string.
466   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
467                   the Null-terminator.
468 
469   @return The number of ASCII characters in Buffer not including the Null-terminator.
470 
471 **/
472 UINTN
473 EFIAPI
474 AsciiValueToString (
475   IN OUT CHAR8  *Buffer,
476   IN UINTN      Flags,
477   IN INT64      Value,
478   IN UINTN      Width
479   );
480 
481 #endif
482