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