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