MdePkg/BaseLib: Add safe string functions [U|A]StrnTo[A|U]StrS
[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 - 2017, 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
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
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 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1540
1541 /**
1542 [ATTENTION] This function is deprecated for security reason.
1543
1544 Convert a Null-terminated Unicode string to a Null-terminated
1545 ASCII string and returns the ASCII string.
1546
1547 This function converts the content of the Unicode string Source
1548 to the ASCII string Destination by copying the lower 8 bits of
1549 each Unicode character. It returns Destination.
1550
1551 The caller is responsible to make sure Destination points to a buffer with size
1552 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1553
1554 If any Unicode characters in Source contain non-zero value in
1555 the upper 8 bits, then ASSERT().
1556
1557 If Destination is NULL, then ASSERT().
1558 If Source is NULL, then ASSERT().
1559 If Source is not aligned on a 16-bit boundary, then ASSERT().
1560 If Source and Destination overlap, then ASSERT().
1561
1562 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1563 more than PcdMaximumUnicodeStringLength Unicode characters not including
1564 the Null-terminator, then ASSERT().
1565
1566 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1567 than PcdMaximumAsciiStringLength Unicode characters not including the
1568 Null-terminator, then ASSERT().
1569
1570 @param Source The pointer to a Null-terminated Unicode string.
1571 @param Destination The pointer to a Null-terminated ASCII string.
1572
1573 @return Destination.
1574
1575 **/
1576 CHAR8 *
1577 EFIAPI
1578 UnicodeStrToAsciiStr (
1579 IN CONST CHAR16 *Source,
1580 OUT CHAR8 *Destination
1581 );
1582
1583 #endif
1584
1585 /**
1586 Convert a Null-terminated Unicode string to a Null-terminated
1587 ASCII string.
1588
1589 This function is similar to AsciiStrCpyS.
1590
1591 This function converts the content of the Unicode string Source
1592 to the ASCII string Destination by copying the lower 8 bits of
1593 each Unicode character. The function terminates the ASCII string
1594 Destination by appending a Null-terminator character at the end.
1595
1596 The caller is responsible to make sure Destination points to a buffer with size
1597 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1598
1599 If any Unicode characters in Source contain non-zero value in
1600 the upper 8 bits, then ASSERT().
1601
1602 If Source is not aligned on a 16-bit boundary, then ASSERT().
1603 If an error would be returned, then the function will also ASSERT().
1604
1605 If an error is returned, then the Destination is unmodified.
1606
1607 @param Source The pointer to a Null-terminated Unicode string.
1608 @param Destination The pointer to a Null-terminated ASCII string.
1609 @param DestMax The maximum number of Destination Ascii
1610 char, including terminating null char.
1611
1612 @retval RETURN_SUCCESS String is converted.
1613 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1614 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1615 If Source is NULL.
1616 If PcdMaximumAsciiStringLength is not zero,
1617 and DestMax is greater than
1618 PcdMaximumAsciiStringLength.
1619 If PcdMaximumUnicodeStringLength is not zero,
1620 and DestMax is greater than
1621 PcdMaximumUnicodeStringLength.
1622 If DestMax is 0.
1623 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1624
1625 **/
1626 RETURN_STATUS
1627 EFIAPI
1628 UnicodeStrToAsciiStrS (
1629 IN CONST CHAR16 *Source,
1630 OUT CHAR8 *Destination,
1631 IN UINTN DestMax
1632 );
1633
1634 /**
1635 Convert not more than Length successive characters from a Null-terminated
1636 Unicode string to a Null-terminated Ascii string. If no null char is copied
1637 from Source, then Destination[Length] is always set to null.
1638
1639 This function converts not more than Length successive characters from the
1640 Unicode string Source to the Ascii string Destination by copying the lower 8
1641 bits of each Unicode character. The function terminates the Ascii string
1642 Destination by appending a Null-terminator character at the end.
1643
1644 The caller is responsible to make sure Destination points to a buffer with size
1645 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1646
1647 If any Unicode characters in Source contain non-zero value in the upper 8
1648 bits, then ASSERT().
1649 If Source is not aligned on a 16-bit boundary, then ASSERT().
1650 If an error would be returned, then the function will also ASSERT().
1651
1652 If an error is returned, then the Destination is unmodified.
1653
1654 @param Source The pointer to a Null-terminated Unicode string.
1655 @param Length The maximum number of Unicode characters to
1656 convert.
1657 @param Destination The pointer to a Null-terminated Ascii string.
1658 @param DestMax The maximum number of Destination Ascii
1659 char, including terminating null char.
1660 @param DestinationLength The number of Unicode characters converted.
1661
1662 @retval RETURN_SUCCESS String is converted.
1663 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1664 If Source is NULL.
1665 If DestinationLength is NULL.
1666 If PcdMaximumAsciiStringLength is not zero,
1667 and Length or DestMax is greater than
1668 PcdMaximumAsciiStringLength.
1669 If PcdMaximumUnicodeStringLength is not
1670 zero, and Length or DestMax is greater than
1671 PcdMaximumUnicodeStringLength.
1672 If DestMax is 0.
1673 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1674 MIN(StrLen(Source), Length).
1675 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1676
1677 **/
1678 RETURN_STATUS
1679 EFIAPI
1680 UnicodeStrnToAsciiStrS (
1681 IN CONST CHAR16 *Source,
1682 IN UINTN Length,
1683 OUT CHAR8 *Destination,
1684 IN UINTN DestMax,
1685 OUT UINTN *DestinationLength
1686 );
1687
1688 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1689
1690 /**
1691 [ATTENTION] This function is deprecated for security reason.
1692
1693 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1694 string and returns the new ASCII string.
1695
1696 This function copies the contents of the ASCII string Source to the ASCII
1697 string Destination, and returns Destination. If Source and Destination
1698 overlap, then the results are undefined.
1699
1700 If Destination is NULL, then ASSERT().
1701 If Source is NULL, then ASSERT().
1702 If Source and Destination overlap, then ASSERT().
1703 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1704 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1705 then ASSERT().
1706
1707 @param Destination The pointer to a Null-terminated ASCII string.
1708 @param Source The pointer to a Null-terminated ASCII string.
1709
1710 @return Destination
1711
1712 **/
1713 CHAR8 *
1714 EFIAPI
1715 AsciiStrCpy (
1716 OUT CHAR8 *Destination,
1717 IN CONST CHAR8 *Source
1718 );
1719
1720
1721 /**
1722 [ATTENTION] This function is deprecated for security reason.
1723
1724 Copies up to a specified length one Null-terminated ASCII string to another
1725 Null-terminated ASCII string and returns the new ASCII string.
1726
1727 This function copies the contents of the ASCII string Source to the ASCII
1728 string Destination, and returns Destination. At most, Length ASCII characters
1729 are copied from Source to Destination. If Length is 0, then Destination is
1730 returned unmodified. If Length is greater that the number of ASCII characters
1731 in Source, then Destination is padded with Null ASCII characters. If Source
1732 and Destination overlap, then the results are undefined.
1733
1734 If Destination is NULL, then ASSERT().
1735 If Source is NULL, then ASSERT().
1736 If Source and Destination overlap, then ASSERT().
1737 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1738 PcdMaximumAsciiStringLength, then ASSERT().
1739 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1740 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1741 then ASSERT().
1742
1743 @param Destination The pointer to a Null-terminated ASCII string.
1744 @param Source The pointer to a Null-terminated ASCII string.
1745 @param Length The maximum number of ASCII characters to copy.
1746
1747 @return Destination
1748
1749 **/
1750 CHAR8 *
1751 EFIAPI
1752 AsciiStrnCpy (
1753 OUT CHAR8 *Destination,
1754 IN CONST CHAR8 *Source,
1755 IN UINTN Length
1756 );
1757 #endif
1758
1759 /**
1760 Returns the length of a Null-terminated ASCII string.
1761
1762 This function returns the number of ASCII characters in the Null-terminated
1763 ASCII string specified by String.
1764
1765 If Length > 0 and Destination is NULL, then ASSERT().
1766 If Length > 0 and Source is NULL, then ASSERT().
1767 If PcdMaximumAsciiStringLength is not zero and String contains more than
1768 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1769 then ASSERT().
1770
1771 @param String The pointer to a Null-terminated ASCII string.
1772
1773 @return The length of String.
1774
1775 **/
1776 UINTN
1777 EFIAPI
1778 AsciiStrLen (
1779 IN CONST CHAR8 *String
1780 );
1781
1782
1783 /**
1784 Returns the size of a Null-terminated ASCII string in bytes, including the
1785 Null terminator.
1786
1787 This function returns the size, in bytes, of the Null-terminated ASCII string
1788 specified by String.
1789
1790 If String is NULL, then ASSERT().
1791 If PcdMaximumAsciiStringLength is not zero and String contains more than
1792 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1793 then ASSERT().
1794
1795 @param String The pointer to a Null-terminated ASCII string.
1796
1797 @return The size of String.
1798
1799 **/
1800 UINTN
1801 EFIAPI
1802 AsciiStrSize (
1803 IN CONST CHAR8 *String
1804 );
1805
1806
1807 /**
1808 Compares two Null-terminated ASCII strings, and returns the difference
1809 between the first mismatched ASCII characters.
1810
1811 This function compares the Null-terminated ASCII string FirstString to the
1812 Null-terminated ASCII string SecondString. If FirstString is identical to
1813 SecondString, then 0 is returned. Otherwise, the value returned is the first
1814 mismatched ASCII character in SecondString subtracted from the first
1815 mismatched ASCII character in FirstString.
1816
1817 If FirstString is NULL, then ASSERT().
1818 If SecondString is NULL, then ASSERT().
1819 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1820 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1821 then ASSERT().
1822 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1823 than PcdMaximumAsciiStringLength ASCII characters not including the
1824 Null-terminator, then ASSERT().
1825
1826 @param FirstString The pointer to a Null-terminated ASCII string.
1827 @param SecondString The pointer to a Null-terminated ASCII string.
1828
1829 @retval ==0 FirstString is identical to SecondString.
1830 @retval !=0 FirstString is not identical to SecondString.
1831
1832 **/
1833 INTN
1834 EFIAPI
1835 AsciiStrCmp (
1836 IN CONST CHAR8 *FirstString,
1837 IN CONST CHAR8 *SecondString
1838 );
1839
1840
1841 /**
1842 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1843 and returns the difference between the first mismatched ASCII characters.
1844
1845 This function performs a case insensitive comparison of the Null-terminated
1846 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1847 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1848 value returned is the first mismatched lower case ASCII character in
1849 SecondString subtracted from the first mismatched lower case ASCII character
1850 in FirstString.
1851
1852 If FirstString is NULL, then ASSERT().
1853 If SecondString is NULL, then ASSERT().
1854 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1855 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1856 then ASSERT().
1857 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1858 than PcdMaximumAsciiStringLength ASCII characters not including the
1859 Null-terminator, then ASSERT().
1860
1861 @param FirstString The pointer to a Null-terminated ASCII string.
1862 @param SecondString The pointer to a Null-terminated ASCII string.
1863
1864 @retval ==0 FirstString is identical to SecondString using case insensitive
1865 comparisons.
1866 @retval !=0 FirstString is not identical to SecondString using case
1867 insensitive comparisons.
1868
1869 **/
1870 INTN
1871 EFIAPI
1872 AsciiStriCmp (
1873 IN CONST CHAR8 *FirstString,
1874 IN CONST CHAR8 *SecondString
1875 );
1876
1877
1878 /**
1879 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1880 the difference between the first mismatched ASCII characters.
1881
1882 This function compares the Null-terminated ASCII string FirstString to the
1883 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1884 will be compared. If Length is 0, then 0 is returned. If FirstString is
1885 identical to SecondString, then 0 is returned. Otherwise, the value returned
1886 is the first mismatched ASCII character in SecondString subtracted from the
1887 first mismatched ASCII character in FirstString.
1888
1889 If Length > 0 and FirstString is NULL, then ASSERT().
1890 If Length > 0 and SecondString is NULL, then ASSERT().
1891 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1892 PcdMaximumAsciiStringLength, then ASSERT().
1893 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
1894 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1895 then ASSERT().
1896 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
1897 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1898 then ASSERT().
1899
1900 @param FirstString The pointer to a Null-terminated ASCII string.
1901 @param SecondString The pointer to a Null-terminated ASCII string.
1902 @param Length The maximum number of ASCII characters for compare.
1903
1904 @retval ==0 FirstString is identical to SecondString.
1905 @retval !=0 FirstString is not identical to SecondString.
1906
1907 **/
1908 INTN
1909 EFIAPI
1910 AsciiStrnCmp (
1911 IN CONST CHAR8 *FirstString,
1912 IN CONST CHAR8 *SecondString,
1913 IN UINTN Length
1914 );
1915
1916
1917 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1918
1919 /**
1920 [ATTENTION] This function is deprecated for security reason.
1921
1922 Concatenates one Null-terminated ASCII string to another Null-terminated
1923 ASCII string, and returns the concatenated ASCII string.
1924
1925 This function concatenates two Null-terminated ASCII strings. The contents of
1926 Null-terminated ASCII string Source are concatenated to the end of Null-
1927 terminated ASCII string Destination. The Null-terminated concatenated ASCII
1928 String is returned.
1929
1930 If Destination is NULL, then ASSERT().
1931 If Source is NULL, then ASSERT().
1932 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
1933 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1934 then ASSERT().
1935 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1936 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1937 then ASSERT().
1938 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
1939 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1940 ASCII characters, then ASSERT().
1941
1942 @param Destination The pointer to a Null-terminated ASCII string.
1943 @param Source The pointer to a Null-terminated ASCII string.
1944
1945 @return Destination
1946
1947 **/
1948 CHAR8 *
1949 EFIAPI
1950 AsciiStrCat (
1951 IN OUT CHAR8 *Destination,
1952 IN CONST CHAR8 *Source
1953 );
1954
1955
1956 /**
1957 [ATTENTION] This function is deprecated for security reason.
1958
1959 Concatenates up to a specified length one Null-terminated ASCII string to
1960 the end of another Null-terminated ASCII string, and returns the
1961 concatenated ASCII string.
1962
1963 This function concatenates two Null-terminated ASCII strings. The contents
1964 of Null-terminated ASCII string Source are concatenated to the end of Null-
1965 terminated ASCII string Destination, and Destination is returned. At most,
1966 Length ASCII characters are concatenated from Source to the end of
1967 Destination, and Destination is always Null-terminated. If Length is 0, then
1968 Destination is returned unmodified. If Source and Destination overlap, then
1969 the results are undefined.
1970
1971 If Length > 0 and Destination is NULL, then ASSERT().
1972 If Length > 0 and Source is NULL, then ASSERT().
1973 If Source and Destination overlap, then ASSERT().
1974 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1975 PcdMaximumAsciiStringLength, then ASSERT().
1976 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
1977 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1978 then ASSERT().
1979 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1980 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1981 then ASSERT().
1982 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
1983 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1984 ASCII characters, not including the Null-terminator, then ASSERT().
1985
1986 @param Destination The pointer to a Null-terminated ASCII string.
1987 @param Source The pointer to a Null-terminated ASCII string.
1988 @param Length The maximum number of ASCII characters to concatenate from
1989 Source.
1990
1991 @return Destination
1992
1993 **/
1994 CHAR8 *
1995 EFIAPI
1996 AsciiStrnCat (
1997 IN OUT CHAR8 *Destination,
1998 IN CONST CHAR8 *Source,
1999 IN UINTN Length
2000 );
2001 #endif
2002
2003 /**
2004 Returns the first occurrence of a Null-terminated ASCII sub-string
2005 in a Null-terminated ASCII string.
2006
2007 This function scans the contents of the ASCII string specified by String
2008 and returns the first occurrence of SearchString. If SearchString is not
2009 found in String, then NULL is returned. If the length of SearchString is zero,
2010 then String is returned.
2011
2012 If String is NULL, then ASSERT().
2013 If SearchString is NULL, then ASSERT().
2014
2015 If PcdMaximumAsciiStringLength is not zero, and SearchString or
2016 String contains more than PcdMaximumAsciiStringLength Unicode characters
2017 not including the Null-terminator, then ASSERT().
2018
2019 @param String The pointer to a Null-terminated ASCII string.
2020 @param SearchString The pointer to a Null-terminated ASCII string to search for.
2021
2022 @retval NULL If the SearchString does not appear in String.
2023 @retval others If there is a match return the first occurrence of SearchingString.
2024 If the length of SearchString is zero,return String.
2025
2026 **/
2027 CHAR8 *
2028 EFIAPI
2029 AsciiStrStr (
2030 IN CONST CHAR8 *String,
2031 IN CONST CHAR8 *SearchString
2032 );
2033
2034
2035 /**
2036 Convert a Null-terminated ASCII decimal string to a value of type
2037 UINTN.
2038
2039 This function returns a value of type UINTN by interpreting the contents
2040 of the ASCII string String as a decimal number. The format of the input
2041 ASCII string String is:
2042
2043 [spaces] [decimal digits].
2044
2045 The valid decimal digit character is in the range [0-9]. The function will
2046 ignore the pad space, which includes spaces or tab characters, before the digits.
2047 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2048 function stops at the first character that is a not a valid decimal character or
2049 Null-terminator, whichever on comes first.
2050
2051 If String has only pad spaces, then 0 is returned.
2052 If String has no pad spaces or valid decimal digits, then 0 is returned.
2053 If the number represented by String overflows according to the range defined by
2054 UINTN, then MAX_UINTN is returned.
2055 If String is NULL, then ASSERT().
2056 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2057 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2058 then ASSERT().
2059
2060 @param String The pointer to a Null-terminated ASCII string.
2061
2062 @retval The value translated from String.
2063
2064 **/
2065 UINTN
2066 EFIAPI
2067 AsciiStrDecimalToUintn (
2068 IN CONST CHAR8 *String
2069 );
2070
2071
2072 /**
2073 Convert a Null-terminated ASCII decimal string to a value of type
2074 UINT64.
2075
2076 This function returns a value of type UINT64 by interpreting the contents
2077 of the ASCII string String as a decimal number. The format of the input
2078 ASCII string String is:
2079
2080 [spaces] [decimal digits].
2081
2082 The valid decimal digit character is in the range [0-9]. The function will
2083 ignore the pad space, which includes spaces or tab characters, before the digits.
2084 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2085 function stops at the first character that is a not a valid decimal character or
2086 Null-terminator, whichever on comes first.
2087
2088 If String has only pad spaces, then 0 is returned.
2089 If String has no pad spaces or valid decimal digits, then 0 is returned.
2090 If the number represented by String overflows according to the range defined by
2091 UINT64, then MAX_UINT64 is returned.
2092 If String is NULL, then ASSERT().
2093 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2094 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2095 then ASSERT().
2096
2097 @param String The pointer to a Null-terminated ASCII string.
2098
2099 @retval Value translated from String.
2100
2101 **/
2102 UINT64
2103 EFIAPI
2104 AsciiStrDecimalToUint64 (
2105 IN CONST CHAR8 *String
2106 );
2107
2108
2109 /**
2110 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
2111
2112 This function returns a value of type UINTN by interpreting the contents of
2113 the ASCII string String as a hexadecimal number. The format of the input ASCII
2114 string String is:
2115
2116 [spaces][zeros][x][hexadecimal digits].
2117
2118 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2119 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2120 appears in the input string, it must be prefixed with at least one 0. The function
2121 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2122 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2123 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2124 digit. Then, the function stops at the first character that is a not a valid
2125 hexadecimal character or Null-terminator, whichever on comes first.
2126
2127 If String has only pad spaces, then 0 is returned.
2128 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2129 0 is returned.
2130
2131 If the number represented by String overflows according to the range defined by UINTN,
2132 then MAX_UINTN is returned.
2133 If String is NULL, then ASSERT().
2134 If PcdMaximumAsciiStringLength is not zero,
2135 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2136 the Null-terminator, then ASSERT().
2137
2138 @param String The pointer to a Null-terminated ASCII string.
2139
2140 @retval Value translated from String.
2141
2142 **/
2143 UINTN
2144 EFIAPI
2145 AsciiStrHexToUintn (
2146 IN CONST CHAR8 *String
2147 );
2148
2149
2150 /**
2151 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
2152
2153 This function returns a value of type UINT64 by interpreting the contents of
2154 the ASCII string String as a hexadecimal number. The format of the input ASCII
2155 string String is:
2156
2157 [spaces][zeros][x][hexadecimal digits].
2158
2159 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2160 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2161 appears in the input string, it must be prefixed with at least one 0. The function
2162 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2163 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2164 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2165 digit. Then, the function stops at the first character that is a not a valid
2166 hexadecimal character or Null-terminator, whichever on comes first.
2167
2168 If String has only pad spaces, then 0 is returned.
2169 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2170 0 is returned.
2171
2172 If the number represented by String overflows according to the range defined by UINT64,
2173 then MAX_UINT64 is returned.
2174 If String is NULL, then ASSERT().
2175 If PcdMaximumAsciiStringLength is not zero,
2176 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2177 the Null-terminator, then ASSERT().
2178
2179 @param String The pointer to a Null-terminated ASCII string.
2180
2181 @retval Value translated from String.
2182
2183 **/
2184 UINT64
2185 EFIAPI
2186 AsciiStrHexToUint64 (
2187 IN CONST CHAR8 *String
2188 );
2189
2190 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2191
2192 /**
2193 [ATTENTION] This function is deprecated for security reason.
2194
2195 Convert one Null-terminated ASCII string to a Null-terminated
2196 Unicode string and returns the Unicode string.
2197
2198 This function converts the contents of the ASCII string Source to the Unicode
2199 string Destination, and returns Destination. The function terminates the
2200 Unicode string Destination by appending a Null-terminator character at the end.
2201 The caller is responsible to make sure Destination points to a buffer with size
2202 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2203
2204 If Destination is NULL, then ASSERT().
2205 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2206 If Source is NULL, then ASSERT().
2207 If Source and Destination overlap, then ASSERT().
2208 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2209 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2210 then ASSERT().
2211 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
2212 PcdMaximumUnicodeStringLength ASCII characters not including the
2213 Null-terminator, then ASSERT().
2214
2215 @param Source The pointer to a Null-terminated ASCII string.
2216 @param Destination The pointer to a Null-terminated Unicode string.
2217
2218 @return Destination.
2219
2220 **/
2221 CHAR16 *
2222 EFIAPI
2223 AsciiStrToUnicodeStr (
2224 IN CONST CHAR8 *Source,
2225 OUT CHAR16 *Destination
2226 );
2227
2228 #endif
2229
2230 /**
2231 Convert one Null-terminated ASCII string to a Null-terminated
2232 Unicode string.
2233
2234 This function is similar to StrCpyS.
2235
2236 This function converts the contents of the ASCII string Source to the Unicode
2237 string Destination. The function terminates the Unicode string Destination by
2238 appending a Null-terminator character at the end.
2239
2240 The caller is responsible to make sure Destination points to a buffer with size
2241 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2242
2243 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2244 If an error would be returned, then the function will also ASSERT().
2245
2246 If an error is returned, then the Destination is unmodified.
2247
2248 @param Source The pointer to a Null-terminated ASCII string.
2249 @param Destination The pointer to a Null-terminated Unicode string.
2250 @param DestMax The maximum number of Destination Unicode
2251 char, including terminating null char.
2252
2253 @retval RETURN_SUCCESS String is converted.
2254 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2255 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2256 If Source is NULL.
2257 If PcdMaximumUnicodeStringLength is not zero,
2258 and DestMax is greater than
2259 PcdMaximumUnicodeStringLength.
2260 If PcdMaximumAsciiStringLength is not zero,
2261 and DestMax is greater than
2262 PcdMaximumAsciiStringLength.
2263 If DestMax is 0.
2264 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2265
2266 **/
2267 RETURN_STATUS
2268 EFIAPI
2269 AsciiStrToUnicodeStrS (
2270 IN CONST CHAR8 *Source,
2271 OUT CHAR16 *Destination,
2272 IN UINTN DestMax
2273 );
2274
2275 /**
2276 Convert not more than Length successive characters from a Null-terminated
2277 Ascii string to a Null-terminated Unicode string. If no null char is copied
2278 from Source, then Destination[Length] is always set to null.
2279
2280 This function converts not more than Length successive characters from the
2281 Ascii string Source to the Unicode string Destination. The function
2282 terminates the Unicode string Destination by appending a Null-terminator
2283 character at the end.
2284
2285 The caller is responsible to make sure Destination points to a buffer with
2286 size not smaller than
2287 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2288
2289 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2290 If an error would be returned, then the function will also ASSERT().
2291
2292 If an error is returned, then Destination and DestinationLength are
2293 unmodified.
2294
2295 @param Source The pointer to a Null-terminated Ascii string.
2296 @param Length The maximum number of Ascii characters to convert.
2297 @param Destination The pointer to a Null-terminated Unicode string.
2298 @param DestMax The maximum number of Destination Unicode char,
2299 including terminating null char.
2300 @param DestinationLength The number of Ascii characters converted.
2301
2302 @retval RETURN_SUCCESS String is converted.
2303 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2304 If Source is NULL.
2305 If DestinationLength is NULL.
2306 If PcdMaximumUnicodeStringLength is not
2307 zero, and Length or DestMax is greater than
2308 PcdMaximumUnicodeStringLength.
2309 If PcdMaximumAsciiStringLength is not zero,
2310 and Length or DestMax is greater than
2311 PcdMaximumAsciiStringLength.
2312 If DestMax is 0.
2313 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2314 MIN(AsciiStrLen(Source), Length).
2315 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2316
2317 **/
2318 RETURN_STATUS
2319 EFIAPI
2320 AsciiStrnToUnicodeStrS (
2321 IN CONST CHAR8 *Source,
2322 IN UINTN Length,
2323 OUT CHAR16 *Destination,
2324 IN UINTN DestMax,
2325 OUT UINTN *DestinationLength
2326 );
2327
2328 /**
2329 Converts an 8-bit value to an 8-bit BCD value.
2330
2331 Converts the 8-bit value specified by Value to BCD. The BCD value is
2332 returned.
2333
2334 If Value >= 100, then ASSERT().
2335
2336 @param Value The 8-bit value to convert to BCD. Range 0..99.
2337
2338 @return The BCD value.
2339
2340 **/
2341 UINT8
2342 EFIAPI
2343 DecimalToBcd8 (
2344 IN UINT8 Value
2345 );
2346
2347
2348 /**
2349 Converts an 8-bit BCD value to an 8-bit value.
2350
2351 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2352 value is returned.
2353
2354 If Value >= 0xA0, then ASSERT().
2355 If (Value & 0x0F) >= 0x0A, then ASSERT().
2356
2357 @param Value The 8-bit BCD value to convert to an 8-bit value.
2358
2359 @return The 8-bit value is returned.
2360
2361 **/
2362 UINT8
2363 EFIAPI
2364 BcdToDecimal8 (
2365 IN UINT8 Value
2366 );
2367
2368 //
2369 // File Path Manipulation Functions
2370 //
2371
2372 /**
2373 Removes the last directory or file entry in a path.
2374
2375 @param[in, out] Path The pointer to the path to modify.
2376
2377 @retval FALSE Nothing was found to remove.
2378 @retval TRUE A directory or file was removed.
2379 **/
2380 BOOLEAN
2381 EFIAPI
2382 PathRemoveLastItem(
2383 IN OUT CHAR16 *Path
2384 );
2385
2386 /**
2387 Function to clean up paths.
2388 - Single periods in the path are removed.
2389 - Double periods in the path are removed along with a single parent directory.
2390 - Forward slashes L'/' are converted to backward slashes L'\'.
2391
2392 This will be done inline and the existing buffer may be larger than required
2393 upon completion.
2394
2395 @param[in] Path The pointer to the string containing the path.
2396
2397 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2398 **/
2399 CHAR16*
2400 EFIAPI
2401 PathCleanUpDirectories(
2402 IN CHAR16 *Path
2403 );
2404
2405 //
2406 // Linked List Functions and Macros
2407 //
2408
2409 /**
2410 Initializes the head node of a doubly linked list that is declared as a
2411 global variable in a module.
2412
2413 Initializes the forward and backward links of a new linked list. After
2414 initializing a linked list with this macro, the other linked list functions
2415 may be used to add and remove nodes from the linked list. This macro results
2416 in smaller executables by initializing the linked list in the data section,
2417 instead if calling the InitializeListHead() function to perform the
2418 equivalent operation.
2419
2420 @param ListHead The head note of a list to initialize.
2421
2422 **/
2423 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2424
2425
2426 /**
2427 Initializes the head node of a doubly linked list, and returns the pointer to
2428 the head node of the doubly linked list.
2429
2430 Initializes the forward and backward links of a new linked list. After
2431 initializing a linked list with this function, the other linked list
2432 functions may be used to add and remove nodes from the linked list. It is up
2433 to the caller of this function to allocate the memory for ListHead.
2434
2435 If ListHead is NULL, then ASSERT().
2436
2437 @param ListHead A pointer to the head node of a new doubly linked list.
2438
2439 @return ListHead
2440
2441 **/
2442 LIST_ENTRY *
2443 EFIAPI
2444 InitializeListHead (
2445 IN OUT LIST_ENTRY *ListHead
2446 );
2447
2448
2449 /**
2450 Adds a node to the beginning of a doubly linked list, and returns the pointer
2451 to the head node of the doubly linked list.
2452
2453 Adds the node Entry at the beginning of the doubly linked list denoted by
2454 ListHead, and returns ListHead.
2455
2456 If ListHead is NULL, then ASSERT().
2457 If Entry is NULL, then ASSERT().
2458 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2459 InitializeListHead(), then ASSERT().
2460 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2461 of nodes in ListHead, including the ListHead node, is greater than or
2462 equal to PcdMaximumLinkedListLength, then ASSERT().
2463
2464 @param ListHead A pointer to the head node of a doubly linked list.
2465 @param Entry A pointer to a node that is to be inserted at the beginning
2466 of a doubly linked list.
2467
2468 @return ListHead
2469
2470 **/
2471 LIST_ENTRY *
2472 EFIAPI
2473 InsertHeadList (
2474 IN OUT LIST_ENTRY *ListHead,
2475 IN OUT LIST_ENTRY *Entry
2476 );
2477
2478
2479 /**
2480 Adds a node to the end of a doubly linked list, and returns the pointer to
2481 the head node of the doubly linked list.
2482
2483 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2484 and returns ListHead.
2485
2486 If ListHead is NULL, then ASSERT().
2487 If Entry is NULL, then ASSERT().
2488 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2489 InitializeListHead(), then ASSERT().
2490 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2491 of nodes in ListHead, including the ListHead node, is greater than or
2492 equal to PcdMaximumLinkedListLength, then ASSERT().
2493
2494 @param ListHead A pointer to the head node of a doubly linked list.
2495 @param Entry A pointer to a node that is to be added at the end of the
2496 doubly linked list.
2497
2498 @return ListHead
2499
2500 **/
2501 LIST_ENTRY *
2502 EFIAPI
2503 InsertTailList (
2504 IN OUT LIST_ENTRY *ListHead,
2505 IN OUT LIST_ENTRY *Entry
2506 );
2507
2508
2509 /**
2510 Retrieves the first node of a doubly linked list.
2511
2512 Returns the first node of a doubly linked list. List must have been
2513 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2514 If List is empty, then List is returned.
2515
2516 If List is NULL, then ASSERT().
2517 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2518 InitializeListHead(), then ASSERT().
2519 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2520 in List, including the List node, is greater than or equal to
2521 PcdMaximumLinkedListLength, then ASSERT().
2522
2523 @param List A pointer to the head node of a doubly linked list.
2524
2525 @return The first node of a doubly linked list.
2526 @retval List The list is empty.
2527
2528 **/
2529 LIST_ENTRY *
2530 EFIAPI
2531 GetFirstNode (
2532 IN CONST LIST_ENTRY *List
2533 );
2534
2535
2536 /**
2537 Retrieves the next node of a doubly linked list.
2538
2539 Returns the node of a doubly linked list that follows Node.
2540 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2541 or InitializeListHead(). If List is empty, then List is returned.
2542
2543 If List is NULL, then ASSERT().
2544 If Node is NULL, then ASSERT().
2545 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2546 InitializeListHead(), then ASSERT().
2547 If PcdMaximumLinkedListLength is not zero, and List contains more than
2548 PcdMaximumLinkedListLength nodes, then ASSERT().
2549 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2550
2551 @param List A pointer to the head node of a doubly linked list.
2552 @param Node A pointer to a node in the doubly linked list.
2553
2554 @return The pointer to the next node if one exists. Otherwise List is returned.
2555
2556 **/
2557 LIST_ENTRY *
2558 EFIAPI
2559 GetNextNode (
2560 IN CONST LIST_ENTRY *List,
2561 IN CONST LIST_ENTRY *Node
2562 );
2563
2564
2565 /**
2566 Retrieves the previous node of a doubly linked list.
2567
2568 Returns the node of a doubly linked list that precedes Node.
2569 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2570 or InitializeListHead(). If List is empty, then List is returned.
2571
2572 If List is NULL, then ASSERT().
2573 If Node is NULL, then ASSERT().
2574 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2575 InitializeListHead(), then ASSERT().
2576 If PcdMaximumLinkedListLength is not zero, and List contains more than
2577 PcdMaximumLinkedListLength nodes, then ASSERT().
2578 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2579
2580 @param List A pointer to the head node of a doubly linked list.
2581 @param Node A pointer to a node in the doubly linked list.
2582
2583 @return The pointer to the previous node if one exists. Otherwise List is returned.
2584
2585 **/
2586 LIST_ENTRY *
2587 EFIAPI
2588 GetPreviousNode (
2589 IN CONST LIST_ENTRY *List,
2590 IN CONST LIST_ENTRY *Node
2591 );
2592
2593
2594 /**
2595 Checks to see if a doubly linked list is empty or not.
2596
2597 Checks to see if the doubly linked list is empty. If the linked list contains
2598 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
2599
2600 If ListHead is NULL, then ASSERT().
2601 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2602 InitializeListHead(), then ASSERT().
2603 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2604 in List, including the List node, is greater than or equal to
2605 PcdMaximumLinkedListLength, then ASSERT().
2606
2607 @param ListHead A pointer to the head node of a doubly linked list.
2608
2609 @retval TRUE The linked list is empty.
2610 @retval FALSE The linked list is not empty.
2611
2612 **/
2613 BOOLEAN
2614 EFIAPI
2615 IsListEmpty (
2616 IN CONST LIST_ENTRY *ListHead
2617 );
2618
2619
2620 /**
2621 Determines if a node in a doubly linked list is the head node of a the same
2622 doubly linked list. This function is typically used to terminate a loop that
2623 traverses all the nodes in a doubly linked list starting with the head node.
2624
2625 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
2626 nodes in the doubly linked list specified by List. List must have been
2627 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2628
2629 If List is NULL, then ASSERT().
2630 If Node is NULL, then ASSERT().
2631 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
2632 then ASSERT().
2633 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2634 in List, including the List node, is greater than or equal to
2635 PcdMaximumLinkedListLength, then ASSERT().
2636 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
2637 to List, then ASSERT().
2638
2639 @param List A pointer to the head node of a doubly linked list.
2640 @param Node A pointer to a node in the doubly linked list.
2641
2642 @retval TRUE Node is the head of the doubly-linked list pointed by List.
2643 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
2644
2645 **/
2646 BOOLEAN
2647 EFIAPI
2648 IsNull (
2649 IN CONST LIST_ENTRY *List,
2650 IN CONST LIST_ENTRY *Node
2651 );
2652
2653
2654 /**
2655 Determines if a node the last node in a doubly linked list.
2656
2657 Returns TRUE if Node is the last node in the doubly linked list specified by
2658 List. Otherwise, FALSE is returned. List must have been initialized with
2659 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2660
2661 If List is NULL, then ASSERT().
2662 If Node is NULL, then ASSERT().
2663 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2664 InitializeListHead(), then ASSERT().
2665 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2666 in List, including the List node, is greater than or equal to
2667 PcdMaximumLinkedListLength, then ASSERT().
2668 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2669
2670 @param List A pointer to the head node of a doubly linked list.
2671 @param Node A pointer to a node in the doubly linked list.
2672
2673 @retval TRUE Node is the last node in the linked list.
2674 @retval FALSE Node is not the last node in the linked list.
2675
2676 **/
2677 BOOLEAN
2678 EFIAPI
2679 IsNodeAtEnd (
2680 IN CONST LIST_ENTRY *List,
2681 IN CONST LIST_ENTRY *Node
2682 );
2683
2684
2685 /**
2686 Swaps the location of two nodes in a doubly linked list, and returns the
2687 first node after the swap.
2688
2689 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
2690 Otherwise, the location of the FirstEntry node is swapped with the location
2691 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
2692 same double linked list as FirstEntry and that double linked list must have
2693 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2694 SecondEntry is returned after the nodes are swapped.
2695
2696 If FirstEntry is NULL, then ASSERT().
2697 If SecondEntry is NULL, then ASSERT().
2698 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
2699 same linked list, then ASSERT().
2700 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2701 linked list containing the FirstEntry and SecondEntry nodes, including
2702 the FirstEntry and SecondEntry nodes, is greater than or equal to
2703 PcdMaximumLinkedListLength, then ASSERT().
2704
2705 @param FirstEntry A pointer to a node in a linked list.
2706 @param SecondEntry A pointer to another node in the same linked list.
2707
2708 @return SecondEntry.
2709
2710 **/
2711 LIST_ENTRY *
2712 EFIAPI
2713 SwapListEntries (
2714 IN OUT LIST_ENTRY *FirstEntry,
2715 IN OUT LIST_ENTRY *SecondEntry
2716 );
2717
2718
2719 /**
2720 Removes a node from a doubly linked list, and returns the node that follows
2721 the removed node.
2722
2723 Removes the node Entry from a doubly linked list. It is up to the caller of
2724 this function to release the memory used by this node if that is required. On
2725 exit, the node following Entry in the doubly linked list is returned. If
2726 Entry is the only node in the linked list, then the head node of the linked
2727 list is returned.
2728
2729 If Entry is NULL, then ASSERT().
2730 If Entry is the head node of an empty list, then ASSERT().
2731 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2732 linked list containing Entry, including the Entry node, is greater than
2733 or equal to PcdMaximumLinkedListLength, then ASSERT().
2734
2735 @param Entry A pointer to a node in a linked list.
2736
2737 @return Entry.
2738
2739 **/
2740 LIST_ENTRY *
2741 EFIAPI
2742 RemoveEntryList (
2743 IN CONST LIST_ENTRY *Entry
2744 );
2745
2746 //
2747 // Math Services
2748 //
2749
2750 /**
2751 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
2752 with zeros. The shifted value is returned.
2753
2754 This function shifts the 64-bit value Operand to the left by Count bits. The
2755 low Count bits are set to zero. The shifted value is returned.
2756
2757 If Count is greater than 63, then ASSERT().
2758
2759 @param Operand The 64-bit operand to shift left.
2760 @param Count The number of bits to shift left.
2761
2762 @return Operand << Count.
2763
2764 **/
2765 UINT64
2766 EFIAPI
2767 LShiftU64 (
2768 IN UINT64 Operand,
2769 IN UINTN Count
2770 );
2771
2772
2773 /**
2774 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
2775 filled with zeros. The shifted value is returned.
2776
2777 This function shifts the 64-bit value Operand to the right by Count bits. The
2778 high Count bits are set to zero. The shifted value is returned.
2779
2780 If Count is greater than 63, then ASSERT().
2781
2782 @param Operand The 64-bit operand to shift right.
2783 @param Count The number of bits to shift right.
2784
2785 @return Operand >> Count
2786
2787 **/
2788 UINT64
2789 EFIAPI
2790 RShiftU64 (
2791 IN UINT64 Operand,
2792 IN UINTN Count
2793 );
2794
2795
2796 /**
2797 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
2798 with original integer's bit 63. The shifted value is returned.
2799
2800 This function shifts the 64-bit value Operand to the right by Count bits. The
2801 high Count bits are set to bit 63 of Operand. The shifted value is returned.
2802
2803 If Count is greater than 63, then ASSERT().
2804
2805 @param Operand The 64-bit operand to shift right.
2806 @param Count The number of bits to shift right.
2807
2808 @return Operand >> Count
2809
2810 **/
2811 UINT64
2812 EFIAPI
2813 ARShiftU64 (
2814 IN UINT64 Operand,
2815 IN UINTN Count
2816 );
2817
2818
2819 /**
2820 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
2821 with the high bits that were rotated.
2822
2823 This function rotates the 32-bit value Operand to the left by Count bits. The
2824 low Count bits are fill with the high Count bits of Operand. The rotated
2825 value is returned.
2826
2827 If Count is greater than 31, then ASSERT().
2828
2829 @param Operand The 32-bit operand to rotate left.
2830 @param Count The number of bits to rotate left.
2831
2832 @return Operand << Count
2833
2834 **/
2835 UINT32
2836 EFIAPI
2837 LRotU32 (
2838 IN UINT32 Operand,
2839 IN UINTN Count
2840 );
2841
2842
2843 /**
2844 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
2845 with the low bits that were rotated.
2846
2847 This function rotates the 32-bit value Operand to the right by Count bits.
2848 The high Count bits are fill with the low Count bits of Operand. The rotated
2849 value is returned.
2850
2851 If Count is greater than 31, then ASSERT().
2852
2853 @param Operand The 32-bit operand to rotate right.
2854 @param Count The number of bits to rotate right.
2855
2856 @return Operand >> Count
2857
2858 **/
2859 UINT32
2860 EFIAPI
2861 RRotU32 (
2862 IN UINT32 Operand,
2863 IN UINTN Count
2864 );
2865
2866
2867 /**
2868 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
2869 with the high bits that were rotated.
2870
2871 This function rotates the 64-bit value Operand to the left by Count bits. The
2872 low Count bits are fill with the high Count bits of Operand. The rotated
2873 value is returned.
2874
2875 If Count is greater than 63, then ASSERT().
2876
2877 @param Operand The 64-bit operand to rotate left.
2878 @param Count The number of bits to rotate left.
2879
2880 @return Operand << Count
2881
2882 **/
2883 UINT64
2884 EFIAPI
2885 LRotU64 (
2886 IN UINT64 Operand,
2887 IN UINTN Count
2888 );
2889
2890
2891 /**
2892 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
2893 with the high low bits that were rotated.
2894
2895 This function rotates the 64-bit value Operand to the right by Count bits.
2896 The high Count bits are fill with the low Count bits of Operand. The rotated
2897 value is returned.
2898
2899 If Count is greater than 63, then ASSERT().
2900
2901 @param Operand The 64-bit operand to rotate right.
2902 @param Count The number of bits to rotate right.
2903
2904 @return Operand >> Count
2905
2906 **/
2907 UINT64
2908 EFIAPI
2909 RRotU64 (
2910 IN UINT64 Operand,
2911 IN UINTN Count
2912 );
2913
2914
2915 /**
2916 Returns the bit position of the lowest bit set in a 32-bit value.
2917
2918 This function computes the bit position of the lowest bit set in the 32-bit
2919 value specified by Operand. If Operand is zero, then -1 is returned.
2920 Otherwise, a value between 0 and 31 is returned.
2921
2922 @param Operand The 32-bit operand to evaluate.
2923
2924 @retval 0..31 The lowest bit set in Operand was found.
2925 @retval -1 Operand is zero.
2926
2927 **/
2928 INTN
2929 EFIAPI
2930 LowBitSet32 (
2931 IN UINT32 Operand
2932 );
2933
2934
2935 /**
2936 Returns the bit position of the lowest bit set in a 64-bit value.
2937
2938 This function computes the bit position of the lowest bit set in the 64-bit
2939 value specified by Operand. If Operand is zero, then -1 is returned.
2940 Otherwise, a value between 0 and 63 is returned.
2941
2942 @param Operand The 64-bit operand to evaluate.
2943
2944 @retval 0..63 The lowest bit set in Operand was found.
2945 @retval -1 Operand is zero.
2946
2947
2948 **/
2949 INTN
2950 EFIAPI
2951 LowBitSet64 (
2952 IN UINT64 Operand
2953 );
2954
2955
2956 /**
2957 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
2958 to log2(x).
2959
2960 This function computes the bit position of the highest bit set in the 32-bit
2961 value specified by Operand. If Operand is zero, then -1 is returned.
2962 Otherwise, a value between 0 and 31 is returned.
2963
2964 @param Operand The 32-bit operand to evaluate.
2965
2966 @retval 0..31 Position of the highest bit set in Operand if found.
2967 @retval -1 Operand is zero.
2968
2969 **/
2970 INTN
2971 EFIAPI
2972 HighBitSet32 (
2973 IN UINT32 Operand
2974 );
2975
2976
2977 /**
2978 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
2979 to log2(x).
2980
2981 This function computes the bit position of the highest bit set in the 64-bit
2982 value specified by Operand. If Operand is zero, then -1 is returned.
2983 Otherwise, a value between 0 and 63 is returned.
2984
2985 @param Operand The 64-bit operand to evaluate.
2986
2987 @retval 0..63 Position of the highest bit set in Operand if found.
2988 @retval -1 Operand is zero.
2989
2990 **/
2991 INTN
2992 EFIAPI
2993 HighBitSet64 (
2994 IN UINT64 Operand
2995 );
2996
2997
2998 /**
2999 Returns the value of the highest bit set in a 32-bit value. Equivalent to
3000 1 << log2(x).
3001
3002 This function computes the value of the highest bit set in the 32-bit value
3003 specified by Operand. If Operand is zero, then zero is returned.
3004
3005 @param Operand The 32-bit operand to evaluate.
3006
3007 @return 1 << HighBitSet32(Operand)
3008 @retval 0 Operand is zero.
3009
3010 **/
3011 UINT32
3012 EFIAPI
3013 GetPowerOfTwo32 (
3014 IN UINT32 Operand
3015 );
3016
3017
3018 /**
3019 Returns the value of the highest bit set in a 64-bit value. Equivalent to
3020 1 << log2(x).
3021
3022 This function computes the value of the highest bit set in the 64-bit value
3023 specified by Operand. If Operand is zero, then zero is returned.
3024
3025 @param Operand The 64-bit operand to evaluate.
3026
3027 @return 1 << HighBitSet64(Operand)
3028 @retval 0 Operand is zero.
3029
3030 **/
3031 UINT64
3032 EFIAPI
3033 GetPowerOfTwo64 (
3034 IN UINT64 Operand
3035 );
3036
3037
3038 /**
3039 Switches the endianness of a 16-bit integer.
3040
3041 This function swaps the bytes in a 16-bit unsigned value to switch the value
3042 from little endian to big endian or vice versa. The byte swapped value is
3043 returned.
3044
3045 @param Value A 16-bit unsigned value.
3046
3047 @return The byte swapped Value.
3048
3049 **/
3050 UINT16
3051 EFIAPI
3052 SwapBytes16 (
3053 IN UINT16 Value
3054 );
3055
3056
3057 /**
3058 Switches the endianness of a 32-bit integer.
3059
3060 This function swaps the bytes in a 32-bit unsigned value to switch the value
3061 from little endian to big endian or vice versa. The byte swapped value is
3062 returned.
3063
3064 @param Value A 32-bit unsigned value.
3065
3066 @return The byte swapped Value.
3067
3068 **/
3069 UINT32
3070 EFIAPI
3071 SwapBytes32 (
3072 IN UINT32 Value
3073 );
3074
3075
3076 /**
3077 Switches the endianness of a 64-bit integer.
3078
3079 This function swaps the bytes in a 64-bit unsigned value to switch the value
3080 from little endian to big endian or vice versa. The byte swapped value is
3081 returned.
3082
3083 @param Value A 64-bit unsigned value.
3084
3085 @return The byte swapped Value.
3086
3087 **/
3088 UINT64
3089 EFIAPI
3090 SwapBytes64 (
3091 IN UINT64 Value
3092 );
3093
3094
3095 /**
3096 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3097 generates a 64-bit unsigned result.
3098
3099 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3100 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3101 bit unsigned result is returned.
3102
3103 @param Multiplicand A 64-bit unsigned value.
3104 @param Multiplier A 32-bit unsigned value.
3105
3106 @return Multiplicand * Multiplier
3107
3108 **/
3109 UINT64
3110 EFIAPI
3111 MultU64x32 (
3112 IN UINT64 Multiplicand,
3113 IN UINT32 Multiplier
3114 );
3115
3116
3117 /**
3118 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3119 generates a 64-bit unsigned result.
3120
3121 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3122 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3123 bit unsigned result is returned.
3124
3125 @param Multiplicand A 64-bit unsigned value.
3126 @param Multiplier A 64-bit unsigned value.
3127
3128 @return Multiplicand * Multiplier.
3129
3130 **/
3131 UINT64
3132 EFIAPI
3133 MultU64x64 (
3134 IN UINT64 Multiplicand,
3135 IN UINT64 Multiplier
3136 );
3137
3138
3139 /**
3140 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3141 64-bit signed result.
3142
3143 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3144 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3145 signed result is returned.
3146
3147 @param Multiplicand A 64-bit signed value.
3148 @param Multiplier A 64-bit signed value.
3149
3150 @return Multiplicand * Multiplier
3151
3152 **/
3153 INT64
3154 EFIAPI
3155 MultS64x64 (
3156 IN INT64 Multiplicand,
3157 IN INT64 Multiplier
3158 );
3159
3160
3161 /**
3162 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3163 a 64-bit unsigned result.
3164
3165 This function divides the 64-bit unsigned value Dividend by the 32-bit
3166 unsigned value Divisor and generates a 64-bit unsigned quotient. This
3167 function returns the 64-bit unsigned quotient.
3168
3169 If Divisor is 0, then ASSERT().
3170
3171 @param Dividend A 64-bit unsigned value.
3172 @param Divisor A 32-bit unsigned value.
3173
3174 @return Dividend / Divisor.
3175
3176 **/
3177 UINT64
3178 EFIAPI
3179 DivU64x32 (
3180 IN UINT64 Dividend,
3181 IN UINT32 Divisor
3182 );
3183
3184
3185 /**
3186 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3187 a 32-bit unsigned remainder.
3188
3189 This function divides the 64-bit unsigned value Dividend by the 32-bit
3190 unsigned value Divisor and generates a 32-bit remainder. This function
3191 returns the 32-bit unsigned remainder.
3192
3193 If Divisor is 0, then ASSERT().
3194
3195 @param Dividend A 64-bit unsigned value.
3196 @param Divisor A 32-bit unsigned value.
3197
3198 @return Dividend % Divisor.
3199
3200 **/
3201 UINT32
3202 EFIAPI
3203 ModU64x32 (
3204 IN UINT64 Dividend,
3205 IN UINT32 Divisor
3206 );
3207
3208
3209 /**
3210 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3211 a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3212
3213 This function divides the 64-bit unsigned value Dividend by the 32-bit
3214 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3215 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3216 This function returns the 64-bit unsigned quotient.
3217
3218 If Divisor is 0, then ASSERT().
3219
3220 @param Dividend A 64-bit unsigned value.
3221 @param Divisor A 32-bit unsigned value.
3222 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3223 optional and may be NULL.
3224
3225 @return Dividend / Divisor.
3226
3227 **/
3228 UINT64
3229 EFIAPI
3230 DivU64x32Remainder (
3231 IN UINT64 Dividend,
3232 IN UINT32 Divisor,
3233 OUT UINT32 *Remainder OPTIONAL
3234 );
3235
3236
3237 /**
3238 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3239 a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3240
3241 This function divides the 64-bit unsigned value Dividend by the 64-bit
3242 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3243 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3244 This function returns the 64-bit unsigned quotient.
3245
3246 If Divisor is 0, then ASSERT().
3247
3248 @param Dividend A 64-bit unsigned value.
3249 @param Divisor A 64-bit unsigned value.
3250 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3251 optional and may be NULL.
3252
3253 @return Dividend / Divisor.
3254
3255 **/
3256 UINT64
3257 EFIAPI
3258 DivU64x64Remainder (
3259 IN UINT64 Dividend,
3260 IN UINT64 Divisor,
3261 OUT UINT64 *Remainder OPTIONAL
3262 );
3263
3264
3265 /**
3266 Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3267 64-bit signed result and a optional 64-bit signed remainder.
3268
3269 This function divides the 64-bit signed value Dividend by the 64-bit signed
3270 value Divisor and generates a 64-bit signed quotient. If Remainder is not
3271 NULL, then the 64-bit signed remainder is returned in Remainder. This
3272 function returns the 64-bit signed quotient.
3273
3274 It is the caller's responsibility to not call this function with a Divisor of 0.
3275 If Divisor is 0, then the quotient and remainder should be assumed to be
3276 the largest negative integer.
3277
3278 If Divisor is 0, then ASSERT().
3279
3280 @param Dividend A 64-bit signed value.
3281 @param Divisor A 64-bit signed value.
3282 @param Remainder A pointer to a 64-bit signed value. This parameter is
3283 optional and may be NULL.
3284
3285 @return Dividend / Divisor.
3286
3287 **/
3288 INT64
3289 EFIAPI
3290 DivS64x64Remainder (
3291 IN INT64 Dividend,
3292 IN INT64 Divisor,
3293 OUT INT64 *Remainder OPTIONAL
3294 );
3295
3296
3297 /**
3298 Reads a 16-bit value from memory that may be unaligned.
3299
3300 This function returns the 16-bit value pointed to by Buffer. The function
3301 guarantees that the read operation does not produce an alignment fault.
3302
3303 If the Buffer is NULL, then ASSERT().
3304
3305 @param Buffer The pointer to a 16-bit value that may be unaligned.
3306
3307 @return The 16-bit value read from Buffer.
3308
3309 **/
3310 UINT16
3311 EFIAPI
3312 ReadUnaligned16 (
3313 IN CONST UINT16 *Buffer
3314 );
3315
3316
3317 /**
3318 Writes a 16-bit value to memory that may be unaligned.
3319
3320 This function writes the 16-bit value specified by Value to Buffer. Value is
3321 returned. The function guarantees that the write operation does not produce
3322 an alignment fault.
3323
3324 If the Buffer is NULL, then ASSERT().
3325
3326 @param Buffer The pointer to a 16-bit value that may be unaligned.
3327 @param Value 16-bit value to write to Buffer.
3328
3329 @return The 16-bit value to write to Buffer.
3330
3331 **/
3332 UINT16
3333 EFIAPI
3334 WriteUnaligned16 (
3335 OUT UINT16 *Buffer,
3336 IN UINT16 Value
3337 );
3338
3339
3340 /**
3341 Reads a 24-bit value from memory that may be unaligned.
3342
3343 This function returns the 24-bit value pointed to by Buffer. The function
3344 guarantees that the read operation does not produce an alignment fault.
3345
3346 If the Buffer is NULL, then ASSERT().
3347
3348 @param Buffer The pointer to a 24-bit value that may be unaligned.
3349
3350 @return The 24-bit value read from Buffer.
3351
3352 **/
3353 UINT32
3354 EFIAPI
3355 ReadUnaligned24 (
3356 IN CONST UINT32 *Buffer
3357 );
3358
3359
3360 /**
3361 Writes a 24-bit value to memory that may be unaligned.
3362
3363 This function writes the 24-bit value specified by Value to Buffer. Value is
3364 returned. The function guarantees that the write operation does not produce
3365 an alignment fault.
3366
3367 If the Buffer is NULL, then ASSERT().
3368
3369 @param Buffer The pointer to a 24-bit value that may be unaligned.
3370 @param Value 24-bit value to write to Buffer.
3371
3372 @return The 24-bit value to write to Buffer.
3373
3374 **/
3375 UINT32
3376 EFIAPI
3377 WriteUnaligned24 (
3378 OUT UINT32 *Buffer,
3379 IN UINT32 Value
3380 );
3381
3382
3383 /**
3384 Reads a 32-bit value from memory that may be unaligned.
3385
3386 This function returns the 32-bit value pointed to by Buffer. The function
3387 guarantees that the read operation does not produce an alignment fault.
3388
3389 If the Buffer is NULL, then ASSERT().
3390
3391 @param Buffer The pointer to a 32-bit value that may be unaligned.
3392
3393 @return The 32-bit value read from Buffer.
3394
3395 **/
3396 UINT32
3397 EFIAPI
3398 ReadUnaligned32 (
3399 IN CONST UINT32 *Buffer
3400 );
3401
3402
3403 /**
3404 Writes a 32-bit value to memory that may be unaligned.
3405
3406 This function writes the 32-bit value specified by Value to Buffer. Value is
3407 returned. The function guarantees that the write operation does not produce
3408 an alignment fault.
3409
3410 If the Buffer is NULL, then ASSERT().
3411
3412 @param Buffer The pointer to a 32-bit value that may be unaligned.
3413 @param Value 32-bit value to write to Buffer.
3414
3415 @return The 32-bit value to write to Buffer.
3416
3417 **/
3418 UINT32
3419 EFIAPI
3420 WriteUnaligned32 (
3421 OUT UINT32 *Buffer,
3422 IN UINT32 Value
3423 );
3424
3425
3426 /**
3427 Reads a 64-bit value from memory that may be unaligned.
3428
3429 This function returns the 64-bit value pointed to by Buffer. The function
3430 guarantees that the read operation does not produce an alignment fault.
3431
3432 If the Buffer is NULL, then ASSERT().
3433
3434 @param Buffer The pointer to a 64-bit value that may be unaligned.
3435
3436 @return The 64-bit value read from Buffer.
3437
3438 **/
3439 UINT64
3440 EFIAPI
3441 ReadUnaligned64 (
3442 IN CONST UINT64 *Buffer
3443 );
3444
3445
3446 /**
3447 Writes a 64-bit value to memory that may be unaligned.
3448
3449 This function writes the 64-bit value specified by Value to Buffer. Value is
3450 returned. The function guarantees that the write operation does not produce
3451 an alignment fault.
3452
3453 If the Buffer is NULL, then ASSERT().
3454
3455 @param Buffer The pointer to a 64-bit value that may be unaligned.
3456 @param Value 64-bit value to write to Buffer.
3457
3458 @return The 64-bit value to write to Buffer.
3459
3460 **/
3461 UINT64
3462 EFIAPI
3463 WriteUnaligned64 (
3464 OUT UINT64 *Buffer,
3465 IN UINT64 Value
3466 );
3467
3468
3469 //
3470 // Bit Field Functions
3471 //
3472
3473 /**
3474 Returns a bit field from an 8-bit value.
3475
3476 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3477
3478 If 8-bit operations are not supported, then ASSERT().
3479 If StartBit is greater than 7, then ASSERT().
3480 If EndBit is greater than 7, then ASSERT().
3481 If EndBit is less than StartBit, then ASSERT().
3482
3483 @param Operand Operand on which to perform the bitfield operation.
3484 @param StartBit The ordinal of the least significant bit in the bit field.
3485 Range 0..7.
3486 @param EndBit The ordinal of the most significant bit in the bit field.
3487 Range 0..7.
3488
3489 @return The bit field read.
3490
3491 **/
3492 UINT8
3493 EFIAPI
3494 BitFieldRead8 (
3495 IN UINT8 Operand,
3496 IN UINTN StartBit,
3497 IN UINTN EndBit
3498 );
3499
3500
3501 /**
3502 Writes a bit field to an 8-bit value, and returns the result.
3503
3504 Writes Value to the bit field specified by the StartBit and the EndBit in
3505 Operand. All other bits in Operand are preserved. The new 8-bit value is
3506 returned.
3507
3508 If 8-bit operations are not supported, then ASSERT().
3509 If StartBit is greater than 7, then ASSERT().
3510 If EndBit is greater than 7, then ASSERT().
3511 If EndBit is less than StartBit, then ASSERT().
3512 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3513
3514 @param Operand Operand on which to perform the bitfield operation.
3515 @param StartBit The ordinal of the least significant bit in the bit field.
3516 Range 0..7.
3517 @param EndBit The ordinal of the most significant bit in the bit field.
3518 Range 0..7.
3519 @param Value New value of the bit field.
3520
3521 @return The new 8-bit value.
3522
3523 **/
3524 UINT8
3525 EFIAPI
3526 BitFieldWrite8 (
3527 IN UINT8 Operand,
3528 IN UINTN StartBit,
3529 IN UINTN EndBit,
3530 IN UINT8 Value
3531 );
3532
3533
3534 /**
3535 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
3536 result.
3537
3538 Performs a bitwise OR between the bit field specified by StartBit
3539 and EndBit in Operand and the value specified by OrData. All other bits in
3540 Operand are preserved. The new 8-bit value is returned.
3541
3542 If 8-bit operations are not supported, then ASSERT().
3543 If StartBit is greater than 7, then ASSERT().
3544 If EndBit is greater than 7, then ASSERT().
3545 If EndBit is less than StartBit, then ASSERT().
3546 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3547
3548 @param Operand Operand on which to perform the bitfield operation.
3549 @param StartBit The ordinal of the least significant bit in the bit field.
3550 Range 0..7.
3551 @param EndBit The ordinal of the most significant bit in the bit field.
3552 Range 0..7.
3553 @param OrData The value to OR with the read value from the value
3554
3555 @return The new 8-bit value.
3556
3557 **/
3558 UINT8
3559 EFIAPI
3560 BitFieldOr8 (
3561 IN UINT8 Operand,
3562 IN UINTN StartBit,
3563 IN UINTN EndBit,
3564 IN UINT8 OrData
3565 );
3566
3567
3568 /**
3569 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
3570 the result.
3571
3572 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3573 in Operand and the value specified by AndData. All other bits in Operand are
3574 preserved. The new 8-bit value is returned.
3575
3576 If 8-bit operations are not supported, then ASSERT().
3577 If StartBit is greater than 7, then ASSERT().
3578 If EndBit is greater than 7, then ASSERT().
3579 If EndBit is less than StartBit, then ASSERT().
3580 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3581
3582 @param Operand Operand on which to perform the bitfield operation.
3583 @param StartBit The ordinal of the least significant bit in the bit field.
3584 Range 0..7.
3585 @param EndBit The ordinal of the most significant bit in the bit field.
3586 Range 0..7.
3587 @param AndData The value to AND with the read value from the value.
3588
3589 @return The new 8-bit value.
3590
3591 **/
3592 UINT8
3593 EFIAPI
3594 BitFieldAnd8 (
3595 IN UINT8 Operand,
3596 IN UINTN StartBit,
3597 IN UINTN EndBit,
3598 IN UINT8 AndData
3599 );
3600
3601
3602 /**
3603 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
3604 bitwise OR, and returns the result.
3605
3606 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3607 in Operand and the value specified by AndData, followed by a bitwise
3608 OR with value specified by OrData. All other bits in Operand are
3609 preserved. The new 8-bit value is returned.
3610
3611 If 8-bit operations are not supported, then ASSERT().
3612 If StartBit is greater than 7, then ASSERT().
3613 If EndBit is greater than 7, then ASSERT().
3614 If EndBit is less than StartBit, then ASSERT().
3615 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3616 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3617
3618 @param Operand Operand on which to perform the bitfield operation.
3619 @param StartBit The ordinal of the least significant bit in the bit field.
3620 Range 0..7.
3621 @param EndBit The ordinal of the most significant bit in the bit field.
3622 Range 0..7.
3623 @param AndData The value to AND with the read value from the value.
3624 @param OrData The value to OR with the result of the AND operation.
3625
3626 @return The new 8-bit value.
3627
3628 **/
3629 UINT8
3630 EFIAPI
3631 BitFieldAndThenOr8 (
3632 IN UINT8 Operand,
3633 IN UINTN StartBit,
3634 IN UINTN EndBit,
3635 IN UINT8 AndData,
3636 IN UINT8 OrData
3637 );
3638
3639
3640 /**
3641 Returns a bit field from a 16-bit value.
3642
3643 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3644
3645 If 16-bit operations are not supported, then ASSERT().
3646 If StartBit is greater than 15, then ASSERT().
3647 If EndBit is greater than 15, then ASSERT().
3648 If EndBit is less than StartBit, then ASSERT().
3649
3650 @param Operand Operand on which to perform the bitfield operation.
3651 @param StartBit The ordinal of the least significant bit in the bit field.
3652 Range 0..15.
3653 @param EndBit The ordinal of the most significant bit in the bit field.
3654 Range 0..15.