MdePkg/BaseLib: Add bit field population calculating methods
[mirror_edk2.git] / MdePkg / Include / Library / BaseLib.h
1 /** @file
2 Provides string functions, linked list functions, math functions, synchronization
3 functions, file path functions, and CPU architecture-specific functions.
4
5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
7 This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. 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 __BASE_LIB__
18 #define __BASE_LIB__
19
20 //
21 // Definitions for architecture-specific types
22 //
23 #if defined (MDE_CPU_IA32)
24 ///
25 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
26 ///
27 typedef struct {
28 UINT32 Ebx;
29 UINT32 Esi;
30 UINT32 Edi;
31 UINT32 Ebp;
32 UINT32 Esp;
33 UINT32 Eip;
34 } BASE_LIBRARY_JUMP_BUFFER;
35
36 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
37
38 #endif // defined (MDE_CPU_IA32)
39
40 #if defined (MDE_CPU_IPF)
41
42 ///
43 /// The Itanium architecture context buffer used by SetJump() and LongJump().
44 ///
45 typedef struct {
46 UINT64 F2[2];
47 UINT64 F3[2];
48 UINT64 F4[2];
49 UINT64 F5[2];
50 UINT64 F16[2];
51 UINT64 F17[2];
52 UINT64 F18[2];
53 UINT64 F19[2];
54 UINT64 F20[2];
55 UINT64 F21[2];
56 UINT64 F22[2];
57 UINT64 F23[2];
58 UINT64 F24[2];
59 UINT64 F25[2];
60 UINT64 F26[2];
61 UINT64 F27[2];
62 UINT64 F28[2];
63 UINT64 F29[2];
64 UINT64 F30[2];
65 UINT64 F31[2];
66 UINT64 R4;
67 UINT64 R5;
68 UINT64 R6;
69 UINT64 R7;
70 UINT64 SP;
71 UINT64 BR0;
72 UINT64 BR1;
73 UINT64 BR2;
74 UINT64 BR3;
75 UINT64 BR4;
76 UINT64 BR5;
77 UINT64 InitialUNAT;
78 UINT64 AfterSpillUNAT;
79 UINT64 PFS;
80 UINT64 BSP;
81 UINT64 Predicates;
82 UINT64 LoopCount;
83 UINT64 FPSR;
84 } BASE_LIBRARY_JUMP_BUFFER;
85
86 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10
87
88 #endif // defined (MDE_CPU_IPF)
89
90 #if defined (MDE_CPU_X64)
91 ///
92 /// The x64 architecture context buffer used by SetJump() and LongJump().
93 ///
94 typedef struct {
95 UINT64 Rbx;
96 UINT64 Rsp;
97 UINT64 Rbp;
98 UINT64 Rdi;
99 UINT64 Rsi;
100 UINT64 R12;
101 UINT64 R13;
102 UINT64 R14;
103 UINT64 R15;
104 UINT64 Rip;
105 UINT64 MxCsr;
106 UINT8 XmmBuffer[160]; ///< XMM6-XMM15.
107 } BASE_LIBRARY_JUMP_BUFFER;
108
109 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
110
111 #endif // defined (MDE_CPU_X64)
112
113 #if defined (MDE_CPU_EBC)
114 ///
115 /// The EBC context buffer used by SetJump() and LongJump().
116 ///
117 typedef struct {
118 UINT64 R0;
119 UINT64 R1;
120 UINT64 R2;
121 UINT64 R3;
122 UINT64 IP;
123 } BASE_LIBRARY_JUMP_BUFFER;
124
125 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
126
127 #endif // defined (MDE_CPU_EBC)
128
129 #if defined (MDE_CPU_ARM)
130
131 typedef struct {
132 UINT32 R3; ///< A copy of R13.
133 UINT32 R4;
134 UINT32 R5;
135 UINT32 R6;
136 UINT32 R7;
137 UINT32 R8;
138 UINT32 R9;
139 UINT32 R10;
140 UINT32 R11;
141 UINT32 R12;
142 UINT32 R14;
143 } BASE_LIBRARY_JUMP_BUFFER;
144
145 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
146
147 #endif // defined (MDE_CPU_ARM)
148
149 #if defined (MDE_CPU_AARCH64)
150 typedef struct {
151 // GP regs
152 UINT64 X19;
153 UINT64 X20;
154 UINT64 X21;
155 UINT64 X22;
156 UINT64 X23;
157 UINT64 X24;
158 UINT64 X25;
159 UINT64 X26;
160 UINT64 X27;
161 UINT64 X28;
162 UINT64 FP;
163 UINT64 LR;
164 UINT64 IP0;
165
166 // FP regs
167 UINT64 D8;
168 UINT64 D9;
169 UINT64 D10;
170 UINT64 D11;
171 UINT64 D12;
172 UINT64 D13;
173 UINT64 D14;
174 UINT64 D15;
175 } BASE_LIBRARY_JUMP_BUFFER;
176
177 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
178
179 #endif // defined (MDE_CPU_AARCH64)
180
181
182 //
183 // String Services
184 //
185
186
187 /**
188 Returns the length of a Null-terminated Unicode string.
189
190 This function is similar as strlen_s defined in C11.
191
192 If String is not aligned on a 16-bit boundary, then ASSERT().
193
194 @param String A pointer to a Null-terminated Unicode string.
195 @param MaxSize The maximum number of Destination Unicode
196 char, including terminating null char.
197
198 @retval 0 If String is NULL.
199 @retval MaxSize If there is no null character in the first MaxSize characters of String.
200 @return The number of characters that percede the terminating null character.
201
202 **/
203 UINTN
204 EFIAPI
205 StrnLenS (
206 IN CONST CHAR16 *String,
207 IN UINTN MaxSize
208 );
209
210 /**
211 Returns the size of a Null-terminated Unicode string in bytes, including the
212 Null terminator.
213
214 This function returns the size of the Null-terminated Unicode string
215 specified by String in bytes, including the Null terminator.
216
217 If String is not aligned on a 16-bit boundary, then ASSERT().
218
219 @param String A pointer to a Null-terminated Unicode string.
220 @param MaxSize The maximum number of Destination Unicode
221 char, including the Null terminator.
222
223 @retval 0 If String is NULL.
224 @retval (sizeof (CHAR16) * (MaxSize + 1))
225 If there is no Null terminator in the first MaxSize characters of
226 String.
227 @return The size of the Null-terminated Unicode string in bytes, including
228 the Null terminator.
229
230 **/
231 UINTN
232 EFIAPI
233 StrnSizeS (
234 IN CONST CHAR16 *String,
235 IN UINTN MaxSize
236 );
237
238 /**
239 Copies the string pointed to by Source (including the terminating null char)
240 to the array pointed to by Destination.
241
242 This function is similar as strcpy_s defined in C11.
243
244 If Destination is not aligned on a 16-bit boundary, then ASSERT().
245 If Source is not aligned on a 16-bit boundary, then ASSERT().
246 If an error would be returned, then the function will also ASSERT().
247
248 If an error is returned, then the Destination is unmodified.
249
250 @param Destination A pointer to a Null-terminated Unicode string.
251 @param DestMax The maximum number of Destination Unicode
252 char, including terminating null char.
253 @param Source A pointer to a Null-terminated Unicode string.
254
255 @retval RETURN_SUCCESS String is copied.
256 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
257 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
258 If Source is NULL.
259 If PcdMaximumUnicodeStringLength is not zero,
260 and DestMax is greater than
261 PcdMaximumUnicodeStringLength.
262 If DestMax is 0.
263 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
264 **/
265 RETURN_STATUS
266 EFIAPI
267 StrCpyS (
268 OUT CHAR16 *Destination,
269 IN UINTN DestMax,
270 IN CONST CHAR16 *Source
271 );
272
273 /**
274 Copies not more than Length successive char from the string pointed to by
275 Source to the array pointed to by Destination. If no null char is copied from
276 Source, then Destination[Length] is always set to null.
277
278 This function is similar as strncpy_s defined in C11.
279
280 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
281 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
282 If an error would be returned, then the function will also ASSERT().
283
284 If an error is returned, then the Destination is unmodified.
285
286 @param Destination A pointer to a Null-terminated Unicode string.
287 @param DestMax The maximum number of Destination Unicode
288 char, including terminating null char.
289 @param Source A pointer to a Null-terminated Unicode string.
290 @param Length The maximum number of Unicode characters to copy.
291
292 @retval RETURN_SUCCESS String is copied.
293 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
294 MIN(StrLen(Source), Length).
295 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
296 If Source is NULL.
297 If PcdMaximumUnicodeStringLength is not zero,
298 and DestMax is greater than
299 PcdMaximumUnicodeStringLength.
300 If DestMax is 0.
301 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
302 **/
303 RETURN_STATUS
304 EFIAPI
305 StrnCpyS (
306 OUT CHAR16 *Destination,
307 IN UINTN DestMax,
308 IN CONST CHAR16 *Source,
309 IN UINTN Length
310 );
311
312 /**
313 Appends a copy of the string pointed to by Source (including the terminating
314 null char) to the end of the string pointed to by Destination.
315
316 This function is similar as strcat_s defined in C11.
317
318 If Destination is not aligned on a 16-bit boundary, then ASSERT().
319 If Source is not aligned on a 16-bit boundary, then ASSERT().
320 If an error would be returned, then the function will also ASSERT().
321
322 If an error is returned, then the Destination is unmodified.
323
324 @param Destination A pointer to a Null-terminated Unicode string.
325 @param DestMax The maximum number of Destination Unicode
326 char, including terminating null char.
327 @param Source A pointer to a Null-terminated Unicode string.
328
329 @retval RETURN_SUCCESS String is appended.
330 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
331 StrLen(Destination).
332 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
333 greater than StrLen(Source).
334 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
335 If Source is NULL.
336 If PcdMaximumUnicodeStringLength is not zero,
337 and DestMax is greater than
338 PcdMaximumUnicodeStringLength.
339 If DestMax is 0.
340 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
341 **/
342 RETURN_STATUS
343 EFIAPI
344 StrCatS (
345 IN OUT CHAR16 *Destination,
346 IN UINTN DestMax,
347 IN CONST CHAR16 *Source
348 );
349
350 /**
351 Appends not more than Length successive char from the string pointed to by
352 Source to the end of the string pointed to by Destination. If no null char is
353 copied from Source, then Destination[StrLen(Destination) + Length] is always
354 set to null.
355
356 This function is similar as strncat_s defined in C11.
357
358 If Destination is not aligned on a 16-bit boundary, then ASSERT().
359 If Source is not aligned on a 16-bit boundary, then ASSERT().
360 If an error would be returned, then the function will also ASSERT().
361
362 If an error is returned, then the Destination is unmodified.
363
364 @param Destination A pointer to a Null-terminated Unicode string.
365 @param DestMax The maximum number of Destination Unicode
366 char, including terminating null char.
367 @param Source A pointer to a Null-terminated Unicode string.
368 @param Length The maximum number of Unicode characters to copy.
369
370 @retval RETURN_SUCCESS String is appended.
371 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
372 StrLen(Destination).
373 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
374 greater than MIN(StrLen(Source), Length).
375 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
376 If Source is NULL.
377 If PcdMaximumUnicodeStringLength is not zero,
378 and DestMax is greater than
379 PcdMaximumUnicodeStringLength.
380 If DestMax is 0.
381 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
382 **/
383 RETURN_STATUS
384 EFIAPI
385 StrnCatS (
386 IN OUT CHAR16 *Destination,
387 IN UINTN DestMax,
388 IN CONST CHAR16 *Source,
389 IN UINTN Length
390 );
391
392 /**
393 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
394
395 This function outputs a value of type UINTN by interpreting the contents of
396 the Unicode string specified by String as a decimal number. The format of the
397 input Unicode string String is:
398
399 [spaces] [decimal digits].
400
401 The valid decimal digit character is in the range [0-9]. The function will
402 ignore the pad space, which includes spaces or tab characters, before
403 [decimal digits]. The running zero in the beginning of [decimal digits] will
404 be ignored. Then, the function stops at the first character that is a not a
405 valid decimal character or a Null-terminator, whichever one comes first.
406
407 If String is NULL, then ASSERT().
408 If Data is NULL, then ASSERT().
409 If String is not aligned in a 16-bit boundary, then ASSERT().
410 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
411 PcdMaximumUnicodeStringLength Unicode characters, not including the
412 Null-terminator, then ASSERT().
413
414 If String has no valid decimal digits in the above format, then 0 is stored
415 at the location pointed to by Data.
416 If the number represented by String exceeds the range defined by UINTN, then
417 MAX_UINTN is stored at the location pointed to by Data.
418
419 If EndPointer is not NULL, a pointer to the character that stopped the scan
420 is stored at the location pointed to by EndPointer. If String has no valid
421 decimal digits right after the optional pad spaces, the value of String is
422 stored at the location pointed to by EndPointer.
423
424 @param String Pointer to a Null-terminated Unicode string.
425 @param EndPointer Pointer to character that stops scan.
426 @param Data Pointer to the converted value.
427
428 @retval RETURN_SUCCESS Value is translated from String.
429 @retval RETURN_INVALID_PARAMETER If String is NULL.
430 If Data is NULL.
431 If PcdMaximumUnicodeStringLength is not
432 zero, and String contains more than
433 PcdMaximumUnicodeStringLength Unicode
434 characters, not including the
435 Null-terminator.
436 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
437 the range defined by UINTN.
438
439 **/
440 RETURN_STATUS
441 EFIAPI
442 StrDecimalToUintnS (
443 IN CONST CHAR16 *String,
444 OUT CHAR16 **EndPointer, OPTIONAL
445 OUT UINTN *Data
446 );
447
448 /**
449 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
450
451 This function outputs a value of type UINT64 by interpreting the contents of
452 the Unicode string specified by String as a decimal number. The format of the
453 input Unicode string String is:
454
455 [spaces] [decimal digits].
456
457 The valid decimal digit character is in the range [0-9]. The function will
458 ignore the pad space, which includes spaces or tab characters, before
459 [decimal digits]. The running zero in the beginning of [decimal digits] will
460 be ignored. Then, the function stops at the first character that is a not a
461 valid decimal character or a Null-terminator, whichever one comes first.
462
463 If String is NULL, then ASSERT().
464 If Data is NULL, then ASSERT().
465 If String is not aligned in a 16-bit boundary, then ASSERT().
466 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
467 PcdMaximumUnicodeStringLength Unicode characters, not including the
468 Null-terminator, then ASSERT().
469
470 If String has no valid decimal digits in the above format, then 0 is stored
471 at the location pointed to by Data.
472 If the number represented by String exceeds the range defined by UINT64, then
473 MAX_UINT64 is stored at the location pointed to by Data.
474
475 If EndPointer is not NULL, a pointer to the character that stopped the scan
476 is stored at the location pointed to by EndPointer. If String has no valid
477 decimal digits right after the optional pad spaces, the value of String is
478 stored at the location pointed to by EndPointer.
479
480 @param String Pointer to a Null-terminated Unicode string.
481 @param EndPointer Pointer to character that stops scan.
482 @param Data Pointer to the converted value.
483
484 @retval RETURN_SUCCESS Value is translated from String.
485 @retval RETURN_INVALID_PARAMETER If String is NULL.
486 If Data is NULL.
487 If PcdMaximumUnicodeStringLength is not
488 zero, and String contains more than
489 PcdMaximumUnicodeStringLength Unicode
490 characters, not including the
491 Null-terminator.
492 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
493 the range defined by UINT64.
494
495 **/
496 RETURN_STATUS
497 EFIAPI
498 StrDecimalToUint64S (
499 IN CONST CHAR16 *String,
500 OUT CHAR16 **EndPointer, OPTIONAL
501 OUT UINT64 *Data
502 );
503
504 /**
505 Convert a Null-terminated Unicode hexadecimal string to a value of type
506 UINTN.
507
508 This function outputs a value of type UINTN by interpreting the contents of
509 the Unicode string specified by String as a hexadecimal number. The format of
510 the input Unicode string String is:
511
512 [spaces][zeros][x][hexadecimal digits].
513
514 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
515 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
516 If "x" appears in the input string, it must be prefixed with at least one 0.
517 The function will ignore the pad space, which includes spaces or tab
518 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
519 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
520 after [x] or the first valid hexadecimal digit. Then, the function stops at
521 the first character that is a not a valid hexadecimal character or NULL,
522 whichever one comes first.
523
524 If String is NULL, then ASSERT().
525 If Data is NULL, then ASSERT().
526 If String is not aligned in a 16-bit boundary, then ASSERT().
527 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
528 PcdMaximumUnicodeStringLength Unicode characters, not including the
529 Null-terminator, then ASSERT().
530
531 If String has no valid hexadecimal digits in the above format, then 0 is
532 stored at the location pointed to by Data.
533 If the number represented by String exceeds the range defined by UINTN, then
534 MAX_UINTN is stored at the location pointed to by Data.
535
536 If EndPointer is not NULL, a pointer to the character that stopped the scan
537 is stored at the location pointed to by EndPointer. If String has no valid
538 hexadecimal digits right after the optional pad spaces, the value of String
539 is stored at the location pointed to by EndPointer.
540
541 @param String Pointer to a Null-terminated Unicode string.
542 @param EndPointer Pointer to character that stops scan.
543 @param Data Pointer to the converted value.
544
545 @retval RETURN_SUCCESS Value is translated from String.
546 @retval RETURN_INVALID_PARAMETER If String is NULL.
547 If Data is NULL.
548 If PcdMaximumUnicodeStringLength is not
549 zero, and String contains more than
550 PcdMaximumUnicodeStringLength Unicode
551 characters, not including the
552 Null-terminator.
553 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
554 the range defined by UINTN.
555
556 **/
557 RETURN_STATUS
558 EFIAPI
559 StrHexToUintnS (
560 IN CONST CHAR16 *String,
561 OUT CHAR16 **EndPointer, OPTIONAL
562 OUT UINTN *Data
563 );
564
565 /**
566 Convert a Null-terminated Unicode hexadecimal string to a value of type
567 UINT64.
568
569 This function outputs a value of type UINT64 by interpreting the contents of
570 the Unicode string specified by String as a hexadecimal number. The format of
571 the input Unicode string String is:
572
573 [spaces][zeros][x][hexadecimal digits].
574
575 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
576 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
577 If "x" appears in the input string, it must be prefixed with at least one 0.
578 The function will ignore the pad space, which includes spaces or tab
579 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
580 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
581 after [x] or the first valid hexadecimal digit. Then, the function stops at
582 the first character that is a not a valid hexadecimal character or NULL,
583 whichever one comes first.
584
585 If String is NULL, then ASSERT().
586 If Data is NULL, then ASSERT().
587 If String is not aligned in a 16-bit boundary, then ASSERT().
588 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
589 PcdMaximumUnicodeStringLength Unicode characters, not including the
590 Null-terminator, then ASSERT().
591
592 If String has no valid hexadecimal digits in the above format, then 0 is
593 stored at the location pointed to by Data.
594 If the number represented by String exceeds the range defined by UINT64, then
595 MAX_UINT64 is stored at the location pointed to by Data.
596
597 If EndPointer is not NULL, a pointer to the character that stopped the scan
598 is stored at the location pointed to by EndPointer. If String has no valid
599 hexadecimal digits right after the optional pad spaces, the value of String
600 is stored at the location pointed to by EndPointer.
601
602 @param String Pointer to a Null-terminated Unicode string.
603 @param EndPointer Pointer to character that stops scan.
604 @param Data Pointer to the converted value.
605
606 @retval RETURN_SUCCESS Value is translated from String.
607 @retval RETURN_INVALID_PARAMETER If String is NULL.
608 If Data is NULL.
609 If PcdMaximumUnicodeStringLength is not
610 zero, and String contains more than
611 PcdMaximumUnicodeStringLength Unicode
612 characters, not including the
613 Null-terminator.
614 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
615 the range defined by UINT64.
616
617 **/
618 RETURN_STATUS
619 EFIAPI
620 StrHexToUint64S (
621 IN CONST CHAR16 *String,
622 OUT CHAR16 **EndPointer, OPTIONAL
623 OUT UINT64 *Data
624 );
625
626 /**
627 Returns the length of a Null-terminated Ascii string.
628
629 This function is similar as strlen_s defined in C11.
630
631 @param String A pointer to a Null-terminated Ascii string.
632 @param MaxSize The maximum number of Destination Ascii
633 char, including terminating null char.
634
635 @retval 0 If String is NULL.
636 @retval MaxSize If there is no null character in the first MaxSize characters of String.
637 @return The number of characters that percede the terminating null character.
638
639 **/
640 UINTN
641 EFIAPI
642 AsciiStrnLenS (
643 IN CONST CHAR8 *String,
644 IN UINTN MaxSize
645 );
646
647 /**
648 Returns the size of a Null-terminated Ascii string in bytes, including the
649 Null terminator.
650
651 This function returns the size of the Null-terminated Ascii string specified
652 by String in bytes, including the Null terminator.
653
654 @param String A pointer to a Null-terminated Ascii string.
655 @param MaxSize The maximum number of Destination Ascii
656 char, including the Null terminator.
657
658 @retval 0 If String is NULL.
659 @retval (sizeof (CHAR8) * (MaxSize + 1))
660 If there is no Null terminator in the first MaxSize characters of
661 String.
662 @return The size of the Null-terminated Ascii string in bytes, including the
663 Null terminator.
664
665 **/
666 UINTN
667 EFIAPI
668 AsciiStrnSizeS (
669 IN CONST CHAR8 *String,
670 IN UINTN MaxSize
671 );
672
673 /**
674 Copies the string pointed to by Source (including the terminating null char)
675 to the array pointed to by Destination.
676
677 This function is similar as strcpy_s defined in C11.
678
679 If an error would be returned, then the function will also ASSERT().
680
681 If an error is returned, then the Destination is unmodified.
682
683 @param Destination A pointer to a Null-terminated Ascii string.
684 @param DestMax The maximum number of Destination Ascii
685 char, including terminating null char.
686 @param Source A pointer to a Null-terminated Ascii string.
687
688 @retval RETURN_SUCCESS String is copied.
689 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
690 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
691 If Source is NULL.
692 If PcdMaximumAsciiStringLength is not zero,
693 and DestMax is greater than
694 PcdMaximumAsciiStringLength.
695 If DestMax is 0.
696 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
697 **/
698 RETURN_STATUS
699 EFIAPI
700 AsciiStrCpyS (
701 OUT CHAR8 *Destination,
702 IN UINTN DestMax,
703 IN CONST CHAR8 *Source
704 );
705
706 /**
707 Copies not more than Length successive char from the string pointed to by
708 Source to the array pointed to by Destination. If no null char is copied from
709 Source, then Destination[Length] is always set to null.
710
711 This function is similar as strncpy_s defined in C11.
712
713 If an error would be returned, then the function will also ASSERT().
714
715 If an error is returned, then the Destination is unmodified.
716
717 @param Destination A pointer to a Null-terminated Ascii string.
718 @param DestMax The maximum number of Destination Ascii
719 char, including terminating null char.
720 @param Source A pointer to a Null-terminated Ascii string.
721 @param Length The maximum number of Ascii characters to copy.
722
723 @retval RETURN_SUCCESS String is copied.
724 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
725 MIN(StrLen(Source), Length).
726 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
727 If Source is NULL.
728 If PcdMaximumAsciiStringLength is not zero,
729 and DestMax is greater than
730 PcdMaximumAsciiStringLength.
731 If DestMax is 0.
732 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
733 **/
734 RETURN_STATUS
735 EFIAPI
736 AsciiStrnCpyS (
737 OUT CHAR8 *Destination,
738 IN UINTN DestMax,
739 IN CONST CHAR8 *Source,
740 IN UINTN Length
741 );
742
743 /**
744 Appends a copy of the string pointed to by Source (including the terminating
745 null char) to the end of the string pointed to by Destination.
746
747 This function is similar as strcat_s defined in C11.
748
749 If an error would be returned, then the function will also ASSERT().
750
751 If an error is returned, then the Destination is unmodified.
752
753 @param Destination A pointer to a Null-terminated Ascii string.
754 @param DestMax The maximum number of Destination Ascii
755 char, including terminating null char.
756 @param Source A pointer to a Null-terminated Ascii string.
757
758 @retval RETURN_SUCCESS String is appended.
759 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
760 StrLen(Destination).
761 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
762 greater than StrLen(Source).
763 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
764 If Source is NULL.
765 If PcdMaximumAsciiStringLength is not zero,
766 and DestMax is greater than
767 PcdMaximumAsciiStringLength.
768 If DestMax is 0.
769 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
770 **/
771 RETURN_STATUS
772 EFIAPI
773 AsciiStrCatS (
774 IN OUT CHAR8 *Destination,
775 IN UINTN DestMax,
776 IN CONST CHAR8 *Source
777 );
778
779 /**
780 Appends not more than Length successive char from the string pointed to by
781 Source to the end of the string pointed to by Destination. If no null char is
782 copied from Source, then Destination[StrLen(Destination) + Length] is always
783 set to null.
784
785 This function is similar as strncat_s defined in C11.
786
787 If an error would be returned, then the function will also ASSERT().
788
789 If an error is returned, then the Destination is unmodified.
790
791 @param Destination A pointer to a Null-terminated Ascii string.
792 @param DestMax The maximum number of Destination Ascii
793 char, including terminating null char.
794 @param Source A pointer to a Null-terminated Ascii string.
795 @param Length The maximum number of Ascii characters to copy.
796
797 @retval RETURN_SUCCESS String is appended.
798 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
799 StrLen(Destination).
800 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
801 greater than MIN(StrLen(Source), Length).
802 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
803 If Source is NULL.
804 If PcdMaximumAsciiStringLength is not zero,
805 and DestMax is greater than
806 PcdMaximumAsciiStringLength.
807 If DestMax is 0.
808 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
809 **/
810 RETURN_STATUS
811 EFIAPI
812 AsciiStrnCatS (
813 IN OUT CHAR8 *Destination,
814 IN UINTN DestMax,
815 IN CONST CHAR8 *Source,
816 IN UINTN Length
817 );
818
819 /**
820 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
821
822 This function outputs a value of type UINTN by interpreting the contents of
823 the Ascii string specified by String as a decimal number. The format of the
824 input Ascii string String is:
825
826 [spaces] [decimal digits].
827
828 The valid decimal digit character is in the range [0-9]. The function will
829 ignore the pad space, which includes spaces or tab characters, before
830 [decimal digits]. The running zero in the beginning of [decimal digits] will
831 be ignored. Then, the function stops at the first character that is a not a
832 valid decimal character or a Null-terminator, whichever one comes first.
833
834 If String is NULL, then ASSERT().
835 If Data is NULL, then ASSERT().
836 If PcdMaximumAsciiStringLength is not zero, and String contains more than
837 PcdMaximumAsciiStringLength Ascii characters, not including the
838 Null-terminator, then ASSERT().
839
840 If String has no valid decimal digits in the above format, then 0 is stored
841 at the location pointed to by Data.
842 If the number represented by String exceeds the range defined by UINTN, then
843 MAX_UINTN is stored at the location pointed to by Data.
844
845 If EndPointer is not NULL, a pointer to the character that stopped the scan
846 is stored at the location pointed to by EndPointer. If String has no valid
847 decimal digits right after the optional pad spaces, the value of String is
848 stored at the location pointed to by EndPointer.
849
850 @param String Pointer to a Null-terminated Ascii string.
851 @param EndPointer Pointer to character that stops scan.
852 @param Data Pointer to the converted value.
853
854 @retval RETURN_SUCCESS Value is translated from String.
855 @retval RETURN_INVALID_PARAMETER If String is NULL.
856 If Data is NULL.
857 If PcdMaximumAsciiStringLength is not zero,
858 and String contains more than
859 PcdMaximumAsciiStringLength Ascii
860 characters, not including the
861 Null-terminator.
862 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
863 the range defined by UINTN.
864
865 **/
866 RETURN_STATUS
867 EFIAPI
868 AsciiStrDecimalToUintnS (
869 IN CONST CHAR8 *String,
870 OUT CHAR8 **EndPointer, OPTIONAL
871 OUT UINTN *Data
872 );
873
874 /**
875 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
876
877 This function outputs a value of type UINT64 by interpreting the contents of
878 the Ascii string specified by String as a decimal number. The format of the
879 input Ascii string String is:
880
881 [spaces] [decimal digits].
882
883 The valid decimal digit character is in the range [0-9]. The function will
884 ignore the pad space, which includes spaces or tab characters, before
885 [decimal digits]. The running zero in the beginning of [decimal digits] will
886 be ignored. Then, the function stops at the first character that is a not a
887 valid decimal character or a Null-terminator, whichever one comes first.
888
889 If String is NULL, then ASSERT().
890 If Data is NULL, then ASSERT().
891 If PcdMaximumAsciiStringLength is not zero, and String contains more than
892 PcdMaximumAsciiStringLength Ascii characters, not including the
893 Null-terminator, then ASSERT().
894
895 If String has no valid decimal digits in the above format, then 0 is stored
896 at the location pointed to by Data.
897 If the number represented by String exceeds the range defined by UINT64, then
898 MAX_UINT64 is stored at the location pointed to by Data.
899
900 If EndPointer is not NULL, a pointer to the character that stopped the scan
901 is stored at the location pointed to by EndPointer. If String has no valid
902 decimal digits right after the optional pad spaces, the value of String is
903 stored at the location pointed to by EndPointer.
904
905 @param String Pointer to a Null-terminated Ascii string.
906 @param EndPointer Pointer to character that stops scan.
907 @param Data Pointer to the converted value.
908
909 @retval RETURN_SUCCESS Value is translated from String.
910 @retval RETURN_INVALID_PARAMETER If String is NULL.
911 If Data is NULL.
912 If PcdMaximumAsciiStringLength is not zero,
913 and String contains more than
914 PcdMaximumAsciiStringLength Ascii
915 characters, not including the
916 Null-terminator.
917 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
918 the range defined by UINT64.
919
920 **/
921 RETURN_STATUS
922 EFIAPI
923 AsciiStrDecimalToUint64S (
924 IN CONST CHAR8 *String,
925 OUT CHAR8 **EndPointer, OPTIONAL
926 OUT UINT64 *Data
927 );
928
929 /**
930 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
931
932 This function outputs a value of type UINTN by interpreting the contents of
933 the Ascii string specified by String as a hexadecimal number. The format of
934 the input Ascii string String is:
935
936 [spaces][zeros][x][hexadecimal digits].
937
938 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
939 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
940 "x" appears in the input string, it must be prefixed with at least one 0. The
941 function will ignore the pad space, which includes spaces or tab characters,
942 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
943 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
944 the first valid hexadecimal digit. Then, the function stops at the first
945 character that is a not a valid hexadecimal character or Null-terminator,
946 whichever on comes first.
947
948 If String is NULL, then ASSERT().
949 If Data is NULL, then ASSERT().
950 If PcdMaximumAsciiStringLength is not zero, and String contains more than
951 PcdMaximumAsciiStringLength Ascii characters, not including the
952 Null-terminator, then ASSERT().
953
954 If String has no valid hexadecimal digits in the above format, then 0 is
955 stored at the location pointed to by Data.
956 If the number represented by String exceeds the range defined by UINTN, then
957 MAX_UINTN is stored at the location pointed to by Data.
958
959 If EndPointer is not NULL, a pointer to the character that stopped the scan
960 is stored at the location pointed to by EndPointer. If String has no valid
961 hexadecimal digits right after the optional pad spaces, the value of String
962 is stored at the location pointed to by EndPointer.
963
964 @param String Pointer to a Null-terminated Ascii string.
965 @param EndPointer Pointer to character that stops scan.
966 @param Data Pointer to the converted value.
967
968 @retval RETURN_SUCCESS Value is translated from String.
969 @retval RETURN_INVALID_PARAMETER If String is NULL.
970 If Data is NULL.
971 If PcdMaximumAsciiStringLength is not zero,
972 and String contains more than
973 PcdMaximumAsciiStringLength Ascii
974 characters, not including the
975 Null-terminator.
976 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
977 the range defined by UINTN.
978
979 **/
980 RETURN_STATUS
981 EFIAPI
982 AsciiStrHexToUintnS (
983 IN CONST CHAR8 *String,
984 OUT CHAR8 **EndPointer, OPTIONAL
985 OUT UINTN *Data
986 );
987
988 /**
989 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
990
991 This function outputs a value of type UINT64 by interpreting the contents of
992 the Ascii string specified by String as a hexadecimal number. The format of
993 the input Ascii string String is:
994
995 [spaces][zeros][x][hexadecimal digits].
996
997 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
998 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
999 "x" appears in the input string, it must be prefixed with at least one 0. The
1000 function will ignore the pad space, which includes spaces or tab characters,
1001 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
1002 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
1003 the first valid hexadecimal digit. Then, the function stops at the first
1004 character that is a not a valid hexadecimal character or Null-terminator,
1005 whichever on comes first.
1006
1007 If String is NULL, then ASSERT().
1008 If Data is NULL, then ASSERT().
1009 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1010 PcdMaximumAsciiStringLength Ascii characters, not including the
1011 Null-terminator, then ASSERT().
1012
1013 If String has no valid hexadecimal digits in the above format, then 0 is
1014 stored at the location pointed to by Data.
1015 If the number represented by String exceeds the range defined by UINT64, then
1016 MAX_UINT64 is stored at the location pointed to by Data.
1017
1018 If EndPointer is not NULL, a pointer to the character that stopped the scan
1019 is stored at the location pointed to by EndPointer. If String has no valid
1020 hexadecimal digits right after the optional pad spaces, the value of String
1021 is stored at the location pointed to by EndPointer.
1022
1023 @param String Pointer to a Null-terminated Ascii string.
1024 @param EndPointer Pointer to character that stops scan.
1025 @param Data Pointer to the converted value.
1026
1027 @retval RETURN_SUCCESS Value is translated from String.
1028 @retval RETURN_INVALID_PARAMETER If String is NULL.
1029 If Data is NULL.
1030 If PcdMaximumAsciiStringLength is not zero,
1031 and String contains more than
1032 PcdMaximumAsciiStringLength Ascii
1033 characters, not including the
1034 Null-terminator.
1035 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
1036 the range defined by UINT64.
1037
1038 **/
1039 RETURN_STATUS
1040 EFIAPI
1041 AsciiStrHexToUint64S (
1042 IN CONST CHAR8 *String,
1043 OUT CHAR8 **EndPointer, OPTIONAL
1044 OUT UINT64 *Data
1045 );
1046
1047
1048 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1049
1050 /**
1051 [ATTENTION] This function is deprecated for security reason.
1052
1053 Copies one Null-terminated Unicode string to another Null-terminated Unicode
1054 string and returns the new Unicode string.
1055
1056 This function copies the contents of the Unicode string Source to the Unicode
1057 string Destination, and returns Destination. If Source and Destination
1058 overlap, then the results are undefined.
1059
1060 If Destination is NULL, then ASSERT().
1061 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1062 If Source is NULL, then ASSERT().
1063 If Source is not aligned on a 16-bit boundary, then ASSERT().
1064 If Source and Destination overlap, then ASSERT().
1065 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1066 PcdMaximumUnicodeStringLength Unicode characters not including the
1067 Null-terminator, then ASSERT().
1068
1069 @param Destination The pointer to a Null-terminated Unicode string.
1070 @param Source The pointer to a Null-terminated Unicode string.
1071
1072 @return Destination.
1073
1074 **/
1075 CHAR16 *
1076 EFIAPI
1077 StrCpy (
1078 OUT CHAR16 *Destination,
1079 IN CONST CHAR16 *Source
1080 );
1081
1082
1083 /**
1084 [ATTENTION] This function is deprecated for security reason.
1085
1086 Copies up to a specified length from one Null-terminated Unicode string to
1087 another Null-terminated Unicode string and returns the new Unicode string.
1088
1089 This function copies the contents of the Unicode string Source to the Unicode
1090 string Destination, and returns Destination. At most, Length Unicode
1091 characters are copied from Source to Destination. If Length is 0, then
1092 Destination is returned unmodified. If Length is greater that the number of
1093 Unicode characters in Source, then Destination is padded with Null Unicode
1094 characters. If Source and Destination overlap, then the results are
1095 undefined.
1096
1097 If Length > 0 and Destination is NULL, then ASSERT().
1098 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1099 If Length > 0 and Source is NULL, then ASSERT().
1100 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1101 If Source and Destination overlap, then ASSERT().
1102 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1103 PcdMaximumUnicodeStringLength, then ASSERT().
1104 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1105 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1106 then ASSERT().
1107
1108 @param Destination The pointer to a Null-terminated Unicode string.
1109 @param Source The pointer to a Null-terminated Unicode string.
1110 @param Length The maximum number of Unicode characters to copy.
1111
1112 @return Destination.
1113
1114 **/
1115 CHAR16 *
1116 EFIAPI
1117 StrnCpy (
1118 OUT CHAR16 *Destination,
1119 IN CONST CHAR16 *Source,
1120 IN UINTN Length
1121 );
1122 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1123
1124 /**
1125 Returns the length of a Null-terminated Unicode string.
1126
1127 This function returns the number of Unicode characters in the Null-terminated
1128 Unicode string specified by String.
1129
1130 If String is NULL, then ASSERT().
1131 If String is not aligned on a 16-bit boundary, then ASSERT().
1132 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1133 PcdMaximumUnicodeStringLength Unicode characters not including the
1134 Null-terminator, then ASSERT().
1135
1136 @param String Pointer to a Null-terminated Unicode string.
1137
1138 @return The length of String.
1139
1140 **/
1141 UINTN
1142 EFIAPI
1143 StrLen (
1144 IN CONST CHAR16 *String
1145 );
1146
1147
1148 /**
1149 Returns the size of a Null-terminated Unicode string in bytes, including the
1150 Null terminator.
1151
1152 This function returns the size, in bytes, of the Null-terminated Unicode string
1153 specified by String.
1154
1155 If String is NULL, then ASSERT().
1156 If String is not aligned on a 16-bit boundary, then ASSERT().
1157 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1158 PcdMaximumUnicodeStringLength Unicode characters not including the
1159 Null-terminator, then ASSERT().
1160
1161 @param String The pointer to a Null-terminated Unicode string.
1162
1163 @return The size of String.
1164
1165 **/
1166 UINTN
1167 EFIAPI
1168 StrSize (
1169 IN CONST CHAR16 *String
1170 );
1171
1172
1173 /**
1174 Compares two Null-terminated Unicode strings, and returns the difference
1175 between the first mismatched Unicode characters.
1176
1177 This function compares the Null-terminated Unicode string FirstString to the
1178 Null-terminated Unicode string SecondString. If FirstString is identical to
1179 SecondString, then 0 is returned. Otherwise, the value returned is the first
1180 mismatched Unicode character in SecondString subtracted from the first
1181 mismatched Unicode character in FirstString.
1182
1183 If FirstString is NULL, then ASSERT().
1184 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1185 If SecondString is NULL, then ASSERT().
1186 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1187 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1188 than PcdMaximumUnicodeStringLength Unicode characters not including the
1189 Null-terminator, then ASSERT().
1190 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1191 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1192 Null-terminator, then ASSERT().
1193
1194 @param FirstString The pointer to a Null-terminated Unicode string.
1195 @param SecondString The pointer to a Null-terminated Unicode string.
1196
1197 @retval 0 FirstString is identical to SecondString.
1198 @return others FirstString is not identical to SecondString.
1199
1200 **/
1201 INTN
1202 EFIAPI
1203 StrCmp (
1204 IN CONST CHAR16 *FirstString,
1205 IN CONST CHAR16 *SecondString
1206 );
1207
1208
1209 /**
1210 Compares up to a specified length the contents of two Null-terminated Unicode strings,
1211 and returns the difference between the first mismatched Unicode characters.
1212
1213 This function compares the Null-terminated Unicode string FirstString to the
1214 Null-terminated Unicode string SecondString. At most, Length Unicode
1215 characters will be compared. If Length is 0, then 0 is returned. If
1216 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1217 value returned is the first mismatched Unicode character in SecondString
1218 subtracted from the first mismatched Unicode character in FirstString.
1219
1220 If Length > 0 and FirstString is NULL, then ASSERT().
1221 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1222 If Length > 0 and SecondString is NULL, then ASSERT().
1223 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1224 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1225 PcdMaximumUnicodeStringLength, then ASSERT().
1226 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1227 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1228 then ASSERT().
1229 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1230 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1231 then ASSERT().
1232
1233 @param FirstString The pointer to a Null-terminated Unicode string.
1234 @param SecondString The pointer to a Null-terminated Unicode string.
1235 @param Length The maximum number of Unicode characters to compare.
1236
1237 @retval 0 FirstString is identical to SecondString.
1238 @return others FirstString is not identical to SecondString.
1239
1240 **/
1241 INTN
1242 EFIAPI
1243 StrnCmp (
1244 IN CONST CHAR16 *FirstString,
1245 IN CONST CHAR16 *SecondString,
1246 IN UINTN Length
1247 );
1248
1249
1250 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1251
1252 /**
1253 [ATTENTION] This function is deprecated for security reason.
1254
1255 Concatenates one Null-terminated Unicode string to another Null-terminated
1256 Unicode string, and returns the concatenated Unicode string.
1257
1258 This function concatenates two Null-terminated Unicode strings. The contents
1259 of Null-terminated Unicode string Source are concatenated to the end of
1260 Null-terminated Unicode string Destination. The Null-terminated concatenated
1261 Unicode String is returned. If Source and Destination overlap, then the
1262 results are undefined.
1263
1264 If Destination is NULL, then ASSERT().
1265 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1266 If Source is NULL, then ASSERT().
1267 If Source is not aligned on a 16-bit boundary, then ASSERT().
1268 If Source and Destination overlap, then ASSERT().
1269 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1270 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1271 Null-terminator, then ASSERT().
1272 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1273 PcdMaximumUnicodeStringLength Unicode characters, not including the
1274 Null-terminator, then ASSERT().
1275 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1276 and Source results in a Unicode string with more than
1277 PcdMaximumUnicodeStringLength Unicode characters, not including the
1278 Null-terminator, then ASSERT().
1279
1280 @param Destination The pointer to a Null-terminated Unicode string.
1281 @param Source The pointer to a Null-terminated Unicode string.
1282
1283 @return Destination.
1284
1285 **/
1286 CHAR16 *
1287 EFIAPI
1288 StrCat (
1289 IN OUT CHAR16 *Destination,
1290 IN CONST CHAR16 *Source
1291 );
1292
1293
1294 /**
1295 [ATTENTION] This function is deprecated for security reason.
1296
1297 Concatenates up to a specified length one Null-terminated Unicode to the end
1298 of another Null-terminated Unicode string, and returns the concatenated
1299 Unicode string.
1300
1301 This function concatenates two Null-terminated Unicode strings. The contents
1302 of Null-terminated Unicode string Source are concatenated to the end of
1303 Null-terminated Unicode string Destination, and Destination is returned. At
1304 most, Length Unicode characters are concatenated from Source to the end of
1305 Destination, and Destination is always Null-terminated. If Length is 0, then
1306 Destination is returned unmodified. If Source and Destination overlap, then
1307 the results are undefined.
1308
1309 If Destination is NULL, then ASSERT().
1310 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1311 If Length > 0 and Source is NULL, then ASSERT().
1312 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1313 If Source and Destination overlap, then ASSERT().
1314 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1315 PcdMaximumUnicodeStringLength, then ASSERT().
1316 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1317 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1318 Null-terminator, then ASSERT().
1319 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1320 PcdMaximumUnicodeStringLength Unicode characters, not including the
1321 Null-terminator, then ASSERT().
1322 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1323 and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength
1324 Unicode characters, not including the Null-terminator, then ASSERT().
1325
1326 @param Destination The pointer to a Null-terminated Unicode string.
1327 @param Source The pointer to a Null-terminated Unicode string.
1328 @param Length The maximum number of Unicode characters to concatenate from
1329 Source.
1330
1331 @return Destination.
1332
1333 **/
1334 CHAR16 *
1335 EFIAPI
1336 StrnCat (
1337 IN OUT CHAR16 *Destination,
1338 IN CONST CHAR16 *Source,
1339 IN UINTN Length
1340 );
1341 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1342
1343 /**
1344 Returns the first occurrence of a Null-terminated Unicode sub-string
1345 in a Null-terminated Unicode string.
1346
1347 This function scans the contents of the Null-terminated Unicode string
1348 specified by String and returns the first occurrence of SearchString.
1349 If SearchString is not found in String, then NULL is returned. If
1350 the length of SearchString is zero, then String is returned.
1351
1352 If String is NULL, then ASSERT().
1353 If String is not aligned on a 16-bit boundary, then ASSERT().
1354 If SearchString is NULL, then ASSERT().
1355 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1356
1357 If PcdMaximumUnicodeStringLength is not zero, and SearchString
1358 or String contains more than PcdMaximumUnicodeStringLength Unicode
1359 characters, not including the Null-terminator, then ASSERT().
1360
1361 @param String The pointer to a Null-terminated Unicode string.
1362 @param SearchString The pointer to a Null-terminated Unicode string to search for.
1363
1364 @retval NULL If the SearchString does not appear in String.
1365 @return others If there is a match.
1366
1367 **/
1368 CHAR16 *
1369 EFIAPI
1370 StrStr (
1371 IN CONST CHAR16 *String,
1372 IN CONST CHAR16 *SearchString
1373 );
1374
1375 /**
1376 Convert a Null-terminated Unicode decimal string to a value of
1377 type UINTN.
1378
1379 This function returns a value of type UINTN by interpreting the contents
1380 of the Unicode string specified by String as a decimal number. The format
1381 of the input Unicode string String is:
1382
1383 [spaces] [decimal digits].
1384
1385 The valid decimal digit character is in the range [0-9]. The
1386 function will ignore the pad space, which includes spaces or
1387 tab characters, before [decimal digits]. The running zero in the
1388 beginning of [decimal digits] will be ignored. Then, the function
1389 stops at the first character that is a not a valid decimal character
1390 or a Null-terminator, whichever one comes first.
1391
1392 If String is NULL, then ASSERT().
1393 If String is not aligned in a 16-bit boundary, then ASSERT().
1394 If String has only pad spaces, then 0 is returned.
1395 If String has no pad spaces or valid decimal digits,
1396 then 0 is returned.
1397 If the number represented by String overflows according
1398 to the range defined by UINTN, then MAX_UINTN is returned.
1399
1400 If PcdMaximumUnicodeStringLength is not zero, and String contains
1401 more than PcdMaximumUnicodeStringLength Unicode characters not including
1402 the Null-terminator, then ASSERT().
1403
1404 @param String The pointer to a Null-terminated Unicode string.
1405
1406 @retval Value translated from String.
1407
1408 **/
1409 UINTN
1410 EFIAPI
1411 StrDecimalToUintn (
1412 IN CONST CHAR16 *String
1413 );
1414
1415 /**
1416 Convert a Null-terminated Unicode decimal string to a value of
1417 type UINT64.
1418
1419 This function returns a value of type UINT64 by interpreting the contents
1420 of the Unicode string specified by String as a decimal number. The format
1421 of the input Unicode string String is:
1422
1423 [spaces] [decimal digits].
1424
1425 The valid decimal digit character is in the range [0-9]. The
1426 function will ignore the pad space, which includes spaces or
1427 tab characters, before [decimal digits]. The running zero in the
1428 beginning of [decimal digits] will be ignored. Then, the function
1429 stops at the first character that is a not a valid decimal character
1430 or a Null-terminator, whichever one comes first.
1431
1432 If String is NULL, then ASSERT().
1433 If String is not aligned in a 16-bit boundary, then ASSERT().
1434 If String has only pad spaces, then 0 is returned.
1435 If String has no pad spaces or valid decimal digits,
1436 then 0 is returned.
1437 If the number represented by String overflows according
1438 to the range defined by UINT64, then MAX_UINT64 is returned.
1439
1440 If PcdMaximumUnicodeStringLength is not zero, and String contains
1441 more than PcdMaximumUnicodeStringLength Unicode characters not including
1442 the Null-terminator, then ASSERT().
1443
1444 @param String The pointer to a Null-terminated Unicode string.
1445
1446 @retval Value translated from String.
1447
1448 **/
1449 UINT64
1450 EFIAPI
1451 StrDecimalToUint64 (
1452 IN CONST CHAR16 *String
1453 );
1454
1455
1456 /**
1457 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1458
1459 This function returns a value of type UINTN by interpreting the contents
1460 of the Unicode string specified by String as a hexadecimal number.
1461 The format of the input Unicode string String is:
1462
1463 [spaces][zeros][x][hexadecimal digits].
1464
1465 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1466 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1467 If "x" appears in the input string, it must be prefixed with at least one 0.
1468 The function will ignore the pad space, which includes spaces or tab characters,
1469 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1470 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1471 first valid hexadecimal digit. Then, the function stops at the first character
1472 that is a not a valid hexadecimal character or NULL, whichever one comes first.
1473
1474 If String is NULL, then ASSERT().
1475 If String is not aligned in a 16-bit boundary, then ASSERT().
1476 If String has only pad spaces, then zero is returned.
1477 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1478 then zero is returned.
1479 If the number represented by String overflows according to the range defined by
1480 UINTN, then MAX_UINTN is returned.
1481
1482 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1483 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1484 then ASSERT().
1485
1486 @param String The pointer to a Null-terminated Unicode string.
1487
1488 @retval Value translated from String.
1489
1490 **/
1491 UINTN
1492 EFIAPI
1493 StrHexToUintn (
1494 IN CONST CHAR16 *String
1495 );
1496
1497
1498 /**
1499 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1500
1501 This function returns a value of type UINT64 by interpreting the contents
1502 of the Unicode string specified by String as a hexadecimal number.
1503 The format of the input Unicode string String is
1504
1505 [spaces][zeros][x][hexadecimal digits].
1506
1507 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1508 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1509 If "x" appears in the input string, it must be prefixed with at least one 0.
1510 The function will ignore the pad space, which includes spaces or tab characters,
1511 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1512 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1513 first valid hexadecimal digit. Then, the function stops at the first character that is
1514 a not a valid hexadecimal character or NULL, whichever one comes first.
1515
1516 If String is NULL, then ASSERT().
1517 If String is not aligned in a 16-bit boundary, then ASSERT().
1518 If String has only pad spaces, then zero is returned.
1519 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1520 then zero is returned.
1521 If the number represented by String overflows according to the range defined by
1522 UINT64, then MAX_UINT64 is returned.
1523
1524 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1525 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1526 then ASSERT().
1527
1528 @param String The pointer to a Null-terminated Unicode string.
1529
1530 @retval Value translated from String.
1531
1532 **/
1533 UINT64
1534 EFIAPI
1535 StrHexToUint64 (
1536 IN CONST CHAR16 *String
1537 );
1538
1539 /**
1540 Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1541
1542 This function outputs a value of type IPv6_ADDRESS and may output a value
1543 of type UINT8 by interpreting the contents of the Unicode string specified
1544 by String. The format of the input Unicode string String is as follows:
1545
1546 X:X:X:X:X:X:X:X[/P]
1547
1548 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1549 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1550 memory address and high byte is stored in high memory address. P contains decimal
1551 digit characters in the range [0-9]. The running zero in the beginning of P will
1552 be ignored. /P is optional.
1553
1554 When /P is not in the String, the function stops at the first character that is
1555 not a valid hexadecimal digit character after eight X's are converted.
1556
1557 When /P is in the String, the function stops at the first character that is not
1558 a valid decimal digit character after P is converted.
1559
1560 "::" can be used to compress one or more groups of X when X contains only 0.
1561 The "::" can only appear once in the String.
1562
1563 If String is NULL, then ASSERT().
1564
1565 If Address is NULL, then ASSERT().
1566
1567 If String is not aligned in a 16-bit boundary, then ASSERT().
1568
1569 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1570 PcdMaximumUnicodeStringLength Unicode characters, not including the
1571 Null-terminator, then ASSERT().
1572
1573 If EndPointer is not NULL and Address is translated from String, a pointer
1574 to the character that stopped the scan is stored at the location pointed to
1575 by EndPointer.
1576
1577 @param String Pointer to a Null-terminated Unicode string.
1578 @param EndPointer Pointer to character that stops scan.
1579 @param Address Pointer to the converted IPv6 address.
1580 @param PrefixLength Pointer to the converted IPv6 address prefix
1581 length. MAX_UINT8 is returned when /P is
1582 not in the String.
1583
1584 @retval RETURN_SUCCESS Address is translated from String.
1585 @retval RETURN_INVALID_PARAMETER If String is NULL.
1586 If Data is NULL.
1587 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1588 digit characters.
1589 If String contains "::" and number of X
1590 is not less than 8.
1591 If P starts with character that is not a
1592 valid decimal digit character.
1593 If the decimal number converted from P
1594 exceeds 128.
1595
1596 **/
1597 RETURN_STATUS
1598 EFIAPI
1599 StrToIpv6Address (
1600 IN CONST CHAR16 *String,
1601 OUT CHAR16 **EndPointer, OPTIONAL
1602 OUT IPv6_ADDRESS *Address,
1603 OUT UINT8 *PrefixLength OPTIONAL
1604 );
1605
1606 /**
1607 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1608
1609 This function outputs a value of type IPv4_ADDRESS and may output a value
1610 of type UINT8 by interpreting the contents of the Unicode string specified
1611 by String. The format of the input Unicode string String is as follows:
1612
1613 D.D.D.D[/P]
1614
1615 D and P are decimal digit characters in the range [0-9]. The running zero in
1616 the beginning of D and P will be ignored. /P is optional.
1617
1618 When /P is not in the String, the function stops at the first character that is
1619 not a valid decimal digit character after four D's are converted.
1620
1621 When /P is in the String, the function stops at the first character that is not
1622 a valid decimal digit character after P is converted.
1623
1624 If String is NULL, then ASSERT().
1625
1626 If Address is NULL, then ASSERT().
1627
1628 If String is not aligned in a 16-bit boundary, then ASSERT().
1629
1630 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1631 PcdMaximumUnicodeStringLength Unicode characters, not including the
1632 Null-terminator, then ASSERT().
1633
1634 If EndPointer is not NULL and Address is translated from String, a pointer
1635 to the character that stopped the scan is stored at the location pointed to
1636 by EndPointer.
1637
1638 @param String Pointer to a Null-terminated Unicode string.
1639 @param EndPointer Pointer to character that stops scan.
1640 @param Address Pointer to the converted IPv4 address.
1641 @param PrefixLength Pointer to the converted IPv4 address prefix
1642 length. MAX_UINT8 is returned when /P is
1643 not in the String.
1644
1645 @retval RETURN_SUCCESS Address is translated from String.
1646 @retval RETURN_INVALID_PARAMETER If String is NULL.
1647 If Data is NULL.
1648 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1649 If any decimal number converted from D
1650 exceeds 255.
1651 If the decimal number converted from P
1652 exceeds 32.
1653
1654 **/
1655 RETURN_STATUS
1656 EFIAPI
1657 StrToIpv4Address (
1658 IN CONST CHAR16 *String,
1659 OUT CHAR16 **EndPointer, OPTIONAL
1660 OUT IPv4_ADDRESS *Address,
1661 OUT UINT8 *PrefixLength OPTIONAL
1662 );
1663
1664 #define GUID_STRING_LENGTH 36
1665
1666 /**
1667 Convert a Null-terminated Unicode GUID string to a value of type
1668 EFI_GUID.
1669
1670 This function outputs a GUID value by interpreting the contents of
1671 the Unicode string specified by String. The format of the input
1672 Unicode string String consists of 36 characters, as follows:
1673
1674 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1675
1676 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1677 [A-F], with each pair representing a single byte hexadecimal value.
1678
1679 The mapping between String and the EFI_GUID structure is as follows:
1680 aa Data1[24:31]
1681 bb Data1[16:23]
1682 cc Data1[8:15]
1683 dd Data1[0:7]
1684 ee Data2[8:15]
1685 ff Data2[0:7]
1686 gg Data3[8:15]
1687 hh Data3[0:7]
1688 ii Data4[0:7]
1689 jj Data4[8:15]
1690 kk Data4[16:23]
1691 ll Data4[24:31]
1692 mm Data4[32:39]
1693 nn Data4[40:47]
1694 oo Data4[48:55]
1695 pp Data4[56:63]
1696
1697 If String is NULL, then ASSERT().
1698 If Guid is NULL, then ASSERT().
1699 If String is not aligned in a 16-bit boundary, then ASSERT().
1700
1701 @param String Pointer to a Null-terminated Unicode string.
1702 @param Guid Pointer to the converted GUID.
1703
1704 @retval RETURN_SUCCESS Guid is translated from String.
1705 @retval RETURN_INVALID_PARAMETER If String is NULL.
1706 If Data is NULL.
1707 @retval RETURN_UNSUPPORTED If String is not as the above format.
1708
1709 **/
1710 RETURN_STATUS
1711 EFIAPI
1712 StrToGuid (
1713 IN CONST CHAR16 *String,
1714 OUT GUID *Guid
1715 );
1716
1717 /**
1718 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1719
1720 This function outputs a byte array by interpreting the contents of
1721 the Unicode string specified by String in hexadecimal format. The format of
1722 the input Unicode string String is:
1723
1724 [XX]*
1725
1726 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1727 The function decodes every two hexadecimal digit characters as one byte. The
1728 decoding stops after Length of characters and outputs Buffer containing
1729 (Length / 2) bytes.
1730
1731 If String is not aligned in a 16-bit boundary, then ASSERT().
1732
1733 If String is NULL, then ASSERT().
1734
1735 If Buffer is NULL, then ASSERT().
1736
1737 If Length is not multiple of 2, then ASSERT().
1738
1739 If PcdMaximumUnicodeStringLength is not zero and Length is greater than
1740 PcdMaximumUnicodeStringLength, then ASSERT().
1741
1742 If MaxBufferSize is less than (Length / 2), then ASSERT().
1743
1744 @param String Pointer to a Null-terminated Unicode string.
1745 @param Length The number of Unicode characters to decode.
1746 @param Buffer Pointer to the converted bytes array.
1747 @param MaxBufferSize The maximum size of Buffer.
1748
1749 @retval RETURN_SUCCESS Buffer is translated from String.
1750 @retval RETURN_INVALID_PARAMETER If String is NULL.
1751 If Data is NULL.
1752 If Length is not multiple of 2.
1753 If PcdMaximumUnicodeStringLength is not zero,
1754 and Length is greater than
1755 PcdMaximumUnicodeStringLength.
1756 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1757 a character that is not valid hexadecimal
1758 digit characters, or a Null-terminator.
1759 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1760 **/
1761 RETURN_STATUS
1762 EFIAPI
1763 StrHexToBytes (
1764 IN CONST CHAR16 *String,
1765 IN UINTN Length,
1766 OUT UINT8 *Buffer,
1767 IN UINTN MaxBufferSize
1768 );
1769
1770 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1771
1772 /**
1773 [ATTENTION] This function is deprecated for security reason.
1774
1775 Convert a Null-terminated Unicode string to a Null-terminated
1776 ASCII string and returns the ASCII string.
1777
1778 This function converts the content of the Unicode string Source
1779 to the ASCII string Destination by copying the lower 8 bits of
1780 each Unicode character. It returns Destination.
1781
1782 The caller is responsible to make sure Destination points to a buffer with size
1783 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1784
1785 If any Unicode characters in Source contain non-zero value in
1786 the upper 8 bits, then ASSERT().
1787
1788 If Destination is NULL, then ASSERT().
1789 If Source is NULL, then ASSERT().
1790 If Source is not aligned on a 16-bit boundary, then ASSERT().
1791 If Source and Destination overlap, then ASSERT().
1792
1793 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1794 more than PcdMaximumUnicodeStringLength Unicode characters not including
1795 the Null-terminator, then ASSERT().
1796
1797 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1798 than PcdMaximumAsciiStringLength Unicode characters not including the
1799 Null-terminator, then ASSERT().
1800
1801 @param Source The pointer to a Null-terminated Unicode string.
1802 @param Destination The pointer to a Null-terminated ASCII string.
1803
1804 @return Destination.
1805
1806 **/
1807 CHAR8 *
1808 EFIAPI
1809 UnicodeStrToAsciiStr (
1810 IN CONST CHAR16 *Source,
1811 OUT CHAR8 *Destination
1812 );
1813
1814 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1815
1816 /**
1817 Convert a Null-terminated Unicode string to a Null-terminated
1818 ASCII string.
1819
1820 This function is similar to AsciiStrCpyS.
1821
1822 This function converts the content of the Unicode string Source
1823 to the ASCII string Destination by copying the lower 8 bits of
1824 each Unicode character. The function terminates the ASCII string
1825 Destination by appending a Null-terminator character at the end.
1826
1827 The caller is responsible to make sure Destination points to a buffer with size
1828 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1829
1830 If any Unicode characters in Source contain non-zero value in
1831 the upper 8 bits, then ASSERT().
1832
1833 If Source is not aligned on a 16-bit boundary, then ASSERT().
1834 If an error would be returned, then the function will also ASSERT().
1835
1836 If an error is returned, then the Destination is unmodified.
1837
1838 @param Source The pointer to a Null-terminated Unicode string.
1839 @param Destination The pointer to a Null-terminated ASCII string.
1840 @param DestMax The maximum number of Destination Ascii
1841 char, including terminating null char.
1842
1843 @retval RETURN_SUCCESS String is converted.
1844 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1845 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1846 If Source is NULL.
1847 If PcdMaximumAsciiStringLength is not zero,
1848 and DestMax is greater than
1849 PcdMaximumAsciiStringLength.
1850 If PcdMaximumUnicodeStringLength is not zero,
1851 and DestMax is greater than
1852 PcdMaximumUnicodeStringLength.
1853 If DestMax is 0.
1854 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1855
1856 **/
1857 RETURN_STATUS
1858 EFIAPI
1859 UnicodeStrToAsciiStrS (
1860 IN CONST CHAR16 *Source,
1861 OUT CHAR8 *Destination,
1862 IN UINTN DestMax
1863 );
1864
1865 /**
1866 Convert not more than Length successive characters from a Null-terminated
1867 Unicode string to a Null-terminated Ascii string. If no null char is copied
1868 from Source, then Destination[Length] is always set to null.
1869
1870 This function converts not more than Length successive characters from the
1871 Unicode string Source to the Ascii string Destination by copying the lower 8
1872 bits of each Unicode character. The function terminates the Ascii string
1873 Destination by appending a Null-terminator character at the end.
1874
1875 The caller is responsible to make sure Destination points to a buffer with size
1876 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1877
1878 If any Unicode characters in Source contain non-zero value in the upper 8
1879 bits, then ASSERT().
1880 If Source is not aligned on a 16-bit boundary, then ASSERT().
1881 If an error would be returned, then the function will also ASSERT().
1882
1883 If an error is returned, then the Destination is unmodified.
1884
1885 @param Source The pointer to a Null-terminated Unicode string.
1886 @param Length The maximum number of Unicode characters to
1887 convert.
1888 @param Destination The pointer to a Null-terminated Ascii string.
1889 @param DestMax The maximum number of Destination Ascii
1890 char, including terminating null char.
1891 @param DestinationLength The number of Unicode characters converted.
1892
1893 @retval RETURN_SUCCESS String is converted.
1894 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1895 If Source is NULL.
1896 If DestinationLength is NULL.
1897 If PcdMaximumAsciiStringLength is not zero,
1898 and Length or DestMax is greater than
1899 PcdMaximumAsciiStringLength.
1900 If PcdMaximumUnicodeStringLength is not
1901 zero, and Length or DestMax is greater than
1902 PcdMaximumUnicodeStringLength.
1903 If DestMax is 0.
1904 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1905 MIN(StrLen(Source), Length).
1906 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1907
1908 **/
1909 RETURN_STATUS
1910 EFIAPI
1911 UnicodeStrnToAsciiStrS (
1912 IN CONST CHAR16 *Source,
1913 IN UINTN Length,
1914 OUT CHAR8 *Destination,
1915 IN UINTN DestMax,
1916 OUT UINTN *DestinationLength
1917 );
1918
1919 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1920
1921 /**
1922 [ATTENTION] This function is deprecated for security reason.
1923
1924 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1925 string and returns the new ASCII string.
1926
1927 This function copies the contents of the ASCII string Source to the ASCII
1928 string Destination, and returns Destination. If Source and Destination
1929 overlap, then the results are undefined.
1930
1931 If Destination is NULL, then ASSERT().
1932 If Source is NULL, then ASSERT().
1933 If Source and Destination overlap, then ASSERT().
1934 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1935 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1936 then ASSERT().
1937
1938 @param Destination The pointer to a Null-terminated ASCII string.
1939 @param Source The pointer to a Null-terminated ASCII string.
1940
1941 @return Destination
1942
1943 **/
1944 CHAR8 *
1945 EFIAPI
1946 AsciiStrCpy (
1947 OUT CHAR8 *Destination,
1948 IN CONST CHAR8 *Source
1949 );
1950
1951
1952 /**
1953 [ATTENTION] This function is deprecated for security reason.
1954
1955 Copies up to a specified length one Null-terminated ASCII string to another
1956 Null-terminated ASCII string and returns the new ASCII string.
1957
1958 This function copies the contents of the ASCII string Source to the ASCII
1959 string Destination, and returns Destination. At most, Length ASCII characters
1960 are copied from Source to Destination. If Length is 0, then Destination is
1961 returned unmodified. If Length is greater that the number of ASCII characters
1962 in Source, then Destination is padded with Null ASCII characters. If Source
1963 and Destination overlap, then the results are undefined.
1964
1965 If Destination is NULL, then ASSERT().
1966 If Source is NULL, then ASSERT().
1967 If Source and Destination overlap, then ASSERT().
1968 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1969 PcdMaximumAsciiStringLength, then ASSERT().
1970 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1971 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1972 then ASSERT().
1973
1974 @param Destination The pointer to a Null-terminated ASCII string.
1975 @param Source The pointer to a Null-terminated ASCII string.
1976 @param Length The maximum number of ASCII characters to copy.
1977
1978 @return Destination
1979
1980 **/
1981 CHAR8 *
1982 EFIAPI
1983 AsciiStrnCpy (
1984 OUT CHAR8 *Destination,
1985 IN CONST CHAR8 *Source,
1986 IN UINTN Length
1987 );
1988 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1989
1990 /**
1991 Returns the length of a Null-terminated ASCII string.
1992
1993 This function returns the number of ASCII characters in the Null-terminated
1994 ASCII string specified by String.
1995
1996 If Length > 0 and Destination is NULL, then ASSERT().
1997 If Length > 0 and Source is NULL, then ASSERT().
1998 If PcdMaximumAsciiStringLength is not zero and String contains more than
1999 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2000 then ASSERT().
2001
2002 @param String The pointer to a Null-terminated ASCII string.
2003
2004 @return The length of String.
2005
2006 **/
2007 UINTN
2008 EFIAPI
2009 AsciiStrLen (
2010 IN CONST CHAR8 *String
2011 );
2012
2013
2014 /**
2015 Returns the size of a Null-terminated ASCII string in bytes, including the
2016 Null terminator.
2017
2018 This function returns the size, in bytes, of the Null-terminated ASCII string
2019 specified by String.
2020
2021 If String is NULL, then ASSERT().
2022 If PcdMaximumAsciiStringLength is not zero and String contains more than
2023 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2024 then ASSERT().
2025
2026 @param String The pointer to a Null-terminated ASCII string.
2027
2028 @return The size of String.
2029
2030 **/
2031 UINTN
2032 EFIAPI
2033 AsciiStrSize (
2034 IN CONST CHAR8 *String
2035 );
2036
2037
2038 /**
2039 Compares two Null-terminated ASCII strings, and returns the difference
2040 between the first mismatched ASCII characters.
2041
2042 This function compares the Null-terminated ASCII string FirstString to the
2043 Null-terminated ASCII string SecondString. If FirstString is identical to
2044 SecondString, then 0 is returned. Otherwise, the value returned is the first
2045 mismatched ASCII character in SecondString subtracted from the first
2046 mismatched ASCII character in FirstString.
2047
2048 If FirstString is NULL, then ASSERT().
2049 If SecondString is NULL, then ASSERT().
2050 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
2051 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2052 then ASSERT().
2053 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2054 than PcdMaximumAsciiStringLength ASCII characters not including the
2055 Null-terminator, then ASSERT().
2056
2057 @param FirstString The pointer to a Null-terminated ASCII string.
2058 @param SecondString The pointer to a Null-terminated ASCII string.
2059
2060 @retval ==0 FirstString is identical to SecondString.
2061 @retval !=0 FirstString is not identical to SecondString.
2062
2063 **/
2064 INTN
2065 EFIAPI
2066 AsciiStrCmp (
2067 IN CONST CHAR8 *FirstString,
2068 IN CONST CHAR8 *SecondString
2069 );
2070
2071
2072 /**
2073 Performs a case insensitive comparison of two Null-terminated ASCII strings,
2074 and returns the difference between the first mismatched ASCII characters.
2075
2076 This function performs a case insensitive comparison of the Null-terminated
2077 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
2078 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
2079 value returned is the first mismatched lower case ASCII character in
2080 SecondString subtracted from the first mismatched lower case ASCII character
2081 in FirstString.
2082
2083 If FirstString is NULL, then ASSERT().
2084 If SecondString is NULL, then ASSERT().
2085 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
2086 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2087 then ASSERT().
2088 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2089 than PcdMaximumAsciiStringLength ASCII characters not including the
2090 Null-terminator, then ASSERT().
2091
2092 @param FirstString The pointer to a Null-terminated ASCII string.
2093 @param SecondString The pointer to a Null-terminated ASCII string.
2094
2095 @retval ==0 FirstString is identical to SecondString using case insensitive
2096 comparisons.
2097 @retval !=0 FirstString is not identical to SecondString using case
2098 insensitive comparisons.
2099
2100 **/
2101 INTN
2102 EFIAPI
2103 AsciiStriCmp (
2104 IN CONST CHAR8 *FirstString,
2105 IN CONST CHAR8 *SecondString
2106 );
2107
2108
2109 /**
2110 Compares two Null-terminated ASCII strings with maximum lengths, and returns
2111 the difference between the first mismatched ASCII characters.
2112
2113 This function compares the Null-terminated ASCII string FirstString to the
2114 Null-terminated ASCII string SecondString. At most, Length ASCII characters
2115 will be compared. If Length is 0, then 0 is returned. If FirstString is
2116 identical to SecondString, then 0 is returned. Otherwise, the value returned
2117 is the first mismatched ASCII character in SecondString subtracted from the
2118 first mismatched ASCII character in FirstString.
2119
2120 If Length > 0 and FirstString is NULL, then ASSERT().
2121 If Length > 0 and SecondString is NULL, then ASSERT().
2122 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
2123 PcdMaximumAsciiStringLength, then ASSERT().
2124 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
2125 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2126 then ASSERT().
2127 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
2128 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2129 then ASSERT().
2130
2131 @param FirstString The pointer to a Null-terminated ASCII string.
2132 @param SecondString The pointer to a Null-terminated ASCII string.
2133 @param Length The maximum number of ASCII characters for compare.
2134
2135 @retval ==0 FirstString is identical to SecondString.
2136 @retval !=0 FirstString is not identical to SecondString.
2137
2138 **/
2139 INTN
2140 EFIAPI
2141 AsciiStrnCmp (
2142 IN CONST CHAR8 *FirstString,
2143 IN CONST CHAR8 *SecondString,
2144 IN UINTN Length
2145 );
2146
2147
2148 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2149
2150 /**
2151 [ATTENTION] This function is deprecated for security reason.
2152
2153 Concatenates one Null-terminated ASCII string to another Null-terminated
2154 ASCII string, and returns the concatenated ASCII string.
2155
2156 This function concatenates two Null-terminated ASCII strings. The contents of
2157 Null-terminated ASCII string Source are concatenated to the end of Null-
2158 terminated ASCII string Destination. The Null-terminated concatenated ASCII
2159 String is returned.
2160
2161 If Destination is NULL, then ASSERT().
2162 If Source is NULL, then ASSERT().
2163 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
2164 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2165 then ASSERT().
2166 If PcdMaximumAsciiStringLength is not zero and Source contains more than
2167 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2168 then ASSERT().
2169 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
2170 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
2171 ASCII characters, then ASSERT().
2172
2173 @param Destination The pointer to a Null-terminated ASCII string.
2174 @param Source The pointer to a Null-terminated ASCII string.
2175
2176 @return Destination
2177
2178 **/
2179 CHAR8 *
2180 EFIAPI
2181 AsciiStrCat (
2182 IN OUT CHAR8 *Destination,
2183 IN CONST CHAR8 *Source
2184 );
2185
2186
2187 /**
2188 [ATTENTION] This function is deprecated for security reason.
2189
2190 Concatenates up to a specified length one Null-terminated ASCII string to
2191 the end of another Null-terminated ASCII string, and returns the
2192 concatenated ASCII string.
2193
2194 This function concatenates two Null-terminated ASCII strings. The contents
2195 of Null-terminated ASCII string Source are concatenated to the end of Null-
2196 terminated ASCII string Destination, and Destination is returned. At most,
2197 Length ASCII characters are concatenated from Source to the end of
2198 Destination, and Destination is always Null-terminated. If Length is 0, then
2199 Destination is returned unmodified. If Source and Destination overlap, then
2200 the results are undefined.
2201
2202 If Length > 0 and Destination is NULL, then ASSERT().
2203 If Length > 0 and Source is NULL, then ASSERT().
2204 If Source and Destination overlap, then ASSERT().
2205 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
2206 PcdMaximumAsciiStringLength, then ASSERT().
2207 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
2208 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2209 then ASSERT().
2210 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2211 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2212 then ASSERT().
2213 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
2214 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
2215 ASCII characters, not including the Null-terminator, then ASSERT().
2216
2217 @param Destination The pointer to a Null-terminated ASCII string.
2218 @param Source The pointer to a Null-terminated ASCII string.
2219 @param Length The maximum number of ASCII characters to concatenate from
2220 Source.
2221
2222 @return Destination
2223
2224 **/
2225 CHAR8 *
2226 EFIAPI
2227 AsciiStrnCat (
2228 IN OUT CHAR8 *Destination,
2229 IN CONST CHAR8 *Source,
2230 IN UINTN Length
2231 );
2232 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
2233
2234 /**
2235 Returns the first occurrence of a Null-terminated ASCII sub-string
2236 in a Null-terminated ASCII string.
2237
2238 This function scans the contents of the ASCII string specified by String
2239 and returns the first occurrence of SearchString. If SearchString is not
2240 found in String, then NULL is returned. If the length of SearchString is zero,
2241 then String is returned.
2242
2243 If String is NULL, then ASSERT().
2244 If SearchString is NULL, then ASSERT().
2245
2246 If PcdMaximumAsciiStringLength is not zero, and SearchString or
2247 String contains more than PcdMaximumAsciiStringLength Unicode characters
2248 not including the Null-terminator, then ASSERT().
2249
2250 @param String The pointer to a Null-terminated ASCII string.
2251 @param SearchString The pointer to a Null-terminated ASCII string to search for.
2252
2253 @retval NULL If the SearchString does not appear in String.
2254 @retval others If there is a match return the first occurrence of SearchingString.
2255 If the length of SearchString is zero,return String.
2256
2257 **/
2258 CHAR8 *
2259 EFIAPI
2260 AsciiStrStr (
2261 IN CONST CHAR8 *String,
2262 IN CONST CHAR8 *SearchString
2263 );
2264
2265
2266 /**
2267 Convert a Null-terminated ASCII decimal string to a value of type
2268 UINTN.
2269
2270 This function returns a value of type UINTN by interpreting the contents
2271 of the ASCII string String as a decimal number. The format of the input
2272 ASCII string String is:
2273
2274 [spaces] [decimal digits].
2275
2276 The valid decimal digit character is in the range [0-9]. The function will
2277 ignore the pad space, which includes spaces or tab characters, before the digits.
2278 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2279 function stops at the first character that is a not a valid decimal character or
2280 Null-terminator, whichever on comes first.
2281
2282 If String has only pad spaces, then 0 is returned.
2283 If String has no pad spaces or valid decimal digits, then 0 is returned.
2284 If the number represented by String overflows according to the range defined by
2285 UINTN, then MAX_UINTN is returned.
2286 If String is NULL, then ASSERT().
2287 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2288 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2289 then ASSERT().
2290
2291 @param String The pointer to a Null-terminated ASCII string.
2292
2293 @retval The value translated from String.
2294
2295 **/
2296 UINTN
2297 EFIAPI
2298 AsciiStrDecimalToUintn (
2299 IN CONST CHAR8 *String
2300 );
2301
2302
2303 /**
2304 Convert a Null-terminated ASCII decimal string to a value of type
2305 UINT64.
2306
2307 This function returns a value of type UINT64 by interpreting the contents
2308 of the ASCII string String as a decimal number. The format of the input
2309 ASCII string String is:
2310
2311 [spaces] [decimal digits].
2312
2313 The valid decimal digit character is in the range [0-9]. The function will
2314 ignore the pad space, which includes spaces or tab characters, before the digits.
2315 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2316 function stops at the first character that is a not a valid decimal character or
2317 Null-terminator, whichever on comes first.
2318
2319 If String has only pad spaces, then 0 is returned.
2320 If String has no pad spaces or valid decimal digits, then 0 is returned.
2321 If the number represented by String overflows according to the range defined by
2322 UINT64, then MAX_UINT64 is returned.
2323 If String is NULL, then ASSERT().
2324 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2325 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2326 then ASSERT().
2327
2328 @param String The pointer to a Null-terminated ASCII string.
2329
2330 @retval Value translated from String.
2331
2332 **/
2333 UINT64
2334 EFIAPI
2335 AsciiStrDecimalToUint64 (
2336 IN CONST CHAR8 *String
2337 );
2338
2339
2340 /**
2341 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
2342
2343 This function returns a value of type UINTN by interpreting the contents of
2344 the ASCII string String as a hexadecimal number. The format of the input ASCII
2345 string String is:
2346
2347 [spaces][zeros][x][hexadecimal digits].
2348
2349 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2350 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2351 appears in the input string, it must be prefixed with at least one 0. The function
2352 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2353 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2354 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2355 digit. Then, the function stops at the first character that is a not a valid
2356 hexadecimal character or Null-terminator, whichever on comes first.
2357
2358 If String has only pad spaces, then 0 is returned.
2359 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2360 0 is returned.
2361
2362 If the number represented by String overflows according to the range defined by UINTN,
2363 then MAX_UINTN is returned.
2364 If String is NULL, then ASSERT().
2365 If PcdMaximumAsciiStringLength is not zero,
2366 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2367 the Null-terminator, then ASSERT().
2368
2369 @param String The pointer to a Null-terminated ASCII string.
2370
2371 @retval Value translated from String.
2372
2373 **/
2374 UINTN
2375 EFIAPI
2376 AsciiStrHexToUintn (
2377 IN CONST CHAR8 *String
2378 );
2379
2380
2381 /**
2382 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
2383
2384 This function returns a value of type UINT64 by interpreting the contents of
2385 the ASCII string String as a hexadecimal number. The format of the input ASCII
2386 string String is:
2387
2388 [spaces][zeros][x][hexadecimal digits].
2389
2390 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2391 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2392 appears in the input string, it must be prefixed with at least one 0. The function
2393 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2394 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2395 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2396 digit. Then, the function stops at the first character that is a not a valid
2397 hexadecimal character or Null-terminator, whichever on comes first.
2398
2399 If String has only pad spaces, then 0 is returned.
2400 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2401 0 is returned.
2402
2403 If the number represented by String overflows according to the range defined by UINT64,
2404 then MAX_UINT64 is returned.
2405 If String is NULL, then ASSERT().
2406 If PcdMaximumAsciiStringLength is not zero,
2407 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2408 the Null-terminator, then ASSERT().
2409
2410 @param String The pointer to a Null-terminated ASCII string.
2411
2412 @retval Value translated from String.
2413
2414 **/
2415 UINT64
2416 EFIAPI
2417 AsciiStrHexToUint64 (
2418 IN CONST CHAR8 *String
2419 );
2420
2421 /**
2422 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
2423
2424 This function outputs a value of type IPv6_ADDRESS and may output a value
2425 of type UINT8 by interpreting the contents of the ASCII string specified
2426 by String. The format of the input ASCII string String is as follows:
2427
2428 X:X:X:X:X:X:X:X[/P]
2429
2430 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
2431 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
2432 memory address and high byte is stored in high memory address. P contains decimal
2433 digit characters in the range [0-9]. The running zero in the beginning of P will
2434 be ignored. /P is optional.
2435
2436 When /P is not in the String, the function stops at the first character that is
2437 not a valid hexadecimal digit character after eight X's are converted.
2438
2439 When /P is in the String, the function stops at the first character that is not
2440 a valid decimal digit character after P is converted.
2441
2442 "::" can be used to compress one or more groups of X when X contains only 0.
2443 The "::" can only appear once in the String.
2444
2445 If String is NULL, then ASSERT().
2446
2447 If Address is NULL, then ASSERT().
2448
2449 If EndPointer is not NULL and Address is translated from String, a pointer
2450 to the character that stopped the scan is stored at the location pointed to
2451 by EndPointer.
2452
2453 @param String Pointer to a Null-terminated ASCII string.
2454 @param EndPointer Pointer to character that stops scan.
2455 @param Address Pointer to the converted IPv6 address.
2456 @param PrefixLength Pointer to the converted IPv6 address prefix
2457 length. MAX_UINT8 is returned when /P is
2458 not in the String.
2459
2460 @retval RETURN_SUCCESS Address is translated from String.
2461 @retval RETURN_INVALID_PARAMETER If String is NULL.
2462 If Data is NULL.
2463 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
2464 digit characters.
2465 If String contains "::" and number of X
2466 is not less than 8.
2467 If P starts with character that is not a
2468 valid decimal digit character.
2469 If the decimal number converted from P
2470 exceeds 128.
2471
2472 **/
2473 RETURN_STATUS
2474 EFIAPI
2475 AsciiStrToIpv6Address (
2476 IN CONST CHAR8 *String,
2477 OUT CHAR8 **EndPointer, OPTIONAL
2478 OUT IPv6_ADDRESS *Address,
2479 OUT UINT8 *PrefixLength OPTIONAL
2480 );
2481
2482 /**
2483 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
2484
2485 This function outputs a value of type IPv4_ADDRESS and may output a value
2486 of type UINT8 by interpreting the contents of the ASCII string specified
2487 by String. The format of the input ASCII string String is as follows:
2488
2489 D.D.D.D[/P]
2490
2491 D and P are decimal digit characters in the range [0-9]. The running zero in
2492 the beginning of D and P will be ignored. /P is optional.
2493
2494 When /P is not in the String, the function stops at the first character that is
2495 not a valid decimal digit character after four D's are converted.
2496
2497 When /P is in the String, the function stops at the first character that is not
2498 a valid decimal digit character after P is converted.
2499
2500 If String is NULL, then ASSERT().
2501
2502 If Address is NULL, then ASSERT().
2503
2504 If EndPointer is not NULL and Address is translated from String, a pointer
2505 to the character that stopped the scan is stored at the location pointed to
2506 by EndPointer.
2507
2508 @param String Pointer to a Null-terminated ASCII string.
2509 @param EndPointer Pointer to character that stops scan.
2510 @param Address Pointer to the converted IPv4 address.
2511 @param PrefixLength Pointer to the converted IPv4 address prefix
2512 length. MAX_UINT8 is returned when /P is
2513 not in the String.
2514
2515 @retval RETURN_SUCCESS Address is translated from String.
2516 @retval RETURN_INVALID_PARAMETER If String is NULL.
2517 If Data is NULL.
2518 @retval RETURN_UNSUPPORTED If String is not in the correct format.
2519 If any decimal number converted from D
2520 exceeds 255.
2521 If the decimal number converted from P
2522 exceeds 32.
2523
2524 **/
2525 RETURN_STATUS
2526 EFIAPI
2527 AsciiStrToIpv4Address (
2528 IN CONST CHAR8 *String,
2529 OUT CHAR8 **EndPointer, OPTIONAL
2530 OUT IPv4_ADDRESS *Address,
2531 OUT UINT8 *PrefixLength OPTIONAL
2532 );
2533
2534 /**
2535 Convert a Null-terminated ASCII GUID string to a value of type
2536 EFI_GUID.
2537
2538 This function outputs a GUID value by interpreting the contents of
2539 the ASCII string specified by String. The format of the input
2540 ASCII string String consists of 36 characters, as follows:
2541
2542 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
2543
2544 The pairs aa - pp are two characters in the range [0-9], [a-f] and
2545 [A-F], with each pair representing a single byte hexadecimal value.
2546
2547 The mapping between String and the EFI_GUID structure is as follows:
2548 aa Data1[24:31]
2549 bb Data1[16:23]
2550 cc Data1[8:15]
2551 dd Data1[0:7]
2552 ee Data2[8:15]
2553 ff Data2[0:7]
2554 gg Data3[8:15]
2555 hh Data3[0:7]
2556 ii Data4[0:7]
2557 jj Data4[8:15]
2558 kk Data4[16:23]
2559 ll Data4[24:31]
2560 mm Data4[32:39]
2561 nn Data4[40:47]
2562 oo Data4[48:55]
2563 pp Data4[56:63]
2564
2565 If String is NULL, then ASSERT().
2566 If Guid is NULL, then ASSERT().
2567
2568 @param String Pointer to a Null-terminated ASCII string.
2569 @param Guid Pointer to the converted GUID.
2570
2571 @retval RETURN_SUCCESS Guid is translated from String.
2572 @retval RETURN_INVALID_PARAMETER If String is NULL.
2573 If Data is NULL.
2574 @retval RETURN_UNSUPPORTED If String is not as the above format.
2575
2576 **/
2577 RETURN_STATUS
2578 EFIAPI
2579 AsciiStrToGuid (
2580 IN CONST CHAR8 *String,
2581 OUT GUID *Guid
2582 );
2583
2584 /**
2585 Convert a Null-terminated ASCII hexadecimal string to a byte array.
2586
2587 This function outputs a byte array by interpreting the contents of
2588 the ASCII string specified by String in hexadecimal format. The format of
2589 the input ASCII string String is:
2590
2591 [XX]*
2592
2593 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
2594 The function decodes every two hexadecimal digit characters as one byte. The
2595 decoding stops after Length of characters and outputs Buffer containing
2596 (Length / 2) bytes.
2597
2598 If String is NULL, then ASSERT().
2599
2600 If Buffer is NULL, then ASSERT().
2601
2602 If Length is not multiple of 2, then ASSERT().
2603
2604 If PcdMaximumAsciiStringLength is not zero and Length is greater than
2605 PcdMaximumAsciiStringLength, then ASSERT().
2606
2607 If MaxBufferSize is less than (Length / 2), then ASSERT().
2608
2609 @param String Pointer to a Null-terminated ASCII string.
2610 @param Length The number of ASCII characters to decode.
2611 @param Buffer Pointer to the converted bytes array.
2612 @param MaxBufferSize The maximum size of Buffer.
2613
2614 @retval RETURN_SUCCESS Buffer is translated from String.
2615 @retval RETURN_INVALID_PARAMETER If String is NULL.
2616 If Data is NULL.
2617 If Length is not multiple of 2.
2618 If PcdMaximumAsciiStringLength is not zero,
2619 and Length is greater than
2620 PcdMaximumAsciiStringLength.
2621 @retval RETURN_UNSUPPORTED If Length of characters from String contain
2622 a character that is not valid hexadecimal
2623 digit characters, or a Null-terminator.
2624 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
2625 **/
2626 RETURN_STATUS
2627 EFIAPI
2628 AsciiStrHexToBytes (
2629 IN CONST CHAR8 *String,
2630 IN UINTN Length,
2631 OUT UINT8 *Buffer,
2632 IN UINTN MaxBufferSize
2633 );
2634
2635 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2636
2637 /**
2638 [ATTENTION] This function is deprecated for security reason.
2639
2640 Convert one Null-terminated ASCII string to a Null-terminated
2641 Unicode string and returns the Unicode string.
2642
2643 This function converts the contents of the ASCII string Source to the Unicode
2644 string Destination, and returns Destination. The function terminates the
2645 Unicode string Destination by appending a Null-terminator character at the end.
2646 The caller is responsible to make sure Destination points to a buffer with size
2647 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2648
2649 If Destination is NULL, then ASSERT().
2650 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2651 If Source is NULL, then ASSERT().
2652 If Source and Destination overlap, then ASSERT().
2653 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2654 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2655 then ASSERT().
2656 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
2657 PcdMaximumUnicodeStringLength ASCII characters not including the
2658 Null-terminator, then ASSERT().
2659
2660 @param Source The pointer to a Null-terminated ASCII string.
2661 @param Destination The pointer to a Null-terminated Unicode string.
2662
2663 @return Destination.
2664
2665 **/
2666 CHAR16 *
2667 EFIAPI
2668 AsciiStrToUnicodeStr (
2669 IN CONST CHAR8 *Source,
2670 OUT CHAR16 *Destination
2671 );
2672
2673 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
2674
2675 /**
2676 Convert one Null-terminated ASCII string to a Null-terminated
2677 Unicode string.
2678
2679 This function is similar to StrCpyS.
2680
2681 This function converts the contents of the ASCII string Source to the Unicode
2682 string Destination. The function terminates the Unicode string Destination by
2683 appending a Null-terminator character at the end.
2684
2685 The caller is responsible to make sure Destination points to a buffer with size
2686 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2687
2688 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2689 If an error would be returned, then the function will also ASSERT().
2690
2691 If an error is returned, then the Destination is unmodified.
2692
2693 @param Source The pointer to a Null-terminated ASCII string.
2694 @param Destination The pointer to a Null-terminated Unicode string.
2695 @param DestMax The maximum number of Destination Unicode
2696 char, including terminating null char.
2697
2698 @retval RETURN_SUCCESS String is converted.
2699 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2700 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2701 If Source is NULL.
2702 If PcdMaximumUnicodeStringLength is not zero,
2703 and DestMax is greater than
2704 PcdMaximumUnicodeStringLength.
2705 If PcdMaximumAsciiStringLength is not zero,
2706 and DestMax is greater than
2707 PcdMaximumAsciiStringLength.
2708 If DestMax is 0.
2709 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2710
2711 **/
2712 RETURN_STATUS
2713 EFIAPI
2714 AsciiStrToUnicodeStrS (
2715 IN CONST CHAR8 *Source,
2716 OUT CHAR16 *Destination,
2717 IN UINTN DestMax
2718 );
2719
2720 /**
2721 Convert not more than Length successive characters from a Null-terminated
2722 Ascii string to a Null-terminated Unicode string. If no null char is copied
2723 from Source, then Destination[Length] is always set to null.
2724
2725 This function converts not more than Length successive characters from the
2726 Ascii string Source to the Unicode string Destination. The function
2727 terminates the Unicode string Destination by appending a Null-terminator
2728 character at the end.
2729
2730 The caller is responsible to make sure Destination points to a buffer with
2731 size not smaller than
2732 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2733
2734 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2735 If an error would be returned, then the function will also ASSERT().
2736
2737 If an error is returned, then Destination and DestinationLength are
2738 unmodified.
2739
2740 @param Source The pointer to a Null-terminated Ascii string.
2741 @param Length The maximum number of Ascii characters to convert.
2742 @param Destination The pointer to a Null-terminated Unicode string.
2743 @param DestMax The maximum number of Destination Unicode char,
2744 including terminating null char.
2745 @param DestinationLength The number of Ascii characters converted.
2746
2747 @retval RETURN_SUCCESS String is converted.
2748 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2749 If Source is NULL.
2750 If DestinationLength is NULL.
2751 If PcdMaximumUnicodeStringLength is not
2752 zero, and Length or DestMax is greater than
2753 PcdMaximumUnicodeStringLength.
2754 If PcdMaximumAsciiStringLength is not zero,
2755 and Length or DestMax is greater than
2756 PcdMaximumAsciiStringLength.
2757 If DestMax is 0.
2758 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2759 MIN(AsciiStrLen(Source), Length).
2760 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2761
2762 **/
2763 RETURN_STATUS
2764 EFIAPI
2765 AsciiStrnToUnicodeStrS (
2766 IN CONST CHAR8 *Source,
2767 IN UINTN Length,
2768 OUT CHAR16 *Destination,
2769 IN UINTN DestMax,
2770 OUT UINTN *DestinationLength
2771 );
2772
2773 /**
2774 Converts an 8-bit value to an 8-bit BCD value.
2775
2776 Converts the 8-bit value specified by Value to BCD. The BCD value is
2777 returned.
2778
2779 If Value >= 100, then ASSERT().
2780
2781 @param Value The 8-bit value to convert to BCD. Range 0..99.
2782
2783 @return The BCD value.
2784
2785 **/
2786 UINT8
2787 EFIAPI
2788 DecimalToBcd8 (
2789 IN UINT8 Value
2790 );
2791
2792
2793 /**
2794 Converts an 8-bit BCD value to an 8-bit value.
2795
2796 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2797 value is returned.
2798
2799 If Value >= 0xA0, then ASSERT().
2800 If (Value & 0x0F) >= 0x0A, then ASSERT().
2801
2802 @param Value The 8-bit BCD value to convert to an 8-bit value.
2803
2804 @return The 8-bit value is returned.
2805
2806 **/
2807 UINT8
2808 EFIAPI
2809 BcdToDecimal8 (
2810 IN UINT8 Value
2811 );
2812
2813 //
2814 // File Path Manipulation Functions
2815 //
2816
2817 /**
2818 Removes the last directory or file entry in a path.
2819
2820 @param[in, out] Path The pointer to the path to modify.
2821
2822 @retval FALSE Nothing was found to remove.
2823 @retval TRUE A directory or file was removed.
2824 **/
2825 BOOLEAN
2826 EFIAPI
2827 PathRemoveLastItem(
2828 IN OUT CHAR16 *Path
2829 );
2830
2831 /**
2832 Function to clean up paths.
2833 - Single periods in the path are removed.
2834 - Double periods in the path are removed along with a single parent directory.
2835 - Forward slashes L'/' are converted to backward slashes L'\'.
2836
2837 This will be done inline and the existing buffer may be larger than required
2838 upon completion.
2839
2840 @param[in] Path The pointer to the string containing the path.
2841
2842 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2843 **/
2844 CHAR16*
2845 EFIAPI
2846 PathCleanUpDirectories(
2847 IN CHAR16 *Path
2848 );
2849
2850 //
2851 // Linked List Functions and Macros
2852 //
2853
2854 /**
2855 Initializes the head node of a doubly linked list that is declared as a
2856 global variable in a module.
2857
2858 Initializes the forward and backward links of a new linked list. After
2859 initializing a linked list with this macro, the other linked list functions
2860 may be used to add and remove nodes from the linked list. This macro results
2861 in smaller executables by initializing the linked list in the data section,
2862 instead if calling the InitializeListHead() function to perform the
2863 equivalent operation.
2864
2865 @param ListHead The head note of a list to initialize.
2866
2867 **/
2868 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2869
2870
2871 /**
2872 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2873 list.
2874
2875 If FirstEntry is NULL, then ASSERT().
2876 If FirstEntry->ForwardLink is NULL, then ASSERT().
2877 If FirstEntry->BackLink is NULL, then ASSERT().
2878 If SecondEntry is NULL, then ASSERT();
2879 If PcdMaximumLinkedListLength is not zero, and List contains more than
2880 PcdMaximumLinkedListLength nodes, then ASSERT().
2881
2882 @param FirstEntry A pointer to a node in a linked list.
2883 @param SecondEntry A pointer to the node to locate.
2884
2885 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.
2886 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,
2887 or FirstEntry is invalid.
2888
2889 **/
2890 BOOLEAN
2891 EFIAPI
2892 IsNodeInList (
2893 IN CONST LIST_ENTRY *FirstEntry,
2894 IN CONST LIST_ENTRY *SecondEntry
2895 );
2896
2897
2898 /**
2899 Initializes the head node of a doubly linked list, and returns the pointer to
2900 the head node of the doubly linked list.
2901
2902 Initializes the forward and backward links of a new linked list. After
2903 initializing a linked list with this function, the other linked list
2904 functions may be used to add and remove nodes from the linked list. It is up
2905 to the caller of this function to allocate the memory for ListHead.
2906
2907 If ListHead is NULL, then ASSERT().
2908
2909 @param ListHead A pointer to the head node of a new doubly linked list.
2910
2911 @return ListHead
2912
2913 **/
2914 LIST_ENTRY *
2915 EFIAPI
2916 InitializeListHead (
2917 IN OUT LIST_ENTRY *ListHead
2918 );
2919
2920
2921 /**
2922 Adds a node to the beginning of a doubly linked list, and returns the pointer
2923 to the head node of the doubly linked list.
2924
2925 Adds the node Entry at the beginning of the doubly linked list denoted by
2926 ListHead, and returns ListHead.
2927
2928 If ListHead is NULL, then ASSERT().
2929 If Entry is NULL, then ASSERT().
2930 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2931 InitializeListHead(), then ASSERT().
2932 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2933 of nodes in ListHead, including the ListHead node, is greater than or
2934 equal to PcdMaximumLinkedListLength, then ASSERT().
2935
2936 @param ListHead A pointer to the head node of a doubly linked list.
2937 @param Entry A pointer to a node that is to be inserted at the beginning
2938 of a doubly linked list.
2939
2940 @return ListHead
2941
2942 **/
2943 LIST_ENTRY *
2944 EFIAPI
2945 InsertHeadList (
2946 IN OUT LIST_ENTRY *ListHead,
2947 IN OUT LIST_ENTRY *Entry
2948 );
2949
2950
2951 /**
2952 Adds a node to the end of a doubly linked list, and returns the pointer to
2953 the head node of the doubly linked list.
2954
2955 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2956 and returns ListHead.
2957
2958 If ListHead is NULL, then ASSERT().
2959 If Entry is NULL, then ASSERT().
2960 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2961 InitializeListHead(), then ASSERT().
2962 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2963 of nodes in ListHead, including the ListHead node, is greater than or
2964 equal to PcdMaximumLinkedListLength, then ASSERT().
2965
2966 @param ListHead A pointer to the head node of a doubly linked list.
2967 @param Entry A pointer to a node that is to be added at the end of the
2968 doubly linked list.
2969
2970 @return ListHead
2971
2972 **/
2973 LIST_ENTRY *
2974 EFIAPI
2975 InsertTailList (
2976 IN OUT LIST_ENTRY *ListHead,
2977 IN OUT LIST_ENTRY *Entry
2978 );
2979
2980
2981 /**
2982 Retrieves the first node of a doubly linked list.
2983
2984 Returns the first node of a doubly linked list. List must have been
2985 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2986 If List is empty, then List is returned.
2987
2988 If List is NULL, then ASSERT().
2989 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2990 InitializeListHead(), then ASSERT().
2991 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2992 in List, including the List node, is greater than or equal to
2993 PcdMaximumLinkedListLength, then ASSERT().
2994
2995 @param List A pointer to the head node of a doubly linked list.
2996
2997 @return The first node of a doubly linked list.
2998 @retval List The list is empty.
2999
3000 **/
3001 LIST_ENTRY *
3002 EFIAPI
3003 GetFirstNode (
3004 IN CONST LIST_ENTRY *List
3005 );
3006
3007
3008 /**
3009 Retrieves the next node of a doubly linked list.
3010
3011 Returns the node of a doubly linked list that follows Node.
3012 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3013 or InitializeListHead(). If List is empty, then List is returned.
3014
3015 If List is NULL, then ASSERT().
3016 If Node is NULL, then ASSERT().
3017 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3018 InitializeListHead(), then ASSERT().
3019 If PcdMaximumLinkedListLength is not zero, and List contains more than
3020 PcdMaximumLinkedListLength nodes, then ASSERT().
3021 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3022
3023 @param List A pointer to the head node of a doubly linked list.
3024 @param Node A pointer to a node in the doubly linked list.
3025
3026 @return The pointer to the next node if one exists. Otherwise List is returned.
3027
3028 **/
3029 LIST_ENTRY *
3030 EFIAPI
3031 GetNextNode (
3032 IN CONST LIST_ENTRY *List,
3033 IN CONST LIST_ENTRY *Node
3034 );
3035
3036
3037 /**
3038 Retrieves the previous node of a doubly linked list.
3039
3040 Returns the node of a doubly linked list that precedes Node.
3041 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3042 or InitializeListHead(). If List is empty, then List is returned.
3043
3044 If List is NULL, then ASSERT().
3045 If Node is NULL, then ASSERT().
3046 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3047 InitializeListHead(), then ASSERT().
3048 If PcdMaximumLinkedListLength is not zero, and List contains more than
3049 PcdMaximumLinkedListLength nodes, then ASSERT().
3050 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3051
3052 @param List A pointer to the head node of a doubly linked list.
3053 @param Node A pointer to a node in the doubly linked list.
3054
3055 @return The pointer to the previous node if one exists. Otherwise List is returned.
3056
3057 **/
3058 LIST_ENTRY *
3059 EFIAPI
3060 GetPreviousNode (
3061 IN CONST LIST_ENTRY *List,
3062 IN CONST LIST_ENTRY *Node
3063 );
3064
3065
3066 /**
3067 Checks to see if a doubly linked list is empty or not.
3068
3069 Checks to see if the doubly linked list is empty. If the linked list contains
3070 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
3071
3072 If ListHead is NULL, then ASSERT().
3073 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3074 InitializeListHead(), then ASSERT().
3075 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3076 in List, including the List node, is greater than or equal to
3077 PcdMaximumLinkedListLength, then ASSERT().
3078
3079 @param ListHead A pointer to the head node of a doubly linked list.
3080
3081 @retval TRUE The linked list is empty.
3082 @retval FALSE The linked list is not empty.
3083
3084 **/
3085 BOOLEAN
3086 EFIAPI
3087 IsListEmpty (
3088 IN CONST LIST_ENTRY *ListHead
3089 );
3090
3091
3092 /**
3093 Determines if a node in a doubly linked list is the head node of a the same
3094 doubly linked list. This function is typically used to terminate a loop that
3095 traverses all the nodes in a doubly linked list starting with the head node.
3096
3097 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
3098 nodes in the doubly linked list specified by List. List must have been
3099 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3100
3101 If List is NULL, then ASSERT().
3102 If Node is NULL, then ASSERT().
3103 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
3104 then ASSERT().
3105 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3106 in List, including the List node, is greater than or equal to
3107 PcdMaximumLinkedListLength, then ASSERT().
3108 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
3109 to List, then ASSERT().
3110
3111 @param List A pointer to the head node of a doubly linked list.
3112 @param Node A pointer to a node in the doubly linked list.
3113
3114 @retval TRUE Node is the head of the doubly-linked list pointed by List.
3115 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
3116
3117 **/
3118 BOOLEAN
3119 EFIAPI
3120 IsNull (
3121 IN CONST LIST_ENTRY *List,
3122 IN CONST LIST_ENTRY *Node
3123 );
3124
3125
3126 /**
3127 Determines if a node the last node in a doubly linked list.
3128
3129 Returns TRUE if Node is the last node in the doubly linked list specified by
3130 List. Otherwise, FALSE is returned. List must have been initialized with
3131 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3132
3133 If List is NULL, then ASSERT().
3134 If Node is NULL, then ASSERT().
3135 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3136 InitializeListHead(), then ASSERT().
3137 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3138 in List, including the List node, is greater than or equal to
3139 PcdMaximumLinkedListLength, then ASSERT().
3140 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3141
3142 @param List A pointer to the head node of a doubly linked list.
3143 @param Node A pointer to a node in the doubly linked list.
3144
3145 @retval TRUE Node is the last node in the linked list.
3146 @retval FALSE Node is not the last node in the linked list.
3147
3148 **/
3149 BOOLEAN
3150 EFIAPI
3151 IsNodeAtEnd (
3152 IN CONST LIST_ENTRY *List,
3153 IN CONST LIST_ENTRY *Node
3154 );
3155
3156
3157 /**
3158 Swaps the location of two nodes in a doubly linked list, and returns the
3159 first node after the swap.
3160
3161 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
3162 Otherwise, the location of the FirstEntry node is swapped with the location
3163 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
3164 same double linked list as FirstEntry and that double linked list must have
3165 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3166 SecondEntry is returned after the nodes are swapped.
3167
3168 If FirstEntry is NULL, then ASSERT().
3169 If SecondEntry is NULL, then ASSERT().
3170 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
3171 same linked list, then ASSERT().
3172 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3173 linked list containing the FirstEntry and SecondEntry nodes, including
3174 the FirstEntry and SecondEntry nodes, is greater than or equal to
3175 PcdMaximumLinkedListLength, then ASSERT().
3176
3177 @param FirstEntry A pointer to a node in a linked list.
3178 @param SecondEntry A pointer to another node in the same linked list.
3179
3180 @return SecondEntry.
3181
3182 **/
3183 LIST_ENTRY *
3184 EFIAPI
3185 SwapListEntries (
3186 IN OUT LIST_ENTRY *FirstEntry,
3187 IN OUT LIST_ENTRY *SecondEntry
3188 );
3189
3190
3191 /**
3192 Removes a node from a doubly linked list, and returns the node that follows
3193 the removed node.
3194
3195 Removes the node Entry from a doubly linked list. It is up to the caller of
3196 this function to release the memory used by this node if that is required. On
3197 exit, the node following Entry in the doubly linked list is returned. If
3198 Entry is the only node in the linked list, then the head node of the linked
3199 list is returned.
3200
3201 If Entry is NULL, then ASSERT().
3202 If Entry is the head node of an empty list, then ASSERT().
3203 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3204 linked list containing Entry, including the Entry node, is greater than
3205 or equal to PcdMaximumLinkedListLength, then ASSERT().
3206
3207 @param Entry A pointer to a node in a linked list.
3208
3209 @return Entry.
3210
3211 **/
3212 LIST_ENTRY *
3213 EFIAPI
3214 RemoveEntryList (
3215 IN CONST LIST_ENTRY *Entry
3216 );
3217
3218 //
3219 // Math Services
3220 //
3221
3222 /**
3223 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
3224 with zeros. The shifted value is returned.
3225
3226 This function shifts the 64-bit value Operand to the left by Count bits. The
3227 low Count bits are set to zero. The shifted value is returned.
3228
3229 If Count is greater than 63, then ASSERT().
3230
3231 @param Operand The 64-bit operand to shift left.
3232 @param Count The number of bits to shift left.
3233
3234 @return Operand << Count.
3235
3236 **/
3237 UINT64
3238 EFIAPI
3239 LShiftU64 (
3240 IN UINT64 Operand,
3241 IN UINTN Count
3242 );
3243
3244
3245 /**
3246 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
3247 filled with zeros. The shifted value is returned.
3248
3249 This function shifts the 64-bit value Operand to the right by Count bits. The
3250 high Count bits are set to zero. The shifted value is returned.
3251
3252 If Count is greater than 63, then ASSERT().
3253
3254 @param Operand The 64-bit operand to shift right.
3255 @param Count The number of bits to shift right.
3256
3257 @return Operand >> Count
3258
3259 **/
3260 UINT64
3261 EFIAPI
3262 RShiftU64 (
3263 IN UINT64 Operand,
3264 IN UINTN Count
3265 );
3266
3267
3268 /**
3269 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
3270 with original integer's bit 63. The shifted value is returned.
3271
3272 This function shifts the 64-bit value Operand to the right by Count bits. The
3273 high Count bits are set to bit 63 of Operand. The shifted value is returned.
3274
3275 If Count is greater than 63, then ASSERT().
3276
3277 @param Operand The 64-bit operand to shift right.
3278 @param Count The number of bits to shift right.
3279
3280 @return Operand >> Count
3281
3282 **/
3283 UINT64
3284 EFIAPI
3285 ARShiftU64 (
3286 IN UINT64 Operand,
3287 IN UINTN Count
3288 );
3289
3290
3291 /**
3292 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
3293 with the high bits that were rotated.
3294
3295 This function rotates the 32-bit value Operand to the left by Count bits. The
3296 low Count bits are fill with the high Count bits of Operand. The rotated
3297 value is returned.
3298
3299 If Count is greater than 31, then ASSERT().
3300
3301 @param Operand The 32-bit operand to rotate left.
3302 @param Count The number of bits to rotate left.
3303
3304 @return Operand << Count
3305
3306 **/
3307 UINT32
3308 EFIAPI
3309 LRotU32 (
3310 IN UINT32 Operand,
3311 IN UINTN Count
3312 );
3313
3314
3315 /**
3316 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
3317 with the low bits that were rotated.
3318
3319 This function rotates the 32-bit value Operand to the right by Count bits.
3320 The high Count bits are fill with the low Count bits of Operand. The rotated
3321 value is returned.
3322
3323 If Count is greater than 31, then ASSERT().
3324
3325 @param Operand The 32-bit operand to rotate right.
3326 @param Count The number of bits to rotate right.
3327
3328 @return Operand >> Count
3329
3330 **/
3331 UINT32
3332 EFIAPI
3333 RRotU32 (
3334 IN UINT32 Operand,
3335 IN UINTN Count
3336 );
3337
3338
3339 /**
3340 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3341 with the high bits that were rotated.
3342
3343 This function rotates the 64-bit value Operand to the left by Count bits. The
3344 low Count bits are fill with the high Count bits of Operand. The rotated
3345 value is returned.
3346
3347 If Count is greater than 63, then ASSERT().
3348
3349 @param Operand The 64-bit operand to rotate left.
3350 @param Count The number of bits to rotate left.
3351
3352 @return Operand << Count
3353
3354 **/
3355 UINT64
3356 EFIAPI
3357 LRotU64 (
3358 IN UINT64 Operand,
3359 IN UINTN Count
3360 );
3361
3362
3363 /**
3364 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3365 with the high low bits that were rotated.
3366
3367 This function rotates the 64-bit value Operand to the right by Count bits.
3368 The high Count bits are fill with the low Count bits of Operand. The rotated
3369 value is returned.
3370
3371 If Count is greater than 63, then ASSERT().
3372
3373 @param Operand The 64-bit operand to rotate right.
3374 @param Count The number of bits to rotate right.
3375
3376 @return Operand >> Count
3377
3378 **/
3379 UINT64
3380 EFIAPI
3381 RRotU64 (
3382 IN UINT64 Operand,
3383 IN UINTN Count
3384 );
3385
3386
3387 /**
3388 Returns the bit position of the lowest bit set in a 32-bit value.
3389
3390 This function computes the bit position of the lowest bit set in the 32-bit
3391 value specified by Operand. If Operand is zero, then -1 is returned.
3392 Otherwise, a value between 0 and 31 is returned.
3393
3394 @param Operand The 32-bit operand to evaluate.
3395
3396 @retval 0..31 The lowest bit set in Operand was found.
3397 @retval -1 Operand is zero.
3398
3399 **/
3400 INTN
3401 EFIAPI
3402 LowBitSet32 (
3403 IN UINT32 Operand
3404 );
3405
3406
3407 /**
3408 Returns the bit position of the lowest bit set in a 64-bit value.
3409
3410 This function computes the bit position of the lowest bit set in the 64-bit
3411 value specified by Operand. If Operand is zero, then -1 is returned.
3412 Otherwise, a value between 0 and 63 is returned.
3413
3414 @param Operand The 64-bit operand to evaluate.
3415
3416 @retval 0..63 The lowest bit set in Operand was found.
3417 @retval -1 Operand is zero.
3418
3419
3420 **/
3421 INTN
3422 EFIAPI
3423 LowBitSet64 (
3424 IN UINT64 Operand
3425 );
3426
3427
3428 /**
3429 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3430 to log2(x).
3431
3432 This function computes the bit position of the highest bit set in the 32-bit
3433 value specified by Operand. If Operand is zero, then -1 is returned.
3434 Otherwise, a value between 0 and 31 is returned.
3435
3436 @param Operand The 32-bit operand to evaluate.
3437
3438 @retval 0..31 Position of the highest bit set in Operand if found.
3439 @retval -1 Operand is zero.
3440
3441 **/
3442 INTN
3443 EFIAPI
3444 HighBitSet32 (
3445 IN UINT32 Operand
3446 );
3447
3448
3449 /**
3450 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3451 to log2(x).
3452
3453 This function computes the bit position of the highest bit set in the 64-bit
3454 value specified by Operand. If Operand is zero, then -1 is returned.
3455 Otherwise, a value between 0 and 63 is returned.
3456
3457 @param Operand The 64-bit operand to evaluate.
3458
3459 @retval 0..63 Position of the highest bit set in Operand if found.
3460 @retval -1 Operand is zero.
3461
3462 **/
3463 INTN
3464 EFIAPI
3465 HighBitSet64 (
3466 IN UINT64 Operand
3467 );
3468
3469
3470 /**
3471 Returns the value of the highest bit set in a 32-bit value. Equivalent to
3472 1 << log2(x).
3473
3474 This function computes the value of the highest bit set in the 32-bit value
3475 specified by Operand. If Operand is zero, then zero is returned.
3476
3477 @param Operand The 32-bit operand to evaluate.
3478
3479 @return 1 << HighBitSet32(Operand)
3480 @retval 0 Operand is zero.
3481
3482 **/
3483 UINT32
3484 EFIAPI
3485 GetPowerOfTwo32 (
3486 IN UINT32 Operand
3487 );
3488
3489
3490 /**
3491 Returns the value of the highest bit set in a 64-bit value. Equivalent to
3492 1 << log2(x).
3493
3494 This function computes the value of the highest bit set in the 64-bit value
3495 specified by Operand. If Operand is zero, then zero is returned.
3496
3497 @param Operand The 64-bit operand to evaluate.
3498
3499 @return 1 << HighBitSet64(Operand)
3500 @retval 0 Operand is zero.
3501
3502 **/
3503 UINT64
3504 EFIAPI
3505 GetPowerOfTwo64 (
3506 IN UINT64 Operand
3507 );
3508
3509
3510 /**
3511 Switches the endianness of a 16-bit integer.
3512
3513 This function swaps the bytes in a 16-bit unsigned value to switch the value
3514 from little endian to big endian or vice versa. The byte swapped value is
3515 returned.
3516
3517 @param Value A 16-bit unsigned value.
3518
3519 @return The byte swapped Value.
3520
3521 **/
3522 UINT16
3523 EFIAPI
3524 SwapBytes16 (
3525 IN UINT16 Value
3526 );
3527
3528
3529 /**
3530 Switches the endianness of a 32-bit integer.
3531
3532 This function swaps the bytes in a 32-bit unsigned value to switch the value
3533 from little endian to big endian or vice versa. The byte swapped value is
3534 returned.
3535
3536 @param Value A 32-bit unsigned value.
3537
3538 @return The byte swapped Value.
3539
3540 **/
3541 UINT32
3542 EFIAPI
3543 SwapBytes32 (
3544 IN UINT32 Value
3545 );
3546
3547
3548 /**
3549 Switches the endianness of a 64-bit integer.
3550
3551 This function swaps the bytes in a 64-bit unsigned value to switch the value
3552 from little endian to big endian or vice versa. The byte swapped value is
3553 returned.
3554
3555 @param Value A 64-bit unsigned value.
3556
3557 @return The byte swapped Value.
3558
3559 **/
3560 UINT64
3561 EFIAPI
3562 SwapBytes64 (
3563 IN UINT64 Value
3564 );
3565
3566
3567 /**
3568 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3569 generates a 64-bit unsigned result.
3570
3571 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3572 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3573 bit unsigned result is returned.
3574
3575 @param Multiplicand A 64-bit unsigned value.
3576 @param Multiplier A 32-bit unsigned value.
3577
3578 @return Multiplicand * Multiplier
3579
3580 **/
3581 UINT64
3582 EFIAPI
3583 MultU64x32 (
3584 IN UINT64 Multiplicand,
3585 IN UINT32 Multiplier
3586 );
3587
3588
3589 /**
3590 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3591 generates a 64-bit unsigned result.
3592
3593 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3594 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3595 bit unsigned result is returned.
3596
3597 @param Multiplicand A 64-bit unsigned value.
3598 @param Multiplier A 64-bit unsigned value.
3599
3600 @return Multiplicand * Multiplier.
3601
3602 **/
3603 UINT64
3604 EFIAPI
3605 MultU64x64 (
3606 IN UINT64 Multiplicand,
3607 IN UINT64 Multiplier
3608 );
3609
3610
3611 /**
3612 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3613 64-bit signed result.
3614
3615 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3616 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3617 signed result is returned.
3618
3619 @param Multiplicand A 64-bit signed value.
3620 @param Multiplier A 64-bit signed value.
3621
3622 @return Multiplicand * Multiplier
3623
3624 **/
3625 INT64
3626 EFIAPI
3627 MultS64x64 (
3628 IN INT64 Multiplicand,