1 /** @file
2 
3   Produces EFI_PRINT2_PROTOCOL and EFI_PRINT2S_PROTOCOL.
4   These protocols define basic print functions to  print the format unicode and
5   ascii string.
6 
7 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
8 SPDX-License-Identifier: BSD-2-Clause-Patent
9 
10 **/
11 
12 #ifndef __PPRINT2_H__
13 #define __PPRINT2_H__
14 
15 #define EFI_PRINT2_PROTOCOL_GUID  \
16   { 0xf05976ef, 0x83f1, 0x4f3d, { 0x86, 0x19, 0xf7, 0x59, 0x5d, 0x41, 0xe5, 0x38 } }
17 
18 //
19 // Forward reference for pure ANSI compatability
20 //
21 typedef struct _EFI_PRINT2_PROTOCOL EFI_PRINT2_PROTOCOL;
22 
23 /**
24   Produces a Null-terminated Unicode string in an output buffer based on
25   a Null-terminated Unicode format string and a BASE_LIST argument list.
26 
27   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
28   and BufferSize.
29   The Unicode string is produced by parsing the format string specified by FormatString.
30   Arguments are pulled from the variable argument list specified by Marker based on the
31   contents of the format string.
32   The number of Unicode characters in the produced output buffer is returned not including
33   the Null-terminator.
34 
35   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
36   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
37 
38   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
39   unmodified and 0 is returned.
40   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
41   unmodified and 0 is returned.
42   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
43   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
44   buffer is unmodified and 0 is returned.
45   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
46   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
47   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
48 
49   If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
50 
51   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
52                           Unicode string.
53   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
54   @param  FormatString    A Null-terminated Unicode format string.
55   @param  Marker          BASE_LIST marker for the variable argument list.
56 
57   @return The number of Unicode characters in the produced output buffer not including the
58           Null-terminator.
59 
60 **/
61 typedef
62 UINTN
63 (EFIAPI *UNICODE_BS_PRINT)(
64   OUT CHAR16        *StartOfBuffer,
65   IN  UINTN         BufferSize,
66   IN  CONST CHAR16  *FormatString,
67   IN  BASE_LIST     Marker
68   );
69 
70 /**
71   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
72   Unicode format string and variable argument list.
73 
74   This function is similar as snprintf_s defined in C11.
75 
76   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
77   and BufferSize.
78   The Unicode string is produced by parsing the format string specified by FormatString.
79   Arguments are pulled from the variable argument list based on the contents of the format string.
80   The number of Unicode characters in the produced output buffer is returned not including
81   the Null-terminator.
82 
83   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
84   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
85 
86   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
87   unmodified and 0 is returned.
88   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
89   unmodified and 0 is returned.
90   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
91   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
92   buffer is unmodified and 0 is returned.
93   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
94   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
95   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
96 
97   If BufferSize is 0 or 1, then the output buffer is unmodified and 0 is returned.
98 
99   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
100                           Unicode string.
101   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
102   @param  FormatString    A Null-terminated Unicode format string.
103   @param  ...             Variable argument list whose contents are accessed based on the
104                           format string specified by FormatString.
105 
106   @return The number of Unicode characters in the produced output buffer not including the
107           Null-terminator.
108 
109 **/
110 typedef
111 UINTN
112 (EFIAPI *UNICODE_S_PRINT)(
113   OUT CHAR16        *StartOfBuffer,
114   IN  UINTN         BufferSize,
115   IN  CONST CHAR16  *FormatString,
116   ...
117   );
118 
119 /**
120   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
121   ASCII format string and a BASE_LIST argument list.
122 
123   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
124   and BufferSize.
125   The Unicode string is produced by parsing the format string specified by FormatString.
126   Arguments are pulled from the variable argument list specified by Marker based on the
127   contents of the format string.
128   The number of Unicode characters in the produced output buffer is returned not including
129   the Null-terminator.
130 
131   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
132 
133   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
134   unmodified and 0 is returned.
135   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
136   unmodified and 0 is returned.
137   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
138   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
139   buffer is unmodified and 0 is returned.
140   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
141   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
142   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
143 
144   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
145 
146   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
147                           Unicode string.
148   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
149   @param  FormatString    A Null-terminated ASCII format string.
150   @param  Marker          BASE_LIST marker for the variable argument list.
151 
152   @return The number of Unicode characters in the produced output buffer not including the
153           Null-terminator.
154 
155 **/
156 typedef
157 UINTN
158 (EFIAPI *UNICODE_BS_PRINT_ASCII_FORMAT)(
159   OUT CHAR16       *StartOfBuffer,
160   IN  UINTN        BufferSize,
161   IN  CONST CHAR8  *FormatString,
162   IN  BASE_LIST    Marker
163   );
164 
165 /**
166   Produces a Null-terminated Unicode string in an output buffer based on a Null-terminated
167   ASCII format string and  variable argument list.
168 
169   This function is similar as snprintf_s defined in C11.
170 
171   Produces a Null-terminated Unicode string in the output buffer specified by StartOfBuffer
172   and BufferSize.
173   The Unicode string is produced by parsing the format string specified by FormatString.
174   Arguments are pulled from the variable argument list based on the contents of the
175   format string.
176   The number of Unicode characters in the produced output buffer is returned not including
177   the Null-terminator.
178 
179   If StartOfBuffer is not aligned on a 16-bit boundary, then ASSERT().
180 
181   If BufferSize > 1 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
182   unmodified and 0 is returned.
183   If BufferSize > 1 and FormatString is NULL, then ASSERT(). Also, the output buffer is
184   unmodified and 0 is returned.
185   If PcdMaximumUnicodeStringLength is not zero, and BufferSize >
186   (PcdMaximumUnicodeStringLength * sizeof (CHAR16) + 1), then ASSERT(). Also, the output
187   buffer is unmodified and 0 is returned.
188   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
189   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
190   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
191 
192   If BufferSize is 0 or 1, then no output buffer is produced and 0 is returned.
193 
194   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
195                           Unicode string.
196   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
197   @param  FormatString    A Null-terminated ASCII format string.
198   @param  ...             Variable argument list whose contents are accessed based on the
199                           format string specified by FormatString.
200 
201   @return The number of Unicode characters in the produced output buffer not including the
202           Null-terminator.
203 
204 **/
205 typedef
206 UINTN
207 (EFIAPI *UNICODE_S_PRINT_ASCII_FORMAT)(
208   OUT CHAR16       *StartOfBuffer,
209   IN  UINTN        BufferSize,
210   IN  CONST CHAR8  *FormatString,
211   ...
212   );
213 
214 /**
215   Converts a decimal value to a Null-terminated Unicode string.
216 
217   Converts the decimal number specified by Value to a Null-terminated Unicode
218   string specified by Buffer containing at most Width characters. No padding of spaces
219   is ever performed. If Width is 0, then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
220   This function returns the number of Unicode characters in Buffer, not including
221   the Null-terminator.
222   If the conversion contains more than Width characters, this function returns
223   the first Width characters in the conversion, along with the total number of characters in the conversion.
224   Additional conversion parameters are specified in Flags.
225 
226   The Flags bit LEFT_JUSTIFY is always ignored.
227   All conversions are left justified in Buffer.
228   If Width is 0, PREFIX_ZERO is ignored in Flags.
229   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
230   are inserted every 3rd digit starting from the right.
231   If RADIX_HEX is set in Flags, then the output buffer will be
232   formatted in hexadecimal format.
233   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
234   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
235   then Buffer is padded with '0' characters so the combination of the optional '-'
236   sign character, '0' characters, digit characters for Value, and the Null-terminator
237   add up to Width characters.
238   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
239   If Buffer is NULL, then ASSERT().
240   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
241   If unsupported bits are set in Flags, then ASSERT().
242   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
243   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
244 
245   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
246                   Unicode string.
247   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
248   @param  Value   The 64-bit signed value to convert to a string.
249   @param  Width   The maximum number of Unicode characters to place in Buffer, not including
250                   the Null-terminator.
251 
252   @return The number of Unicode characters in Buffer not including the Null-terminator.
253 
254 **/
255 typedef
256 UINTN
257 (EFIAPI *UNICODE_VALUE_TO_STRING)(
258   IN OUT CHAR16  *Buffer,
259   IN UINTN       Flags,
260   IN INT64       Value,
261   IN UINTN       Width
262   );
263 
264 /**
265   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
266   ASCII format string and a BASE_LIST argument list.
267 
268   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
269   and BufferSize.
270   The ASCII string is produced by parsing the format string specified by FormatString.
271   Arguments are pulled from the variable argument list specified by Marker based on
272   the contents of the format string.
273   The number of ASCII characters in the produced output buffer is returned not including
274   the Null-terminator.
275 
276   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
277   unmodified and 0 is returned.
278   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
279   unmodified and 0 is returned.
280   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
281   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
282   is unmodified and 0 is returned.
283   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
284   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
285   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
286 
287   If BufferSize is 0, then no output buffer is produced and 0 is returned.
288 
289   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
290                           ASCII string.
291   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
292   @param  FormatString    A Null-terminated ASCII format string.
293   @param  Marker          BASE_LIST marker for the variable argument list.
294 
295   @return The number of ASCII characters in the produced output buffer not including the
296           Null-terminator.
297 
298 **/
299 typedef
300 UINTN
301 (EFIAPI *ASCII_BS_PRINT)(
302   OUT CHAR8         *StartOfBuffer,
303   IN  UINTN         BufferSize,
304   IN  CONST CHAR8   *FormatString,
305   IN  BASE_LIST     Marker
306   );
307 
308 /**
309   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
310   ASCII format string and  variable argument list.
311 
312   This function is similar as snprintf_s defined in C11.
313 
314   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
315   and BufferSize.
316   The ASCII string is produced by parsing the format string specified by FormatString.
317   Arguments are pulled from the variable argument list based on the contents of the
318   format string.
319   The number of ASCII characters in the produced output buffer is returned not including
320   the Null-terminator.
321 
322   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
323   unmodified and 0 is returned.
324   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
325   unmodified and 0 is returned.
326   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
327   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
328   is unmodified and 0 is returned.
329   If PcdMaximumAsciiStringLength is not zero, and FormatString contains more than
330   PcdMaximumAsciiStringLength Ascii characters not including the Null-terminator, then
331   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
332 
333   If BufferSize is 0, then no output buffer is produced and 0 is returned.
334 
335   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
336                           ASCII string.
337   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
338   @param  FormatString    A Null-terminated ASCII format string.
339   @param  ...             Variable argument list whose contents are accessed based on the
340                           format string specified by FormatString.
341 
342   @return The number of ASCII characters in the produced output buffer not including the
343           Null-terminator.
344 
345 **/
346 typedef
347 UINTN
348 (EFIAPI *ASCII_S_PRINT)(
349   OUT CHAR8        *StartOfBuffer,
350   IN  UINTN        BufferSize,
351   IN  CONST CHAR8  *FormatString,
352   ...
353   );
354 
355 /**
356   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
357   Unicode format string and a BASE_LIST argument list.
358 
359   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
360   and BufferSize.
361   The ASCII string is produced by parsing the format string specified by FormatString.
362   Arguments are pulled from the variable argument list specified by Marker based on
363   the contents of the format string.
364   The number of ASCII characters in the produced output buffer is returned not including
365   the Null-terminator.
366 
367   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
368 
369   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
370   unmodified and 0 is returned.
371   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
372   unmodified and 0 is returned.
373   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
374   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
375   is unmodified and 0 is returned.
376   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
377   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
378   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
379 
380   If BufferSize is 0, then no output buffer is produced and 0 is returned.
381 
382   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
383                           ASCII string.
384   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
385   @param  FormatString    A Null-terminated Unicode format string.
386   @param  Marker          BASE_LIST marker for the variable argument list.
387 
388   @return The number of ASCII characters in the produced output buffer not including the
389           Null-terminator.
390 
391 **/
392 typedef
393 UINTN
394 (EFIAPI *ASCII_BS_PRINT_UNICODE_FORMAT)(
395   OUT CHAR8         *StartOfBuffer,
396   IN  UINTN         BufferSize,
397   IN  CONST CHAR16  *FormatString,
398   IN  BASE_LIST     Marker
399   );
400 
401 /**
402   Produces a Null-terminated ASCII string in an output buffer based on a Null-terminated
403   Unicode format string and  variable argument list.
404 
405   This function is similar as snprintf_s defined in C11.
406 
407   Produces a Null-terminated ASCII string in the output buffer specified by StartOfBuffer
408   and BufferSize.
409   The ASCII string is produced by parsing the format string specified by FormatString.
410   Arguments are pulled from the variable argument list based on the contents of the
411   format string.
412   The number of ASCII characters in the produced output buffer is returned not including
413   the Null-terminator.
414 
415   If FormatString is not aligned on a 16-bit boundary, then ASSERT().
416 
417   If BufferSize > 0 and StartOfBuffer is NULL, then ASSERT(). Also, the output buffer is
418   unmodified and 0 is returned.
419   If BufferSize > 0 and FormatString is NULL, then ASSERT(). Also, the output buffer is
420   unmodified and 0 is returned.
421   If PcdMaximumAsciiStringLength is not zero, and BufferSize >
422   (PcdMaximumAsciiStringLength * sizeof (CHAR8)), then ASSERT(). Also, the output buffer
423   is unmodified and 0 is returned.
424   If PcdMaximumUnicodeStringLength is not zero, and FormatString contains more than
425   PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, then
426   ASSERT(). Also, the output buffer is unmodified and 0 is returned.
427 
428   If BufferSize is 0, then no output buffer is produced and 0 is returned.
429 
430   @param  StartOfBuffer   A pointer to the output buffer for the produced Null-terminated
431                           ASCII string.
432   @param  BufferSize      The size, in bytes, of the output buffer specified by StartOfBuffer.
433   @param  FormatString    A Null-terminated Unicode format string.
434   @param  ...             Variable argument list whose contents are accessed based on the
435                           format string specified by FormatString.
436 
437   @return The number of ASCII characters in the produced output buffer not including the
438           Null-terminator.
439 
440 **/
441 typedef
442 UINTN
443 (EFIAPI *ASCII_S_PRINT_UNICODE_FORMAT)(
444   OUT CHAR8         *StartOfBuffer,
445   IN  UINTN         BufferSize,
446   IN  CONST CHAR16  *FormatString,
447   ...
448   );
449 
450 /**
451   Converts a decimal value to a Null-terminated ASCII string.
452 
453   Converts the decimal number specified by Value to a Null-terminated ASCII string
454   specified by Buffer containing at most Width characters. No padding of spaces is ever performed.
455   If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed.
456   The number of ASCII characters in Buffer is returned not including the Null-terminator.
457   If the conversion contains more than Width characters, then only the first Width
458   characters are returned, and the total number of characters required to perform
459   the conversion is returned.
460   Additional conversion parameters are specified in Flags.
461   The Flags bit LEFT_JUSTIFY is always ignored.
462   All conversions are left justified in Buffer.
463   If Width is 0, PREFIX_ZERO is ignored in Flags.
464   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas
465   are inserted every 3rd digit starting from the right.
466   If RADIX_HEX is set in Flags, then the output buffer will be
467   formatted in hexadecimal format.
468   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'.
469   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored,
470   then Buffer is padded with '0' characters so the combination of the optional '-'
471   sign character, '0' characters, digit characters for Value, and the Null-terminator
472   add up to Width characters.
473 
474   If Buffer is NULL, then ASSERT().
475   If unsupported bits are set in Flags, then ASSERT().
476   If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT().
477   If Width >= MAXIMUM_VALUE_CHARACTERS, then ASSERT()
478 
479   @param  Buffer  The pointer to the output buffer for the produced Null-terminated
480                   ASCII string.
481   @param  Flags   The bitmask of flags that specify left justification, zero pad, and commas.
482   @param  Value   The 64-bit signed value to convert to a string.
483   @param  Width   The maximum number of ASCII characters to place in Buffer, not including
484                   the Null-terminator.
485 
486   @return The number of ASCII characters in Buffer not including the Null-terminator.
487 
488 **/
489 typedef
490 UINTN
491 (EFIAPI *ASCII_VALUE_TO_STRING)(
492   OUT CHAR8      *Buffer,
493   IN  UINTN      Flags,
494   IN  INT64      Value,
495   IN  UINTN      Width
496   );
497 
498 struct _EFI_PRINT2_PROTOCOL {
499   UNICODE_BS_PRINT                 UnicodeBSPrint;
500   UNICODE_S_PRINT                  UnicodeSPrint;
501   UNICODE_BS_PRINT_ASCII_FORMAT    UnicodeBSPrintAsciiFormat;
502   UNICODE_S_PRINT_ASCII_FORMAT     UnicodeSPrintAsciiFormat;
503   UNICODE_VALUE_TO_STRING          UnicodeValueToString;
504   ASCII_BS_PRINT                   AsciiBSPrint;
505   ASCII_S_PRINT                    AsciiSPrint;
506   ASCII_BS_PRINT_UNICODE_FORMAT    AsciiBSPrintUnicodeFormat;
507   ASCII_S_PRINT_UNICODE_FORMAT     AsciiSPrintUnicodeFormat;
508   ASCII_VALUE_TO_STRING            AsciiValueToString;
509 };
510 
511 extern EFI_GUID  gEfiPrint2ProtocolGuid;
512 
513 #define EFI_PRINT2S_PROTOCOL_GUID  \
514   { 0xcc252d2, 0xc106, 0x4661, { 0xb5, 0xbd, 0x31, 0x47, 0xa4, 0xf8, 0x1f, 0x92 } }
515 
516 //
517 // Forward reference for pure ANSI compatability
518 //
519 typedef struct _EFI_PRINT2S_PROTOCOL EFI_PRINT2S_PROTOCOL;
520 
521 /**
522   Converts a decimal value to a Null-terminated Unicode string.
523 
524   Converts the decimal number specified by Value to a Null-terminated Unicode
525   string specified by Buffer containing at most Width characters. No padding of
526   spaces is ever performed. If Width is 0 then a width of
527   MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
528   Width characters, then only the first Width characters are placed in Buffer.
529   Additional conversion parameters are specified in Flags.
530 
531   The Flags bit LEFT_JUSTIFY is always ignored.
532   All conversions are left justified in Buffer.
533   If Width is 0, PREFIX_ZERO is ignored in Flags.
534   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
535   commas are inserted every 3rd digit starting from the right.
536   If RADIX_HEX is set in Flags, then the output buffer will be formatted in
537   hexadecimal format.
538   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
539   Buffer is a '-'.
540   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
541   Buffer is padded with '0' characters so the combination of the optional '-'
542   sign character, '0' characters, digit characters for Value, and the
543   Null-terminator add up to Width characters.
544 
545   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
546   If an error would be returned, then the function will also ASSERT().
547 
548   @param  Buffer      The pointer to the output buffer for the produced
549                       Null-terminated Unicode string.
550   @param  BufferSize  The size of Buffer in bytes, including the
551                       Null-terminator.
552   @param  Flags       The bitmask of flags that specify left justification,
553                       zero pad, and commas.
554   @param  Value       The 64-bit signed value to convert to a string.
555   @param  Width       The maximum number of Unicode characters to place in
556                       Buffer, not including the Null-terminator.
557 
558   @retval RETURN_SUCCESS           The decimal value is converted.
559   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
560                                    value.
561   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
562                                    If PcdMaximumUnicodeStringLength is not
563                                    zero, and BufferSize is greater than
564                                    (PcdMaximumUnicodeStringLength *
565                                    sizeof (CHAR16) + 1).
566                                    If unsupported bits are set in Flags.
567                                    If both COMMA_TYPE and RADIX_HEX are set in
568                                    Flags.
569                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
570 
571 **/
572 typedef
573 RETURN_STATUS
574 (EFIAPI *UNICODE_VALUE_TO_STRING_S)(
575   IN OUT CHAR16  *Buffer,
576   IN UINTN       BufferSize,
577   IN UINTN       Flags,
578   IN INT64       Value,
579   IN UINTN       Width
580   );
581 
582 /**
583   Converts a decimal value to a Null-terminated Ascii string.
584 
585   Converts the decimal number specified by Value to a Null-terminated Ascii
586   string specified by Buffer containing at most Width characters. No padding of
587   spaces is ever performed. If Width is 0 then a width of
588   MAXIMUM_VALUE_CHARACTERS is assumed. If the conversion contains more than
589   Width characters, then only the first Width characters are placed in Buffer.
590   Additional conversion parameters are specified in Flags.
591 
592   The Flags bit LEFT_JUSTIFY is always ignored.
593   All conversions are left justified in Buffer.
594   If Width is 0, PREFIX_ZERO is ignored in Flags.
595   If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and
596   commas are inserted every 3rd digit starting from the right.
597   If RADIX_HEX is set in Flags, then the output buffer will be formatted in
598   hexadecimal format.
599   If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in
600   Buffer is a '-'.
601   If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, then
602   Buffer is padded with '0' characters so the combination of the optional '-'
603   sign character, '0' characters, digit characters for Value, and the
604   Null-terminator add up to Width characters.
605 
606   If an error would be returned, then the function will ASSERT().
607 
608   @param  Buffer      The pointer to the output buffer for the produced
609                       Null-terminated Ascii string.
610   @param  BufferSize  The size of Buffer in bytes, including the
611                       Null-terminator.
612   @param  Flags       The bitmask of flags that specify left justification,
613                       zero pad, and commas.
614   @param  Value       The 64-bit signed value to convert to a string.
615   @param  Width       The maximum number of Ascii characters to place in
616                       Buffer, not including the Null-terminator.
617 
618   @retval RETURN_SUCCESS           The decimal value is converted.
619   @retval RETURN_BUFFER_TOO_SMALL  If BufferSize cannot hold the converted
620                                    value.
621   @retval RETURN_INVALID_PARAMETER If Buffer is NULL.
622                                    If PcdMaximumAsciiStringLength is not
623                                    zero, and BufferSize is greater than
624                                    PcdMaximumAsciiStringLength.
625                                    If unsupported bits are set in Flags.
626                                    If both COMMA_TYPE and RADIX_HEX are set in
627                                    Flags.
628                                    If Width >= MAXIMUM_VALUE_CHARACTERS.
629 
630 **/
631 typedef
632 RETURN_STATUS
633 (EFIAPI *ASCII_VALUE_TO_STRING_S)(
634   IN OUT CHAR8   *Buffer,
635   IN  UINTN      BufferSize,
636   IN  UINTN      Flags,
637   IN  INT64      Value,
638   IN  UINTN      Width
639   );
640 
641 struct _EFI_PRINT2S_PROTOCOL {
642   UNICODE_BS_PRINT                 UnicodeBSPrint;
643   UNICODE_S_PRINT                  UnicodeSPrint;
644   UNICODE_BS_PRINT_ASCII_FORMAT    UnicodeBSPrintAsciiFormat;
645   UNICODE_S_PRINT_ASCII_FORMAT     UnicodeSPrintAsciiFormat;
646   UNICODE_VALUE_TO_STRING_S        UnicodeValueToStringS;
647   ASCII_BS_PRINT                   AsciiBSPrint;
648   ASCII_S_PRINT                    AsciiSPrint;
649   ASCII_BS_PRINT_UNICODE_FORMAT    AsciiBSPrintUnicodeFormat;
650   ASCII_S_PRINT_UNICODE_FORMAT     AsciiSPrintUnicodeFormat;
651   ASCII_VALUE_TO_STRING_S          AsciiValueToStringS;
652 };
653 
654 extern EFI_GUID  gEfiPrint2SProtocolGuid;
655 
656 #endif
657