2 Provides string functions, linked list functions, math functions, synchronization
3 functions, file path functions, and CPU architecture-specific functions.
5 Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
7 Copyright (c) Microsoft Corporation.<BR>
8 Portions Copyright (c) 2020, Hewlett Packard Enterprise Development LP. All rights reserved.<BR>
10 SPDX-License-Identifier: BSD-2-Clause-Patent
18 // Definitions for architecture-specific types
20 #if defined (MDE_CPU_IA32)
22 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
32 } BASE_LIBRARY_JUMP_BUFFER
;
34 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
36 #endif // defined (MDE_CPU_IA32)
38 #if defined (MDE_CPU_X64)
40 /// The x64 architecture context buffer used by SetJump() and LongJump().
54 UINT8 XmmBuffer
[160]; ///< XMM6-XMM15.
56 } BASE_LIBRARY_JUMP_BUFFER
;
58 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
60 #endif // defined (MDE_CPU_X64)
62 #if defined (MDE_CPU_EBC)
64 /// The EBC context buffer used by SetJump() and LongJump().
72 } BASE_LIBRARY_JUMP_BUFFER
;
74 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
76 #endif // defined (MDE_CPU_EBC)
78 #if defined (MDE_CPU_ARM)
81 UINT32 R3
; ///< A copy of R13.
92 } BASE_LIBRARY_JUMP_BUFFER
;
94 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
96 #endif // defined (MDE_CPU_ARM)
98 #if defined (MDE_CPU_AARCH64)
124 } BASE_LIBRARY_JUMP_BUFFER
;
126 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
128 #endif // defined (MDE_CPU_AARCH64)
130 #if defined (MDE_CPU_RISCV64)
132 /// The RISC-V architecture context buffer used by SetJump() and LongJump().
149 } BASE_LIBRARY_JUMP_BUFFER
;
151 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
153 #endif // defined (MDE_CPU_RISCV64)
161 Returns the length of a Null-terminated Unicode string.
163 This function is similar as strlen_s defined in C11.
165 If String is not aligned on a 16-bit boundary, then ASSERT().
167 @param String A pointer to a Null-terminated Unicode string.
168 @param MaxSize The maximum number of Destination Unicode
169 char, including terminating null char.
171 @retval 0 If String is NULL.
172 @retval MaxSize If there is no null character in the first MaxSize characters of String.
173 @return The number of characters that percede the terminating null character.
179 IN CONST CHAR16
*String
,
184 Returns the size of a Null-terminated Unicode string in bytes, including the
187 This function returns the size of the Null-terminated Unicode string
188 specified by String in bytes, including the Null terminator.
190 If String is not aligned on a 16-bit boundary, then ASSERT().
192 @param String A pointer to a Null-terminated Unicode string.
193 @param MaxSize The maximum number of Destination Unicode
194 char, including the Null terminator.
196 @retval 0 If String is NULL.
197 @retval (sizeof (CHAR16) * (MaxSize + 1))
198 If there is no Null terminator in the first MaxSize characters of
200 @return The size of the Null-terminated Unicode string in bytes, including
207 IN CONST CHAR16
*String
,
212 Copies the string pointed to by Source (including the terminating null char)
213 to the array pointed to by Destination.
215 This function is similar as strcpy_s defined in C11.
217 If Destination is not aligned on a 16-bit boundary, then ASSERT().
218 If Source is not aligned on a 16-bit boundary, then ASSERT().
219 If an error would be returned, then the function will also ASSERT().
221 If an error is returned, then the Destination is unmodified.
223 @param Destination A pointer to a Null-terminated Unicode string.
224 @param DestMax The maximum number of Destination Unicode
225 char, including terminating null char.
226 @param Source A pointer to a Null-terminated Unicode string.
228 @retval RETURN_SUCCESS String is copied.
229 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
230 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
232 If PcdMaximumUnicodeStringLength is not zero,
233 and DestMax is greater than
234 PcdMaximumUnicodeStringLength.
236 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
241 OUT CHAR16
*Destination
,
243 IN CONST CHAR16
*Source
247 Copies not more than Length successive char from the string pointed to by
248 Source to the array pointed to by Destination. If no null char is copied from
249 Source, then Destination[Length] is always set to null.
251 This function is similar as strncpy_s defined in C11.
253 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
254 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
255 If an error would be returned, then the function will also ASSERT().
257 If an error is returned, then the Destination is unmodified.
259 @param Destination A pointer to a Null-terminated Unicode string.
260 @param DestMax The maximum number of Destination Unicode
261 char, including terminating null char.
262 @param Source A pointer to a Null-terminated Unicode string.
263 @param Length The maximum number of Unicode characters to copy.
265 @retval RETURN_SUCCESS String is copied.
266 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
267 MIN(StrLen(Source), Length).
268 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
270 If PcdMaximumUnicodeStringLength is not zero,
271 and DestMax is greater than
272 PcdMaximumUnicodeStringLength.
274 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
279 OUT CHAR16
*Destination
,
281 IN CONST CHAR16
*Source
,
286 Appends a copy of the string pointed to by Source (including the terminating
287 null char) to the end of the string pointed to by Destination.
289 This function is similar as strcat_s defined in C11.
291 If Destination is not aligned on a 16-bit boundary, then ASSERT().
292 If Source is not aligned on a 16-bit boundary, then ASSERT().
293 If an error would be returned, then the function will also ASSERT().
295 If an error is returned, then the Destination is unmodified.
297 @param Destination A pointer to a Null-terminated Unicode string.
298 @param DestMax The maximum number of Destination Unicode
299 char, including terminating null char.
300 @param Source A pointer to a Null-terminated Unicode string.
302 @retval RETURN_SUCCESS String is appended.
303 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
305 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
306 greater than StrLen(Source).
307 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
309 If PcdMaximumUnicodeStringLength is not zero,
310 and DestMax is greater than
311 PcdMaximumUnicodeStringLength.
313 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
318 IN OUT CHAR16
*Destination
,
320 IN CONST CHAR16
*Source
324 Appends not more than Length successive char from the string pointed to by
325 Source to the end of the string pointed to by Destination. If no null char is
326 copied from Source, then Destination[StrLen(Destination) + Length] is always
329 This function is similar as strncat_s defined in C11.
331 If Destination is not aligned on a 16-bit boundary, then ASSERT().
332 If Source is not aligned on a 16-bit boundary, then ASSERT().
333 If an error would be returned, then the function will also ASSERT().
335 If an error is returned, then the Destination is unmodified.
337 @param Destination A pointer to a Null-terminated Unicode string.
338 @param DestMax The maximum number of Destination Unicode
339 char, including terminating null char.
340 @param Source A pointer to a Null-terminated Unicode string.
341 @param Length The maximum number of Unicode characters to copy.
343 @retval RETURN_SUCCESS String is appended.
344 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
346 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
347 greater than MIN(StrLen(Source), Length).
348 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
350 If PcdMaximumUnicodeStringLength is not zero,
351 and DestMax is greater than
352 PcdMaximumUnicodeStringLength.
354 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
359 IN OUT CHAR16
*Destination
,
361 IN CONST CHAR16
*Source
,
366 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
368 This function outputs a value of type UINTN by interpreting the contents of
369 the Unicode string specified by String as a decimal number. The format of the
370 input Unicode string String is:
372 [spaces] [decimal digits].
374 The valid decimal digit character is in the range [0-9]. The function will
375 ignore the pad space, which includes spaces or tab characters, before
376 [decimal digits]. The running zero in the beginning of [decimal digits] will
377 be ignored. Then, the function stops at the first character that is a not a
378 valid decimal character or a Null-terminator, whichever one comes first.
380 If String is NULL, then ASSERT().
381 If Data is NULL, then ASSERT().
382 If String is not aligned in a 16-bit boundary, then ASSERT().
383 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
384 PcdMaximumUnicodeStringLength Unicode characters, not including the
385 Null-terminator, then ASSERT().
387 If String has no valid decimal digits in the above format, then 0 is stored
388 at the location pointed to by Data.
389 If the number represented by String exceeds the range defined by UINTN, then
390 MAX_UINTN is stored at the location pointed to by Data.
392 If EndPointer is not NULL, a pointer to the character that stopped the scan
393 is stored at the location pointed to by EndPointer. If String has no valid
394 decimal digits right after the optional pad spaces, the value of String is
395 stored at the location pointed to by EndPointer.
397 @param String Pointer to a Null-terminated Unicode string.
398 @param EndPointer Pointer to character that stops scan.
399 @param Data Pointer to the converted value.
401 @retval RETURN_SUCCESS Value is translated from String.
402 @retval RETURN_INVALID_PARAMETER If String is NULL.
404 If PcdMaximumUnicodeStringLength is not
405 zero, and String contains more than
406 PcdMaximumUnicodeStringLength Unicode
407 characters, not including the
409 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
410 the range defined by UINTN.
416 IN CONST CHAR16
*String
,
417 OUT CHAR16
**EndPointer
, OPTIONAL
422 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
424 This function outputs a value of type UINT64 by interpreting the contents of
425 the Unicode string specified by String as a decimal number. The format of the
426 input Unicode string String is:
428 [spaces] [decimal digits].
430 The valid decimal digit character is in the range [0-9]. The function will
431 ignore the pad space, which includes spaces or tab characters, before
432 [decimal digits]. The running zero in the beginning of [decimal digits] will
433 be ignored. Then, the function stops at the first character that is a not a
434 valid decimal character or a Null-terminator, whichever one comes first.
436 If String is NULL, then ASSERT().
437 If Data is NULL, then ASSERT().
438 If String is not aligned in a 16-bit boundary, then ASSERT().
439 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
440 PcdMaximumUnicodeStringLength Unicode characters, not including the
441 Null-terminator, then ASSERT().
443 If String has no valid decimal digits in the above format, then 0 is stored
444 at the location pointed to by Data.
445 If the number represented by String exceeds the range defined by UINT64, then
446 MAX_UINT64 is stored at the location pointed to by Data.
448 If EndPointer is not NULL, a pointer to the character that stopped the scan
449 is stored at the location pointed to by EndPointer. If String has no valid
450 decimal digits right after the optional pad spaces, the value of String is
451 stored at the location pointed to by EndPointer.
453 @param String Pointer to a Null-terminated Unicode string.
454 @param EndPointer Pointer to character that stops scan.
455 @param Data Pointer to the converted value.
457 @retval RETURN_SUCCESS Value is translated from String.
458 @retval RETURN_INVALID_PARAMETER If String is NULL.
460 If PcdMaximumUnicodeStringLength is not
461 zero, and String contains more than
462 PcdMaximumUnicodeStringLength Unicode
463 characters, not including the
465 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
466 the range defined by UINT64.
471 StrDecimalToUint64S (
472 IN CONST CHAR16
*String
,
473 OUT CHAR16
**EndPointer
, OPTIONAL
478 Convert a Null-terminated Unicode hexadecimal string to a value of type
481 This function outputs a value of type UINTN by interpreting the contents of
482 the Unicode string specified by String as a hexadecimal number. The format of
483 the input Unicode string String is:
485 [spaces][zeros][x][hexadecimal digits].
487 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
488 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
489 If "x" appears in the input string, it must be prefixed with at least one 0.
490 The function will ignore the pad space, which includes spaces or tab
491 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
492 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
493 after [x] or the first valid hexadecimal digit. Then, the function stops at
494 the first character that is a not a valid hexadecimal character or NULL,
495 whichever one comes first.
497 If String is NULL, then ASSERT().
498 If Data is NULL, then ASSERT().
499 If String is not aligned in a 16-bit boundary, then ASSERT().
500 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
501 PcdMaximumUnicodeStringLength Unicode characters, not including the
502 Null-terminator, then ASSERT().
504 If String has no valid hexadecimal digits in the above format, then 0 is
505 stored at the location pointed to by Data.
506 If the number represented by String exceeds the range defined by UINTN, then
507 MAX_UINTN is stored at the location pointed to by Data.
509 If EndPointer is not NULL, a pointer to the character that stopped the scan
510 is stored at the location pointed to by EndPointer. If String has no valid
511 hexadecimal digits right after the optional pad spaces, the value of String
512 is stored at the location pointed to by EndPointer.
514 @param String Pointer to a Null-terminated Unicode string.
515 @param EndPointer Pointer to character that stops scan.
516 @param Data Pointer to the converted value.
518 @retval RETURN_SUCCESS Value is translated from String.
519 @retval RETURN_INVALID_PARAMETER If String is NULL.
521 If PcdMaximumUnicodeStringLength is not
522 zero, and String contains more than
523 PcdMaximumUnicodeStringLength Unicode
524 characters, not including the
526 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
527 the range defined by UINTN.
533 IN CONST CHAR16
*String
,
534 OUT CHAR16
**EndPointer
, OPTIONAL
539 Convert a Null-terminated Unicode hexadecimal string to a value of type
542 This function outputs a value of type UINT64 by interpreting the contents of
543 the Unicode string specified by String as a hexadecimal number. The format of
544 the input Unicode string String is:
546 [spaces][zeros][x][hexadecimal digits].
548 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
549 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
550 If "x" appears in the input string, it must be prefixed with at least one 0.
551 The function will ignore the pad space, which includes spaces or tab
552 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
553 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
554 after [x] or the first valid hexadecimal digit. Then, the function stops at
555 the first character that is a not a valid hexadecimal character or NULL,
556 whichever one comes first.
558 If String is NULL, then ASSERT().
559 If Data is NULL, then ASSERT().
560 If String is not aligned in a 16-bit boundary, then ASSERT().
561 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
562 PcdMaximumUnicodeStringLength Unicode characters, not including the
563 Null-terminator, then ASSERT().
565 If String has no valid hexadecimal digits in the above format, then 0 is
566 stored at the location pointed to by Data.
567 If the number represented by String exceeds the range defined by UINT64, then
568 MAX_UINT64 is stored at the location pointed to by Data.
570 If EndPointer is not NULL, a pointer to the character that stopped the scan
571 is stored at the location pointed to by EndPointer. If String has no valid
572 hexadecimal digits right after the optional pad spaces, the value of String
573 is stored at the location pointed to by EndPointer.
575 @param String Pointer to a Null-terminated Unicode string.
576 @param EndPointer Pointer to character that stops scan.
577 @param Data Pointer to the converted value.
579 @retval RETURN_SUCCESS Value is translated from String.
580 @retval RETURN_INVALID_PARAMETER If String is NULL.
582 If PcdMaximumUnicodeStringLength is not
583 zero, and String contains more than
584 PcdMaximumUnicodeStringLength Unicode
585 characters, not including the
587 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
588 the range defined by UINT64.
594 IN CONST CHAR16
*String
,
595 OUT CHAR16
**EndPointer
, OPTIONAL
600 Returns the length of a Null-terminated Ascii string.
602 This function is similar as strlen_s defined in C11.
604 @param String A pointer to a Null-terminated Ascii string.
605 @param MaxSize The maximum number of Destination Ascii
606 char, including terminating null char.
608 @retval 0 If String is NULL.
609 @retval MaxSize If there is no null character in the first MaxSize characters of String.
610 @return The number of characters that percede the terminating null character.
616 IN CONST CHAR8
*String
,
621 Returns the size of a Null-terminated Ascii string in bytes, including the
624 This function returns the size of the Null-terminated Ascii string specified
625 by String in bytes, including the Null terminator.
627 @param String A pointer to a Null-terminated Ascii string.
628 @param MaxSize The maximum number of Destination Ascii
629 char, including the Null terminator.
631 @retval 0 If String is NULL.
632 @retval (sizeof (CHAR8) * (MaxSize + 1))
633 If there is no Null terminator in the first MaxSize characters of
635 @return The size of the Null-terminated Ascii string in bytes, including the
642 IN CONST CHAR8
*String
,
647 Copies the string pointed to by Source (including the terminating null char)
648 to the array pointed to by Destination.
650 This function is similar as strcpy_s defined in C11.
652 If an error would be returned, then the function will also ASSERT().
654 If an error is returned, then the Destination is unmodified.
656 @param Destination A pointer to a Null-terminated Ascii string.
657 @param DestMax The maximum number of Destination Ascii
658 char, including terminating null char.
659 @param Source A pointer to a Null-terminated Ascii string.
661 @retval RETURN_SUCCESS String is copied.
662 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
663 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
665 If PcdMaximumAsciiStringLength is not zero,
666 and DestMax is greater than
667 PcdMaximumAsciiStringLength.
669 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
674 OUT CHAR8
*Destination
,
676 IN CONST CHAR8
*Source
680 Copies not more than Length successive char from the string pointed to by
681 Source to the array pointed to by Destination. If no null char is copied from
682 Source, then Destination[Length] is always set to null.
684 This function is similar as strncpy_s defined in C11.
686 If an error would be returned, then the function will also ASSERT().
688 If an error is returned, then the Destination is unmodified.
690 @param Destination A pointer to a Null-terminated Ascii string.
691 @param DestMax The maximum number of Destination Ascii
692 char, including terminating null char.
693 @param Source A pointer to a Null-terminated Ascii string.
694 @param Length The maximum number of Ascii characters to copy.
696 @retval RETURN_SUCCESS String is copied.
697 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
698 MIN(StrLen(Source), Length).
699 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
701 If PcdMaximumAsciiStringLength is not zero,
702 and DestMax is greater than
703 PcdMaximumAsciiStringLength.
705 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
710 OUT CHAR8
*Destination
,
712 IN CONST CHAR8
*Source
,
717 Appends a copy of the string pointed to by Source (including the terminating
718 null char) to the end of the string pointed to by Destination.
720 This function is similar as strcat_s defined in C11.
722 If an error would be returned, then the function will also ASSERT().
724 If an error is returned, then the Destination is unmodified.
726 @param Destination A pointer to a Null-terminated Ascii string.
727 @param DestMax The maximum number of Destination Ascii
728 char, including terminating null char.
729 @param Source A pointer to a Null-terminated Ascii string.
731 @retval RETURN_SUCCESS String is appended.
732 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
734 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
735 greater than StrLen(Source).
736 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
738 If PcdMaximumAsciiStringLength is not zero,
739 and DestMax is greater than
740 PcdMaximumAsciiStringLength.
742 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
747 IN OUT CHAR8
*Destination
,
749 IN CONST CHAR8
*Source
753 Appends not more than Length successive char from the string pointed to by
754 Source to the end of the string pointed to by Destination. If no null char is
755 copied from Source, then Destination[StrLen(Destination) + Length] is always
758 This function is similar as strncat_s defined in C11.
760 If an error would be returned, then the function will also ASSERT().
762 If an error is returned, then the Destination is unmodified.
764 @param Destination A pointer to a Null-terminated Ascii string.
765 @param DestMax The maximum number of Destination Ascii
766 char, including terminating null char.
767 @param Source A pointer to a Null-terminated Ascii string.
768 @param Length The maximum number of Ascii characters to copy.
770 @retval RETURN_SUCCESS String is appended.
771 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
773 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
774 greater than MIN(StrLen(Source), Length).
775 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
777 If PcdMaximumAsciiStringLength is not zero,
778 and DestMax is greater than
779 PcdMaximumAsciiStringLength.
781 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
786 IN OUT CHAR8
*Destination
,
788 IN CONST CHAR8
*Source
,
793 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
795 This function outputs a value of type UINTN by interpreting the contents of
796 the Ascii string specified by String as a decimal number. The format of the
797 input Ascii string String is:
799 [spaces] [decimal digits].
801 The valid decimal digit character is in the range [0-9]. The function will
802 ignore the pad space, which includes spaces or tab characters, before
803 [decimal digits]. The running zero in the beginning of [decimal digits] will
804 be ignored. Then, the function stops at the first character that is a not a
805 valid decimal character or a Null-terminator, whichever one comes first.
807 If String is NULL, then ASSERT().
808 If Data is NULL, then ASSERT().
809 If PcdMaximumAsciiStringLength is not zero, and String contains more than
810 PcdMaximumAsciiStringLength Ascii characters, not including the
811 Null-terminator, then ASSERT().
813 If String has no valid decimal digits in the above format, then 0 is stored
814 at the location pointed to by Data.
815 If the number represented by String exceeds the range defined by UINTN, then
816 MAX_UINTN is stored at the location pointed to by Data.
818 If EndPointer is not NULL, a pointer to the character that stopped the scan
819 is stored at the location pointed to by EndPointer. If String has no valid
820 decimal digits right after the optional pad spaces, the value of String is
821 stored at the location pointed to by EndPointer.
823 @param String Pointer to a Null-terminated Ascii string.
824 @param EndPointer Pointer to character that stops scan.
825 @param Data Pointer to the converted value.
827 @retval RETURN_SUCCESS Value is translated from String.
828 @retval RETURN_INVALID_PARAMETER If String is NULL.
830 If PcdMaximumAsciiStringLength is not zero,
831 and String contains more than
832 PcdMaximumAsciiStringLength Ascii
833 characters, not including the
835 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
836 the range defined by UINTN.
841 AsciiStrDecimalToUintnS (
842 IN CONST CHAR8
*String
,
843 OUT CHAR8
**EndPointer
, OPTIONAL
848 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
850 This function outputs a value of type UINT64 by interpreting the contents of
851 the Ascii string specified by String as a decimal number. The format of the
852 input Ascii string String is:
854 [spaces] [decimal digits].
856 The valid decimal digit character is in the range [0-9]. The function will
857 ignore the pad space, which includes spaces or tab characters, before
858 [decimal digits]. The running zero in the beginning of [decimal digits] will
859 be ignored. Then, the function stops at the first character that is a not a
860 valid decimal character or a Null-terminator, whichever one comes first.
862 If String is NULL, then ASSERT().
863 If Data is NULL, then ASSERT().
864 If PcdMaximumAsciiStringLength is not zero, and String contains more than
865 PcdMaximumAsciiStringLength Ascii characters, not including the
866 Null-terminator, then ASSERT().
868 If String has no valid decimal digits in the above format, then 0 is stored
869 at the location pointed to by Data.
870 If the number represented by String exceeds the range defined by UINT64, then
871 MAX_UINT64 is stored at the location pointed to by Data.
873 If EndPointer is not NULL, a pointer to the character that stopped the scan
874 is stored at the location pointed to by EndPointer. If String has no valid
875 decimal digits right after the optional pad spaces, the value of String is
876 stored at the location pointed to by EndPointer.
878 @param String Pointer to a Null-terminated Ascii string.
879 @param EndPointer Pointer to character that stops scan.
880 @param Data Pointer to the converted value.
882 @retval RETURN_SUCCESS Value is translated from String.
883 @retval RETURN_INVALID_PARAMETER If String is NULL.
885 If PcdMaximumAsciiStringLength is not zero,
886 and String contains more than
887 PcdMaximumAsciiStringLength Ascii
888 characters, not including the
890 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
891 the range defined by UINT64.
896 AsciiStrDecimalToUint64S (
897 IN CONST CHAR8
*String
,
898 OUT CHAR8
**EndPointer
, OPTIONAL
903 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
905 This function outputs a value of type UINTN by interpreting the contents of
906 the Ascii string specified by String as a hexadecimal number. The format of
907 the input Ascii string String is:
909 [spaces][zeros][x][hexadecimal digits].
911 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
912 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
913 "x" appears in the input string, it must be prefixed with at least one 0. The
914 function will ignore the pad space, which includes spaces or tab characters,
915 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
916 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
917 the first valid hexadecimal digit. Then, the function stops at the first
918 character that is a not a valid hexadecimal character or Null-terminator,
919 whichever on comes first.
921 If String is NULL, then ASSERT().
922 If Data is NULL, then ASSERT().
923 If PcdMaximumAsciiStringLength is not zero, and String contains more than
924 PcdMaximumAsciiStringLength Ascii characters, not including the
925 Null-terminator, then ASSERT().
927 If String has no valid hexadecimal digits in the above format, then 0 is
928 stored at the location pointed to by Data.
929 If the number represented by String exceeds the range defined by UINTN, then
930 MAX_UINTN is stored at the location pointed to by Data.
932 If EndPointer is not NULL, a pointer to the character that stopped the scan
933 is stored at the location pointed to by EndPointer. If String has no valid
934 hexadecimal digits right after the optional pad spaces, the value of String
935 is stored at the location pointed to by EndPointer.
937 @param String Pointer to a Null-terminated Ascii string.
938 @param EndPointer Pointer to character that stops scan.
939 @param Data Pointer to the converted value.
941 @retval RETURN_SUCCESS Value is translated from String.
942 @retval RETURN_INVALID_PARAMETER If String is NULL.
944 If PcdMaximumAsciiStringLength is not zero,
945 and String contains more than
946 PcdMaximumAsciiStringLength Ascii
947 characters, not including the
949 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
950 the range defined by UINTN.
955 AsciiStrHexToUintnS (
956 IN CONST CHAR8
*String
,
957 OUT CHAR8
**EndPointer
, OPTIONAL
962 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
964 This function outputs a value of type UINT64 by interpreting the contents of
965 the Ascii string specified by String as a hexadecimal number. The format of
966 the input Ascii string String is:
968 [spaces][zeros][x][hexadecimal digits].
970 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
971 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
972 "x" appears in the input string, it must be prefixed with at least one 0. The
973 function will ignore the pad space, which includes spaces or tab characters,
974 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
975 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
976 the first valid hexadecimal digit. Then, the function stops at the first
977 character that is a not a valid hexadecimal character or Null-terminator,
978 whichever on comes first.
980 If String is NULL, then ASSERT().
981 If Data is NULL, then ASSERT().
982 If PcdMaximumAsciiStringLength is not zero, and String contains more than
983 PcdMaximumAsciiStringLength Ascii characters, not including the
984 Null-terminator, then ASSERT().
986 If String has no valid hexadecimal digits in the above format, then 0 is
987 stored at the location pointed to by Data.
988 If the number represented by String exceeds the range defined by UINT64, then
989 MAX_UINT64 is stored at the location pointed to by Data.
991 If EndPointer is not NULL, a pointer to the character that stopped the scan
992 is stored at the location pointed to by EndPointer. If String has no valid
993 hexadecimal digits right after the optional pad spaces, the value of String
994 is stored at the location pointed to by EndPointer.
996 @param String Pointer to a Null-terminated Ascii string.
997 @param EndPointer Pointer to character that stops scan.
998 @param Data Pointer to the converted value.
1000 @retval RETURN_SUCCESS Value is translated from String.
1001 @retval RETURN_INVALID_PARAMETER If String is NULL.
1003 If PcdMaximumAsciiStringLength is not zero,
1004 and String contains more than
1005 PcdMaximumAsciiStringLength Ascii
1006 characters, not including the
1008 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
1009 the range defined by UINT64.
1014 AsciiStrHexToUint64S (
1015 IN CONST CHAR8
*String
,
1016 OUT CHAR8
**EndPointer
, OPTIONAL
1021 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1024 [ATTENTION] This function is deprecated for security reason.
1026 Copies one Null-terminated Unicode string to another Null-terminated Unicode
1027 string and returns the new Unicode string.
1029 This function copies the contents of the Unicode string Source to the Unicode
1030 string Destination, and returns Destination. If Source and Destination
1031 overlap, then the results are undefined.
1033 If Destination is NULL, then ASSERT().
1034 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1035 If Source is NULL, then ASSERT().
1036 If Source is not aligned on a 16-bit boundary, then ASSERT().
1037 If Source and Destination overlap, then ASSERT().
1038 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1039 PcdMaximumUnicodeStringLength Unicode characters not including the
1040 Null-terminator, then ASSERT().
1042 @param Destination The pointer to a Null-terminated Unicode string.
1043 @param Source The pointer to a Null-terminated Unicode string.
1045 @return Destination.
1051 OUT CHAR16
*Destination
,
1052 IN CONST CHAR16
*Source
1057 [ATTENTION] This function is deprecated for security reason.
1059 Copies up to a specified length from one Null-terminated Unicode string to
1060 another Null-terminated Unicode string and returns the new Unicode string.
1062 This function copies the contents of the Unicode string Source to the Unicode
1063 string Destination, and returns Destination. At most, Length Unicode
1064 characters are copied from Source to Destination. If Length is 0, then
1065 Destination is returned unmodified. If Length is greater that the number of
1066 Unicode characters in Source, then Destination is padded with Null Unicode
1067 characters. If Source and Destination overlap, then the results are
1070 If Length > 0 and Destination is NULL, then ASSERT().
1071 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1072 If Length > 0 and Source is NULL, then ASSERT().
1073 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1074 If Source and Destination overlap, then ASSERT().
1075 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1076 PcdMaximumUnicodeStringLength, then ASSERT().
1077 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1078 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1081 @param Destination The pointer to a Null-terminated Unicode string.
1082 @param Source The pointer to a Null-terminated Unicode string.
1083 @param Length The maximum number of Unicode characters to copy.
1085 @return Destination.
1091 OUT CHAR16
*Destination
,
1092 IN CONST CHAR16
*Source
,
1095 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1098 Returns the length of a Null-terminated Unicode string.
1100 This function returns the number of Unicode characters in the Null-terminated
1101 Unicode string specified by String.
1103 If String is NULL, then ASSERT().
1104 If String is not aligned on a 16-bit boundary, then ASSERT().
1105 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1106 PcdMaximumUnicodeStringLength Unicode characters not including the
1107 Null-terminator, then ASSERT().
1109 @param String Pointer to a Null-terminated Unicode string.
1111 @return The length of String.
1117 IN CONST CHAR16
*String
1122 Returns the size of a Null-terminated Unicode string in bytes, including the
1125 This function returns the size, in bytes, of the Null-terminated Unicode string
1126 specified by String.
1128 If String is NULL, then ASSERT().
1129 If String is not aligned on a 16-bit boundary, then ASSERT().
1130 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1131 PcdMaximumUnicodeStringLength Unicode characters not including the
1132 Null-terminator, then ASSERT().
1134 @param String The pointer to a Null-terminated Unicode string.
1136 @return The size of String.
1142 IN CONST CHAR16
*String
1147 Compares two Null-terminated Unicode strings, and returns the difference
1148 between the first mismatched Unicode characters.
1150 This function compares the Null-terminated Unicode string FirstString to the
1151 Null-terminated Unicode string SecondString. If FirstString is identical to
1152 SecondString, then 0 is returned. Otherwise, the value returned is the first
1153 mismatched Unicode character in SecondString subtracted from the first
1154 mismatched Unicode character in FirstString.
1156 If FirstString is NULL, then ASSERT().
1157 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1158 If SecondString is NULL, then ASSERT().
1159 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1160 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1161 than PcdMaximumUnicodeStringLength Unicode characters not including the
1162 Null-terminator, then ASSERT().
1163 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1164 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1165 Null-terminator, then ASSERT().
1167 @param FirstString The pointer to a Null-terminated Unicode string.
1168 @param SecondString The pointer to a Null-terminated Unicode string.
1170 @retval 0 FirstString is identical to SecondString.
1171 @return others FirstString is not identical to SecondString.
1177 IN CONST CHAR16
*FirstString
,
1178 IN CONST CHAR16
*SecondString
1183 Compares up to a specified length the contents of two Null-terminated Unicode strings,
1184 and returns the difference between the first mismatched Unicode characters.
1186 This function compares the Null-terminated Unicode string FirstString to the
1187 Null-terminated Unicode string SecondString. At most, Length Unicode
1188 characters will be compared. If Length is 0, then 0 is returned. If
1189 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1190 value returned is the first mismatched Unicode character in SecondString
1191 subtracted from the first mismatched Unicode character in FirstString.
1193 If Length > 0 and FirstString is NULL, then ASSERT().
1194 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1195 If Length > 0 and SecondString is NULL, then ASSERT().
1196 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1197 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1198 PcdMaximumUnicodeStringLength, then ASSERT().
1199 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1200 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1202 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1203 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1206 @param FirstString The pointer to a Null-terminated Unicode string.
1207 @param SecondString The pointer to a Null-terminated Unicode string.
1208 @param Length The maximum number of Unicode characters to compare.
1210 @retval 0 FirstString is identical to SecondString.
1211 @return others FirstString is not identical to SecondString.
1217 IN CONST CHAR16
*FirstString
,
1218 IN CONST CHAR16
*SecondString
,
1223 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1226 [ATTENTION] This function is deprecated for security reason.
1228 Concatenates one Null-terminated Unicode string to another Null-terminated
1229 Unicode string, and returns the concatenated Unicode string.
1231 This function concatenates two Null-terminated Unicode strings. The contents
1232 of Null-terminated Unicode string Source are concatenated to the end of
1233 Null-terminated Unicode string Destination. The Null-terminated concatenated
1234 Unicode String is returned. If Source and Destination overlap, then the
1235 results are undefined.
1237 If Destination is NULL, then ASSERT().
1238 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1239 If Source is NULL, then ASSERT().
1240 If Source is not aligned on a 16-bit boundary, then ASSERT().
1241 If Source and Destination overlap, then ASSERT().
1242 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1243 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1244 Null-terminator, then ASSERT().
1245 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1246 PcdMaximumUnicodeStringLength Unicode characters, not including the
1247 Null-terminator, then ASSERT().
1248 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1249 and Source results in a Unicode string with more than
1250 PcdMaximumUnicodeStringLength Unicode characters, not including the
1251 Null-terminator, then ASSERT().
1253 @param Destination The pointer to a Null-terminated Unicode string.
1254 @param Source The pointer to a Null-terminated Unicode string.
1256 @return Destination.
1262 IN OUT CHAR16
*Destination
,
1263 IN CONST CHAR16
*Source
1268 [ATTENTION] This function is deprecated for security reason.
1270 Concatenates up to a specified length one Null-terminated Unicode to the end
1271 of another Null-terminated Unicode string, and returns the concatenated
1274 This function concatenates two Null-terminated Unicode strings. The contents
1275 of Null-terminated Unicode string Source are concatenated to the end of
1276 Null-terminated Unicode string Destination, and Destination is returned. At
1277 most, Length Unicode characters are concatenated from Source to the end of
1278 Destination, and Destination is always Null-terminated. If Length is 0, then
1279 Destination is returned unmodified. If Source and Destination overlap, then
1280 the results are undefined.
1282 If Destination is NULL, then ASSERT().
1283 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1284 If Length > 0 and Source is NULL, then ASSERT().
1285 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1286 If Source and Destination overlap, then ASSERT().
1287 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1288 PcdMaximumUnicodeStringLength, then ASSERT().
1289 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1290 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1291 Null-terminator, then ASSERT().
1292 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1293 PcdMaximumUnicodeStringLength Unicode characters, not including the
1294 Null-terminator, then ASSERT().
1295 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1296 and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength
1297 Unicode characters, not including the Null-terminator, then ASSERT().
1299 @param Destination The pointer to a Null-terminated Unicode string.
1300 @param Source The pointer to a Null-terminated Unicode string.
1301 @param Length The maximum number of Unicode characters to concatenate from
1304 @return Destination.
1310 IN OUT CHAR16
*Destination
,
1311 IN CONST CHAR16
*Source
,
1314 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1317 Returns the first occurrence of a Null-terminated Unicode sub-string
1318 in a Null-terminated Unicode string.
1320 This function scans the contents of the Null-terminated Unicode string
1321 specified by String and returns the first occurrence of SearchString.
1322 If SearchString is not found in String, then NULL is returned. If
1323 the length of SearchString is zero, then String is returned.
1325 If String is NULL, then ASSERT().
1326 If String is not aligned on a 16-bit boundary, then ASSERT().
1327 If SearchString is NULL, then ASSERT().
1328 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1330 If PcdMaximumUnicodeStringLength is not zero, and SearchString
1331 or String contains more than PcdMaximumUnicodeStringLength Unicode
1332 characters, not including the Null-terminator, then ASSERT().
1334 @param String The pointer to a Null-terminated Unicode string.
1335 @param SearchString The pointer to a Null-terminated Unicode string to search for.
1337 @retval NULL If the SearchString does not appear in String.
1338 @return others If there is a match.
1344 IN CONST CHAR16
*String
,
1345 IN CONST CHAR16
*SearchString
1349 Convert a Null-terminated Unicode decimal string to a value of
1352 This function returns a value of type UINTN by interpreting the contents
1353 of the Unicode string specified by String as a decimal number. The format
1354 of the input Unicode string String is:
1356 [spaces] [decimal digits].
1358 The valid decimal digit character is in the range [0-9]. The
1359 function will ignore the pad space, which includes spaces or
1360 tab characters, before [decimal digits]. The running zero in the
1361 beginning of [decimal digits] will be ignored. Then, the function
1362 stops at the first character that is a not a valid decimal character
1363 or a Null-terminator, whichever one comes first.
1365 If String is NULL, then ASSERT().
1366 If String is not aligned in a 16-bit boundary, then ASSERT().
1367 If String has only pad spaces, then 0 is returned.
1368 If String has no pad spaces or valid decimal digits,
1370 If the number represented by String overflows according
1371 to the range defined by UINTN, then MAX_UINTN is returned.
1373 If PcdMaximumUnicodeStringLength is not zero, and String contains
1374 more than PcdMaximumUnicodeStringLength Unicode characters not including
1375 the Null-terminator, then ASSERT().
1377 @param String The pointer to a Null-terminated Unicode string.
1379 @retval Value translated from String.
1385 IN CONST CHAR16
*String
1389 Convert a Null-terminated Unicode decimal string to a value of
1392 This function returns a value of type UINT64 by interpreting the contents
1393 of the Unicode string specified by String as a decimal number. The format
1394 of the input Unicode string String is:
1396 [spaces] [decimal digits].
1398 The valid decimal digit character is in the range [0-9]. The
1399 function will ignore the pad space, which includes spaces or
1400 tab characters, before [decimal digits]. The running zero in the
1401 beginning of [decimal digits] will be ignored. Then, the function
1402 stops at the first character that is a not a valid decimal character
1403 or a Null-terminator, whichever one comes first.
1405 If String is NULL, then ASSERT().
1406 If String is not aligned in a 16-bit boundary, then ASSERT().
1407 If String has only pad spaces, then 0 is returned.
1408 If String has no pad spaces or valid decimal digits,
1410 If the number represented by String overflows according
1411 to the range defined by UINT64, then MAX_UINT64 is returned.
1413 If PcdMaximumUnicodeStringLength is not zero, and String contains
1414 more than PcdMaximumUnicodeStringLength Unicode characters not including
1415 the Null-terminator, then ASSERT().
1417 @param String The pointer to a Null-terminated Unicode string.
1419 @retval Value translated from String.
1424 StrDecimalToUint64 (
1425 IN CONST CHAR16
*String
1430 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1432 This function returns a value of type UINTN by interpreting the contents
1433 of the Unicode string specified by String as a hexadecimal number.
1434 The format of the input Unicode string String is:
1436 [spaces][zeros][x][hexadecimal digits].
1438 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1439 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1440 If "x" appears in the input string, it must be prefixed with at least one 0.
1441 The function will ignore the pad space, which includes spaces or tab characters,
1442 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1443 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1444 first valid hexadecimal digit. Then, the function stops at the first character
1445 that is a not a valid hexadecimal character or NULL, whichever one comes first.
1447 If String is NULL, then ASSERT().
1448 If String is not aligned in a 16-bit boundary, then ASSERT().
1449 If String has only pad spaces, then zero is returned.
1450 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1451 then zero is returned.
1452 If the number represented by String overflows according to the range defined by
1453 UINTN, then MAX_UINTN is returned.
1455 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1456 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1459 @param String The pointer to a Null-terminated Unicode string.
1461 @retval Value translated from String.
1467 IN CONST CHAR16
*String
1472 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1474 This function returns a value of type UINT64 by interpreting the contents
1475 of the Unicode string specified by String as a hexadecimal number.
1476 The format of the input Unicode string String is
1478 [spaces][zeros][x][hexadecimal digits].
1480 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1481 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1482 If "x" appears in the input string, it must be prefixed with at least one 0.
1483 The function will ignore the pad space, which includes spaces or tab characters,
1484 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1485 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1486 first valid hexadecimal digit. Then, the function stops at the first character that is
1487 a not a valid hexadecimal character or NULL, whichever one comes first.
1489 If String is NULL, then ASSERT().
1490 If String is not aligned in a 16-bit boundary, then ASSERT().
1491 If String has only pad spaces, then zero is returned.
1492 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1493 then zero is returned.
1494 If the number represented by String overflows according to the range defined by
1495 UINT64, then MAX_UINT64 is returned.
1497 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1498 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1501 @param String The pointer to a Null-terminated Unicode string.
1503 @retval Value translated from String.
1509 IN CONST CHAR16
*String
1513 Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1515 This function outputs a value of type IPv6_ADDRESS and may output a value
1516 of type UINT8 by interpreting the contents of the Unicode string specified
1517 by String. The format of the input Unicode string String is as follows:
1521 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1522 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1523 memory address and high byte is stored in high memory address. P contains decimal
1524 digit characters in the range [0-9]. The running zero in the beginning of P will
1525 be ignored. /P is optional.
1527 When /P is not in the String, the function stops at the first character that is
1528 not a valid hexadecimal digit character after eight X's are converted.
1530 When /P is in the String, the function stops at the first character that is not
1531 a valid decimal digit character after P is converted.
1533 "::" can be used to compress one or more groups of X when X contains only 0.
1534 The "::" can only appear once in the String.
1536 If String is NULL, then ASSERT().
1538 If Address is NULL, then ASSERT().
1540 If String is not aligned in a 16-bit boundary, then ASSERT().
1542 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1543 PcdMaximumUnicodeStringLength Unicode characters, not including the
1544 Null-terminator, then ASSERT().
1546 If EndPointer is not NULL and Address is translated from String, a pointer
1547 to the character that stopped the scan is stored at the location pointed to
1550 @param String Pointer to a Null-terminated Unicode string.
1551 @param EndPointer Pointer to character that stops scan.
1552 @param Address Pointer to the converted IPv6 address.
1553 @param PrefixLength Pointer to the converted IPv6 address prefix
1554 length. MAX_UINT8 is returned when /P is
1557 @retval RETURN_SUCCESS Address is translated from String.
1558 @retval RETURN_INVALID_PARAMETER If String is NULL.
1560 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1562 If String contains "::" and number of X
1564 If P starts with character that is not a
1565 valid decimal digit character.
1566 If the decimal number converted from P
1573 IN CONST CHAR16
*String
,
1574 OUT CHAR16
**EndPointer
, OPTIONAL
1575 OUT IPv6_ADDRESS
*Address
,
1576 OUT UINT8
*PrefixLength OPTIONAL
1580 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1582 This function outputs a value of type IPv4_ADDRESS and may output a value
1583 of type UINT8 by interpreting the contents of the Unicode string specified
1584 by String. The format of the input Unicode string String is as follows:
1588 D and P are decimal digit characters in the range [0-9]. The running zero in
1589 the beginning of D and P will be ignored. /P is optional.
1591 When /P is not in the String, the function stops at the first character that is
1592 not a valid decimal digit character after four D's are converted.
1594 When /P is in the String, the function stops at the first character that is not
1595 a valid decimal digit character after P is converted.
1597 If String is NULL, then ASSERT().
1599 If Address is NULL, then ASSERT().
1601 If String is not aligned in a 16-bit boundary, then ASSERT().
1603 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1604 PcdMaximumUnicodeStringLength Unicode characters, not including the
1605 Null-terminator, then ASSERT().
1607 If EndPointer is not NULL and Address is translated from String, a pointer
1608 to the character that stopped the scan is stored at the location pointed to
1611 @param String Pointer to a Null-terminated Unicode string.
1612 @param EndPointer Pointer to character that stops scan.
1613 @param Address Pointer to the converted IPv4 address.
1614 @param PrefixLength Pointer to the converted IPv4 address prefix
1615 length. MAX_UINT8 is returned when /P is
1618 @retval RETURN_SUCCESS Address is translated from String.
1619 @retval RETURN_INVALID_PARAMETER If String is NULL.
1621 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1622 If any decimal number converted from D
1624 If the decimal number converted from P
1631 IN CONST CHAR16
*String
,
1632 OUT CHAR16
**EndPointer
, OPTIONAL
1633 OUT IPv4_ADDRESS
*Address
,
1634 OUT UINT8
*PrefixLength OPTIONAL
1637 #define GUID_STRING_LENGTH 36
1640 Convert a Null-terminated Unicode GUID string to a value of type
1643 This function outputs a GUID value by interpreting the contents of
1644 the Unicode string specified by String. The format of the input
1645 Unicode string String consists of 36 characters, as follows:
1647 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1649 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1650 [A-F], with each pair representing a single byte hexadecimal value.
1652 The mapping between String and the EFI_GUID structure is as follows:
1670 If String is NULL, then ASSERT().
1671 If Guid is NULL, then ASSERT().
1672 If String is not aligned in a 16-bit boundary, then ASSERT().
1674 @param String Pointer to a Null-terminated Unicode string.
1675 @param Guid Pointer to the converted GUID.
1677 @retval RETURN_SUCCESS Guid is translated from String.
1678 @retval RETURN_INVALID_PARAMETER If String is NULL.
1680 @retval RETURN_UNSUPPORTED If String is not as the above format.
1686 IN CONST CHAR16
*String
,
1691 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1693 This function outputs a byte array by interpreting the contents of
1694 the Unicode string specified by String in hexadecimal format. The format of
1695 the input Unicode string String is:
1699 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1700 The function decodes every two hexadecimal digit characters as one byte. The
1701 decoding stops after Length of characters and outputs Buffer containing
1704 If String is not aligned in a 16-bit boundary, then ASSERT().
1706 If String is NULL, then ASSERT().
1708 If Buffer is NULL, then ASSERT().
1710 If Length is not multiple of 2, then ASSERT().
1712 If PcdMaximumUnicodeStringLength is not zero and Length is greater than
1713 PcdMaximumUnicodeStringLength, then ASSERT().
1715 If MaxBufferSize is less than (Length / 2), then ASSERT().
1717 @param String Pointer to a Null-terminated Unicode string.
1718 @param Length The number of Unicode characters to decode.
1719 @param Buffer Pointer to the converted bytes array.
1720 @param MaxBufferSize The maximum size of Buffer.
1722 @retval RETURN_SUCCESS Buffer is translated from String.
1723 @retval RETURN_INVALID_PARAMETER If String is NULL.
1725 If Length is not multiple of 2.
1726 If PcdMaximumUnicodeStringLength is not zero,
1727 and Length is greater than
1728 PcdMaximumUnicodeStringLength.
1729 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1730 a character that is not valid hexadecimal
1731 digit characters, or a Null-terminator.
1732 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1737 IN CONST CHAR16
*String
,
1740 IN UINTN MaxBufferSize
1743 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1746 [ATTENTION] This function is deprecated for security reason.
1748 Convert a Null-terminated Unicode string to a Null-terminated
1749 ASCII string and returns the ASCII string.
1751 This function converts the content of the Unicode string Source
1752 to the ASCII string Destination by copying the lower 8 bits of
1753 each Unicode character. It returns Destination.
1755 The caller is responsible to make sure Destination points to a buffer with size
1756 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1758 If any Unicode characters in Source contain non-zero value in
1759 the upper 8 bits, then ASSERT().
1761 If Destination is NULL, then ASSERT().
1762 If Source is NULL, then ASSERT().
1763 If Source is not aligned on a 16-bit boundary, then ASSERT().
1764 If Source and Destination overlap, then ASSERT().
1766 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1767 more than PcdMaximumUnicodeStringLength Unicode characters not including
1768 the Null-terminator, then ASSERT().
1770 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1771 than PcdMaximumAsciiStringLength Unicode characters not including the
1772 Null-terminator, then ASSERT().
1774 @param Source The pointer to a Null-terminated Unicode string.
1775 @param Destination The pointer to a Null-terminated ASCII string.
1777 @return Destination.
1782 UnicodeStrToAsciiStr (
1783 IN CONST CHAR16
*Source
,
1784 OUT CHAR8
*Destination
1787 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1790 Convert a Null-terminated Unicode string to a Null-terminated
1793 This function is similar to AsciiStrCpyS.
1795 This function converts the content of the Unicode string Source
1796 to the ASCII string Destination by copying the lower 8 bits of
1797 each Unicode character. The function terminates the ASCII string
1798 Destination by appending a Null-terminator character at the end.
1800 The caller is responsible to make sure Destination points to a buffer with size
1801 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1803 If any Unicode characters in Source contain non-zero value in
1804 the upper 8 bits, then ASSERT().
1806 If Source is not aligned on a 16-bit boundary, then ASSERT().
1807 If an error would be returned, then the function will also ASSERT().
1809 If an error is returned, then the Destination is unmodified.
1811 @param Source The pointer to a Null-terminated Unicode string.
1812 @param Destination The pointer to a Null-terminated ASCII string.
1813 @param DestMax The maximum number of Destination Ascii
1814 char, including terminating null char.
1816 @retval RETURN_SUCCESS String is converted.
1817 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1818 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1820 If PcdMaximumAsciiStringLength is not zero,
1821 and DestMax is greater than
1822 PcdMaximumAsciiStringLength.
1823 If PcdMaximumUnicodeStringLength is not zero,
1824 and DestMax is greater than
1825 PcdMaximumUnicodeStringLength.
1827 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1832 UnicodeStrToAsciiStrS (
1833 IN CONST CHAR16
*Source
,
1834 OUT CHAR8
*Destination
,
1839 Convert not more than Length successive characters from a Null-terminated
1840 Unicode string to a Null-terminated Ascii string. If no null char is copied
1841 from Source, then Destination[Length] is always set to null.
1843 This function converts not more than Length successive characters from the
1844 Unicode string Source to the Ascii string Destination by copying the lower 8
1845 bits of each Unicode character. The function terminates the Ascii string
1846 Destination by appending a Null-terminator character at the end.
1848 The caller is responsible to make sure Destination points to a buffer with size
1849 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1851 If any Unicode characters in Source contain non-zero value in the upper 8
1852 bits, then ASSERT().
1853 If Source is not aligned on a 16-bit boundary, then ASSERT().
1854 If an error would be returned, then the function will also ASSERT().
1856 If an error is returned, then the Destination is unmodified.
1858 @param Source The pointer to a Null-terminated Unicode string.
1859 @param Length The maximum number of Unicode characters to
1861 @param Destination The pointer to a Null-terminated Ascii string.
1862 @param DestMax The maximum number of Destination Ascii
1863 char, including terminating null char.
1864 @param DestinationLength The number of Unicode characters converted.
1866 @retval RETURN_SUCCESS String is converted.
1867 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1869 If DestinationLength is NULL.
1870 If PcdMaximumAsciiStringLength is not zero,
1871 and Length or DestMax is greater than
1872 PcdMaximumAsciiStringLength.
1873 If PcdMaximumUnicodeStringLength is not
1874 zero, and Length or DestMax is greater than
1875 PcdMaximumUnicodeStringLength.
1877 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1878 MIN(StrLen(Source), Length).
1879 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1884 UnicodeStrnToAsciiStrS (
1885 IN CONST CHAR16
*Source
,
1887 OUT CHAR8
*Destination
,
1889 OUT UINTN
*DestinationLength
1892 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1895 [ATTENTION] This function is deprecated for security reason.
1897 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1898 string and returns the new ASCII string.
1900 This function copies the contents of the ASCII string Source to the ASCII
1901 string Destination, and returns Destination. If Source and Destination
1902 overlap, then the results are undefined.
1904 If Destination is NULL, then ASSERT().
1905 If Source is NULL, then ASSERT().
1906 If Source and Destination overlap, then ASSERT().
1907 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1908 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1911 @param Destination The pointer to a Null-terminated ASCII string.
1912 @param Source The pointer to a Null-terminated ASCII string.
1920 OUT CHAR8
*Destination
,
1921 IN CONST CHAR8
*Source
1926 [ATTENTION] This function is deprecated for security reason.
1928 Copies up to a specified length one Null-terminated ASCII string to another
1929 Null-terminated ASCII string and returns the new ASCII string.
1931 This function copies the contents of the ASCII string Source to the ASCII
1932 string Destination, and returns Destination. At most, Length ASCII characters
1933 are copied from Source to Destination. If Length is 0, then Destination is
1934 returned unmodified. If Length is greater that the number of ASCII characters
1935 in Source, then Destination is padded with Null ASCII characters. If Source
1936 and Destination overlap, then the results are undefined.
1938 If Destination is NULL, then ASSERT().
1939 If Source is NULL, then ASSERT().
1940 If Source and Destination overlap, then ASSERT().
1941 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1942 PcdMaximumAsciiStringLength, then ASSERT().
1943 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1944 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1947 @param Destination The pointer to a Null-terminated ASCII string.
1948 @param Source The pointer to a Null-terminated ASCII string.
1949 @param Length The maximum number of ASCII characters to copy.
1957 OUT CHAR8
*Destination
,
1958 IN CONST CHAR8
*Source
,
1961 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1964 Returns the length of a Null-terminated ASCII string.
1966 This function returns the number of ASCII characters in the Null-terminated
1967 ASCII string specified by String.
1969 If Length > 0 and Destination is NULL, then ASSERT().
1970 If Length > 0 and Source is NULL, then ASSERT().
1971 If PcdMaximumAsciiStringLength is not zero and String contains more than
1972 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1975 @param String The pointer to a Null-terminated ASCII string.
1977 @return The length of String.
1983 IN CONST CHAR8
*String
1988 Returns the size of a Null-terminated ASCII string in bytes, including the
1991 This function returns the size, in bytes, of the Null-terminated ASCII string
1992 specified by String.
1994 If String is NULL, then ASSERT().
1995 If PcdMaximumAsciiStringLength is not zero and String contains more than
1996 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1999 @param String The pointer to a Null-terminated ASCII string.
2001 @return The size of String.
2007 IN CONST CHAR8
*String
2012 Compares two Null-terminated ASCII strings, and returns the difference
2013 between the first mismatched ASCII characters.
2015 This function compares the Null-terminated ASCII string FirstString to the
2016 Null-terminated ASCII string SecondString. If FirstString is identical to
2017 SecondString, then 0 is returned. Otherwise, the value returned is the first
2018 mismatched ASCII character in SecondString subtracted from the first
2019 mismatched ASCII character in FirstString.
2021 If FirstString is NULL, then ASSERT().
2022 If SecondString is NULL, then ASSERT().
2023 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
2024 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2026 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2027 than PcdMaximumAsciiStringLength ASCII characters not including the
2028 Null-terminator, then ASSERT().
2030 @param FirstString The pointer to a Null-terminated ASCII string.
2031 @param SecondString The pointer to a Null-terminated ASCII string.
2033 @retval ==0 FirstString is identical to SecondString.
2034 @retval !=0 FirstString is not identical to SecondString.
2040 IN CONST CHAR8
*FirstString
,
2041 IN CONST CHAR8
*SecondString
2046 Performs a case insensitive comparison of two Null-terminated ASCII strings,
2047 and returns the difference between the first mismatched ASCII characters.
2049 This function performs a case insensitive comparison of the Null-terminated
2050 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
2051 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
2052 value returned is the first mismatched lower case ASCII character in
2053 SecondString subtracted from the first mismatched lower case ASCII character
2056 If FirstString is NULL, then ASSERT().
2057 If SecondString is NULL, then ASSERT().
2058 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
2059 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2061 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2062 than PcdMaximumAsciiStringLength ASCII characters not including the
2063 Null-terminator, then ASSERT().
2065 @param FirstString The pointer to a Null-terminated ASCII string.
2066 @param SecondString The pointer to a Null-terminated ASCII string.
2068 @retval ==0 FirstString is identical to SecondString using case insensitive
2070 @retval !=0 FirstString is not identical to SecondString using case
2071 insensitive comparisons.
2077 IN CONST CHAR8
*FirstString
,
2078 IN CONST CHAR8
*SecondString
2083 Compares two Null-terminated ASCII strings with maximum lengths, and returns
2084 the difference between the first mismatched ASCII characters.
2086 This function compares the Null-terminated ASCII string FirstString to the
2087 Null-terminated ASCII string SecondString. At most, Length ASCII characters
2088 will be compared. If Length is 0, then 0 is returned. If FirstString is
2089 identical to SecondString, then 0 is returned. Otherwise, the value returned
2090 is the first mismatched ASCII character in SecondString subtracted from the
2091 first mismatched ASCII character in FirstString.
2093 If Length > 0 and FirstString is NULL, then ASSERT().
2094 If Length > 0 and SecondString is NULL, then ASSERT().
2095 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
2096 PcdMaximumAsciiStringLength, then ASSERT().
2097 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
2098 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2100 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
2101 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2104 @param FirstString The pointer to a Null-terminated ASCII string.
2105 @param SecondString The pointer to a Null-terminated ASCII string.
2106 @param Length The maximum number of ASCII characters for compare.
2108 @retval ==0 FirstString is identical to SecondString.
2109 @retval !=0 FirstString is not identical to SecondString.
2115 IN CONST CHAR8
*FirstString
,
2116 IN CONST CHAR8
*SecondString
,
2121 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2124 [ATTENTION] This function is deprecated for security reason.
2126 Concatenates one Null-terminated ASCII string to another Null-terminated
2127 ASCII string, and returns the concatenated ASCII string.
2129 This function concatenates two Null-terminated ASCII strings. The contents of
2130 Null-terminated ASCII string Source are concatenated to the end of Null-
2131 terminated ASCII string Destination. The Null-terminated concatenated ASCII
2134 If Destination is NULL, then ASSERT().
2135 If Source is NULL, then ASSERT().
2136 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
2137 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2139 If PcdMaximumAsciiStringLength is not zero and Source contains more than
2140 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2142 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
2143 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
2144 ASCII characters, then ASSERT().
2146 @param Destination The pointer to a Null-terminated ASCII string.
2147 @param Source The pointer to a Null-terminated ASCII string.
2155 IN OUT CHAR8
*Destination
,
2156 IN CONST CHAR8
*Source
2161 [ATTENTION] This function is deprecated for security reason.
2163 Concatenates up to a specified length one Null-terminated ASCII string to
2164 the end of another Null-terminated ASCII string, and returns the
2165 concatenated ASCII string.
2167 This function concatenates two Null-terminated ASCII strings. The contents
2168 of Null-terminated ASCII string Source are concatenated to the end of Null-
2169 terminated ASCII string Destination, and Destination is returned. At most,
2170 Length ASCII characters are concatenated from Source to the end of
2171 Destination, and Destination is always Null-terminated. If Length is 0, then
2172 Destination is returned unmodified. If Source and Destination overlap, then
2173 the results are undefined.
2175 If Length > 0 and Destination is NULL, then ASSERT().
2176 If Length > 0 and Source is NULL, then ASSERT().
2177 If Source and Destination overlap, then ASSERT().
2178 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
2179 PcdMaximumAsciiStringLength, then ASSERT().
2180 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
2181 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2183 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2184 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2186 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
2187 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
2188 ASCII characters, not including the Null-terminator, then ASSERT().
2190 @param Destination The pointer to a Null-terminated ASCII string.
2191 @param Source The pointer to a Null-terminated ASCII string.
2192 @param Length The maximum number of ASCII characters to concatenate from
2201 IN OUT CHAR8
*Destination
,
2202 IN CONST CHAR8
*Source
,
2205 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
2208 Returns the first occurrence of a Null-terminated ASCII sub-string
2209 in a Null-terminated ASCII string.
2211 This function scans the contents of the ASCII string specified by String
2212 and returns the first occurrence of SearchString. If SearchString is not
2213 found in String, then NULL is returned. If the length of SearchString is zero,
2214 then String is returned.
2216 If String is NULL, then ASSERT().
2217 If SearchString is NULL, then ASSERT().
2219 If PcdMaximumAsciiStringLength is not zero, and SearchString or
2220 String contains more than PcdMaximumAsciiStringLength Unicode characters
2221 not including the Null-terminator, then ASSERT().
2223 @param String The pointer to a Null-terminated ASCII string.
2224 @param SearchString The pointer to a Null-terminated ASCII string to search for.
2226 @retval NULL If the SearchString does not appear in String.
2227 @retval others If there is a match return the first occurrence of SearchingString.
2228 If the length of SearchString is zero,return String.
2234 IN CONST CHAR8
*String
,
2235 IN CONST CHAR8
*SearchString
2240 Convert a Null-terminated ASCII decimal string to a value of type
2243 This function returns a value of type UINTN by interpreting the contents
2244 of the ASCII string String as a decimal number. The format of the input
2245 ASCII string String is:
2247 [spaces] [decimal digits].
2249 The valid decimal digit character is in the range [0-9]. The function will
2250 ignore the pad space, which includes spaces or tab characters, before the digits.
2251 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2252 function stops at the first character that is a not a valid decimal character or
2253 Null-terminator, whichever on comes first.
2255 If String has only pad spaces, then 0 is returned.
2256 If String has no pad spaces or valid decimal digits, then 0 is returned.
2257 If the number represented by String overflows according to the range defined by
2258 UINTN, then MAX_UINTN is returned.
2259 If String is NULL, then ASSERT().
2260 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2261 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2264 @param String The pointer to a Null-terminated ASCII string.
2266 @retval The value translated from String.
2271 AsciiStrDecimalToUintn (
2272 IN CONST CHAR8
*String
2277 Convert a Null-terminated ASCII decimal string to a value of type
2280 This function returns a value of type UINT64 by interpreting the contents
2281 of the ASCII string String as a decimal number. The format of the input
2282 ASCII string String is:
2284 [spaces] [decimal digits].
2286 The valid decimal digit character is in the range [0-9]. The function will
2287 ignore the pad space, which includes spaces or tab characters, before the digits.
2288 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2289 function stops at the first character that is a not a valid decimal character or
2290 Null-terminator, whichever on comes first.
2292 If String has only pad spaces, then 0 is returned.
2293 If String has no pad spaces or valid decimal digits, then 0 is returned.
2294 If the number represented by String overflows according to the range defined by
2295 UINT64, then MAX_UINT64 is returned.
2296 If String is NULL, then ASSERT().
2297 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2298 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2301 @param String The pointer to a Null-terminated ASCII string.
2303 @retval Value translated from String.
2308 AsciiStrDecimalToUint64 (
2309 IN CONST CHAR8
*String
2314 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
2316 This function returns a value of type UINTN by interpreting the contents of
2317 the ASCII string String as a hexadecimal number. The format of the input ASCII
2320 [spaces][zeros][x][hexadecimal digits].
2322 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2323 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2324 appears in the input string, it must be prefixed with at least one 0. The function
2325 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2326 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2327 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2328 digit. Then, the function stops at the first character that is a not a valid
2329 hexadecimal character or Null-terminator, whichever on comes first.
2331 If String has only pad spaces, then 0 is returned.
2332 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2335 If the number represented by String overflows according to the range defined by UINTN,
2336 then MAX_UINTN is returned.
2337 If String is NULL, then ASSERT().
2338 If PcdMaximumAsciiStringLength is not zero,
2339 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2340 the Null-terminator, then ASSERT().
2342 @param String The pointer to a Null-terminated ASCII string.
2344 @retval Value translated from String.
2349 AsciiStrHexToUintn (
2350 IN CONST CHAR8
*String
2355 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
2357 This function returns a value of type UINT64 by interpreting the contents of
2358 the ASCII string String as a hexadecimal number. The format of the input ASCII
2361 [spaces][zeros][x][hexadecimal digits].
2363 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2364 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2365 appears in the input string, it must be prefixed with at least one 0. The function
2366 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2367 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2368 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2369 digit. Then, the function stops at the first character that is a not a valid
2370 hexadecimal character or Null-terminator, whichever on comes first.
2372 If String has only pad spaces, then 0 is returned.
2373 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2376 If the number represented by String overflows according to the range defined by UINT64,
2377 then MAX_UINT64 is returned.
2378 If String is NULL, then ASSERT().
2379 If PcdMaximumAsciiStringLength is not zero,
2380 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2381 the Null-terminator, then ASSERT().
2383 @param String The pointer to a Null-terminated ASCII string.
2385 @retval Value translated from String.
2390 AsciiStrHexToUint64 (
2391 IN CONST CHAR8
*String
2395 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
2397 This function outputs a value of type IPv6_ADDRESS and may output a value
2398 of type UINT8 by interpreting the contents of the ASCII string specified
2399 by String. The format of the input ASCII string String is as follows:
2403 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
2404 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
2405 memory address and high byte is stored in high memory address. P contains decimal
2406 digit characters in the range [0-9]. The running zero in the beginning of P will
2407 be ignored. /P is optional.
2409 When /P is not in the String, the function stops at the first character that is
2410 not a valid hexadecimal digit character after eight X's are converted.
2412 When /P is in the String, the function stops at the first character that is not
2413 a valid decimal digit character after P is converted.
2415 "::" can be used to compress one or more groups of X when X contains only 0.
2416 The "::" can only appear once in the String.
2418 If String is NULL, then ASSERT().
2420 If Address is NULL, then ASSERT().
2422 If EndPointer is not NULL and Address is translated from String, a pointer
2423 to the character that stopped the scan is stored at the location pointed to
2426 @param String Pointer to a Null-terminated ASCII string.
2427 @param EndPointer Pointer to character that stops scan.
2428 @param Address Pointer to the converted IPv6 address.
2429 @param PrefixLength Pointer to the converted IPv6 address prefix
2430 length. MAX_UINT8 is returned when /P is
2433 @retval RETURN_SUCCESS Address is translated from String.
2434 @retval RETURN_INVALID_PARAMETER If String is NULL.
2436 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
2438 If String contains "::" and number of X
2440 If P starts with character that is not a
2441 valid decimal digit character.
2442 If the decimal number converted from P
2448 AsciiStrToIpv6Address (
2449 IN CONST CHAR8
*String
,
2450 OUT CHAR8
**EndPointer
, OPTIONAL
2451 OUT IPv6_ADDRESS
*Address
,
2452 OUT UINT8
*PrefixLength OPTIONAL
2456 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
2458 This function outputs a value of type IPv4_ADDRESS and may output a value
2459 of type UINT8 by interpreting the contents of the ASCII string specified
2460 by String. The format of the input ASCII string String is as follows:
2464 D and P are decimal digit characters in the range [0-9]. The running zero in
2465 the beginning of D and P will be ignored. /P is optional.
2467 When /P is not in the String, the function stops at the first character that is
2468 not a valid decimal digit character after four D's are converted.
2470 When /P is in the String, the function stops at the first character that is not
2471 a valid decimal digit character after P is converted.
2473 If String is NULL, then ASSERT().
2475 If Address is NULL, then ASSERT().
2477 If EndPointer is not NULL and Address is translated from String, a pointer
2478 to the character that stopped the scan is stored at the location pointed to
2481 @param String Pointer to a Null-terminated ASCII string.
2482 @param EndPointer Pointer to character that stops scan.
2483 @param Address Pointer to the converted IPv4 address.
2484 @param PrefixLength Pointer to the converted IPv4 address prefix
2485 length. MAX_UINT8 is returned when /P is
2488 @retval RETURN_SUCCESS Address is translated from String.
2489 @retval RETURN_INVALID_PARAMETER If String is NULL.
2491 @retval RETURN_UNSUPPORTED If String is not in the correct format.
2492 If any decimal number converted from D
2494 If the decimal number converted from P
2500 AsciiStrToIpv4Address (
2501 IN CONST CHAR8
*String
,
2502 OUT CHAR8
**EndPointer
, OPTIONAL
2503 OUT IPv4_ADDRESS
*Address
,
2504 OUT UINT8
*PrefixLength OPTIONAL
2508 Convert a Null-terminated ASCII GUID string to a value of type
2511 This function outputs a GUID value by interpreting the contents of
2512 the ASCII string specified by String. The format of the input
2513 ASCII string String consists of 36 characters, as follows:
2515 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
2517 The pairs aa - pp are two characters in the range [0-9], [a-f] and
2518 [A-F], with each pair representing a single byte hexadecimal value.
2520 The mapping between String and the EFI_GUID structure is as follows:
2538 If String is NULL, then ASSERT().
2539 If Guid is NULL, then ASSERT().
2541 @param String Pointer to a Null-terminated ASCII string.
2542 @param Guid Pointer to the converted GUID.
2544 @retval RETURN_SUCCESS Guid is translated from String.
2545 @retval RETURN_INVALID_PARAMETER If String is NULL.
2547 @retval RETURN_UNSUPPORTED If String is not as the above format.
2553 IN CONST CHAR8
*String
,
2558 Convert a Null-terminated ASCII hexadecimal string to a byte array.
2560 This function outputs a byte array by interpreting the contents of
2561 the ASCII string specified by String in hexadecimal format. The format of
2562 the input ASCII string String is:
2566 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
2567 The function decodes every two hexadecimal digit characters as one byte. The
2568 decoding stops after Length of characters and outputs Buffer containing
2571 If String is NULL, then ASSERT().
2573 If Buffer is NULL, then ASSERT().
2575 If Length is not multiple of 2, then ASSERT().
2577 If PcdMaximumAsciiStringLength is not zero and Length is greater than
2578 PcdMaximumAsciiStringLength, then ASSERT().
2580 If MaxBufferSize is less than (Length / 2), then ASSERT().
2582 @param String Pointer to a Null-terminated ASCII string.
2583 @param Length The number of ASCII characters to decode.
2584 @param Buffer Pointer to the converted bytes array.
2585 @param MaxBufferSize The maximum size of Buffer.
2587 @retval RETURN_SUCCESS Buffer is translated from String.
2588 @retval RETURN_INVALID_PARAMETER If String is NULL.
2590 If Length is not multiple of 2.
2591 If PcdMaximumAsciiStringLength is not zero,
2592 and Length is greater than
2593 PcdMaximumAsciiStringLength.
2594 @retval RETURN_UNSUPPORTED If Length of characters from String contain
2595 a character that is not valid hexadecimal
2596 digit characters, or a Null-terminator.
2597 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
2601 AsciiStrHexToBytes (
2602 IN CONST CHAR8
*String
,
2605 IN UINTN MaxBufferSize
2608 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2611 [ATTENTION] This function is deprecated for security reason.
2613 Convert one Null-terminated ASCII string to a Null-terminated
2614 Unicode string and returns the Unicode string.
2616 This function converts the contents of the ASCII string Source to the Unicode
2617 string Destination, and returns Destination. The function terminates the
2618 Unicode string Destination by appending a Null-terminator character at the end.
2619 The caller is responsible to make sure Destination points to a buffer with size
2620 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2622 If Destination is NULL, then ASSERT().
2623 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2624 If Source is NULL, then ASSERT().
2625 If Source and Destination overlap, then ASSERT().
2626 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2627 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2629 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
2630 PcdMaximumUnicodeStringLength ASCII characters not including the
2631 Null-terminator, then ASSERT().
2633 @param Source The pointer to a Null-terminated ASCII string.
2634 @param Destination The pointer to a Null-terminated Unicode string.
2636 @return Destination.
2641 AsciiStrToUnicodeStr (
2642 IN CONST CHAR8
*Source
,
2643 OUT CHAR16
*Destination
2646 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
2649 Convert one Null-terminated ASCII string to a Null-terminated
2652 This function is similar to StrCpyS.
2654 This function converts the contents of the ASCII string Source to the Unicode
2655 string Destination. The function terminates the Unicode string Destination by
2656 appending a Null-terminator character at the end.
2658 The caller is responsible to make sure Destination points to a buffer with size
2659 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2661 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2662 If an error would be returned, then the function will also ASSERT().
2664 If an error is returned, then the Destination is unmodified.
2666 @param Source The pointer to a Null-terminated ASCII string.
2667 @param Destination The pointer to a Null-terminated Unicode string.
2668 @param DestMax The maximum number of Destination Unicode
2669 char, including terminating null char.
2671 @retval RETURN_SUCCESS String is converted.
2672 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2673 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2675 If PcdMaximumUnicodeStringLength is not zero,
2676 and DestMax is greater than
2677 PcdMaximumUnicodeStringLength.
2678 If PcdMaximumAsciiStringLength is not zero,
2679 and DestMax is greater than
2680 PcdMaximumAsciiStringLength.
2682 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2687 AsciiStrToUnicodeStrS (
2688 IN CONST CHAR8
*Source
,
2689 OUT CHAR16
*Destination
,
2694 Convert not more than Length successive characters from a Null-terminated
2695 Ascii string to a Null-terminated Unicode string. If no null char is copied
2696 from Source, then Destination[Length] is always set to null.
2698 This function converts not more than Length successive characters from the
2699 Ascii string Source to the Unicode string Destination. The function
2700 terminates the Unicode string Destination by appending a Null-terminator
2701 character at the end.
2703 The caller is responsible to make sure Destination points to a buffer with
2704 size not smaller than
2705 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2707 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2708 If an error would be returned, then the function will also ASSERT().
2710 If an error is returned, then Destination and DestinationLength are
2713 @param Source The pointer to a Null-terminated Ascii string.
2714 @param Length The maximum number of Ascii characters to convert.
2715 @param Destination The pointer to a Null-terminated Unicode string.
2716 @param DestMax The maximum number of Destination Unicode char,
2717 including terminating null char.
2718 @param DestinationLength The number of Ascii characters converted.
2720 @retval RETURN_SUCCESS String is converted.
2721 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2723 If DestinationLength is NULL.
2724 If PcdMaximumUnicodeStringLength is not
2725 zero, and Length or DestMax is greater than
2726 PcdMaximumUnicodeStringLength.
2727 If PcdMaximumAsciiStringLength is not zero,
2728 and Length or DestMax is greater than
2729 PcdMaximumAsciiStringLength.
2731 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2732 MIN(AsciiStrLen(Source), Length).
2733 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2738 AsciiStrnToUnicodeStrS (
2739 IN CONST CHAR8
*Source
,
2741 OUT CHAR16
*Destination
,
2743 OUT UINTN
*DestinationLength
2747 Convert a Unicode character to upper case only if
2748 it maps to a valid small-case ASCII character.
2750 This internal function only deal with Unicode character
2751 which maps to a valid small-case ASCII character, i.e.
2752 L'a' to L'z'. For other Unicode character, the input character
2753 is returned directly.
2755 @param Char The character to convert.
2757 @retval LowerCharacter If the Char is with range L'a' to L'z'.
2758 @retval Unchanged Otherwise.
2768 Converts a lowercase Ascii character to upper one.
2770 If Chr is lowercase Ascii character, then converts it to upper one.
2772 If Value >= 0xA0, then ASSERT().
2773 If (Value & 0x0F) >= 0x0A, then ASSERT().
2775 @param Chr one Ascii character
2777 @return The uppercase value of Ascii character
2787 Convert binary data to a Base64 encoded ascii string based on RFC4648.
2789 Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
2790 The Ascii string is produced by converting the data string specified by Source and SourceLength.
2792 @param Source Input UINT8 data
2793 @param SourceLength Number of UINT8 bytes of data
2794 @param Destination Pointer to output string buffer
2795 @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed.
2796 Caller is responsible for passing in buffer of DestinationSize
2798 @retval RETURN_SUCCESS When ascii buffer is filled in.
2799 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
2800 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
2801 @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1.
2802 @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize.
2808 IN CONST UINT8
*Source
,
2809 IN UINTN SourceLength
,
2810 OUT CHAR8
*Destination OPTIONAL
,
2811 IN OUT UINTN
*DestinationSize
2815 Decode Base64 ASCII encoded data to 8-bit binary representation, based on
2818 Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648.
2820 Whitespace is ignored at all positions:
2821 - 0x09 ('\t') horizontal tab
2822 - 0x0A ('\n') new line
2823 - 0x0B ('\v') vertical tab
2824 - 0x0C ('\f') form feed
2825 - 0x0D ('\r') carriage return
2828 The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated
2829 and enforced at the end of the Base64 ASCII encoded data, and only there.
2831 Other characters outside of the encoding alphabet cause the function to
2832 reject the Base64 ASCII encoded data.
2834 @param[in] Source Array of CHAR8 elements containing the Base64
2835 ASCII encoding. May be NULL if SourceSize is
2838 @param[in] SourceSize Number of CHAR8 elements in Source.
2840 @param[out] Destination Array of UINT8 elements receiving the decoded
2841 8-bit binary representation. Allocated by the
2842 caller. May be NULL if DestinationSize is
2843 zero on input. If NULL, decoding is
2844 performed, but the 8-bit binary
2845 representation is not stored. If non-NULL and
2846 the function returns an error, the contents
2847 of Destination are indeterminate.
2849 @param[in,out] DestinationSize On input, the number of UINT8 elements that
2850 the caller allocated for Destination. On
2851 output, if the function returns
2852 RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL,
2853 the number of UINT8 elements that are
2854 required for decoding the Base64 ASCII
2855 representation. If the function returns a
2856 value different from both RETURN_SUCCESS and
2857 RETURN_BUFFER_TOO_SMALL, then DestinationSize
2858 is indeterminate on output.
2860 @retval RETURN_SUCCESS SourceSize CHAR8 elements at Source have
2861 been decoded to on-output DestinationSize
2862 UINT8 elements at Destination. Note that
2863 RETURN_SUCCESS covers the case when
2864 DestinationSize is zero on input, and
2865 Source decodes to zero bytes (due to
2866 containing at most ignored whitespace).
2868 @retval RETURN_BUFFER_TOO_SMALL The input value of DestinationSize is not
2869 large enough for decoding SourceSize CHAR8
2870 elements at Source. The required number of
2871 UINT8 elements has been stored to
2874 @retval RETURN_INVALID_PARAMETER DestinationSize is NULL.
2876 @retval RETURN_INVALID_PARAMETER Source is NULL, but SourceSize is not zero.
2878 @retval RETURN_INVALID_PARAMETER Destination is NULL, but DestinationSize is
2881 @retval RETURN_INVALID_PARAMETER Source is non-NULL, and (Source +
2882 SourceSize) would wrap around MAX_ADDRESS.
2884 @retval RETURN_INVALID_PARAMETER Destination is non-NULL, and (Destination +
2885 DestinationSize) would wrap around
2886 MAX_ADDRESS, as specified on input.
2888 @retval RETURN_INVALID_PARAMETER None of Source and Destination are NULL,
2889 and CHAR8[SourceSize] at Source overlaps
2890 UINT8[DestinationSize] at Destination, as
2893 @retval RETURN_INVALID_PARAMETER Invalid CHAR8 element encountered in
2899 IN CONST CHAR8
*Source OPTIONAL
,
2900 IN UINTN SourceSize
,
2901 OUT UINT8
*Destination OPTIONAL
,
2902 IN OUT UINTN
*DestinationSize
2906 Converts an 8-bit value to an 8-bit BCD value.
2908 Converts the 8-bit value specified by Value to BCD. The BCD value is
2911 If Value >= 100, then ASSERT().
2913 @param Value The 8-bit value to convert to BCD. Range 0..99.
2915 @return The BCD value.
2926 Converts an 8-bit BCD value to an 8-bit value.
2928 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2931 If Value >= 0xA0, then ASSERT().
2932 If (Value & 0x0F) >= 0x0A, then ASSERT().
2934 @param Value The 8-bit BCD value to convert to an 8-bit value.
2936 @return The 8-bit value is returned.
2946 // File Path Manipulation Functions
2950 Removes the last directory or file entry in a path.
2952 @param[in, out] Path The pointer to the path to modify.
2954 @retval FALSE Nothing was found to remove.
2955 @retval TRUE A directory or file was removed.
2964 Function to clean up paths.
2965 - Single periods in the path are removed.
2966 - Double periods in the path are removed along with a single parent directory.
2967 - Forward slashes L'/' are converted to backward slashes L'\'.
2969 This will be done inline and the existing buffer may be larger than required
2972 @param[in] Path The pointer to the string containing the path.
2974 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2978 PathCleanUpDirectories(
2983 // Linked List Functions and Macros
2987 Initializes the head node of a doubly linked list that is declared as a
2988 global variable in a module.
2990 Initializes the forward and backward links of a new linked list. After
2991 initializing a linked list with this macro, the other linked list functions
2992 may be used to add and remove nodes from the linked list. This macro results
2993 in smaller executables by initializing the linked list in the data section,
2994 instead if calling the InitializeListHead() function to perform the
2995 equivalent operation.
2997 @param ListHead The head note of a list to initialize.
3000 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
3003 Iterates over each node in a doubly linked list using each node's forward link.
3005 @param Entry A pointer to a list node used as a loop cursor during iteration
3006 @param ListHead The head node of the doubly linked list
3009 #define BASE_LIST_FOR_EACH(Entry, ListHead) \
3010 for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)
3013 Iterates over each node in a doubly linked list using each node's forward link
3014 with safety against node removal.
3016 This macro uses NextEntry to temporarily store the next list node so the node
3017 pointed to by Entry may be deleted in the current loop iteration step and
3018 iteration can continue from the node pointed to by NextEntry.
3020 @param Entry A pointer to a list node used as a loop cursor during iteration
3021 @param NextEntry A pointer to a list node used to temporarily store the next node
3022 @param ListHead The head node of the doubly linked list
3025 #define BASE_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \
3026 for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
3027 Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
3030 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
3033 If FirstEntry is NULL, then ASSERT().
3034 If FirstEntry->ForwardLink is NULL, then ASSERT().
3035 If FirstEntry->BackLink is NULL, then ASSERT().
3036 If SecondEntry is NULL, then ASSERT();
3037 If PcdMaximumLinkedListLength is not zero, and List contains more than
3038 PcdMaximumLinkedListLength nodes, then ASSERT().
3040 @param FirstEntry A pointer to a node in a linked list.
3041 @param SecondEntry A pointer to the node to locate.
3043 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.
3044 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,
3045 or FirstEntry is invalid.
3051 IN CONST LIST_ENTRY
*FirstEntry
,
3052 IN CONST LIST_ENTRY
*SecondEntry
3057 Initializes the head node of a doubly linked list, and returns the pointer to
3058 the head node of the doubly linked list.
3060 Initializes the forward and backward links of a new linked list. After
3061 initializing a linked list with this function, the other linked list
3062 functions may be used to add and remove nodes from the linked list. It is up
3063 to the caller of this function to allocate the memory for ListHead.
3065 If ListHead is NULL, then ASSERT().
3067 @param ListHead A pointer to the head node of a new doubly linked list.
3074 InitializeListHead (
3075 IN OUT LIST_ENTRY
*ListHead
3080 Adds a node to the beginning of a doubly linked list, and returns the pointer
3081 to the head node of the doubly linked list.
3083 Adds the node Entry at the beginning of the doubly linked list denoted by
3084 ListHead, and returns ListHead.
3086 If ListHead is NULL, then ASSERT().
3087 If Entry is NULL, then ASSERT().
3088 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3089 InitializeListHead(), then ASSERT().
3090 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
3091 of nodes in ListHead, including the ListHead node, is greater than or
3092 equal to PcdMaximumLinkedListLength, then ASSERT().
3094 @param ListHead A pointer to the head node of a doubly linked list.
3095 @param Entry A pointer to a node that is to be inserted at the beginning
3096 of a doubly linked list.
3104 IN OUT LIST_ENTRY
*ListHead
,
3105 IN OUT LIST_ENTRY
*Entry
3110 Adds a node to the end of a doubly linked list, and returns the pointer to
3111 the head node of the doubly linked list.
3113 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
3114 and returns ListHead.
3116 If ListHead is NULL, then ASSERT().
3117 If Entry is NULL, then ASSERT().
3118 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3119 InitializeListHead(), then ASSERT().
3120 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
3121 of nodes in ListHead, including the ListHead node, is greater than or
3122 equal to PcdMaximumLinkedListLength, then ASSERT().
3124 @param ListHead A pointer to the head node of a doubly linked list.
3125 @param Entry A pointer to a node that is to be added at the end of the
3134 IN OUT LIST_ENTRY
*ListHead
,
3135 IN OUT LIST_ENTRY
*Entry
3140 Retrieves the first node of a doubly linked list.
3142 Returns the first node of a doubly linked list. List must have been
3143 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3144 If List is empty, then List is returned.
3146 If List is NULL, then ASSERT().
3147 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3148 InitializeListHead(), then ASSERT().
3149 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3150 in List, including the List node, is greater than or equal to
3151 PcdMaximumLinkedListLength, then ASSERT().
3153 @param List A pointer to the head node of a doubly linked list.
3155 @return The first node of a doubly linked list.
3156 @retval List The list is empty.
3162 IN CONST LIST_ENTRY
*List
3167 Retrieves the next node of a doubly linked list.
3169 Returns the node of a doubly linked list that follows Node.
3170 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3171 or InitializeListHead(). If List is empty, then List is returned.
3173 If List is NULL, then ASSERT().
3174 If Node is NULL, then ASSERT().
3175 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3176 InitializeListHead(), then ASSERT().
3177 If PcdMaximumLinkedListLength is not zero, and List contains more than
3178 PcdMaximumLinkedListLength nodes, then ASSERT().
3179 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3181 @param List A pointer to the head node of a doubly linked list.
3182 @param Node A pointer to a node in the doubly linked list.
3184 @return The pointer to the next node if one exists. Otherwise List is returned.
3190 IN CONST LIST_ENTRY
*List
,
3191 IN CONST LIST_ENTRY
*Node
3196 Retrieves the previous node of a doubly linked list.
3198 Returns the node of a doubly linked list that precedes Node.
3199 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3200 or InitializeListHead(). If List is empty, then List is returned.
3202 If List is NULL, then ASSERT().
3203 If Node is NULL, then ASSERT().
3204 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3205 InitializeListHead(), then ASSERT().
3206 If PcdMaximumLinkedListLength is not zero, and List contains more than
3207 PcdMaximumLinkedListLength nodes, then ASSERT().
3208 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3210 @param List A pointer to the head node of a doubly linked list.
3211 @param Node A pointer to a node in the doubly linked list.
3213 @return The pointer to the previous node if one exists. Otherwise List is returned.
3219 IN CONST LIST_ENTRY
*List
,
3220 IN CONST LIST_ENTRY
*Node
3225 Checks to see if a doubly linked list is empty or not.
3227 Checks to see if the doubly linked list is empty. If the linked list contains
3228 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
3230 If ListHead is NULL, then ASSERT().
3231 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3232 InitializeListHead(), then ASSERT().
3233 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3234 in List, including the List node, is greater than or equal to
3235 PcdMaximumLinkedListLength, then ASSERT().
3237 @param ListHead A pointer to the head node of a doubly linked list.
3239 @retval TRUE The linked list is empty.
3240 @retval FALSE The linked list is not empty.
3246 IN CONST LIST_ENTRY
*ListHead
3251 Determines if a node in a doubly linked list is the head node of a the same
3252 doubly linked list. This function is typically used to terminate a loop that
3253 traverses all the nodes in a doubly linked list starting with the head node.
3255 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
3256 nodes in the doubly linked list specified by List. List must have been
3257 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3259 If List is NULL, then ASSERT().
3260 If Node is NULL, then ASSERT().
3261 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
3263 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3264 in List, including the List node, is greater than or equal to
3265 PcdMaximumLinkedListLength, then ASSERT().
3266 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
3267 to List, then ASSERT().
3269 @param List A pointer to the head node of a doubly linked list.
3270 @param Node A pointer to a node in the doubly linked list.
3272 @retval TRUE Node is the head of the doubly-linked list pointed by List.
3273 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
3279 IN CONST LIST_ENTRY
*List
,
3280 IN CONST LIST_ENTRY
*Node
3285 Determines if a node the last node in a doubly linked list.
3287 Returns TRUE if Node is the last node in the doubly linked list specified by
3288 List. Otherwise, FALSE is returned. List must have been initialized with
3289 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3291 If List is NULL, then ASSERT().
3292 If Node is NULL, then ASSERT().
3293 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3294 InitializeListHead(), then ASSERT().
3295 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3296 in List, including the List node, is greater than or equal to
3297 PcdMaximumLinkedListLength, then ASSERT().
3298 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3300 @param List A pointer to the head node of a doubly linked list.
3301 @param Node A pointer to a node in the doubly linked list.
3303 @retval TRUE Node is the last node in the linked list.
3304 @retval FALSE Node is not the last node in the linked list.
3310 IN CONST LIST_ENTRY
*List
,
3311 IN CONST LIST_ENTRY
*Node
3316 Swaps the location of two nodes in a doubly linked list, and returns the
3317 first node after the swap.
3319 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
3320 Otherwise, the location of the FirstEntry node is swapped with the location
3321 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
3322 same double linked list as FirstEntry and that double linked list must have
3323 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3324 SecondEntry is returned after the nodes are swapped.
3326 If FirstEntry is NULL, then ASSERT().
3327 If SecondEntry is NULL, then ASSERT().
3328 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
3329 same linked list, then ASSERT().
3330 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3331 linked list containing the FirstEntry and SecondEntry nodes, including
3332 the FirstEntry and SecondEntry nodes, is greater than or equal to
3333 PcdMaximumLinkedListLength, then ASSERT().
3335 @param FirstEntry A pointer to a node in a linked list.
3336 @param SecondEntry A pointer to another node in the same linked list.
3338 @return SecondEntry.
3344 IN OUT LIST_ENTRY
*FirstEntry
,
3345 IN OUT LIST_ENTRY
*SecondEntry
3350 Removes a node from a doubly linked list, and returns the node that follows
3353 Removes the node Entry from a doubly linked list. It is up to the caller of
3354 this function to release the memory used by this node if that is required. On
3355 exit, the node following Entry in the doubly linked list is returned. If
3356 Entry is the only node in the linked list, then the head node of the linked
3359 If Entry is NULL, then ASSERT().
3360 If Entry is the head node of an empty list, then ASSERT().
3361 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3362 linked list containing Entry, including the Entry node, is greater than
3363 or equal to PcdMaximumLinkedListLength, then ASSERT().
3365 @param Entry A pointer to a node in a linked list.
3373 IN CONST LIST_ENTRY
*Entry
3381 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
3382 with zeros. The shifted value is returned.
3384 This function shifts the 64-bit value Operand to the left by Count bits. The
3385 low Count bits are set to zero. The shifted value is returned.
3387 If Count is greater than 63, then ASSERT().
3389 @param Operand The 64-bit operand to shift left.
3390 @param Count The number of bits to shift left.
3392 @return Operand << Count.
3404 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
3405 filled with zeros. The shifted value is returned.
3407 This function shifts the 64-bit value Operand to the right by Count bits. The
3408 high Count bits are set to zero. The shifted value is returned.
3410 If Count is greater than 63, then ASSERT().
3412 @param Operand The 64-bit operand to shift right.
3413 @param Count The number of bits to shift right.
3415 @return Operand >> Count
3427 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
3428 with original integer's bit 63. The shifted value is returned.
3430 This function shifts the 64-bit value Operand to the right by Count bits. The
3431 high Count bits are set to bit 63 of Operand. The shifted value is returned.
3433 If Count is greater than 63, then ASSERT().
3435 @param Operand The 64-bit operand to shift right.
3436 @param Count The number of bits to shift right.
3438 @return Operand >> Count
3450 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
3451 with the high bits that were rotated.
3453 This function rotates the 32-bit value Operand to the left by Count bits. The
3454 low Count bits are fill with the high Count bits of Operand. The rotated
3457 If Count is greater than 31, then ASSERT().
3459 @param Operand The 32-bit operand to rotate left.
3460 @param Count The number of bits to rotate left.
3462 @return Operand << Count
3474 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
3475 with the low bits that were rotated.
3477 This function rotates the 32-bit value Operand to the right by Count bits.
3478 The high Count bits are fill with the low Count bits of Operand. The rotated
3481 If Count is greater than 31, then ASSERT().
3483 @param Operand The 32-bit operand to rotate right.
3484 @param Count The number of bits to rotate right.
3486 @return Operand >> Count
3498 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3499 with the high bits that were rotated.
3501 This function rotates the 64-bit value Operand to the left by Count bits. The
3502 low Count bits are fill with the high Count bits of Operand. The rotated
3505 If Count is greater than 63, then ASSERT().
3507 @param Operand The 64-bit operand to rotate left.
3508 @param Count The number of bits to rotate left.
3510 @return Operand << Count
3522 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3523 with the high low bits that were rotated.
3525 This function rotates the 64-bit value Operand to the right by Count bits.
3526 The high Count bits are fill with the low Count bits of Operand. The rotated
3529 If Count is greater than 63, then ASSERT().
3531 @param Operand The 64-bit operand to rotate right.
3532 @param Count The number of bits to rotate right.
3534 @return Operand >> Count
3546 Returns the bit position of the lowest bit set in a 32-bit value.
3548 This function computes the bit position of the lowest bit set in the 32-bit
3549 value specified by Operand. If Operand is zero, then -1 is returned.
3550 Otherwise, a value between 0 and 31 is returned.
3552 @param Operand The 32-bit operand to evaluate.
3554 @retval 0..31 The lowest bit set in Operand was found.
3555 @retval -1 Operand is zero.
3566 Returns the bit position of the lowest bit set in a 64-bit value.
3568 This function computes the bit position of the lowest bit set in the 64-bit
3569 value specified by Operand. If Operand is zero, then -1 is returned.
3570 Otherwise, a value between 0 and 63 is returned.
3572 @param Operand The 64-bit operand to evaluate.
3574 @retval 0..63 The lowest bit set in Operand was found.
3575 @retval -1 Operand is zero.
3587 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3590 This function computes the bit position of the highest bit set in the 32-bit
3591 value specified by Operand. If Operand is zero, then -1 is returned.
3592 Otherwise, a value between 0 and 31 is returned.
3594 @param Operand The 32-bit operand to evaluate.
3596 @retval 0..31 Position of the highest bit set in Operand if found.
3597 @retval -1 Operand is zero.
3608 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3611 This function computes the bit position of the highest bit set in the 64-bit
3612 value specified by Operand. If Operand is zero, then -1 is returned.
3613 Otherwise, a value between 0 and 63 is returned.
3615 @param Operand The 64-bit operand to evaluate.
3617 @retval 0..63 Position of the highest bit set in Operand if found.
3618 @retval -1 Operand is zero.
3629 Returns the value of the highest bit set in a 32-bit value. Equivalent to
3632 This function computes the value of the highest bit set in the 32-bit value
3633 specified by Operand. If Operand is zero, then zero is returned.
3635 @param Operand The 32-bit operand to evaluate.
3637 @return 1 << HighBitSet32(Operand)
3638 @retval 0 Operand is zero.
3649 Returns the value of the highest bit set in a 64-bit value. Equivalent to
3652 This function computes the value of the highest bit set in the 64-bit value
3653 specified by Operand. If Operand is zero, then zero is returned.
3655 @param Operand The 64-bit operand to evaluate.
3657 @return 1 << HighBitSet64(Operand)
3658 @retval 0 Operand is zero.
3669 Switches the endianness of a 16-bit integer.
3671 This function swaps the bytes in a 16-bit unsigned value to switch the value
3672 from little endian to big endian or vice versa. The byte swapped value is
3675 @param Value A 16-bit unsigned value.
3677 @return The byte swapped Value.
3688 Switches the endianness of a 32-bit integer.
3690 This function swaps the bytes in a 32-bit unsigned value to switch the value
3691 from little endian to big endian or vice versa. The byte swapped value is
3694 @param Value A 32-bit unsigned value.
3696 @return The byte swapped Value.
3707 Switches the endianness of a 64-bit integer.
3709 This function swaps the bytes in a 64-bit unsigned value to switch the value
3710 from little endian to big endian or vice versa. The byte swapped value is
3713 @param Value A 64-bit unsigned value.
3715 @return The byte swapped Value.
3726 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3727 generates a 64-bit unsigned result.
3729 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3730 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3731 bit unsigned result is returned.
3733 @param Multiplicand A 64-bit unsigned value.
3734 @param Multiplier A 32-bit unsigned value.
3736 @return Multiplicand * Multiplier
3742 IN UINT64 Multiplicand
,
3743 IN UINT32 Multiplier
3748 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3749 generates a 64-bit unsigned result.
3751 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3752 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3753 bit unsigned result is returned.
3755 @param Multiplicand A 64-bit unsigned value.
3756 @param Multiplier A 64-bit unsigned value.
3758 @return Multiplicand * Multiplier.
3764 IN UINT64 Multiplicand
,
3765 IN UINT64 Multiplier
3770 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3771 64-bit signed result.
3773 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3774 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3775 signed result is returned.
3777 @param Multiplicand A 64-bit signed value.
3778 @param Multiplier A 64-bit signed value.
3780 @return Multiplicand * Multiplier
3786 IN INT64 Multiplicand
,
3792 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3793 a 64-bit unsigned result.
3795 This function divides the 64-bit unsigned value Dividend by the 32-bit
3796 unsigned value Divisor and generates a 64-bit unsigned quotient. This
3797 function returns the 64-bit unsigned quotient.
3799 If Divisor is 0, then ASSERT().
3801 @param Dividend A 64-bit unsigned value.
3802 @param Divisor A 32-bit unsigned value.
3804 @return Dividend / Divisor.
3816 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3817 a 32-bit unsigned remainder.
3819 This function divides the 64-bit unsigned value Dividend by the 32-bit
3820 unsigned value Divisor and generates a 32-bit remainder. This function
3821 returns the 32-bit unsigned remainder.
3823 If Divisor is 0, then ASSERT().
3825 @param Dividend A 64-bit unsigned value.
3826 @param Divisor A 32-bit unsigned value.
3828 @return Dividend % Divisor.
3840 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3841 a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3843 This function divides the 64-bit unsigned value Dividend by the 32-bit
3844 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3845 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3846 This function returns the 64-bit unsigned quotient.
3848 If Divisor is 0, then ASSERT().
3850 @param Dividend A 64-bit unsigned value.
3851 @param Divisor A 32-bit unsigned value.
3852 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3853 optional and may be NULL.
3855 @return Dividend / Divisor.
3860 DivU64x32Remainder (
3863 OUT UINT32
*Remainder OPTIONAL
3868 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3869 a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3871 This function divides the 64-bit unsigned value Dividend by the 64-bit
3872 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3873 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3874 This function returns the 64-bit unsigned quotient.
3876 If Divisor is 0, then ASSERT().
3878 @param Dividend A 64-bit unsigned value.
3879 @param Divisor A 64-bit unsigned value.
3880 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3881 optional and may be NULL.
3883 @return Dividend / Divisor.
3888 DivU64x64Remainder (
3891 OUT UINT64
*Remainder OPTIONAL
3896 Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3897 64-bit signed result and a optional 64-bit signed remainder.
3899 This function divides the 64-bit signed value Dividend by the 64-bit signed
3900 value Divisor and generates a 64-bit signed quotient. If Remainder is not
3901 NULL, then the 64-bit signed remainder is returned in Remainder. This
3902 function returns the 64-bit signed quotient.
3904 It is the caller's responsibility to not call this function with a Divisor of 0.
3905 If Divisor is 0, then the quotient and remainder should be assumed to be
3906 the largest negative integer.
3908 If Divisor is 0, then ASSERT().
3910 @param Dividend A 64-bit signed value.
3911 @param Divisor A 64-bit signed value.
3912 @param Remainder A pointer to a 64-bit signed value. This parameter is
3913 optional and may be NULL.
3915 @return Dividend / Divisor.
3920 DivS64x64Remainder (
3923 OUT INT64
*Remainder OPTIONAL
3928 Reads a 16-bit value from memory that may be unaligned.
3930 This function returns the 16-bit value pointed to by Buffer. The function
3931 guarantees that the read operation does not produce an alignment fault.
3933 If the Buffer is NULL, then ASSERT().
3935 @param Buffer The pointer to a 16-bit value that may be unaligned.
3937 @return The 16-bit value read from Buffer.
3943 IN CONST UINT16
*Buffer
3948 Writes a 16-bit value to memory that may be unaligned.
3950 This function writes the 16-bit value specified by Value to Buffer. Value is
3951 returned. The function guarantees that the write operation does not produce
3954 If the Buffer is NULL, then ASSERT().
3956 @param Buffer The pointer to a 16-bit value that may be unaligned.
3957 @param Value 16-bit value to write to Buffer.
3959 @return The 16-bit value to write to Buffer.
3971 Reads a 24-bit value from memory that may be unaligned.
3973 This function returns the 24-bit value pointed to by Buffer. The function
3974 guarantees that the read operation does not produce an alignment fault.
3976 If the Buffer is NULL, then ASSERT().
3978 @param Buffer The pointer to a 24-bit value that may be unaligned.
3980 @return The 24-bit value read from Buffer.
3986 IN CONST UINT32
*Buffer
3991 Writes a 24-bit value to memory that may be unaligned.
3993 This function writes the 24-bit value specified by Value to Buffer. Value is
3994 returned. The function guarantees that the write operation does not produce
3997 If the Buffer is NULL, then ASSERT().
3999 @param Buffer The pointer to a 24-bit value that may be unaligned.
4000 @param Value 24-bit value to write to Buffer.
4002 @return The 24-bit value to write to Buffer.
4014 Reads a 32-bit value from memory that may be unaligned.
4016 This function returns the 32-bit value pointed to by Buffer. The function
4017 guarantees that the read operation does not produce an alignment fault.
4019 If the Buffer is NULL, then ASSERT().
4021 @param Buffer The pointer to a 32-bit value that may be unaligned.
4023 @return The 32-bit value read from Buffer.
4029 IN CONST UINT32
*Buffer
4034 Writes a 32-bit value to memory that may be unaligned.
4036 This function writes the 32-bit value specified by Value to Buffer. Value is
4037 returned. The function guarantees that the write operation does not produce
4040 If the Buffer is NULL, then ASSERT().
4042 @param Buffer The pointer to a 32-bit value that may be unaligned.
4043 @param Value 32-bit value to write to Buffer.
4045 @return The 32-bit value to write to Buffer.
4057 Reads a 64-bit value from memory that may be unaligned.
4059 This function returns the 64-bit value pointed to by Buffer. The function
4060 guarantees that the read operation does not produce an alignment fault.
4062 If the Buffer is NULL, then ASSERT().
4064 @param Buffer The pointer to a 64-bit value that may be unaligned.
4066 @return The 64-bit value read from Buffer.
4072 IN CONST UINT64
*Buffer
4077 Writes a 64-bit value to memory that may be unaligned.
4079 This function writes the 64-bit value specified by Value to Buffer. Value is
4080 returned. The function guarantees that the write operation does not produce
4083 If the Buffer is NULL, then ASSERT().
4085 @param Buffer The pointer to a 64-bit value that may be unaligned.
4086 @param Value 64-bit value to write to Buffer.
4088 @return The 64-bit value to write to Buffer.
4100 // Bit Field Functions
4104 Returns a bit field from an 8-bit value.
4106 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4108 If 8-bit operations are not supported, then ASSERT().
4109 If StartBit is greater than 7, then ASSERT().
4110 If EndBit is greater than 7, then ASSERT().
4111 If EndBit is less than StartBit, then ASSERT().
4113 @param Operand Operand on which to perform the bitfield operation.
4114 @param StartBit The ordinal of the least significant bit in the bit field.
4116 @param EndBit The ordinal of the most significant bit in the bit field.
4119 @return The bit field read.
4132 Writes a bit field to an 8-bit value, and returns the result.
4134 Writes Value to the bit field specified by the StartBit and the EndBit in
4135 Operand. All other bits in Operand are preserved. The new 8-bit value is
4138 If 8-bit operations are not supported, then ASSERT().
4139 If StartBit is greater than 7, then ASSERT().
4140 If EndBit is greater than 7, then ASSERT().
4141 If EndBit is less than StartBit, then ASSERT().
4142 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4144 @param Operand Operand on which to perform the bitfield operation.
4145 @param StartBit The ordinal of the least significant bit in the bit field.
4147 @param EndBit The ordinal of the most significant bit in the bit field.
4149 @param Value New value of the bit field.
4151 @return The new 8-bit value.
4165 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
4168 Performs a bitwise OR between the bit field specified by StartBit
4169 and EndBit in Operand and the value specified by OrData. All other bits in
4170 Operand are preserved. The new 8-bit value is returned.
4172 If 8-bit operations are not supported, then ASSERT().
4173 If StartBit is greater than 7, then ASSERT().
4174 If EndBit is greater than 7, then ASSERT().
4175 If EndBit is less than StartBit, then ASSERT().
4176 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4178 @param Operand Operand on which to perform the bitfield operation.
4179 @param StartBit The ordinal of the least significant bit in the bit field.
4181 @param EndBit The ordinal of the most significant bit in the bit field.
4183 @param OrData The value to OR with the read value from the value
4185 @return The new 8-bit value.
4199 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
4202 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4203 in Operand and the value specified by AndData. All other bits in Operand are
4204 preserved. The new 8-bit value is returned.
4206 If 8-bit operations are not supported, then ASSERT().
4207 If StartBit is greater than 7, then ASSERT().
4208 If EndBit is greater than 7, then ASSERT().
4209 If EndBit is less than StartBit, then ASSERT().
4210 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4212 @param Operand Operand on which to perform the bitfield operation.
4213 @param StartBit The ordinal of the least significant bit in the bit field.
4215 @param EndBit The ordinal of the most significant bit in the bit field.
4217 @param AndData The value to AND with the read value from the value.
4219 @return The new 8-bit value.
4233 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
4234 bitwise OR, and returns the result.
4236 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4237 in Operand and the value specified by AndData, followed by a bitwise
4238 OR with value specified by OrData. All other bits in Operand are
4239 preserved. The new 8-bit value is returned.
4241 If 8-bit operations are not supported, then ASSERT().
4242 If StartBit is greater than 7, then ASSERT().
4243 If EndBit is greater than 7, then ASSERT().
4244 If EndBit is less than StartBit, then ASSERT().
4245 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4246 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4248 @param Operand Operand on which to perform the bitfield operation.
4249 @param StartBit The ordinal of the least significant bit in the bit field.
4251 @param EndBit The ordinal of the most significant bit in the bit field.
4253 @param AndData The value to AND with the read value from the value.
4254 @param OrData The value to OR with the result of the AND operation.
4256 @return The new 8-bit value.
4261 BitFieldAndThenOr8 (
4271 Returns a bit field from a 16-bit value.
4273 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4275 If 16-bit operations are not supported, then ASSERT().
4276 If StartBit is greater than 15, then ASSERT().
4277 If EndBit is greater than 15, then ASSERT().
4278 If EndBit is less than StartBit, then ASSERT().
4280 @param Operand Operand on which to perform the bitfield operation.
4281 @param StartBit The ordinal of the least significant bit in the bit field.
4283 @param EndBit The ordinal of the most significant bit in the bit field.
4286 @return The bit field read.
4299 Writes a bit field to a 16-bit value, and returns the result.
4301 Writes Value to the bit field specified by the StartBit and the EndBit in
4302 Operand. All other bits in Operand are preserved. The new 16-bit value is
4305 If 16-bit operations are not supported, then ASSERT().
4306 If StartBit is greater than 15, then ASSERT().
4307 If EndBit is greater than 15, then ASSERT().
4308 If EndBit is less than StartBit, then ASSERT().
4309 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4311 @param Operand Operand on which to perform the bitfield operation.
4312 @param StartBit The ordinal of the least significant bit in the bit field.
4314 @param EndBit The ordinal of the most significant bit in the bit field.
4316 @param Value New value of the bit field.
4318 @return The new 16-bit value.
4332 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
4335 Performs a bitwise OR between the bit field specified by StartBit
4336 and EndBit in Operand and the value specified by OrData. All other bits in
4337 Operand are preserved. The new 16-bit value is returned.
4339 If 16-bit operations are not supported, then ASSERT().
4340 If StartBit is greater than 15, then ASSERT().
4341 If EndBit is greater than 15, then ASSERT().
4342 If EndBit is less than StartBit, then ASSERT().
4343 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4345 @param Operand Operand on which to perform the bitfield operation.
4346 @param StartBit The ordinal of the least significant bit in the bit field.
4348 @param EndBit The ordinal of the most significant bit in the bit field.
4350 @param OrData The value to OR with the read value from the value
4352 @return The new 16-bit value.
4366 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
4369 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4370 in Operand and the value specified by AndData. All other bits in Operand are
4371 preserved. The new 16-bit value is returned.
4373 If 16-bit operations are not supported, then ASSERT().
4374 If StartBit is greater than 15, then ASSERT().
4375 If EndBit is greater than 15, then ASSERT().
4376 If EndBit is less than StartBit, then ASSERT().
4377 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4379 @param Operand Operand on which to perform the bitfield operation.
4380 @param StartBit The ordinal of the least significant bit in the bit field.
4382 @param EndBit The ordinal of the most significant bit in the bit field.
4384 @param AndData The value to AND with the read value from the value
4386 @return The new 16-bit value.
4400 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
4401 bitwise OR, and returns the result.
4403 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4404 in Operand and the value specified by AndData, followed by a bitwise
4405 OR with value specified by OrData. All other bits in Operand are
4406 preserved. The new 16-bit value is returned.
4408 If 16-bit operations are not supported, then ASSERT().
4409 If StartBit is greater than 15, then ASSERT().
4410 If EndBit is greater than 15, then ASSERT().
4411 If EndBit is less than StartBit, then ASSERT().
4412 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4413 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4415 @param Operand Operand on which to perform the bitfield operation.
4416 @param StartBit The ordinal of the least significant bit in the bit field.
4418 @param EndBit The ordinal of the most significant bit in the bit field.
4420 @param AndData The value to AND with the read value from the value.
4421 @param OrData The value to OR with the result of the AND operation.
4423 @return The new 16-bit value.
4428 BitFieldAndThenOr16 (
4438 Returns a bit field from a 32-bit value.
4440 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4442 If 32-bit operations are not supported, then ASSERT().
4443 If StartBit is greater than 31, then ASSERT().
4444 If EndBit is greater than 31, then ASSERT().
4445 If EndBit is less than StartBit, then ASSERT().
4447 @param Operand Operand on which to perform the bitfield operation.
4448 @param StartBit The ordinal of the least significant bit in the bit field.
4450 @param EndBit The ordinal of the most significant bit in the bit field.
4453 @return The bit field read.
4466 Writes a bit field to a 32-bit value, and returns the result.
4468 Writes Value to the bit field specified by the StartBit and the EndBit in
4469 Operand. All other bits in Operand are preserved. The new 32-bit value is
4472 If 32-bit operations are not supported, then ASSERT().
4473 If StartBit is greater than 31, then ASSERT().
4474 If EndBit is greater than 31, then ASSERT().
4475 If EndBit is less than StartBit, then ASSERT().
4476 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4478 @param Operand Operand on which to perform the bitfield operation.
4479 @param StartBit The ordinal of the least significant bit in the bit field.
4481 @param EndBit The ordinal of the most significant bit in the bit field.
4483 @param Value New value of the bit field.
4485 @return The new 32-bit value.
4499 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
4502 Performs a bitwise OR between the bit field specified by StartBit
4503 and EndBit in Operand and the value specified by OrData. All other bits in
4504 Operand are preserved. The new 32-bit value is returned.
4506 If 32-bit operations are not supported, then ASSERT().
4507 If StartBit is greater than 31, then ASSERT().
4508 If EndBit is greater than 31, then ASSERT().
4509 If EndBit is less than StartBit, then ASSERT().
4510 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4512 @param Operand Operand on which to perform the bitfield operation.
4513 @param StartBit The ordinal of the least significant bit in the bit field.
4515 @param EndBit The ordinal of the most significant bit in the bit field.
4517 @param OrData The value to OR with the read value from the value.
4519 @return The new 32-bit value.
4533 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
4536 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4537 in Operand and the value specified by AndData. All other bits in Operand are
4538 preserved. The new 32-bit value is returned.
4540 If 32-bit operations are not supported, then ASSERT().
4541 If StartBit is greater than 31, then ASSERT().
4542 If EndBit is greater than 31, then ASSERT().
4543 If EndBit is less than StartBit, then ASSERT().
4544 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4546 @param Operand Operand on which to perform the bitfield operation.
4547 @param StartBit The ordinal of the least significant bit in the bit field.
4549 @param EndBit The ordinal of the most significant bit in the bit field.
4551 @param AndData The value to AND with the read value from the value
4553 @return The new 32-bit value.
4567 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4568 bitwise OR, and returns the result.
4570 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4571 in Operand and the value specified by AndData, followed by a bitwise
4572 OR with value specified by OrData. All other bits in Operand are
4573 preserved. The new 32-bit value is returned.
4575 If 32-bit operations are not supported, then ASSERT().
4576 If StartBit is greater than 31, then ASSERT().
4577 If EndBit is greater than 31, then ASSERT().
4578 If EndBit is less than StartBit, then ASSERT().
4579 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4580 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4582 @param Operand Operand on which to perform the bitfield operation.
4583 @param StartBit The ordinal of the least significant bit in the bit field.
4585 @param EndBit The ordinal of the most significant bit in the bit field.
4587 @param AndData The value to AND with the read value from the value.
4588 @param OrData The value to OR with the result of the AND operation.
4590 @return The new 32-bit value.
4595 BitFieldAndThenOr32 (
4605 Returns a bit field from a 64-bit value.
4607 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4609 If 64-bit operations are not supported, then ASSERT().
4610 If StartBit is greater than 63, then ASSERT().
4611 If EndBit is greater than 63, then ASSERT().
4612 If EndBit is less than StartBit, then ASSERT().
4614 @param Operand Operand on which to perform the bitfield operation.
4615 @param StartBit The ordinal of the least significant bit in the bit field.
4617 @param EndBit The ordinal of the most significant bit in the bit field.
4620 @return The bit field read.
4633 Writes a bit field to a 64-bit value, and returns the result.
4635 Writes Value to the bit field specified by the StartBit and the EndBit in
4636 Operand. All other bits in Operand are preserved. The new 64-bit value is
4639 If 64-bit operations are not supported, then ASSERT().
4640 If StartBit is greater than 63, then ASSERT().
4641 If EndBit is greater than 63, then ASSERT().
4642 If EndBit is less than StartBit, then ASSERT().
4643 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4645 @param Operand Operand on which to perform the bitfield operation.
4646 @param StartBit The ordinal of the least significant bit in the bit field.
4648 @param EndBit The ordinal of the most significant bit in the bit field.
4650 @param Value New value of the bit field.
4652 @return The new 64-bit value.
4666 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4669 Performs a bitwise OR between the bit field specified by StartBit
4670 and EndBit in Operand and the value specified by OrData. All other bits in
4671 Operand are preserved. The new 64-bit value is returned.
4673 If 64-bit operations are not supported, then ASSERT().
4674 If StartBit is greater than 63, then ASSERT().
4675 If EndBit is greater than 63, then ASSERT().
4676 If EndBit is less than StartBit, then ASSERT().
4677 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4679 @param Operand Operand on which to perform the bitfield operation.
4680 @param StartBit The ordinal of the least significant bit in the bit field.
4682 @param EndBit The ordinal of the most significant bit in the bit field.
4684 @param OrData The value to OR with the read value from the value
4686 @return The new 64-bit value.
4700 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4703 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4704 in Operand and the value specified by AndData. All other bits in Operand are
4705 preserved. The new 64-bit value is returned.
4707 If 64-bit operations are not supported, then ASSERT().
4708 If StartBit is greater than 63, then ASSERT().
4709 If EndBit is greater than 63, then ASSERT().
4710 If EndBit is less than StartBit, then ASSERT().
4711 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4713 @param Operand Operand on which to perform the bitfield operation.
4714 @param StartBit The ordinal of the least significant bit in the bit field.
4716 @param EndBit The ordinal of the most significant bit in the bit field.
4718 @param AndData The value to AND with the read value from the value
4720 @return The new 64-bit value.
4734 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4735 bitwise OR, and returns the result.
4737 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4738 in Operand and the value specified by AndData, followed by a bitwise
4739 OR with value specified by OrData. All other bits in Operand are
4740 preserved. The new 64-bit value is returned.
4742 If 64-bit operations are not supported, then ASSERT().
4743 If StartBit is greater than 63, then ASSERT().
4744 If EndBit is greater than 63, then ASSERT().
4745 If EndBit is less than StartBit, then ASSERT().
4746 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4747 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4749 @param Operand Operand on which to perform the bitfield operation.
4750 @param StartBit The ordinal of the least significant bit in the bit field.
4752 @param EndBit The ordinal of the most significant bit in the bit field.
4754 @param AndData The value to AND with the read value from the value.
4755 @param OrData The value to OR with the result of the AND operation.
4757 @return The new 64-bit value.
4762 BitFieldAndThenOr64 (
4771 Reads a bit field from a 32-bit value, counts and returns
4772 the number of set bits.
4774 Counts the number of set bits in the bit field specified by
4775 StartBit and EndBit in Operand. The count is returned.
4777 If StartBit is greater than 31, then ASSERT().
4778 If EndBit is greater than 31, then ASSERT().
4779 If EndBit is less than StartBit, then ASSERT().
4781 @param Operand Operand on which to perform the bitfield operation.
4782 @param StartBit The ordinal of the least significant bit in the bit field.
4784 @param EndBit The ordinal of the most significant bit in the bit field.
4787 @return The number of bits set between StartBit and EndBit.
4792 BitFieldCountOnes32 (
4799 Reads a bit field from a 64-bit value, counts and returns
4800 the number of set bits.
4802 Counts the number of set bits in the bit field specified by
4803 StartBit and EndBit in Operand. The count is returned.
4805 If StartBit is greater than 63, then ASSERT().
4806 If EndBit is greater than 63, then ASSERT().
4807 If EndBit is less than StartBit, then ASSERT().
4809 @param Operand Operand on which to perform the bitfield operation.
4810 @param StartBit The ordinal of the least significant bit in the bit field.
4812 @param EndBit The ordinal of the most significant bit in the bit field.
4815 @return The number of bits set between StartBit and EndBit.
4820 BitFieldCountOnes64 (
4827 // Base Library Checksum Functions
4831 Returns the sum of all elements in a buffer in unit of UINT8.
4832 During calculation, the carry bits are dropped.
4834 This function calculates the sum of all elements in a buffer
4835 in unit of UINT8. The carry bits in result of addition are dropped.
4836 The result is returned as UINT8. If Length is Zero, then Zero is
4839 If Buffer is NULL, then ASSERT().
4840 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4842 @param Buffer The pointer to the buffer to carry out the sum operation.
4843 @param Length The size, in bytes, of Buffer.
4845 @return Sum The sum of Buffer with carry bits dropped during additions.
4851 IN CONST UINT8
*Buffer
,
4857 Returns the two's complement checksum of all elements in a buffer
4860 This function first calculates the sum of the 8-bit values in the
4861 buffer specified by Buffer and Length. The carry bits in the result
4862 of addition are dropped. Then, the two's complement of the sum is
4863 returned. If Length is 0, then 0 is returned.
4865 If Buffer is NULL, then ASSERT().
4866 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4868 @param Buffer The pointer to the buffer to carry out the checksum operation.
4869 @param Length The size, in bytes, of Buffer.
4871 @return Checksum The two's complement checksum of Buffer.
4876 CalculateCheckSum8 (
4877 IN CONST UINT8
*Buffer
,
4883 Returns the sum of all elements in a buffer of 16-bit values. During
4884 calculation, the carry bits are dropped.
4886 This function calculates the sum of the 16-bit values in the buffer
4887 specified by Buffer and Length. The carry bits in result of addition are dropped.
4888 The 16-bit result is returned. If Length is 0, then 0 is returned.
4890 If Buffer is NULL, then ASSERT().
4891 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4892 If Length is not aligned on a 16-bit boundary, then ASSERT().
4893 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4895 @param Buffer The pointer to the buffer to carry out the sum operation.
4896 @param Length The size, in bytes, of Buffer.
4898 @return Sum The sum of Buffer with carry bits dropped during additions.
4904 IN CONST UINT16
*Buffer
,
4910 Returns the two's complement checksum of all elements in a buffer of
4913 This function first calculates the sum of the 16-bit values in the buffer
4914 specified by Buffer and Length. The carry bits in the result of addition
4915 are dropped. Then, the two's complement of the sum is returned. If Length
4916 is 0, then 0 is returned.
4918 If Buffer is NULL, then ASSERT().
4919 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4920 If Length is not aligned on a 16-bit boundary, then ASSERT().
4921 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4923 @param Buffer The pointer to the buffer to carry out the checksum operation.
4924 @param Length The size, in bytes, of Buffer.
4926 @return Checksum The two's complement checksum of Buffer.
4931 CalculateCheckSum16 (
4932 IN CONST UINT16
*Buffer
,
4938 Returns the sum of all elements in a buffer of 32-bit values. During
4939 calculation, the carry bits are dropped.
4941 This function calculates the sum of the 32-bit values in the buffer
4942 specified by Buffer and Length. The carry bits in result of addition are dropped.
4943 The 32-bit result is returned. If Length is 0, then 0 is returned.
4945 If Buffer is NULL, then ASSERT().
4946 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4947 If Length is not aligned on a 32-bit boundary, then ASSERT().
4948 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4950 @param Buffer The pointer to the buffer to carry out the sum operation.
4951 @param Length The size, in bytes, of Buffer.
4953 @return Sum The sum of Buffer with carry bits dropped during additions.
4959 IN CONST UINT32
*Buffer
,
4965 Returns the two's complement checksum of all elements in a buffer of
4968 This function first calculates the sum of the 32-bit values in the buffer
4969 specified by Buffer and Length. The carry bits in the result of addition
4970 are dropped. Then, the two's complement of the sum is returned. If Length
4971 is 0, then 0 is returned.
4973 If Buffer is NULL, then ASSERT().
4974 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4975 If Length is not aligned on a 32-bit boundary, then ASSERT().
4976 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4978 @param Buffer The pointer to the buffer to carry out the checksum operation.
4979 @param Length The size, in bytes, of Buffer.
4981 @return Checksum The two's complement checksum of Buffer.
4986 CalculateCheckSum32 (
4987 IN CONST UINT32
*Buffer
,
4993 Returns the sum of all elements in a buffer of 64-bit values. During
4994 calculation, the carry bits are dropped.
4996 This function calculates the sum of the 64-bit values in the buffer
4997 specified by Buffer and Length. The carry bits in result of addition are dropped.
4998 The 64-bit result is returned. If Length is 0, then 0 is returned.
5000 If Buffer is NULL, then ASSERT().
5001 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
5002 If Length is not aligned on a 64-bit boundary, then ASSERT().
5003 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
5005 @param Buffer The pointer to the buffer to carry out the sum operation.
5006 @param Length The size, in bytes, of Buffer.
5008 @return Sum The sum of Buffer with carry bits dropped during additions.
5014 IN CONST UINT64
*Buffer
,
5020 Returns the two's complement checksum of all elements in a buffer of
5023 This function first calculates the sum of the 64-bit values in the buffer
5024 specified by Buffer and Length. The carry bits in the result of addition
5025 are dropped. Then, the two's complement of the sum is returned. If Length
5026 is 0, then 0 is returned.
5028 If Buffer is NULL, then ASSERT().
5029 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
5030 If Length is not aligned on a 64-bit boundary, then ASSERT().
5031 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
5033 @param Buffer The pointer to the buffer to carry out the checksum operation.
5034 @param Length The size, in bytes, of Buffer.
5036 @return Checksum The two's complement checksum of Buffer.
5041 CalculateCheckSum64 (
5042 IN CONST UINT64
*Buffer
,
5047 Computes and returns a 32-bit CRC for a data buffer.
5048 CRC32 value bases on ITU-T V.42.
5050 If Buffer is NULL, then ASSERT().
5051 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
5053 @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed.
5054 @param[in] Length The number of bytes in the buffer Data.
5056 @retval Crc32 The 32-bit CRC was computed for the data buffer.
5067 // Base Library CPU Functions
5071 Function entry point used when a stack switch is requested with SwitchStack()
5073 @param Context1 Context1 parameter passed into SwitchStack().
5074 @param Context2 Context2 parameter passed into SwitchStack().
5079 (EFIAPI
*SWITCH_STACK_ENTRY_POINT
)(
5080 IN VOID
*Context1
, OPTIONAL
5081 IN VOID
*Context2 OPTIONAL
5086 Used to serialize load and store operations.
5088 All loads and stores that proceed calls to this function are guaranteed to be
5089 globally visible when this function returns.
5100 Saves the current CPU context that can be restored with a call to LongJump()
5103 Saves the current CPU context in the buffer specified by JumpBuffer and
5104 returns 0. The initial call to SetJump() must always return 0. Subsequent
5105 calls to LongJump() cause a non-zero value to be returned by SetJump().
5107 If JumpBuffer is NULL, then ASSERT().
5108 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
5110 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
5111 The same structure must never be used for more than one CPU architecture context.
5112 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
5113 SetJump()/LongJump() is not currently supported for the EBC processor type.
5115 @param JumpBuffer A pointer to CPU context buffer.
5117 @retval 0 Indicates a return from SetJump().
5124 OUT BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
5129 Restores the CPU context that was saved with SetJump().
5131 Restores the CPU context from the buffer specified by JumpBuffer. This
5132 function never returns to the caller. Instead is resumes execution based on
5133 the state of JumpBuffer.
5135 If JumpBuffer is NULL, then ASSERT().
5136 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
5137 If Value is 0, then ASSERT().
5139 @param JumpBuffer A pointer to CPU context buffer.
5140 @param Value The value to return when the SetJump() context is
5141 restored and must be non-zero.
5147 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
5153 Enables CPU interrupts.
5164 Disables CPU interrupts.
5175 Disables CPU interrupts and returns the interrupt state prior to the disable
5178 @retval TRUE CPU interrupts were enabled on entry to this call.
5179 @retval FALSE CPU interrupts were disabled on entry to this call.
5184 SaveAndDisableInterrupts (
5190 Enables CPU interrupts for the smallest window required to capture any
5196 EnableDisableInterrupts (
5202 Retrieves the current CPU interrupt state.
5204 Returns TRUE if interrupts are currently enabled. Otherwise
5207 @retval TRUE CPU interrupts are enabled.
5208 @retval FALSE CPU interrupts are disabled.
5219 Set the current CPU interrupt state.
5221 Sets the current CPU interrupt state to the state specified by
5222 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
5223 InterruptState is FALSE, then interrupts are disabled. InterruptState is
5226 @param InterruptState TRUE if interrupts should enabled. FALSE if
5227 interrupts should be disabled.
5229 @return InterruptState
5235 IN BOOLEAN InterruptState
5240 Requests CPU to pause for a short period of time.
5242 Requests CPU to pause for a short period of time. Typically used in MP
5243 systems to prevent memory starvation while waiting for a spin lock.
5254 Transfers control to a function starting with a new stack.
5256 Transfers control to the function specified by EntryPoint using the
5257 new stack specified by NewStack and passing in the parameters specified
5258 by Context1 and Context2. Context1 and Context2 are optional and may
5259 be NULL. The function EntryPoint must never return. This function
5260 supports a variable number of arguments following the NewStack parameter.
5261 These additional arguments are ignored on IA-32, x64, and EBC architectures.
5262 Itanium processors expect one additional parameter of type VOID * that specifies
5263 the new backing store pointer.
5265 If EntryPoint is NULL, then ASSERT().
5266 If NewStack is NULL, then ASSERT().
5268 @param EntryPoint A pointer to function to call with the new stack.
5269 @param Context1 A pointer to the context to pass into the EntryPoint
5271 @param Context2 A pointer to the context to pass into the EntryPoint
5273 @param NewStack A pointer to the new stack to use for the EntryPoint
5275 @param ... This variable argument list is ignored for IA-32, x64, and
5276 EBC architectures. For Itanium processors, this variable
5277 argument list is expected to contain a single parameter of
5278 type VOID * that specifies the new backing store pointer.
5285 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
5286 IN VOID
*Context1
, OPTIONAL
5287 IN VOID
*Context2
, OPTIONAL
5294 Generates a breakpoint on the CPU.
5296 Generates a breakpoint on the CPU. The breakpoint must be implemented such
5297 that code can resume normal execution after the breakpoint.
5308 Executes an infinite loop.
5310 Forces the CPU to execute an infinite loop. A debugger may be used to skip
5311 past the loop and the code that follows the loop must execute properly. This
5312 implies that the infinite loop must not cause the code that follow it to be
5324 Uses as a barrier to stop speculative execution.
5326 Ensures that no later instruction will execute speculatively, until all prior
5327 instructions have completed.
5332 SpeculationBarrier (
5337 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
5339 /// IA32 and x64 Specific Functions.
5340 /// Byte packed structure for 16-bit Real Mode EFLAGS.
5344 UINT32 CF
:1; ///< Carry Flag.
5345 UINT32 Reserved_0
:1; ///< Reserved.
5346 UINT32 PF
:1; ///< Parity Flag.
5347 UINT32 Reserved_1
:1; ///< Reserved.
5348 UINT32 AF
:1; ///< Auxiliary Carry Flag.
5349 UINT32 Reserved_2
:1; ///< Reserved.
5350 UINT32 ZF
:1; ///< Zero Flag.
5351 UINT32 SF
:1; ///< Sign Flag.
5352 UINT32 TF
:1; ///< Trap Flag.
5353 UINT32 IF
:1; ///< Interrupt Enable Flag.
5354 UINT32 DF
:1; ///< Direction Flag.
5355 UINT32 OF
:1; ///< Overflow Flag.
5356 UINT32 IOPL
:2; ///< I/O Privilege Level.
5357 UINT32 NT
:1; ///< Nested Task.
5358 UINT32 Reserved_3
:1; ///< Reserved.
5364 /// Byte packed structure for EFLAGS/RFLAGS.
5365 /// 32-bits on IA-32.
5366 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5370 UINT32 CF
:1; ///< Carry Flag.
5371 UINT32 Reserved_0
:1; ///< Reserved.
5372 UINT32 PF
:1; ///< Parity Flag.
5373 UINT32 Reserved_1
:1; ///< Reserved.
5374 UINT32 AF
:1; ///< Auxiliary Carry Flag.
5375 UINT32 Reserved_2
:1; ///< Reserved.
5376 UINT32 ZF
:1; ///< Zero Flag.
5377 UINT32 SF
:1; ///< Sign Flag.
5378 UINT32 TF
:1; ///< Trap Flag.
5379 UINT32 IF
:1; ///< Interrupt Enable Flag.
5380 UINT32 DF
:1; ///< Direction Flag.
5381 UINT32 OF
:1; ///< Overflow Flag.
5382 UINT32 IOPL
:2; ///< I/O Privilege Level.
5383 UINT32 NT
:1; ///< Nested Task.
5384 UINT32 Reserved_3
:1; ///< Reserved.
5385 UINT32 RF
:1; ///< Resume Flag.
5386 UINT32 VM
:1; ///< Virtual 8086 Mode.
5387 UINT32 AC
:1; ///< Alignment Check.
5388 UINT32 VIF
:1; ///< Virtual Interrupt Flag.
5389 UINT32 VIP
:1; ///< Virtual Interrupt Pending.
5390 UINT32 ID
:1; ///< ID Flag.
5391 UINT32 Reserved_4
:10; ///< Reserved.
5397 /// Byte packed structure for Control Register 0 (CR0).
5398 /// 32-bits on IA-32.
5399 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5403 UINT32 PE
:1; ///< Protection Enable.
5404 UINT32 MP
:1; ///< Monitor Coprocessor.
5405 UINT32 EM
:1; ///< Emulation.
5406 UINT32 TS
:1; ///< Task Switched.
5407 UINT32 ET
:1; ///< Extension Type.
5408 UINT32 NE
:1; ///< Numeric Error.
5409 UINT32 Reserved_0
:10; ///< Reserved.
5410 UINT32 WP
:1; ///< Write Protect.
5411 UINT32 Reserved_1
:1; ///< Reserved.
5412 UINT32 AM
:1; ///< Alignment Mask.
5413 UINT32 Reserved_2
:10; ///< Reserved.
5414 UINT32 NW
:1; ///< Mot Write-through.
5415 UINT32 CD
:1; ///< Cache Disable.
5416 UINT32 PG
:1; ///< Paging.
5422 /// Byte packed structure for Control Register 4 (CR4).
5423 /// 32-bits on IA-32.
5424 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5428 UINT32 VME
:1; ///< Virtual-8086 Mode Extensions.
5429 UINT32 PVI
:1; ///< Protected-Mode Virtual Interrupts.
5430 UINT32 TSD
:1; ///< Time Stamp Disable.
5431 UINT32 DE
:1; ///< Debugging Extensions.
5432 UINT32 PSE
:1; ///< Page Size Extensions.
5433 UINT32 PAE
:1; ///< Physical Address Extension.
5434 UINT32 MCE
:1; ///< Machine Check Enable.
5435 UINT32 PGE
:1; ///< Page Global Enable.
5436 UINT32 PCE
:1; ///< Performance Monitoring Counter
5438 UINT32 OSFXSR
:1; ///< Operating System Support for
5439 ///< FXSAVE and FXRSTOR instructions
5440 UINT32 OSXMMEXCPT
:1; ///< Operating System Support for
5441 ///< Unmasked SIMD Floating Point
5443 UINT32 UMIP
:1; ///< User-Mode Instruction Prevention.
5444 UINT32 LA57
:1; ///< Linear Address 57bit.
5445 UINT32 VMXE
:1; ///< VMX Enable.
5446 UINT32 SMXE
:1; ///< SMX Enable.
5447 UINT32 Reserved_3
:1; ///< Reserved.
5448 UINT32 FSGSBASE
:1; ///< FSGSBASE Enable.
5449 UINT32 PCIDE
:1; ///< PCID Enable.
5450 UINT32 OSXSAVE
:1; ///< XSAVE and Processor Extended States Enable.
5451 UINT32 Reserved_4
:1; ///< Reserved.
5452 UINT32 SMEP
:1; ///< SMEP Enable.
5453 UINT32 SMAP
:1; ///< SMAP Enable.
5454 UINT32 PKE
:1; ///< Protection-Key Enable.
5455 UINT32 Reserved_5
:9; ///< Reserved.
5461 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5480 } IA32_SEGMENT_DESCRIPTOR
;
5483 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5492 #define IA32_IDT_GATE_TYPE_TASK 0x85
5493 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5494 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5495 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5496 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5498 #define IA32_GDT_TYPE_TSS 0x9
5499 #define IA32_GDT_ALIGNMENT 8
5501 #if defined (MDE_CPU_IA32)
5503 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5507 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5508 UINT32 Selector
:16; ///< Selector.
5509 UINT32 Reserved_0
:8; ///< Reserved.
5510 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5511 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5514 } IA32_IDT_GATE_DESCRIPTOR
;
5518 // IA32 Task-State Segment Definition
5521 UINT16 PreviousTaskLink
;
5555 UINT16 LDTSegmentSelector
;
5558 UINT16 IOMapBaseAddress
;
5559 } IA32_TASK_STATE_SEGMENT
;
5563 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5564 UINT32 BaseLow
:16; ///< Base Address 15..00
5565 UINT32 BaseMid
:8; ///< Base Address 23..16
5566 UINT32 Type
:4; ///< Type (1 0 B 1)
5567 UINT32 Reserved_43
:1; ///< 0
5568 UINT32 DPL
:2; ///< Descriptor Privilege Level
5569 UINT32 P
:1; ///< Segment Present
5570 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5571 UINT32 AVL
:1; ///< Available for use by system software
5572 UINT32 Reserved_52
:2; ///< 0 0
5573 UINT32 G
:1; ///< Granularity
5574 UINT32 BaseHigh
:8; ///< Base Address 31..24
5577 } IA32_TSS_DESCRIPTOR
;
5580 #endif // defined (MDE_CPU_IA32)
5582 #if defined (MDE_CPU_X64)
5584 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5588 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5589 UINT32 Selector
:16; ///< Selector.
5590 UINT32 Reserved_0
:8; ///< Reserved.
5591 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5592 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5593 UINT32 OffsetUpper
:32; ///< Offset bits 63..32.
5594 UINT32 Reserved_1
:32; ///< Reserved.
5600 } IA32_IDT_GATE_DESCRIPTOR
;
5604 // IA32 Task-State Segment Definition
5614 UINT16 Reserved_100
;
5615 UINT16 IOMapBaseAddress
;
5616 } IA32_TASK_STATE_SEGMENT
;
5620 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5621 UINT32 BaseLow
:16; ///< Base Address 15..00
5622 UINT32 BaseMidl
:8; ///< Base Address 23..16
5623 UINT32 Type
:4; ///< Type (1 0 B 1)
5624 UINT32 Reserved_43
:1; ///< 0
5625 UINT32 DPL
:2; ///< Descriptor Privilege Level
5626 UINT32 P
:1; ///< Segment Present
5627 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5628 UINT32 AVL
:1; ///< Available for use by system software
5629 UINT32 Reserved_52
:2; ///< 0 0
5630 UINT32 G
:1; ///< Granularity
5631 UINT32 BaseMidh
:8; ///< Base Address 31..24
5632 UINT32 BaseHigh
:32; ///< Base Address 63..32
5633 UINT32 Reserved_96
:32; ///< Reserved
5639 } IA32_TSS_DESCRIPTOR
;
5642 #endif // defined (MDE_CPU_X64)
5645 /// Byte packed structure for an FP/SSE/SSE2 context.
5652 /// Structures for the 16-bit real mode thunks.
5705 IA32_EFLAGS32 EFLAGS
;
5715 } IA32_REGISTER_SET
;
5718 /// Byte packed structure for an 16-bit real mode thunks.
5721 IA32_REGISTER_SET
*RealModeState
;
5722 VOID
*RealModeBuffer
;
5723 UINT32 RealModeBufferSize
;
5724 UINT32 ThunkAttributes
;
5727 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5728 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5729 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5732 /// Type definition for representing labels in NASM source code that allow for
5733 /// the patching of immediate operands of IA32 and X64 instructions.
5735 /// While the type is technically defined as a function type (note: not a
5736 /// pointer-to-function type), such labels in NASM source code never stand for
5737 /// actual functions, and identifiers declared with this function type should
5738 /// never be called. This is also why the EFIAPI calling convention specifier
5739 /// is missing from the typedef, and why the typedef does not follow the usual
5740 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5741 /// return type and the VOID argument list are merely artifacts.
5743 typedef VOID (X86_ASSEMBLY_PATCH_LABEL
) (VOID
);
5746 Retrieves CPUID information.
5748 Executes the CPUID instruction with EAX set to the value specified by Index.
5749 This function always returns Index.
5750 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5751 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5752 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5753 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5754 This function is only available on IA-32 and x64.
5756 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5758 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5759 instruction. This is an optional parameter that may be NULL.
5760 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5761 instruction. This is an optional parameter that may be NULL.
5762 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5763 instruction. This is an optional parameter that may be NULL.
5764 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5765 instruction. This is an optional parameter that may be NULL.
5774 OUT UINT32
*Eax
, OPTIONAL
5775 OUT UINT32
*Ebx
, OPTIONAL
5776 OUT UINT32
*Ecx
, OPTIONAL
5777 OUT UINT32
*Edx OPTIONAL
5782 Retrieves CPUID information using an extended leaf identifier.
5784 Executes the CPUID instruction with EAX set to the value specified by Index
5785 and ECX set to the value specified by SubIndex. This function always returns
5786 Index. This function is only available on IA-32 and x64.
5788 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5789 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5790 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5791 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5793 @param Index The 32-bit value to load into EAX prior to invoking the
5795 @param SubIndex The 32-bit value to load into ECX prior to invoking the
5797 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5798 instruction. This is an optional parameter that may be
5800 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5801 instruction. This is an optional parameter that may be
5803 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5804 instruction. This is an optional parameter that may be
5806 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5807 instruction. This is an optional parameter that may be
5818 OUT UINT32
*Eax
, OPTIONAL
5819 OUT UINT32
*Ebx
, OPTIONAL
5820 OUT UINT32
*Ecx
, OPTIONAL
5821 OUT UINT32
*Edx OPTIONAL
5826 Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5828 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5829 and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5840 Perform a WBINVD and clear both the CD and NW bits of CR0.
5842 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5843 bits of CR0 to 0. This function is only available on IA-32 and x64.
5854 Returns the lower 32-bits of a Machine Specific Register(MSR).
5856 Reads and returns the lower 32-bits of the MSR specified by Index.
5857 No parameter checking is performed on Index, and some Index values may cause
5858 CPU exceptions. The caller must either guarantee that Index is valid, or the
5859 caller must set up exception handlers to catch the exceptions. This function
5860 is only available on IA-32 and x64.
5862 @param Index The 32-bit MSR index to read.
5864 @return The lower 32 bits of the MSR identified by Index.
5875 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5876 The upper 32-bits of the MSR are set to zero.
5878 Writes the 32-bit value specified by Value to the MSR specified by Index. The
5879 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5880 the MSR is returned. No parameter checking is performed on Index or Value,
5881 and some of these may cause CPU exceptions. The caller must either guarantee
5882 that Index and Value are valid, or the caller must establish proper exception
5883 handlers. This function is only available on IA-32 and x64.
5885 @param Index The 32-bit MSR index to write.
5886 @param Value The 32-bit value to write to the MSR.
5900 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5901 writes the result back to the 64-bit MSR.
5903 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5904 between the lower 32-bits of the read result and the value specified by
5905 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5906 32-bits of the value written to the MSR is returned. No parameter checking is
5907 performed on Index or OrData, and some of these may cause CPU exceptions. The
5908 caller must either guarantee that Index and OrData are valid, or the caller
5909 must establish proper exception handlers. This function is only available on
5912 @param Index The 32-bit MSR index to write.
5913 @param OrData The value to OR with the read value from the MSR.
5915 @return The lower 32-bit value written to the MSR.
5927 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5928 the result back to the 64-bit MSR.
5930 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5931 lower 32-bits of the read result and the value specified by AndData, and
5932 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5933 the value written to the MSR is returned. No parameter checking is performed
5934 on Index or AndData, and some of these may cause CPU exceptions. The caller
5935 must either guarantee that Index and AndData are valid, or the caller must
5936 establish proper exception handlers. This function is only available on IA-32
5939 @param Index The 32-bit MSR index to write.
5940 @param AndData The value to AND with the read value from the MSR.
5942 @return The lower 32-bit value written to the MSR.
5954 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5955 on the lower 32-bits, and writes the result back to the 64-bit MSR.
5957 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5958 lower 32-bits of the read result and the value specified by AndData
5959 preserving the upper 32-bits, performs a bitwise OR between the
5960 result of the AND operation and the value specified by OrData, and writes the
5961 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5962 written to the MSR is returned. No parameter checking is performed on Index,
5963 AndData, or OrData, and some of these may cause CPU exceptions. The caller
5964 must either guarantee that Index, AndData, and OrData are valid, or the
5965 caller must establish proper exception handlers. This function is only
5966 available on IA-32 and x64.
5968 @param Index The 32-bit MSR index to write.
5969 @param AndData The value to AND with the read value from the MSR.
5970 @param OrData The value to OR with the result of the AND operation.
5972 @return The lower 32-bit value written to the MSR.
5985 Reads a bit field of an MSR.
5987 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5988 specified by the StartBit and the EndBit. The value of the bit field is
5989 returned. The caller must either guarantee that Index is valid, or the caller
5990 must set up exception handlers to catch the exceptions. This function is only
5991 available on IA-32 and x64.
5993 If StartBit is greater than 31, then ASSERT().
5994 If EndBit is greater than 31, then ASSERT().
5995 If EndBit is less than StartBit, then ASSERT().
5997 @param Index The 32-bit MSR index to read.
5998 @param StartBit The ordinal of the least significant bit in the bit field.
6000 @param EndBit The ordinal of the most significant bit in the bit field.
6003 @return The bit field read from the MSR.
6008 AsmMsrBitFieldRead32 (
6016 Writes a bit field to an MSR.
6018 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
6019 field is specified by the StartBit and the EndBit. All other bits in the
6020 destination MSR are preserved. The lower 32-bits of the MSR written is
6021 returned. The caller must either guarantee that Index and the data written
6022 is valid, or the caller must set up exception handlers to catch the exceptions.
6023 This function is only available on IA-32 and x64.
6025 If StartBit is greater than 31, then ASSERT().
6026 If EndBit is greater than 31, then ASSERT().
6027 If EndBit is less than StartBit, then ASSERT().
6028 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6030 @param Index The 32-bit MSR index to write.
6031 @param StartBit The ordinal of the least significant bit in the bit field.
6033 @param EndBit The ordinal of the most significant bit in the bit field.
6035 @param Value New value of the bit field.
6037 @return The lower 32-bit of the value written to the MSR.
6042 AsmMsrBitFieldWrite32 (
6051 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
6052 result back to the bit field in the 64-bit MSR.
6054 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6055 between the read result and the value specified by OrData, and writes the
6056 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
6057 written to the MSR are returned. Extra left bits in OrData are stripped. The
6058 caller must either guarantee that Index and the data written is valid, or
6059 the caller must set up exception handlers to catch the exceptions. This
6060 function is only available on IA-32 and x64.
6062 If StartBit is greater than 31, then ASSERT().
6063 If EndBit is greater than 31, then ASSERT().
6064 If EndBit is less than StartBit, then ASSERT().
6065 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6067 @param Index The 32-bit MSR index to write.
6068 @param StartBit The ordinal of the least significant bit in the bit field.
6070 @param EndBit The ordinal of the most significant bit in the bit field.
6072 @param OrData The value to OR with the read value from the MSR.
6074 @return The lower 32-bit of the value written to the MSR.
6079 AsmMsrBitFieldOr32 (
6088 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6089 result back to the bit field in the 64-bit MSR.
6091 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6092 read result and the value specified by AndData, and writes the result to the
6093 64-bit MSR specified by Index. The lower 32-bits of the value written to the
6094 MSR are returned. Extra left bits in AndData are stripped. The caller must
6095 either guarantee that Index and the data written is valid, or the caller must
6096 set up exception handlers to catch the exceptions. This function is only
6097 available on IA-32 and x64.
6099 If StartBit is greater than 31, then ASSERT().
6100 If EndBit is greater than 31, then ASSERT().
6101 If EndBit is less than StartBit, then ASSERT().
6102 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6104 @param Index The 32-bit MSR index to write.
6105 @param StartBit The ordinal of the least significant bit in the bit field.
6107 @param EndBit The ordinal of the most significant bit in the bit field.
6109 @param AndData The value to AND with the read value from the MSR.
6111 @return The lower 32-bit of the value written to the MSR.
6116 AsmMsrBitFieldAnd32 (
6125 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6126 bitwise OR, and writes the result back to the bit field in the
6129 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
6130 bitwise OR between the read result and the value specified by
6131 AndData, and writes the result to the 64-bit MSR specified by Index. The
6132 lower 32-bits of the value written to the MSR are returned. Extra left bits
6133 in both AndData and OrData are stripped. The caller must either guarantee
6134 that Index and the data written is valid, or the caller must set up exception
6135 handlers to catch the exceptions. This function is only available on IA-32
6138 If StartBit is greater than 31, then ASSERT().
6139 If EndBit is greater than 31, then ASSERT().
6140 If EndBit is less than StartBit, then ASSERT().
6141 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6142 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6144 @param Index The 32-bit MSR index to write.
6145 @param StartBit The ordinal of the least significant bit in the bit field.
6147 @param EndBit The ordinal of the most significant bit in the bit field.
6149 @param AndData The value to AND with the read value from the MSR.
6150 @param OrData The value to OR with the result of the AND operation.
6152 @return The lower 32-bit of the value written to the MSR.
6157 AsmMsrBitFieldAndThenOr32 (
6167 Returns a 64-bit Machine Specific Register(MSR).
6169 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
6170 performed on Index, and some Index values may cause CPU exceptions. The
6171 caller must either guarantee that Index is valid, or the caller must set up
6172 exception handlers to catch the exceptions. This function is only available
6175 @param Index The 32-bit MSR index to read.
6177 @return The value of the MSR identified by Index.
6188 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
6191 Writes the 64-bit value specified by Value to the MSR specified by Index. The
6192 64-bit value written to the MSR is returned. No parameter checking is
6193 performed on Index or Value, and some of these may cause CPU exceptions. The
6194 caller must either guarantee that Index and Value are valid, or the caller
6195 must establish proper exception handlers. This function is only available on
6198 @param Index The 32-bit MSR index to write.
6199 @param Value The 64-bit value to write to the MSR.
6213 Reads a 64-bit MSR, performs a bitwise OR, and writes the result
6214 back to the 64-bit MSR.
6216 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6217 between the read result and the value specified by OrData, and writes the
6218 result to the 64-bit MSR specified by Index. The value written to the MSR is
6219 returned. No parameter checking is performed on Index or OrData, and some of
6220 these may cause CPU exceptions. The caller must either guarantee that Index
6221 and OrData are valid, or the caller must establish proper exception handlers.
6222 This function is only available on IA-32 and x64.
6224 @param Index The 32-bit MSR index to write.
6225 @param OrData The value to OR with the read value from the MSR.
6227 @return The value written back to the MSR.
6239 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
6242 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6243 read result and the value specified by OrData, and writes the result to the
6244 64-bit MSR specified by Index. The value written to the MSR is returned. No
6245 parameter checking is performed on Index or OrData, and some of these may
6246 cause CPU exceptions. The caller must either guarantee that Index and OrData
6247 are valid, or the caller must establish proper exception handlers. This
6248 function is only available on IA-32 and x64.
6250 @param Index The 32-bit MSR index to write.
6251 @param AndData The value to AND with the read value from the MSR.
6253 @return The value written back to the MSR.
6265 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
6266 OR, and writes the result back to the 64-bit MSR.
6268 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
6269 result and the value specified by AndData, performs a bitwise OR
6270 between the result of the AND operation and the value specified by OrData,
6271 and writes the result to the 64-bit MSR specified by Index. The value written
6272 to the MSR is returned. No parameter checking is performed on Index, AndData,
6273 or OrData, and some of these may cause CPU exceptions. The caller must either
6274 guarantee that Index, AndData, and OrData are valid, or the caller must
6275 establish proper exception handlers. This function is only available on IA-32
6278 @param Index The 32-bit MSR index to write.
6279 @param AndData The value to AND with the read value from the MSR.
6280 @param OrData The value to OR with the result of the AND operation.
6282 @return The value written back to the MSR.
6295 Reads a bit field of an MSR.
6297 Reads the bit field in the 64-bit MSR. The bit field is specified by the
6298 StartBit and the EndBit. The value of the bit field is returned. The caller
6299 must either guarantee that Index is valid, or the caller must set up
6300 exception handlers to catch the exceptions. This function is only available
6303 If StartBit is greater than 63, then ASSERT().
6304 If EndBit is greater than 63, then ASSERT().
6305 If EndBit is less than StartBit, then ASSERT().
6307 @param Index The 32-bit MSR index to read.
6308 @param StartBit The ordinal of the least significant bit in the bit field.
6310 @param EndBit The ordinal of the most significant bit in the bit field.
6313 @return The value read from the MSR.
6318 AsmMsrBitFieldRead64 (
6326 Writes a bit field to an MSR.
6328 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
6329 the StartBit and the EndBit. All other bits in the destination MSR are
6330 preserved. The MSR written is returned. The caller must either guarantee
6331 that Index and the data written is valid, or the caller must set up exception
6332 handlers to catch the exceptions. This function is only available on IA-32 and x64.
6334 If StartBit is greater than 63, then ASSERT().
6335 If EndBit is greater than 63, then ASSERT().
6336 If EndBit is less than StartBit, then ASSERT().
6337 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6339 @param Index The 32-bit MSR index to write.
6340 @param StartBit The ordinal of the least significant bit in the bit field.
6342 @param EndBit The ordinal of the most significant bit in the bit field.
6344 @param Value New value of the bit field.
6346 @return The value written back to the MSR.
6351 AsmMsrBitFieldWrite64 (
6360 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
6361 writes the result back to the bit field in the 64-bit MSR.
6363 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6364 between the read result and the value specified by OrData, and writes the
6365 result to the 64-bit MSR specified by Index. The value written to the MSR is
6366 returned. Extra left bits in OrData are stripped. The caller must either
6367 guarantee that Index and the data written is valid, or the caller must set up
6368 exception handlers to catch the exceptions. This function is only available
6371 If StartBit is greater than 63, then ASSERT().
6372 If EndBit is greater than 63, then ASSERT().
6373 If EndBit is less than StartBit, then ASSERT().
6374 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6376 @param Index The 32-bit MSR index to write.
6377 @param StartBit The ordinal of the least significant bit in the bit field.
6379 @param EndBit The ordinal of the most significant bit in the bit field.
6381 @param OrData The value to OR with the read value from the bit field.
6383 @return The value written back to the MSR.
6388 AsmMsrBitFieldOr64 (
6397 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6398 result back to the bit field in the 64-bit MSR.
6400 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6401 read result and the value specified by AndData, and writes the result to the
6402 64-bit MSR specified by Index. The value written to the MSR is returned.
6403 Extra left bits in AndData are stripped. The caller must either guarantee
6404 that Index and the data written is valid, or the caller must set up exception
6405 handlers to catch the exceptions. This function is only available on IA-32
6408 If StartBit is greater than 63, then ASSERT().
6409 If EndBit is greater than 63, then ASSERT().
6410 If EndBit is less than StartBit, then ASSERT().
6411 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6413 @param Index The 32-bit MSR index to write.
6414 @param StartBit The ordinal of the least significant bit in the bit field.
6416 @param EndBit The ordinal of the most significant bit in the bit field.
6418 @param AndData The value to AND with the read value from the bit field.
6420 @return The value written back to the MSR.
6425 AsmMsrBitFieldAnd64 (
6434 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6435 bitwise OR, and writes the result back to the bit field in the
6438 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6439 a bitwise OR between the read result and the value specified by
6440 AndData, and writes the result to the 64-bit MSR specified by Index. The
6441 value written to the MSR is returned. Extra left bits in both AndData and
6442 OrData are stripped. The caller must either guarantee that Index and the data
6443 written is valid, or the caller must set up exception handlers to catch the
6444 exceptions. This function is only available on IA-32 and x64.
6446 If StartBit is greater than 63, then ASSERT().
6447 If EndBit is greater than 63, then ASSERT().
6448 If EndBit is less than StartBit, then ASSERT().
6449 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6450 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6452 @param Index The 32-bit MSR index to write.
6453 @param StartBit The ordinal of the least significant bit in the bit field.
6455 @param EndBit The ordinal of the most significant bit in the bit field.
6457 @param AndData The value to AND with the read value from the bit field.
6458 @param OrData The value to OR with the result of the AND operation.
6460 @return The value written back to the MSR.
6465 AsmMsrBitFieldAndThenOr64 (
6475 Reads the current value of the EFLAGS register.
6477 Reads and returns the current value of the EFLAGS register. This function is
6478 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6479 64-bit value on x64.
6481 @return EFLAGS on IA-32 or RFLAGS on x64.
6492 Reads the current value of the Control Register 0 (CR0).
6494 Reads and returns the current value of CR0. This function is only available
6495 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6498 @return The value of the Control Register 0 (CR0).
6509 Reads the current value of the Control Register 2 (CR2).
6511 Reads and returns the current value of CR2. This function is only available
6512 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6515 @return The value of the Control Register 2 (CR2).
6526 Reads the current value of the Control Register 3 (CR3).
6528 Reads and returns the current value of CR3. This function is only available
6529 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6532 @return The value of the Control Register 3 (CR3).
6543 Reads the current value of the Control Register 4 (CR4).
6545 Reads and returns the current value of CR4. This function is only available
6546 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6549 @return The value of the Control Register 4 (CR4).
6560 Writes a value to Control Register 0 (CR0).
6562 Writes and returns a new value to CR0. This function is only available on
6563 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6565 @param Cr0 The value to write to CR0.
6567 @return The value written to CR0.
6578 Writes a value to Control Register 2 (CR2).
6580 Writes and returns a new value to CR2. This function is only available on
6581 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6583 @param Cr2 The value to write to CR2.
6585 @return The value written to CR2.
6596 Writes a value to Control Register 3 (CR3).
6598 Writes and returns a new value to CR3. This function is only available on
6599 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6601 @param Cr3 The value to write to CR3.
6603 @return The value written to CR3.
6614 Writes a value to Control Register 4 (CR4).
6616 Writes and returns a new value to CR4. This function is only available on
6617 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6619 @param Cr4 The value to write to CR4.
6621 @return The value written to CR4.
6632 Reads the current value of Debug Register 0 (DR0).
6634 Reads and returns the current value of DR0. This function is only available
6635 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6638 @return The value of Debug Register 0 (DR0).
6649 Reads the current value of Debug Register 1 (DR1).
6651 Reads and returns the current value of DR1. This function is only available
6652 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6655 @return The value of Debug Register 1 (DR1).
6666 Reads the current value of Debug Register 2 (DR2).
6668 Reads and returns the current value of DR2. This function is only available
6669 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6672 @return The value of Debug Register 2 (DR2).
6683 Reads the current value of Debug Register 3 (DR3).
6685 Reads and returns the current value of DR3. This function is only available
6686 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6689 @return The value of Debug Register 3 (DR3).
6700 Reads the current value of Debug Register 4 (DR4).
6702 Reads and returns the current value of DR4. This function is only available
6703 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6706 @return The value of Debug Register 4 (DR4).
6717 Reads the current value of Debug Register 5 (DR5).
6719 Reads and returns the current value of DR5. This function is only available
6720 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6723 @return The value of Debug Register 5 (DR5).
6734 Reads the current value of Debug Register 6 (DR6).
6736 Reads and returns the current value of DR6. This function is only available
6737 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6740 @return The value of Debug Register 6 (DR6).
6751 Reads the current value of Debug Register 7 (DR7).
6753 Reads and returns the current value of DR7. This function is only available
6754 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6757 @return The value of Debug Register 7 (DR7).
6768 Writes a value to Debug Register 0 (DR0).
6770 Writes and returns a new value to DR0. This function is only available on
6771 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6773 @param Dr0 The value to write to Dr0.
6775 @return The value written to Debug Register 0 (DR0).
6786 Writes a value to Debug Register 1 (DR1).
6788 Writes and returns a new value to DR1. This function is only available on
6789 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6791 @param Dr1 The value to write to Dr1.
6793 @return The value written to Debug Register 1 (DR1).
6804 Writes a value to Debug Register 2 (DR2).
6806 Writes and returns a new value to DR2. This function is only available on
6807 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6809 @param Dr2 The value to write to Dr2.
6811 @return The value written to Debug Register 2 (DR2).
6822 Writes a value to Debug Register 3 (DR3).
6824 Writes and returns a new value to DR3. This function is only available on
6825 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6827 @param Dr3 The value to write to Dr3.
6829 @return The value written to Debug Register 3 (DR3).
6840 Writes a value to Debug Register 4 (DR4).
6842 Writes and returns a new value to DR4. This function is only available on
6843 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6845 @param Dr4 The value to write to Dr4.
6847 @return The value written to Debug Register 4 (DR4).
6858 Writes a value to Debug Register 5 (DR5).
6860 Writes and returns a new value to DR5. This function is only available on
6861 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6863 @param Dr5 The value to write to Dr5.
6865 @return The value written to Debug Register 5 (DR5).
6876 Writes a value to Debug Register 6 (DR6).
6878 Writes and returns a new value to DR6. This function is only available on
6879 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6881 @param Dr6 The value to write to Dr6.
6883 @return The value written to Debug Register 6 (DR6).
6894 Writes a value to Debug Register 7 (DR7).
6896 Writes and returns a new value to DR7. This function is only available on
6897 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6899 @param Dr7 The value to write to Dr7.
6901 @return The value written to Debug Register 7 (DR7).
6912 Reads the current value of Code Segment Register (CS).
6914 Reads and returns the current value of CS. This function is only available on
6917 @return The current value of CS.
6928 Reads the current value of Data Segment Register (DS).
6930 Reads and returns the current value of DS. This function is only available on
6933 @return The current value of DS.
6944 Reads the current value of Extra Segment Register (ES).
6946 Reads and returns the current value of ES. This function is only available on
6949 @return The current value of ES.
6960 Reads the current value of FS Data Segment Register (FS).
6962 Reads and returns the current value of FS. This function is only available on
6965 @return The current value of FS.
6976 Reads the current value of GS Data Segment Register (GS).
6978 Reads and returns the current value of GS. This function is only available on
6981 @return The current value of GS.
6992 Reads the current value of Stack Segment Register (SS).
6994 Reads and returns the current value of SS. This function is only available on
6997 @return The current value of SS.
7008 Reads the current value of Task Register (TR).
7010 Reads and returns the current value of TR. This function is only available on
7013 @return The current value of TR.
7024 Reads the current Global Descriptor Table Register(GDTR) descriptor.
7026 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
7027 function is only available on IA-32 and x64.
7029 If Gdtr is NULL, then ASSERT().
7031 @param Gdtr The pointer to a GDTR descriptor.
7037 OUT IA32_DESCRIPTOR
*Gdtr
7042 Writes the current Global Descriptor Table Register (GDTR) descriptor.
7044 Writes and the current GDTR descriptor specified by Gdtr. This function is
7045 only available on IA-32 and x64.
7047 If Gdtr is NULL, then ASSERT().
7049 @param Gdtr The pointer to a GDTR descriptor.
7055 IN CONST IA32_DESCRIPTOR
*Gdtr
7060 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
7062 Reads and returns the current IDTR descriptor and returns it in Idtr. This
7063 function is only available on IA-32 and x64.
7065 If Idtr is NULL, then ASSERT().
7067 @param Idtr The pointer to a IDTR descriptor.
7073 OUT IA32_DESCRIPTOR
*Idtr
7078 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
7080 Writes the current IDTR descriptor and returns it in Idtr. This function is
7081 only available on IA-32 and x64.
7083 If Idtr is NULL, then ASSERT().
7085 @param Idtr The pointer to a IDTR descriptor.
7091 IN CONST IA32_DESCRIPTOR
*Idtr
7096 Reads the current Local Descriptor Table Register(LDTR) selector.
7098 Reads and returns the current 16-bit LDTR descriptor value. This function is
7099 only available on IA-32 and x64.
7101 @return The current selector of LDT.
7112 Writes the current Local Descriptor Table Register (LDTR) selector.
7114 Writes and the current LDTR descriptor specified by Ldtr. This function is
7115 only available on IA-32 and x64.
7117 @param Ldtr 16-bit LDTR selector value.
7128 Save the current floating point/SSE/SSE2 context to a buffer.
7130 Saves the current floating point/SSE/SSE2 state to the buffer specified by
7131 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
7132 available on IA-32 and x64.
7134 If Buffer is NULL, then ASSERT().
7135 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7137 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7143 OUT IA32_FX_BUFFER
*Buffer
7148 Restores the current floating point/SSE/SSE2 context from a buffer.
7150 Restores the current floating point/SSE/SSE2 state from the buffer specified
7151 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
7152 only available on IA-32 and x64.
7154 If Buffer is NULL, then ASSERT().
7155 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7156 If Buffer was not saved with AsmFxSave(), then ASSERT().
7158 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7164 IN CONST IA32_FX_BUFFER
*Buffer
7169 Reads the current value of 64-bit MMX Register #0 (MM0).
7171 Reads and returns the current value of MM0. This function is only available
7174 @return The current value of MM0.
7185 Reads the current value of 64-bit MMX Register #1 (MM1).
7187 Reads and returns the current value of MM1. This function is only available
7190 @return The current value of MM1.
7201 Reads the current value of 64-bit MMX Register #2 (MM2).
7203 Reads and returns the current value of MM2. This function is only available
7206 @return The current value of MM2.
7217 Reads the current value of 64-bit MMX Register #3 (MM3).
7219 Reads and returns the current value of MM3. This function is only available
7222 @return The current value of MM3.
7233 Reads the current value of 64-bit MMX Register #4 (MM4).
7235 Reads and returns the current value of MM4. This function is only available
7238 @return The current value of MM4.
7249 Reads the current value of 64-bit MMX Register #5 (MM5).
7251 Reads and returns the current value of MM5. This function is only available
7254 @return The current value of MM5.
7265 Reads the current value of 64-bit MMX Register #6 (MM6).
7267 Reads and returns the current value of MM6. This function is only available
7270 @return The current value of MM6.
7281 Reads the current value of 64-bit MMX Register #7 (MM7).
7283 Reads and returns the current value of MM7. This function is only available
7286 @return The current value of MM7.
7297 Writes the current value of 64-bit MMX Register #0 (MM0).
7299 Writes the current value of MM0. This function is only available on IA32 and
7302 @param Value The 64-bit value to write to MM0.
7313 Writes the current value of 64-bit MMX Register #1 (MM1).
7315 Writes the current value of MM1. This function is only available on IA32 and
7318 @param Value The 64-bit value to write to MM1.
7329 Writes the current value of 64-bit MMX Register #2 (MM2).
7331 Writes the current value of MM2. This function is only available on IA32 and
7334 @param Value The 64-bit value to write to MM2.
7345 Writes the current value of 64-bit MMX Register #3 (MM3).
7347 Writes the current value of MM3. This function is only available on IA32 and
7350 @param Value The 64-bit value to write to MM3.
7361 Writes the current value of 64-bit MMX Register #4 (MM4).
7363 Writes the current value of MM4. This function is only available on IA32 and
7366 @param Value The 64-bit value to write to MM4.
7377 Writes the current value of 64-bit MMX Register #5 (MM5).
7379 Writes the current value of MM5. This function is only available on IA32 and
7382 @param Value The 64-bit value to write to MM5.
7393 Writes the current value of 64-bit MMX Register #6 (MM6).
7395 Writes the current value of MM6. This function is only available on IA32 and
7398 @param Value The 64-bit value to write to MM6.
7409 Writes the current value of 64-bit MMX Register #7 (MM7).
7411 Writes the current value of MM7. This function is only available on IA32 and
7414 @param Value The 64-bit value to write to MM7.
7425 Reads the current value of Time Stamp Counter (TSC).
7427 Reads and returns the current value of TSC. This function is only available
7430 @return The current value of TSC
7441 Reads the current value of a Performance Counter (PMC).
7443 Reads and returns the current value of performance counter specified by
7444 Index. This function is only available on IA-32 and x64.
7446 @param Index The 32-bit Performance Counter index to read.
7448 @return The value of the PMC specified by Index.
7459 Sets up a monitor buffer that is used by AsmMwait().
7461 Executes a MONITOR instruction with the register state specified by Eax, Ecx
7462 and Edx. Returns Eax. This function is only available on IA-32 and x64.
7464 @param Eax The value to load into EAX or RAX before executing the MONITOR
7466 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7468 @param Edx The value to load into EDX or RDX before executing the MONITOR
7484 Executes an MWAIT instruction.
7486 Executes an MWAIT instruction with the register state specified by Eax and
7487 Ecx. Returns Eax. This function is only available on IA-32 and x64.
7489 @param Eax The value to load into EAX or RAX before executing the MONITOR
7491 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7506 Executes a WBINVD instruction.
7508 Executes a WBINVD instruction. This function is only available on IA-32 and
7520 Executes a INVD instruction.
7522 Executes a INVD instruction. This function is only available on IA-32 and
7534 Flushes a cache line from all the instruction and data caches within the
7535 coherency domain of the CPU.
7537 Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7538 This function is only available on IA-32 and x64.
7540 @param LinearAddress The address of the cache line to flush. If the CPU is
7541 in a physical addressing mode, then LinearAddress is a
7542 physical address. If the CPU is in a virtual
7543 addressing mode, then LinearAddress is a virtual
7546 @return LinearAddress.
7551 IN VOID
*LinearAddress
7556 Enables the 32-bit paging mode on the CPU.
7558 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7559 must be properly initialized prior to calling this service. This function
7560 assumes the current execution mode is 32-bit protected mode. This function is
7561 only available on IA-32. After the 32-bit paging mode is enabled, control is
7562 transferred to the function specified by EntryPoint using the new stack
7563 specified by NewStack and passing in the parameters specified by Context1 and
7564 Context2. Context1 and Context2 are optional and may be NULL. The function
7565 EntryPoint must never return.
7567 If the current execution mode is not 32-bit protected mode, then ASSERT().
7568 If EntryPoint is NULL, then ASSERT().
7569 If NewStack is NULL, then ASSERT().
7571 There are a number of constraints that must be followed before calling this
7573 1) Interrupts must be disabled.
7574 2) The caller must be in 32-bit protected mode with flat descriptors. This
7575 means all descriptors must have a base of 0 and a limit of 4GB.
7576 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
7578 4) CR3 must point to valid page tables that will be used once the transition
7579 is complete, and those page tables must guarantee that the pages for this
7580 function and the stack are identity mapped.
7582 @param EntryPoint A pointer to function to call with the new stack after
7584 @param Context1 A pointer to the context to pass into the EntryPoint
7585 function as the first parameter after paging is enabled.
7586 @param Context2 A pointer to the context to pass into the EntryPoint
7587 function as the second parameter after paging is enabled.
7588 @param NewStack A pointer to the new stack to use for the EntryPoint
7589 function after paging is enabled.
7595 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7596 IN VOID
*Context1
, OPTIONAL
7597 IN VOID
*Context2
, OPTIONAL
7603 Disables the 32-bit paging mode on the CPU.
7605 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7606 mode. This function assumes the current execution mode is 32-paged protected
7607 mode. This function is only available on IA-32. After the 32-bit paging mode
7608 is disabled, control is transferred to the function specified by EntryPoint
7609 using the new stack specified by NewStack and passing in the parameters
7610 specified by Context1 and Context2. Context1 and Context2 are optional and
7611 may be NULL. The function EntryPoint must never return.
7613 If the current execution mode is not 32-bit paged mode, then ASSERT().
7614 If EntryPoint is NULL, then ASSERT().
7615 If NewStack is NULL, then ASSERT().
7617 There are a number of constraints that must be followed before calling this
7619 1) Interrupts must be disabled.
7620 2) The caller must be in 32-bit paged mode.
7621 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7622 4) CR3 must point to valid page tables that guarantee that the pages for
7623 this function and the stack are identity mapped.
7625 @param EntryPoint A pointer to function to call with the new stack after
7627 @param Context1 A pointer to the context to pass into the EntryPoint
7628 function as the first parameter after paging is disabled.
7629 @param Context2 A pointer to the context to pass into the EntryPoint
7630 function as the second parameter after paging is
7632 @param NewStack A pointer to the new stack to use for the EntryPoint
7633 function after paging is disabled.
7638 AsmDisablePaging32 (
7639 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7640 IN VOID
*Context1
, OPTIONAL
7641 IN VOID
*Context2
, OPTIONAL
7647 Enables the 64-bit paging mode on the CPU.
7649 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7650 must be properly initialized prior to calling this service. This function
7651 assumes the current execution mode is 32-bit protected mode with flat
7652 descriptors. This function is only available on IA-32. After the 64-bit
7653 paging mode is enabled, control is transferred to the function specified by
7654 EntryPoint using the new stack specified by NewStack and passing in the
7655 parameters specified by Context1 and Context2. Context1 and Context2 are
7656 optional and may be 0. The function EntryPoint must never return.
7658 If the current execution mode is not 32-bit protected mode with flat
7659 descriptors, then ASSERT().
7660 If EntryPoint is 0, then ASSERT().
7661 If NewStack is 0, then ASSERT().
7663 @param Cs The 16-bit selector to load in the CS before EntryPoint
7664 is called. The descriptor in the GDT that this selector
7665 references must be setup for long mode.
7666 @param EntryPoint The 64-bit virtual address of the function to call with
7667 the new stack after paging is enabled.
7668 @param Context1 The 64-bit virtual address of the context to pass into
7669 the EntryPoint function as the first parameter after
7671 @param Context2 The 64-bit virtual address of the context to pass into
7672 the EntryPoint function as the second parameter after
7674 @param NewStack The 64-bit virtual address of the new stack to use for
7675 the EntryPoint function after paging is enabled.
7682 IN UINT64 EntryPoint
,
7683 IN UINT64 Context1
, OPTIONAL
7684 IN UINT64 Context2
, OPTIONAL
7690 Disables the 64-bit paging mode on the CPU.
7692 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7693 mode. This function assumes the current execution mode is 64-paging mode.
7694 This function is only available on x64. After the 64-bit paging mode is
7695 disabled, control is transferred to the function specified by EntryPoint
7696 using the new stack specified by NewStack and passing in the parameters
7697 specified by Context1 and Context2. Context1 and Context2 are optional and
7698 may be 0. The function EntryPoint must never return.
7700 If the current execution mode is not 64-bit paged mode, then ASSERT().
7701 If EntryPoint is 0, then ASSERT().
7702 If NewStack is 0, then ASSERT().
7704 @param Cs The 16-bit selector to load in the CS before EntryPoint
7705 is called. The descriptor in the GDT that this selector
7706 references must be setup for 32-bit protected mode.
7707 @param EntryPoint The 64-bit virtual address of the function to call with
7708 the new stack after paging is disabled.
7709 @param Context1 The 64-bit virtual address of the context to pass into
7710 the EntryPoint function as the first parameter after
7712 @param Context2 The 64-bit virtual address of the context to pass into
7713 the EntryPoint function as the second parameter after
7715 @param NewStack The 64-bit virtual address of the new stack to use for
7716 the EntryPoint function after paging is disabled.
7721 AsmDisablePaging64 (
7723 IN UINT32 EntryPoint
,
7724 IN UINT32 Context1
, OPTIONAL
7725 IN UINT32 Context2
, OPTIONAL
7731 // 16-bit thunking services
7735 Retrieves the properties for 16-bit thunk functions.
7737 Computes the size of the buffer and stack below 1MB required to use the
7738 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7739 buffer size is returned in RealModeBufferSize, and the stack size is returned
7740 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7741 then the actual minimum stack size is ExtraStackSize plus the maximum number
7742 of bytes that need to be passed to the 16-bit real mode code.
7744 If RealModeBufferSize is NULL, then ASSERT().
7745 If ExtraStackSize is NULL, then ASSERT().
7747 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
7748 required to use the 16-bit thunk functions.
7749 @param ExtraStackSize A pointer to the extra size of stack below 1MB
7750 that the 16-bit thunk functions require for
7751 temporary storage in the transition to and from
7757 AsmGetThunk16Properties (
7758 OUT UINT32
*RealModeBufferSize
,
7759 OUT UINT32
*ExtraStackSize
7764 Prepares all structures a code required to use AsmThunk16().
7766 Prepares all structures and code required to use AsmThunk16().
7768 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7769 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7771 If ThunkContext is NULL, then ASSERT().
7773 @param ThunkContext A pointer to the context structure that describes the
7774 16-bit real mode code to call.
7780 IN OUT THUNK_CONTEXT
*ThunkContext
7785 Transfers control to a 16-bit real mode entry point and returns the results.
7787 Transfers control to a 16-bit real mode entry point and returns the results.
7788 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7789 This function must be called with interrupts disabled.
7791 The register state from the RealModeState field of ThunkContext is restored just prior
7792 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
7793 which is used to set the interrupt state when a 16-bit real mode entry point is called.
7794 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7795 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
7796 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7797 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7798 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7799 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7800 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7801 after the RETF instruction is executed.
7803 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7804 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7805 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7807 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7808 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7809 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7811 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7812 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7814 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7815 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7816 disable the A20 mask.
7818 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7819 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
7820 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7822 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7823 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7825 If ThunkContext is NULL, then ASSERT().
7826 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7827 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7828 ThunkAttributes, then ASSERT().
7830 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7831 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7833 @param ThunkContext A pointer to the context structure that describes the
7834 16-bit real mode code to call.
7840 IN OUT THUNK_CONTEXT
*ThunkContext
7845 Prepares all structures and code for a 16-bit real mode thunk, transfers
7846 control to a 16-bit real mode entry point, and returns the results.
7848 Prepares all structures and code for a 16-bit real mode thunk, transfers
7849 control to a 16-bit real mode entry point, and returns the results. If the
7850 caller only need to perform a single 16-bit real mode thunk, then this
7851 service should be used. If the caller intends to make more than one 16-bit
7852 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7853 once and AsmThunk16() can be called for each 16-bit real mode thunk.
7855 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7856 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7858 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7860 @param ThunkContext A pointer to the context structure that describes the
7861 16-bit real mode code to call.
7866 AsmPrepareAndThunk16 (
7867 IN OUT THUNK_CONTEXT
*ThunkContext
7871 Generates a 16-bit random number through RDRAND instruction.
7873 if Rand is NULL, then ASSERT().
7875 @param[out] Rand Buffer pointer to store the random result.
7877 @retval TRUE RDRAND call was successful.
7878 @retval FALSE Failed attempts to call RDRAND.
7888 Generates a 32-bit random number through RDRAND instruction.
7890 if Rand is NULL, then ASSERT().
7892 @param[out] Rand Buffer pointer to store the random result.
7894 @retval TRUE RDRAND call was successful.
7895 @retval FALSE Failed attempts to call RDRAND.
7905 Generates a 64-bit random number through RDRAND instruction.
7907 if Rand is NULL, then ASSERT().
7909 @param[out] Rand Buffer pointer to store the random result.
7911 @retval TRUE RDRAND call was successful.
7912 @retval FALSE Failed attempts to call RDRAND.
7922 Load given selector into TR register.
7924 @param[in] Selector Task segment selector
7933 Performs a serializing operation on all load-from-memory instructions that
7934 were issued prior the AsmLfence function.
7936 Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7946 Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7947 word, dword or qword operand is encoded at the end of the instruction's
7948 binary representation.
7950 This function should be used to update object code that was compiled with
7951 NASM from assembly source code. Example:
7955 mov eax, strict dword 0 ; the imm32 zero operand will be patched
7961 X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7962 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7964 @param[out] InstructionEnd Pointer right past the instruction to patch. The
7965 immediate operand to patch is expected to
7966 comprise the trailing bytes of the instruction.
7967 If InstructionEnd is closer to address 0 than
7968 ValueSize permits, then ASSERT().
7970 @param[in] PatchValue The constant to write to the immediate operand.
7971 The caller is responsible for ensuring that
7972 PatchValue can be represented in the byte, word,
7973 dword or qword operand (as indicated through
7974 ValueSize); otherwise ASSERT().
7976 @param[in] ValueSize The size of the operand in bytes; must be 1, 2,
7977 4, or 8. ASSERT() otherwise.
7981 PatchInstructionX86 (
7982 OUT X86_ASSEMBLY_PATCH_LABEL
*InstructionEnd
,
7983 IN UINT64 PatchValue
,
7987 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7988 #endif // !defined (__BASE_LIB__)