2 Provides string functions, linked list functions, math functions, synchronization
3 functions, file path functions, and CPU architecture-specific functions.
5 Copyright (c) 2006 - 2021, 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>
9 Portions Copyright (c) 2022, Loongson Technology Corporation Limited. All rights reserved.<BR>
11 SPDX-License-Identifier: BSD-2-Clause-Patent
19 // Definitions for architecture-specific types
21 #if defined (MDE_CPU_IA32)
23 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
33 } BASE_LIBRARY_JUMP_BUFFER
;
35 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
37 #endif // defined (MDE_CPU_IA32)
39 #if defined (MDE_CPU_X64)
41 /// The x64 architecture context buffer used by SetJump() and LongJump().
55 UINT8 XmmBuffer
[160]; ///< XMM6-XMM15.
57 } BASE_LIBRARY_JUMP_BUFFER
;
59 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
61 #endif // defined (MDE_CPU_X64)
63 #if defined (MDE_CPU_EBC)
65 /// The EBC context buffer used by SetJump() and LongJump().
73 } BASE_LIBRARY_JUMP_BUFFER
;
75 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
77 #endif // defined (MDE_CPU_EBC)
79 #if defined (MDE_CPU_ARM)
82 UINT32 R3
; ///< A copy of R13.
93 } BASE_LIBRARY_JUMP_BUFFER
;
95 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
97 #endif // defined (MDE_CPU_ARM)
99 #if defined (MDE_CPU_AARCH64)
125 } BASE_LIBRARY_JUMP_BUFFER
;
127 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
129 #endif // defined (MDE_CPU_AARCH64)
131 #if defined (MDE_CPU_RISCV64)
133 /// The RISC-V architecture context buffer used by SetJump() and LongJump().
150 } BASE_LIBRARY_JUMP_BUFFER
;
152 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
155 RiscVSetSupervisorScratch (
160 RiscVGetSupervisorScratch (
165 RiscVSetSupervisorStvec (
170 RiscVGetSupervisorStvec (
175 RiscVGetSupervisorTrapCause (
180 RiscVSetSupervisorAddressTranslationRegister (
190 RiscVEnableTimerInterrupt (
195 RiscVDisableTimerInterrupt (
200 RiscVClearPendingTimerInterrupt (
204 #endif // defined (MDE_CPU_RISCV64)
206 #if defined (MDE_CPU_LOONGARCH64)
208 /// The LoongArch architecture context buffer used by SetJump() and LongJump()
223 } BASE_LIBRARY_JUMP_BUFFER
;
225 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
227 #endif // defined (MDE_CPU_LOONGARCH64)
234 Returns the length of a Null-terminated Unicode string.
236 This function is similar as strlen_s defined in C11.
238 If String is not aligned on a 16-bit boundary, then ASSERT().
240 @param String A pointer to a Null-terminated Unicode string.
241 @param MaxSize The maximum number of Destination Unicode
242 char, including terminating null char.
244 @retval 0 If String is NULL.
245 @retval MaxSize If there is no null character in the first MaxSize characters of String.
246 @return The number of characters that percede the terminating null character.
252 IN CONST CHAR16
*String
,
257 Returns the size of a Null-terminated Unicode string in bytes, including the
260 This function returns the size of the Null-terminated Unicode string
261 specified by String in bytes, including the Null terminator.
263 If String is not aligned on a 16-bit boundary, then ASSERT().
265 @param String A pointer to a Null-terminated Unicode string.
266 @param MaxSize The maximum number of Destination Unicode
267 char, including the Null terminator.
269 @retval 0 If String is NULL.
270 @retval (sizeof (CHAR16) * (MaxSize + 1))
271 If there is no Null terminator in the first MaxSize characters of
273 @return The size of the Null-terminated Unicode string in bytes, including
280 IN CONST CHAR16
*String
,
285 Copies the string pointed to by Source (including the terminating null char)
286 to the array pointed to by Destination.
288 This function is similar as strcpy_s defined in C11.
290 If Destination is not aligned on a 16-bit boundary, then ASSERT().
291 If Source is not aligned on a 16-bit boundary, then ASSERT().
293 If an error is returned, then the Destination is unmodified.
295 @param Destination A pointer to a Null-terminated Unicode string.
296 @param DestMax The maximum number of Destination Unicode
297 char, including terminating null char.
298 @param Source A pointer to a Null-terminated Unicode string.
300 @retval RETURN_SUCCESS String is copied.
301 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
302 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
304 If PcdMaximumUnicodeStringLength is not zero,
305 and DestMax is greater than
306 PcdMaximumUnicodeStringLength.
308 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
313 OUT CHAR16
*Destination
,
315 IN CONST CHAR16
*Source
319 Copies not more than Length successive char from the string pointed to by
320 Source to the array pointed to by Destination. If no null char is copied from
321 Source, then Destination[Length] is always set to null.
323 This function is similar as strncpy_s defined in C11.
325 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
326 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
328 If an error is returned, then the Destination is unmodified.
330 @param Destination A pointer to a Null-terminated Unicode string.
331 @param DestMax The maximum number of Destination Unicode
332 char, including terminating null char.
333 @param Source A pointer to a Null-terminated Unicode string.
334 @param Length The maximum number of Unicode characters to copy.
336 @retval RETURN_SUCCESS String is copied.
337 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
338 MIN(StrLen(Source), Length).
339 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
341 If PcdMaximumUnicodeStringLength is not zero,
342 and DestMax is greater than
343 PcdMaximumUnicodeStringLength.
345 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
350 OUT CHAR16
*Destination
,
352 IN CONST CHAR16
*Source
,
357 Appends a copy of the string pointed to by Source (including the terminating
358 null char) to the end of the string pointed to by Destination.
360 This function is similar as strcat_s defined in C11.
362 If Destination is not aligned on a 16-bit boundary, then ASSERT().
363 If Source is not aligned on a 16-bit boundary, then ASSERT().
365 If an error is returned, then the Destination is unmodified.
367 @param Destination A pointer to a Null-terminated Unicode string.
368 @param DestMax The maximum number of Destination Unicode
369 char, including terminating null char.
370 @param Source A pointer to a Null-terminated Unicode string.
372 @retval RETURN_SUCCESS String is appended.
373 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
375 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
376 greater than StrLen(Source).
377 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
379 If PcdMaximumUnicodeStringLength is not zero,
380 and DestMax is greater than
381 PcdMaximumUnicodeStringLength.
383 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
388 IN OUT CHAR16
*Destination
,
390 IN CONST CHAR16
*Source
394 Appends not more than Length successive char from the string pointed to by
395 Source to the end of the string pointed to by Destination. If no null char is
396 copied from Source, then Destination[StrLen(Destination) + Length] is always
399 This function is similar as strncat_s defined in C11.
401 If Destination is not aligned on a 16-bit boundary, then ASSERT().
402 If Source is not aligned on a 16-bit boundary, then ASSERT().
404 If an error is returned, then the Destination is unmodified.
406 @param Destination A pointer to a Null-terminated Unicode string.
407 @param DestMax The maximum number of Destination Unicode
408 char, including terminating null char.
409 @param Source A pointer to a Null-terminated Unicode string.
410 @param Length The maximum number of Unicode characters to copy.
412 @retval RETURN_SUCCESS String is appended.
413 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
415 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
416 greater than MIN(StrLen(Source), Length).
417 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
419 If PcdMaximumUnicodeStringLength is not zero,
420 and DestMax is greater than
421 PcdMaximumUnicodeStringLength.
423 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
428 IN OUT CHAR16
*Destination
,
430 IN CONST CHAR16
*Source
,
435 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
437 This function outputs a value of type UINTN by interpreting the contents of
438 the Unicode string specified by String as a decimal number. The format of the
439 input Unicode string String is:
441 [spaces] [decimal digits].
443 The valid decimal digit character is in the range [0-9]. The function will
444 ignore the pad space, which includes spaces or tab characters, before
445 [decimal digits]. The running zero in the beginning of [decimal digits] will
446 be ignored. Then, the function stops at the first character that is a not a
447 valid decimal character or a Null-terminator, whichever one comes first.
449 If String is not aligned in a 16-bit boundary, then ASSERT().
451 If String has no valid decimal digits in the above format, then 0 is stored
452 at the location pointed to by Data.
453 If the number represented by String exceeds the range defined by UINTN, then
454 MAX_UINTN is stored at the location pointed to by Data.
456 If EndPointer is not NULL, a pointer to the character that stopped the scan
457 is stored at the location pointed to by EndPointer. If String has no valid
458 decimal digits right after the optional pad spaces, the value of String is
459 stored at the location pointed to by EndPointer.
461 @param String Pointer to a Null-terminated Unicode string.
462 @param EndPointer Pointer to character that stops scan.
463 @param Data Pointer to the converted value.
465 @retval RETURN_SUCCESS Value is translated from String.
466 @retval RETURN_INVALID_PARAMETER If String is NULL.
468 If PcdMaximumUnicodeStringLength is not
469 zero, and String contains more than
470 PcdMaximumUnicodeStringLength Unicode
471 characters, not including the
473 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
474 the range defined by UINTN.
480 IN CONST CHAR16
*String
,
481 OUT CHAR16
**EndPointer OPTIONAL
,
486 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
488 This function outputs a value of type UINT64 by interpreting the contents of
489 the Unicode string specified by String as a decimal number. The format of the
490 input Unicode string String is:
492 [spaces] [decimal digits].
494 The valid decimal digit character is in the range [0-9]. The function will
495 ignore the pad space, which includes spaces or tab characters, before
496 [decimal digits]. The running zero in the beginning of [decimal digits] will
497 be ignored. Then, the function stops at the first character that is a not a
498 valid decimal character or a Null-terminator, whichever one comes first.
500 If String is not aligned in a 16-bit boundary, then ASSERT().
502 If String has no valid decimal digits in the above format, then 0 is stored
503 at the location pointed to by Data.
504 If the number represented by String exceeds the range defined by UINT64, then
505 MAX_UINT64 is stored at the location pointed to by Data.
507 If EndPointer is not NULL, a pointer to the character that stopped the scan
508 is stored at the location pointed to by EndPointer. If String has no valid
509 decimal digits right after the optional pad spaces, the value of String is
510 stored at the location pointed to by EndPointer.
512 @param String Pointer to a Null-terminated Unicode string.
513 @param EndPointer Pointer to character that stops scan.
514 @param Data Pointer to the converted value.
516 @retval RETURN_SUCCESS Value is translated from String.
517 @retval RETURN_INVALID_PARAMETER If String is NULL.
519 If PcdMaximumUnicodeStringLength is not
520 zero, and String contains more than
521 PcdMaximumUnicodeStringLength Unicode
522 characters, not including the
524 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
525 the range defined by UINT64.
530 StrDecimalToUint64S (
531 IN CONST CHAR16
*String
,
532 OUT CHAR16
**EndPointer OPTIONAL
,
537 Convert a Null-terminated Unicode hexadecimal string to a value of type
540 This function outputs a value of type UINTN by interpreting the contents of
541 the Unicode string specified by String as a hexadecimal number. The format of
542 the input Unicode string String is:
544 [spaces][zeros][x][hexadecimal digits].
546 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
547 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
548 If "x" appears in the input string, it must be prefixed with at least one 0.
549 The function will ignore the pad space, which includes spaces or tab
550 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
551 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
552 after [x] or the first valid hexadecimal digit. Then, the function stops at
553 the first character that is a not a valid hexadecimal character or NULL,
554 whichever one comes first.
556 If String is not aligned in a 16-bit boundary, then ASSERT().
558 If String has no valid hexadecimal digits in the above format, then 0 is
559 stored at the location pointed to by Data.
560 If the number represented by String exceeds the range defined by UINTN, then
561 MAX_UINTN is stored at the location pointed to by Data.
563 If EndPointer is not NULL, a pointer to the character that stopped the scan
564 is stored at the location pointed to by EndPointer. If String has no valid
565 hexadecimal digits right after the optional pad spaces, the value of String
566 is stored at the location pointed to by EndPointer.
568 @param String Pointer to a Null-terminated Unicode string.
569 @param EndPointer Pointer to character that stops scan.
570 @param Data Pointer to the converted value.
572 @retval RETURN_SUCCESS Value is translated from String.
573 @retval RETURN_INVALID_PARAMETER If String is NULL.
575 If PcdMaximumUnicodeStringLength is not
576 zero, and String contains more than
577 PcdMaximumUnicodeStringLength Unicode
578 characters, not including the
580 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
581 the range defined by UINTN.
587 IN CONST CHAR16
*String
,
588 OUT CHAR16
**EndPointer OPTIONAL
,
593 Convert a Null-terminated Unicode hexadecimal string to a value of type
596 This function outputs a value of type UINT64 by interpreting the contents of
597 the Unicode string specified by String as a hexadecimal number. The format of
598 the input Unicode string String is:
600 [spaces][zeros][x][hexadecimal digits].
602 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
603 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
604 If "x" appears in the input string, it must be prefixed with at least one 0.
605 The function will ignore the pad space, which includes spaces or tab
606 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
607 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
608 after [x] or the first valid hexadecimal digit. Then, the function stops at
609 the first character that is a not a valid hexadecimal character or NULL,
610 whichever one comes first.
612 If String is not aligned in a 16-bit boundary, then ASSERT().
614 If String has no valid hexadecimal digits in the above format, then 0 is
615 stored at the location pointed to by Data.
616 If the number represented by String exceeds the range defined by UINT64, then
617 MAX_UINT64 is stored at the location pointed to by Data.
619 If EndPointer is not NULL, a pointer to the character that stopped the scan
620 is stored at the location pointed to by EndPointer. If String has no valid
621 hexadecimal digits right after the optional pad spaces, the value of String
622 is stored at the location pointed to by EndPointer.
624 @param String Pointer to a Null-terminated Unicode string.
625 @param EndPointer Pointer to character that stops scan.
626 @param Data Pointer to the converted value.
628 @retval RETURN_SUCCESS Value is translated from String.
629 @retval RETURN_INVALID_PARAMETER If String is NULL.
631 If PcdMaximumUnicodeStringLength is not
632 zero, and String contains more than
633 PcdMaximumUnicodeStringLength Unicode
634 characters, not including the
636 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
637 the range defined by UINT64.
643 IN CONST CHAR16
*String
,
644 OUT CHAR16
**EndPointer OPTIONAL
,
649 Returns the length of a Null-terminated Ascii string.
651 This function is similar as strlen_s defined in C11.
653 @param String A pointer to a Null-terminated Ascii string.
654 @param MaxSize The maximum number of Destination Ascii
655 char, including terminating null char.
657 @retval 0 If String is NULL.
658 @retval MaxSize If there is no null character in the first MaxSize characters of String.
659 @return The number of characters that percede the terminating null character.
665 IN CONST CHAR8
*String
,
670 Returns the size of a Null-terminated Ascii string in bytes, including the
673 This function returns the size of the Null-terminated Ascii string specified
674 by String in bytes, including the Null terminator.
676 @param String A pointer to a Null-terminated Ascii string.
677 @param MaxSize The maximum number of Destination Ascii
678 char, including the Null terminator.
680 @retval 0 If String is NULL.
681 @retval (sizeof (CHAR8) * (MaxSize + 1))
682 If there is no Null terminator in the first MaxSize characters of
684 @return The size of the Null-terminated Ascii string in bytes, including the
691 IN CONST CHAR8
*String
,
696 Copies the string pointed to by Source (including the terminating null char)
697 to the array pointed to by Destination.
699 This function is similar as strcpy_s defined in C11.
701 If an error is returned, then the Destination is unmodified.
703 @param Destination A pointer to a Null-terminated Ascii string.
704 @param DestMax The maximum number of Destination Ascii
705 char, including terminating null char.
706 @param Source A pointer to a Null-terminated Ascii string.
708 @retval RETURN_SUCCESS String is copied.
709 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
710 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
712 If PcdMaximumAsciiStringLength is not zero,
713 and DestMax is greater than
714 PcdMaximumAsciiStringLength.
716 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
721 OUT CHAR8
*Destination
,
723 IN CONST CHAR8
*Source
727 Copies not more than Length successive char from the string pointed to by
728 Source to the array pointed to by Destination. If no null char is copied from
729 Source, then Destination[Length] is always set to null.
731 This function is similar as strncpy_s defined in C11.
733 If an error is returned, then the Destination is unmodified.
735 @param Destination A pointer to a Null-terminated Ascii string.
736 @param DestMax The maximum number of Destination Ascii
737 char, including terminating null char.
738 @param Source A pointer to a Null-terminated Ascii string.
739 @param Length The maximum number of Ascii characters to copy.
741 @retval RETURN_SUCCESS String is copied.
742 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
743 MIN(StrLen(Source), Length).
744 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
746 If PcdMaximumAsciiStringLength is not zero,
747 and DestMax is greater than
748 PcdMaximumAsciiStringLength.
750 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
755 OUT CHAR8
*Destination
,
757 IN CONST CHAR8
*Source
,
762 Appends a copy of the string pointed to by Source (including the terminating
763 null char) to the end of the string pointed to by Destination.
765 This function is similar as strcat_s defined in C11.
767 If an error is returned, then the Destination is unmodified.
769 @param Destination A pointer to a Null-terminated Ascii string.
770 @param DestMax The maximum number of Destination Ascii
771 char, including terminating null char.
772 @param Source A pointer to a Null-terminated Ascii string.
774 @retval RETURN_SUCCESS String is appended.
775 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
777 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
778 greater than StrLen(Source).
779 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
781 If PcdMaximumAsciiStringLength is not zero,
782 and DestMax is greater than
783 PcdMaximumAsciiStringLength.
785 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
790 IN OUT CHAR8
*Destination
,
792 IN CONST CHAR8
*Source
796 Appends not more than Length successive char from the string pointed to by
797 Source to the end of the string pointed to by Destination. If no null char is
798 copied from Source, then Destination[StrLen(Destination) + Length] is always
801 This function is similar as strncat_s defined in C11.
803 If an error is returned, then the Destination is unmodified.
805 @param Destination A pointer to a Null-terminated Ascii string.
806 @param DestMax The maximum number of Destination Ascii
807 char, including terminating null char.
808 @param Source A pointer to a Null-terminated Ascii string.
809 @param Length The maximum number of Ascii characters to copy.
811 @retval RETURN_SUCCESS String is appended.
812 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
814 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
815 greater than MIN(StrLen(Source), Length).
816 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
818 If PcdMaximumAsciiStringLength is not zero,
819 and DestMax is greater than
820 PcdMaximumAsciiStringLength.
822 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
827 IN OUT CHAR8
*Destination
,
829 IN CONST CHAR8
*Source
,
834 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
836 This function outputs a value of type UINTN by interpreting the contents of
837 the Ascii string specified by String as a decimal number. The format of the
838 input Ascii string String is:
840 [spaces] [decimal digits].
842 The valid decimal digit character is in the range [0-9]. The function will
843 ignore the pad space, which includes spaces or tab characters, before
844 [decimal digits]. The running zero in the beginning of [decimal digits] will
845 be ignored. Then, the function stops at the first character that is a not a
846 valid decimal character or a Null-terminator, whichever one comes first.
848 If String has no valid decimal digits in the above format, then 0 is stored
849 at the location pointed to by Data.
850 If the number represented by String exceeds the range defined by UINTN, then
851 MAX_UINTN is stored at the location pointed to by Data.
853 If EndPointer is not NULL, a pointer to the character that stopped the scan
854 is stored at the location pointed to by EndPointer. If String has no valid
855 decimal digits right after the optional pad spaces, the value of String is
856 stored at the location pointed to by EndPointer.
858 @param String Pointer to a Null-terminated Ascii string.
859 @param EndPointer Pointer to character that stops scan.
860 @param Data Pointer to the converted value.
862 @retval RETURN_SUCCESS Value is translated from String.
863 @retval RETURN_INVALID_PARAMETER If String is NULL.
865 If PcdMaximumAsciiStringLength is not zero,
866 and String contains more than
867 PcdMaximumAsciiStringLength Ascii
868 characters, not including the
870 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
871 the range defined by UINTN.
876 AsciiStrDecimalToUintnS (
877 IN CONST CHAR8
*String
,
878 OUT CHAR8
**EndPointer OPTIONAL
,
883 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
885 This function outputs a value of type UINT64 by interpreting the contents of
886 the Ascii string specified by String as a decimal number. The format of the
887 input Ascii string String is:
889 [spaces] [decimal digits].
891 The valid decimal digit character is in the range [0-9]. The function will
892 ignore the pad space, which includes spaces or tab characters, before
893 [decimal digits]. The running zero in the beginning of [decimal digits] will
894 be ignored. Then, the function stops at the first character that is a not a
895 valid decimal character or a Null-terminator, whichever one comes first.
897 If String has no valid decimal digits in the above format, then 0 is stored
898 at the location pointed to by Data.
899 If the number represented by String exceeds the range defined by UINT64, then
900 MAX_UINT64 is stored at the location pointed to by Data.
902 If EndPointer is not NULL, a pointer to the character that stopped the scan
903 is stored at the location pointed to by EndPointer. If String has no valid
904 decimal digits right after the optional pad spaces, the value of String is
905 stored at the location pointed to by EndPointer.
907 @param String Pointer to a Null-terminated Ascii string.
908 @param EndPointer Pointer to character that stops scan.
909 @param Data Pointer to the converted value.
911 @retval RETURN_SUCCESS Value is translated from String.
912 @retval RETURN_INVALID_PARAMETER If String is NULL.
914 If PcdMaximumAsciiStringLength is not zero,
915 and String contains more than
916 PcdMaximumAsciiStringLength Ascii
917 characters, not including the
919 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
920 the range defined by UINT64.
925 AsciiStrDecimalToUint64S (
926 IN CONST CHAR8
*String
,
927 OUT CHAR8
**EndPointer OPTIONAL
,
932 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
934 This function outputs a value of type UINTN by interpreting the contents of
935 the Ascii string specified by String as a hexadecimal number. The format of
936 the input Ascii string String is:
938 [spaces][zeros][x][hexadecimal digits].
940 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
941 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
942 "x" appears in the input string, it must be prefixed with at least one 0. The
943 function will ignore the pad space, which includes spaces or tab characters,
944 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
945 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
946 the first valid hexadecimal digit. Then, the function stops at the first
947 character that is a not a valid hexadecimal character or Null-terminator,
948 whichever on comes first.
950 If String has no valid hexadecimal digits in the above format, then 0 is
951 stored at the location pointed to by Data.
952 If the number represented by String exceeds the range defined by UINTN, then
953 MAX_UINTN is stored at the location pointed to by Data.
955 If EndPointer is not NULL, a pointer to the character that stopped the scan
956 is stored at the location pointed to by EndPointer. If String has no valid
957 hexadecimal digits right after the optional pad spaces, the value of String
958 is stored at the location pointed to by EndPointer.
960 @param String Pointer to a Null-terminated Ascii string.
961 @param EndPointer Pointer to character that stops scan.
962 @param Data Pointer to the converted value.
964 @retval RETURN_SUCCESS Value is translated from String.
965 @retval RETURN_INVALID_PARAMETER If String is NULL.
967 If PcdMaximumAsciiStringLength is not zero,
968 and String contains more than
969 PcdMaximumAsciiStringLength Ascii
970 characters, not including the
972 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
973 the range defined by UINTN.
978 AsciiStrHexToUintnS (
979 IN CONST CHAR8
*String
,
980 OUT CHAR8
**EndPointer OPTIONAL
,
985 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
987 This function outputs a value of type UINT64 by interpreting the contents of
988 the Ascii string specified by String as a hexadecimal number. The format of
989 the input Ascii string String is:
991 [spaces][zeros][x][hexadecimal digits].
993 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
994 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
995 "x" appears in the input string, it must be prefixed with at least one 0. The
996 function will ignore the pad space, which includes spaces or tab characters,
997 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
998 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
999 the first valid hexadecimal digit. Then, the function stops at the first
1000 character that is a not a valid hexadecimal character or Null-terminator,
1001 whichever on comes first.
1003 If String has no valid hexadecimal digits in the above format, then 0 is
1004 stored at the location pointed to by Data.
1005 If the number represented by String exceeds the range defined by UINT64, then
1006 MAX_UINT64 is stored at the location pointed to by Data.
1008 If EndPointer is not NULL, a pointer to the character that stopped the scan
1009 is stored at the location pointed to by EndPointer. If String has no valid
1010 hexadecimal digits right after the optional pad spaces, the value of String
1011 is stored at the location pointed to by EndPointer.
1013 @param String Pointer to a Null-terminated Ascii string.
1014 @param EndPointer Pointer to character that stops scan.
1015 @param Data Pointer to the converted value.
1017 @retval RETURN_SUCCESS Value is translated from String.
1018 @retval RETURN_INVALID_PARAMETER If String is NULL.
1020 If PcdMaximumAsciiStringLength is not zero,
1021 and String contains more than
1022 PcdMaximumAsciiStringLength Ascii
1023 characters, not including the
1025 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
1026 the range defined by UINT64.
1031 AsciiStrHexToUint64S (
1032 IN CONST CHAR8
*String
,
1033 OUT CHAR8
**EndPointer OPTIONAL
,
1038 Returns the length of a Null-terminated Unicode string.
1040 This function returns the number of Unicode characters in the Null-terminated
1041 Unicode string specified by String.
1043 If String is NULL, then ASSERT().
1044 If String is not aligned on a 16-bit boundary, then ASSERT().
1045 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1046 PcdMaximumUnicodeStringLength Unicode characters not including the
1047 Null-terminator, then ASSERT().
1049 @param String Pointer to a Null-terminated Unicode string.
1051 @return The length of String.
1057 IN CONST CHAR16
*String
1061 Returns the size of a Null-terminated Unicode string in bytes, including the
1064 This function returns the size, in bytes, of the Null-terminated Unicode string
1065 specified by String.
1067 If String is NULL, then ASSERT().
1068 If String is not aligned on a 16-bit boundary, then ASSERT().
1069 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1070 PcdMaximumUnicodeStringLength Unicode characters not including the
1071 Null-terminator, then ASSERT().
1073 @param String The pointer to a Null-terminated Unicode string.
1075 @return The size of String.
1081 IN CONST CHAR16
*String
1085 Compares two Null-terminated Unicode strings, and returns the difference
1086 between the first mismatched Unicode characters.
1088 This function compares the Null-terminated Unicode string FirstString to the
1089 Null-terminated Unicode string SecondString. If FirstString is identical to
1090 SecondString, then 0 is returned. Otherwise, the value returned is the first
1091 mismatched Unicode character in SecondString subtracted from the first
1092 mismatched Unicode character in FirstString.
1094 If FirstString is NULL, then ASSERT().
1095 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1096 If SecondString is NULL, then ASSERT().
1097 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1098 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1099 than PcdMaximumUnicodeStringLength Unicode characters not including the
1100 Null-terminator, then ASSERT().
1101 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1102 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1103 Null-terminator, then ASSERT().
1105 @param FirstString The pointer to a Null-terminated Unicode string.
1106 @param SecondString The pointer to a Null-terminated Unicode string.
1108 @retval 0 FirstString is identical to SecondString.
1109 @return others FirstString is not identical to SecondString.
1115 IN CONST CHAR16
*FirstString
,
1116 IN CONST CHAR16
*SecondString
1120 Compares up to a specified length the contents of two Null-terminated Unicode strings,
1121 and returns the difference between the first mismatched Unicode characters.
1123 This function compares the Null-terminated Unicode string FirstString to the
1124 Null-terminated Unicode string SecondString. At most, Length Unicode
1125 characters will be compared. If Length is 0, then 0 is returned. If
1126 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1127 value returned is the first mismatched Unicode character in SecondString
1128 subtracted from the first mismatched Unicode character in FirstString.
1130 If Length > 0 and FirstString is NULL, then ASSERT().
1131 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1132 If Length > 0 and SecondString is NULL, then ASSERT().
1133 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1134 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1135 PcdMaximumUnicodeStringLength, then ASSERT().
1136 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1137 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1139 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1140 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1143 @param FirstString The pointer to a Null-terminated Unicode string.
1144 @param SecondString The pointer to a Null-terminated Unicode string.
1145 @param Length The maximum number of Unicode characters to compare.
1147 @retval 0 FirstString is identical to SecondString.
1148 @return others FirstString is not identical to SecondString.
1154 IN CONST CHAR16
*FirstString
,
1155 IN CONST CHAR16
*SecondString
,
1160 Returns the first occurrence of a Null-terminated Unicode sub-string
1161 in a Null-terminated Unicode string.
1163 This function scans the contents of the Null-terminated Unicode string
1164 specified by String and returns the first occurrence of SearchString.
1165 If SearchString is not found in String, then NULL is returned. If
1166 the length of SearchString is zero, then String is returned.
1168 If String is NULL, then ASSERT().
1169 If String is not aligned on a 16-bit boundary, then ASSERT().
1170 If SearchString is NULL, then ASSERT().
1171 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1173 If PcdMaximumUnicodeStringLength is not zero, and SearchString
1174 or String contains more than PcdMaximumUnicodeStringLength Unicode
1175 characters, not including the Null-terminator, then ASSERT().
1177 @param String The pointer to a Null-terminated Unicode string.
1178 @param SearchString The pointer to a Null-terminated Unicode string to search for.
1180 @retval NULL If the SearchString does not appear in String.
1181 @return others If there is a match.
1187 IN CONST CHAR16
*String
,
1188 IN CONST CHAR16
*SearchString
1192 Convert a Null-terminated Unicode decimal string to a value of
1195 This function returns a value of type UINTN by interpreting the contents
1196 of the Unicode string specified by String as a decimal number. The format
1197 of the input Unicode string String is:
1199 [spaces] [decimal digits].
1201 The valid decimal digit character is in the range [0-9]. The
1202 function will ignore the pad space, which includes spaces or
1203 tab characters, before [decimal digits]. The running zero in the
1204 beginning of [decimal digits] will be ignored. Then, the function
1205 stops at the first character that is a not a valid decimal character
1206 or a Null-terminator, whichever one comes first.
1208 If String is NULL, then ASSERT().
1209 If String is not aligned in a 16-bit boundary, then ASSERT().
1210 If String has only pad spaces, then 0 is returned.
1211 If String has no pad spaces or valid decimal digits,
1213 If the number represented by String overflows according
1214 to the range defined by UINTN, then MAX_UINTN is returned.
1216 If PcdMaximumUnicodeStringLength is not zero, and String contains
1217 more than PcdMaximumUnicodeStringLength Unicode characters not including
1218 the Null-terminator, then ASSERT().
1220 @param String The pointer to a Null-terminated Unicode string.
1222 @retval Value translated from String.
1228 IN CONST CHAR16
*String
1232 Convert a Null-terminated Unicode decimal string to a value of
1235 This function returns a value of type UINT64 by interpreting the contents
1236 of the Unicode string specified by String as a decimal number. The format
1237 of the input Unicode string String is:
1239 [spaces] [decimal digits].
1241 The valid decimal digit character is in the range [0-9]. The
1242 function will ignore the pad space, which includes spaces or
1243 tab characters, before [decimal digits]. The running zero in the
1244 beginning of [decimal digits] will be ignored. Then, the function
1245 stops at the first character that is a not a valid decimal character
1246 or a Null-terminator, whichever one comes first.
1248 If String is NULL, then ASSERT().
1249 If String is not aligned in a 16-bit boundary, then ASSERT().
1250 If String has only pad spaces, then 0 is returned.
1251 If String has no pad spaces or valid decimal digits,
1253 If the number represented by String overflows according
1254 to the range defined by UINT64, then MAX_UINT64 is returned.
1256 If PcdMaximumUnicodeStringLength is not zero, and String contains
1257 more than PcdMaximumUnicodeStringLength Unicode characters not including
1258 the Null-terminator, then ASSERT().
1260 @param String The pointer to a Null-terminated Unicode string.
1262 @retval Value translated from String.
1267 StrDecimalToUint64 (
1268 IN CONST CHAR16
*String
1272 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1274 This function returns a value of type UINTN by interpreting the contents
1275 of the Unicode string specified by String as a hexadecimal number.
1276 The format of the input Unicode string String is:
1278 [spaces][zeros][x][hexadecimal digits].
1280 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1281 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1282 If "x" appears in the input string, it must be prefixed with at least one 0.
1283 The function will ignore the pad space, which includes spaces or tab characters,
1284 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1285 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1286 first valid hexadecimal digit. Then, the function stops at the first character
1287 that is a not a valid hexadecimal character or NULL, whichever one comes first.
1289 If String is NULL, then ASSERT().
1290 If String is not aligned in a 16-bit boundary, then ASSERT().
1291 If String has only pad spaces, then zero is returned.
1292 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1293 then zero is returned.
1294 If the number represented by String overflows according to the range defined by
1295 UINTN, then MAX_UINTN is returned.
1297 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1298 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1301 @param String The pointer to a Null-terminated Unicode string.
1303 @retval Value translated from String.
1309 IN CONST CHAR16
*String
1313 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1315 This function returns a value of type UINT64 by interpreting the contents
1316 of the Unicode string specified by String as a hexadecimal number.
1317 The format of the input Unicode string String is
1319 [spaces][zeros][x][hexadecimal digits].
1321 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1322 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1323 If "x" appears in the input string, it must be prefixed with at least one 0.
1324 The function will ignore the pad space, which includes spaces or tab characters,
1325 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1326 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1327 first valid hexadecimal digit. Then, the function stops at the first character that is
1328 a not a valid hexadecimal character or NULL, whichever one comes first.
1330 If String is NULL, then ASSERT().
1331 If String is not aligned in a 16-bit boundary, then ASSERT().
1332 If String has only pad spaces, then zero is returned.
1333 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1334 then zero is returned.
1335 If the number represented by String overflows according to the range defined by
1336 UINT64, then MAX_UINT64 is returned.
1338 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1339 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1342 @param String The pointer to a Null-terminated Unicode string.
1344 @retval Value translated from String.
1350 IN CONST CHAR16
*String
1354 Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1356 This function outputs a value of type IPv6_ADDRESS and may output a value
1357 of type UINT8 by interpreting the contents of the Unicode string specified
1358 by String. The format of the input Unicode string String is as follows:
1362 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1363 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1364 memory address and high byte is stored in high memory address. P contains decimal
1365 digit characters in the range [0-9]. The running zero in the beginning of P will
1366 be ignored. /P is optional.
1368 When /P is not in the String, the function stops at the first character that is
1369 not a valid hexadecimal digit character after eight X's are converted.
1371 When /P is in the String, the function stops at the first character that is not
1372 a valid decimal digit character after P is converted.
1374 "::" can be used to compress one or more groups of X when X contains only 0.
1375 The "::" can only appear once in the String.
1377 If String is not aligned in a 16-bit boundary, then ASSERT().
1379 If EndPointer is not NULL and Address is translated from String, a pointer
1380 to the character that stopped the scan is stored at the location pointed to
1383 @param String Pointer to a Null-terminated Unicode string.
1384 @param EndPointer Pointer to character that stops scan.
1385 @param Address Pointer to the converted IPv6 address.
1386 @param PrefixLength Pointer to the converted IPv6 address prefix
1387 length. MAX_UINT8 is returned when /P is
1390 @retval RETURN_SUCCESS Address is translated from String.
1391 @retval RETURN_INVALID_PARAMETER If String is NULL.
1393 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1395 If String contains "::" and number of X
1397 If P starts with character that is not a
1398 valid decimal digit character.
1399 If the decimal number converted from P
1406 IN CONST CHAR16
*String
,
1407 OUT CHAR16
**EndPointer OPTIONAL
,
1408 OUT IPv6_ADDRESS
*Address
,
1409 OUT UINT8
*PrefixLength OPTIONAL
1413 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1415 This function outputs a value of type IPv4_ADDRESS and may output a value
1416 of type UINT8 by interpreting the contents of the Unicode string specified
1417 by String. The format of the input Unicode string String is as follows:
1421 D and P are decimal digit characters in the range [0-9]. The running zero in
1422 the beginning of D and P will be ignored. /P is optional.
1424 When /P is not in the String, the function stops at the first character that is
1425 not a valid decimal digit character after four D's are converted.
1427 When /P is in the String, the function stops at the first character that is not
1428 a valid decimal digit character after P is converted.
1430 If String is not aligned in a 16-bit boundary, then ASSERT().
1432 If EndPointer is not NULL and Address is translated from String, a pointer
1433 to the character that stopped the scan is stored at the location pointed to
1436 @param String Pointer to a Null-terminated Unicode string.
1437 @param EndPointer Pointer to character that stops scan.
1438 @param Address Pointer to the converted IPv4 address.
1439 @param PrefixLength Pointer to the converted IPv4 address prefix
1440 length. MAX_UINT8 is returned when /P is
1443 @retval RETURN_SUCCESS Address is translated from String.
1444 @retval RETURN_INVALID_PARAMETER If String is NULL.
1446 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1447 If any decimal number converted from D
1449 If the decimal number converted from P
1456 IN CONST CHAR16
*String
,
1457 OUT CHAR16
**EndPointer OPTIONAL
,
1458 OUT IPv4_ADDRESS
*Address
,
1459 OUT UINT8
*PrefixLength OPTIONAL
1462 #define GUID_STRING_LENGTH 36
1465 Convert a Null-terminated Unicode GUID string to a value of type
1468 This function outputs a GUID value by interpreting the contents of
1469 the Unicode string specified by String. The format of the input
1470 Unicode string String consists of 36 characters, as follows:
1472 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1474 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1475 [A-F], with each pair representing a single byte hexadecimal value.
1477 The mapping between String and the EFI_GUID structure is as follows:
1495 If String is not aligned in a 16-bit boundary, then ASSERT().
1497 @param String Pointer to a Null-terminated Unicode string.
1498 @param Guid Pointer to the converted GUID.
1500 @retval RETURN_SUCCESS Guid is translated from String.
1501 @retval RETURN_INVALID_PARAMETER If String is NULL.
1503 @retval RETURN_UNSUPPORTED If String is not as the above format.
1509 IN CONST CHAR16
*String
,
1514 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1516 This function outputs a byte array by interpreting the contents of
1517 the Unicode string specified by String in hexadecimal format. The format of
1518 the input Unicode string String is:
1522 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1523 The function decodes every two hexadecimal digit characters as one byte. The
1524 decoding stops after Length of characters and outputs Buffer containing
1527 If String is not aligned in a 16-bit boundary, then ASSERT().
1529 @param String Pointer to a Null-terminated Unicode string.
1530 @param Length The number of Unicode characters to decode.
1531 @param Buffer Pointer to the converted bytes array.
1532 @param MaxBufferSize The maximum size of Buffer.
1534 @retval RETURN_SUCCESS Buffer is translated from String.
1535 @retval RETURN_INVALID_PARAMETER If String is NULL.
1537 If Length is not multiple of 2.
1538 If PcdMaximumUnicodeStringLength is not zero,
1539 and Length is greater than
1540 PcdMaximumUnicodeStringLength.
1541 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1542 a character that is not valid hexadecimal
1543 digit characters, or a Null-terminator.
1544 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1549 IN CONST CHAR16
*String
,
1552 IN UINTN MaxBufferSize
1556 Convert a Null-terminated Unicode string to a Null-terminated
1559 This function is similar to AsciiStrCpyS.
1561 This function converts the content of the Unicode string Source
1562 to the ASCII string Destination by copying the lower 8 bits of
1563 each Unicode character. The function terminates the ASCII string
1564 Destination by appending a Null-terminator character at the end.
1566 The caller is responsible to make sure Destination points to a buffer with size
1567 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1569 If any Unicode characters in Source contain non-zero value in
1570 the upper 8 bits, then ASSERT().
1572 If Source is not aligned on a 16-bit boundary, then ASSERT().
1574 If an error is returned, then the Destination is unmodified.
1576 @param Source The pointer to a Null-terminated Unicode string.
1577 @param Destination The pointer to a Null-terminated ASCII string.
1578 @param DestMax The maximum number of Destination Ascii
1579 char, including terminating null char.
1581 @retval RETURN_SUCCESS String is converted.
1582 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1583 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1585 If PcdMaximumAsciiStringLength is not zero,
1586 and DestMax is greater than
1587 PcdMaximumAsciiStringLength.
1588 If PcdMaximumUnicodeStringLength is not zero,
1589 and DestMax is greater than
1590 PcdMaximumUnicodeStringLength.
1592 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1597 UnicodeStrToAsciiStrS (
1598 IN CONST CHAR16
*Source
,
1599 OUT CHAR8
*Destination
,
1604 Convert not more than Length successive characters from a Null-terminated
1605 Unicode string to a Null-terminated Ascii string. If no null char is copied
1606 from Source, then Destination[Length] is always set to null.
1608 This function converts not more than Length successive characters from the
1609 Unicode string Source to the Ascii string Destination by copying the lower 8
1610 bits of each Unicode character. The function terminates the Ascii string
1611 Destination by appending a Null-terminator character at the end.
1613 The caller is responsible to make sure Destination points to a buffer with size
1614 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1616 If any Unicode characters in Source contain non-zero value in the upper 8
1617 bits, then ASSERT().
1618 If Source is not aligned on a 16-bit boundary, then ASSERT().
1620 If an error is returned, then the Destination is unmodified.
1622 @param Source The pointer to a Null-terminated Unicode string.
1623 @param Length The maximum number of Unicode characters to
1625 @param Destination The pointer to a Null-terminated Ascii string.
1626 @param DestMax The maximum number of Destination Ascii
1627 char, including terminating null char.
1628 @param DestinationLength The number of Unicode characters converted.
1630 @retval RETURN_SUCCESS String is converted.
1631 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1633 If DestinationLength is NULL.
1634 If PcdMaximumAsciiStringLength is not zero,
1635 and Length or DestMax is greater than
1636 PcdMaximumAsciiStringLength.
1637 If PcdMaximumUnicodeStringLength is not
1638 zero, and Length or DestMax is greater than
1639 PcdMaximumUnicodeStringLength.
1641 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1642 MIN(StrLen(Source), Length).
1643 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1648 UnicodeStrnToAsciiStrS (
1649 IN CONST CHAR16
*Source
,
1651 OUT CHAR8
*Destination
,
1653 OUT UINTN
*DestinationLength
1657 Returns the length of a Null-terminated ASCII string.
1659 This function returns the number of ASCII characters in the Null-terminated
1660 ASCII string specified by String.
1662 If Length > 0 and Destination is NULL, then ASSERT().
1663 If Length > 0 and Source is NULL, then ASSERT().
1664 If PcdMaximumAsciiStringLength is not zero and String contains more than
1665 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1668 @param String The pointer to a Null-terminated ASCII string.
1670 @return The length of String.
1676 IN CONST CHAR8
*String
1680 Returns the size of a Null-terminated ASCII string in bytes, including the
1683 This function returns the size, in bytes, of the Null-terminated ASCII string
1684 specified by String.
1686 If String is NULL, then ASSERT().
1687 If PcdMaximumAsciiStringLength is not zero and String contains more than
1688 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1691 @param String The pointer to a Null-terminated ASCII string.
1693 @return The size of String.
1699 IN CONST CHAR8
*String
1703 Compares two Null-terminated ASCII strings, and returns the difference
1704 between the first mismatched ASCII characters.
1706 This function compares the Null-terminated ASCII string FirstString to the
1707 Null-terminated ASCII string SecondString. If FirstString is identical to
1708 SecondString, then 0 is returned. Otherwise, the value returned is the first
1709 mismatched ASCII character in SecondString subtracted from the first
1710 mismatched ASCII character in FirstString.
1712 If FirstString is NULL, then ASSERT().
1713 If SecondString is NULL, then ASSERT().
1714 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1715 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1717 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1718 than PcdMaximumAsciiStringLength ASCII characters not including the
1719 Null-terminator, then ASSERT().
1721 @param FirstString The pointer to a Null-terminated ASCII string.
1722 @param SecondString The pointer to a Null-terminated ASCII string.
1724 @retval ==0 FirstString is identical to SecondString.
1725 @retval !=0 FirstString is not identical to SecondString.
1731 IN CONST CHAR8
*FirstString
,
1732 IN CONST CHAR8
*SecondString
1736 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1737 and returns the difference between the first mismatched ASCII characters.
1739 This function performs a case insensitive comparison of the Null-terminated
1740 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1741 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1742 value returned is the first mismatched lower case ASCII character in
1743 SecondString subtracted from the first mismatched lower case ASCII character
1746 If FirstString is NULL, then ASSERT().
1747 If SecondString is NULL, then ASSERT().
1748 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1749 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1751 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1752 than PcdMaximumAsciiStringLength ASCII characters not including the
1753 Null-terminator, then ASSERT().
1755 @param FirstString The pointer to a Null-terminated ASCII string.
1756 @param SecondString The pointer to a Null-terminated ASCII string.
1758 @retval ==0 FirstString is identical to SecondString using case insensitive
1760 @retval !=0 FirstString is not identical to SecondString using case
1761 insensitive comparisons.
1767 IN CONST CHAR8
*FirstString
,
1768 IN CONST CHAR8
*SecondString
1772 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1773 the difference between the first mismatched ASCII characters.
1775 This function compares the Null-terminated ASCII string FirstString to the
1776 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1777 will be compared. If Length is 0, then 0 is returned. If FirstString is
1778 identical to SecondString, then 0 is returned. Otherwise, the value returned
1779 is the first mismatched ASCII character in SecondString subtracted from the
1780 first mismatched ASCII character in FirstString.
1782 If Length > 0 and FirstString is NULL, then ASSERT().
1783 If Length > 0 and SecondString is NULL, then ASSERT().
1784 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1785 PcdMaximumAsciiStringLength, then ASSERT().
1786 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
1787 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1789 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
1790 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1793 @param FirstString The pointer to a Null-terminated ASCII string.
1794 @param SecondString The pointer to a Null-terminated ASCII string.
1795 @param Length The maximum number of ASCII characters for compare.
1797 @retval ==0 FirstString is identical to SecondString.
1798 @retval !=0 FirstString is not identical to SecondString.
1804 IN CONST CHAR8
*FirstString
,
1805 IN CONST CHAR8
*SecondString
,
1810 Returns the first occurrence of a Null-terminated ASCII sub-string
1811 in a Null-terminated ASCII string.
1813 This function scans the contents of the ASCII string specified by String
1814 and returns the first occurrence of SearchString. If SearchString is not
1815 found in String, then NULL is returned. If the length of SearchString is zero,
1816 then String is returned.
1818 If String is NULL, then ASSERT().
1819 If SearchString is NULL, then ASSERT().
1821 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1822 String contains more than PcdMaximumAsciiStringLength Unicode characters
1823 not including the Null-terminator, then ASSERT().
1825 @param String The pointer to a Null-terminated ASCII string.
1826 @param SearchString The pointer to a Null-terminated ASCII string to search for.
1828 @retval NULL If the SearchString does not appear in String.
1829 @retval others If there is a match return the first occurrence of SearchingString.
1830 If the length of SearchString is zero,return String.
1836 IN CONST CHAR8
*String
,
1837 IN CONST CHAR8
*SearchString
1841 Convert a Null-terminated ASCII decimal string to a value of type
1844 This function returns a value of type UINTN by interpreting the contents
1845 of the ASCII string String as a decimal number. The format of the input
1846 ASCII string String is:
1848 [spaces] [decimal digits].
1850 The valid decimal digit character is in the range [0-9]. The function will
1851 ignore the pad space, which includes spaces or tab characters, before the digits.
1852 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1853 function stops at the first character that is a not a valid decimal character or
1854 Null-terminator, whichever on comes first.
1856 If String has only pad spaces, then 0 is returned.
1857 If String has no pad spaces or valid decimal digits, then 0 is returned.
1858 If the number represented by String overflows according to the range defined by
1859 UINTN, then MAX_UINTN is returned.
1860 If String is NULL, then ASSERT().
1861 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1862 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1865 @param String The pointer to a Null-terminated ASCII string.
1867 @retval The value translated from String.
1872 AsciiStrDecimalToUintn (
1873 IN CONST CHAR8
*String
1877 Convert a Null-terminated ASCII decimal string to a value of type
1880 This function returns a value of type UINT64 by interpreting the contents
1881 of the ASCII string String as a decimal number. The format of the input
1882 ASCII string String is:
1884 [spaces] [decimal digits].
1886 The valid decimal digit character is in the range [0-9]. The function will
1887 ignore the pad space, which includes spaces or tab characters, before the digits.
1888 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1889 function stops at the first character that is a not a valid decimal character or
1890 Null-terminator, whichever on comes first.
1892 If String has only pad spaces, then 0 is returned.
1893 If String has no pad spaces or valid decimal digits, then 0 is returned.
1894 If the number represented by String overflows according to the range defined by
1895 UINT64, then MAX_UINT64 is returned.
1896 If String is NULL, then ASSERT().
1897 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1898 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1901 @param String The pointer to a Null-terminated ASCII string.
1903 @retval Value translated from String.
1908 AsciiStrDecimalToUint64 (
1909 IN CONST CHAR8
*String
1913 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1915 This function returns a value of type UINTN by interpreting the contents of
1916 the ASCII string String as a hexadecimal number. The format of the input ASCII
1919 [spaces][zeros][x][hexadecimal digits].
1921 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1922 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1923 appears in the input string, it must be prefixed with at least one 0. The function
1924 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1925 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1926 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1927 digit. Then, the function stops at the first character that is a not a valid
1928 hexadecimal character or Null-terminator, whichever on comes first.
1930 If String has only pad spaces, then 0 is returned.
1931 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1934 If the number represented by String overflows according to the range defined by UINTN,
1935 then MAX_UINTN is returned.
1936 If String is NULL, then ASSERT().
1937 If PcdMaximumAsciiStringLength is not zero,
1938 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1939 the Null-terminator, then ASSERT().
1941 @param String The pointer to a Null-terminated ASCII string.
1943 @retval Value translated from String.
1948 AsciiStrHexToUintn (
1949 IN CONST CHAR8
*String
1953 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1955 This function returns a value of type UINT64 by interpreting the contents of
1956 the ASCII string String as a hexadecimal number. The format of the input ASCII
1959 [spaces][zeros][x][hexadecimal digits].
1961 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1962 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1963 appears in the input string, it must be prefixed with at least one 0. The function
1964 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1965 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1966 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1967 digit. Then, the function stops at the first character that is a not a valid
1968 hexadecimal character or Null-terminator, whichever on comes first.
1970 If String has only pad spaces, then 0 is returned.
1971 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1974 If the number represented by String overflows according to the range defined by UINT64,
1975 then MAX_UINT64 is returned.
1976 If String is NULL, then ASSERT().
1977 If PcdMaximumAsciiStringLength is not zero,
1978 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1979 the Null-terminator, then ASSERT().
1981 @param String The pointer to a Null-terminated ASCII string.
1983 @retval Value translated from String.
1988 AsciiStrHexToUint64 (
1989 IN CONST CHAR8
*String
1993 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
1995 This function outputs a value of type IPv6_ADDRESS and may output a value
1996 of type UINT8 by interpreting the contents of the ASCII string specified
1997 by String. The format of the input ASCII string String is as follows:
2001 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
2002 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
2003 memory address and high byte is stored in high memory address. P contains decimal
2004 digit characters in the range [0-9]. The running zero in the beginning of P will
2005 be ignored. /P is optional.
2007 When /P is not in the String, the function stops at the first character that is
2008 not a valid hexadecimal digit character after eight X's are converted.
2010 When /P is in the String, the function stops at the first character that is not
2011 a valid decimal digit character after P is converted.
2013 "::" can be used to compress one or more groups of X when X contains only 0.
2014 The "::" can only appear once in the String.
2016 If EndPointer is not NULL and Address is translated from String, a pointer
2017 to the character that stopped the scan is stored at the location pointed to
2020 @param String Pointer to a Null-terminated ASCII string.
2021 @param EndPointer Pointer to character that stops scan.
2022 @param Address Pointer to the converted IPv6 address.
2023 @param PrefixLength Pointer to the converted IPv6 address prefix
2024 length. MAX_UINT8 is returned when /P is
2027 @retval RETURN_SUCCESS Address is translated from String.
2028 @retval RETURN_INVALID_PARAMETER If String is NULL.
2030 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
2032 If String contains "::" and number of X
2034 If P starts with character that is not a
2035 valid decimal digit character.
2036 If the decimal number converted from P
2042 AsciiStrToIpv6Address (
2043 IN CONST CHAR8
*String
,
2044 OUT CHAR8
**EndPointer OPTIONAL
,
2045 OUT IPv6_ADDRESS
*Address
,
2046 OUT UINT8
*PrefixLength OPTIONAL
2050 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
2052 This function outputs a value of type IPv4_ADDRESS and may output a value
2053 of type UINT8 by interpreting the contents of the ASCII string specified
2054 by String. The format of the input ASCII string String is as follows:
2058 D and P are decimal digit characters in the range [0-9]. The running zero in
2059 the beginning of D and P will be ignored. /P is optional.
2061 When /P is not in the String, the function stops at the first character that is
2062 not a valid decimal digit character after four D's are converted.
2064 When /P is in the String, the function stops at the first character that is not
2065 a valid decimal digit character after P is converted.
2067 If EndPointer is not NULL and Address is translated from String, a pointer
2068 to the character that stopped the scan is stored at the location pointed to
2071 @param String Pointer to a Null-terminated ASCII string.
2072 @param EndPointer Pointer to character that stops scan.
2073 @param Address Pointer to the converted IPv4 address.
2074 @param PrefixLength Pointer to the converted IPv4 address prefix
2075 length. MAX_UINT8 is returned when /P is
2078 @retval RETURN_SUCCESS Address is translated from String.
2079 @retval RETURN_INVALID_PARAMETER If String is NULL.
2081 @retval RETURN_UNSUPPORTED If String is not in the correct format.
2082 If any decimal number converted from D
2084 If the decimal number converted from P
2090 AsciiStrToIpv4Address (
2091 IN CONST CHAR8
*String
,
2092 OUT CHAR8
**EndPointer OPTIONAL
,
2093 OUT IPv4_ADDRESS
*Address
,
2094 OUT UINT8
*PrefixLength OPTIONAL
2098 Convert a Null-terminated ASCII GUID string to a value of type
2101 This function outputs a GUID value by interpreting the contents of
2102 the ASCII string specified by String. The format of the input
2103 ASCII string String consists of 36 characters, as follows:
2105 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
2107 The pairs aa - pp are two characters in the range [0-9], [a-f] and
2108 [A-F], with each pair representing a single byte hexadecimal value.
2110 The mapping between String and the EFI_GUID structure is as follows:
2128 @param String Pointer to a Null-terminated ASCII string.
2129 @param Guid Pointer to the converted GUID.
2131 @retval RETURN_SUCCESS Guid is translated from String.
2132 @retval RETURN_INVALID_PARAMETER If String is NULL.
2134 @retval RETURN_UNSUPPORTED If String is not as the above format.
2140 IN CONST CHAR8
*String
,
2145 Convert a Null-terminated ASCII hexadecimal string to a byte array.
2147 This function outputs a byte array by interpreting the contents of
2148 the ASCII string specified by String in hexadecimal format. The format of
2149 the input ASCII string String is:
2153 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
2154 The function decodes every two hexadecimal digit characters as one byte. The
2155 decoding stops after Length of characters and outputs Buffer containing
2158 @param String Pointer to a Null-terminated ASCII string.
2159 @param Length The number of ASCII characters to decode.
2160 @param Buffer Pointer to the converted bytes array.
2161 @param MaxBufferSize The maximum size of Buffer.
2163 @retval RETURN_SUCCESS Buffer is translated from String.
2164 @retval RETURN_INVALID_PARAMETER If String is NULL.
2166 If Length is not multiple of 2.
2167 If PcdMaximumAsciiStringLength is not zero,
2168 and Length is greater than
2169 PcdMaximumAsciiStringLength.
2170 @retval RETURN_UNSUPPORTED If Length of characters from String contain
2171 a character that is not valid hexadecimal
2172 digit characters, or a Null-terminator.
2173 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
2177 AsciiStrHexToBytes (
2178 IN CONST CHAR8
*String
,
2181 IN UINTN MaxBufferSize
2185 Convert one Null-terminated ASCII string to a Null-terminated
2188 This function is similar to StrCpyS.
2190 This function converts the contents of the ASCII string Source to the Unicode
2191 string Destination. The function terminates the Unicode string Destination by
2192 appending a Null-terminator character at the end.
2194 The caller is responsible to make sure Destination points to a buffer with size
2195 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2197 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2199 If an error is returned, then the Destination is unmodified.
2201 @param Source The pointer to a Null-terminated ASCII string.
2202 @param Destination The pointer to a Null-terminated Unicode string.
2203 @param DestMax The maximum number of Destination Unicode
2204 char, including terminating null char.
2206 @retval RETURN_SUCCESS String is converted.
2207 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2208 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2210 If PcdMaximumUnicodeStringLength is not zero,
2211 and DestMax is greater than
2212 PcdMaximumUnicodeStringLength.
2213 If PcdMaximumAsciiStringLength is not zero,
2214 and DestMax is greater than
2215 PcdMaximumAsciiStringLength.
2217 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2222 AsciiStrToUnicodeStrS (
2223 IN CONST CHAR8
*Source
,
2224 OUT CHAR16
*Destination
,
2229 Convert not more than Length successive characters from a Null-terminated
2230 Ascii string to a Null-terminated Unicode string. If no null char is copied
2231 from Source, then Destination[Length] is always set to null.
2233 This function converts not more than Length successive characters from the
2234 Ascii string Source to the Unicode string Destination. The function
2235 terminates the Unicode string Destination by appending a Null-terminator
2236 character at the end.
2238 The caller is responsible to make sure Destination points to a buffer with
2239 size not smaller than
2240 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2242 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2244 If an error is returned, then Destination and DestinationLength are
2247 @param Source The pointer to a Null-terminated Ascii string.
2248 @param Length The maximum number of Ascii characters to convert.
2249 @param Destination The pointer to a Null-terminated Unicode string.
2250 @param DestMax The maximum number of Destination Unicode char,
2251 including terminating null char.
2252 @param DestinationLength The number of Ascii characters converted.
2254 @retval RETURN_SUCCESS String is converted.
2255 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2257 If DestinationLength is NULL.
2258 If PcdMaximumUnicodeStringLength is not
2259 zero, and Length or DestMax is greater than
2260 PcdMaximumUnicodeStringLength.
2261 If PcdMaximumAsciiStringLength is not zero,
2262 and Length or DestMax is greater than
2263 PcdMaximumAsciiStringLength.
2265 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2266 MIN(AsciiStrLen(Source), Length).
2267 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2272 AsciiStrnToUnicodeStrS (
2273 IN CONST CHAR8
*Source
,
2275 OUT CHAR16
*Destination
,
2277 OUT UINTN
*DestinationLength
2281 Convert a Unicode character to upper case only if
2282 it maps to a valid small-case ASCII character.
2284 This internal function only deal with Unicode character
2285 which maps to a valid small-case ASCII character, i.e.
2286 L'a' to L'z'. For other Unicode character, the input character
2287 is returned directly.
2289 @param Char The character to convert.
2291 @retval LowerCharacter If the Char is with range L'a' to L'z'.
2292 @retval Unchanged Otherwise.
2302 Converts a lowercase Ascii character to upper one.
2304 If Chr is lowercase Ascii character, then converts it to upper one.
2306 If Value >= 0xA0, then ASSERT().
2307 If (Value & 0x0F) >= 0x0A, then ASSERT().
2309 @param Chr one Ascii character
2311 @return The uppercase value of Ascii character
2321 Convert binary data to a Base64 encoded ascii string based on RFC4648.
2323 Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
2324 The Ascii string is produced by converting the data string specified by Source and SourceLength.
2326 @param Source Input UINT8 data
2327 @param SourceLength Number of UINT8 bytes of data
2328 @param Destination Pointer to output string buffer
2329 @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed.
2330 Caller is responsible for passing in buffer of DestinationSize
2332 @retval RETURN_SUCCESS When ascii buffer is filled in.
2333 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
2334 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
2335 @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1.
2336 @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize.
2342 IN CONST UINT8
*Source
,
2343 IN UINTN SourceLength
,
2344 OUT CHAR8
*Destination OPTIONAL
,
2345 IN OUT UINTN
*DestinationSize
2349 Decode Base64 ASCII encoded data to 8-bit binary representation, based on
2352 Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648.
2354 Whitespace is ignored at all positions:
2355 - 0x09 ('\t') horizontal tab
2356 - 0x0A ('\n') new line
2357 - 0x0B ('\v') vertical tab
2358 - 0x0C ('\f') form feed
2359 - 0x0D ('\r') carriage return
2362 The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated
2363 and enforced at the end of the Base64 ASCII encoded data, and only there.
2365 Other characters outside of the encoding alphabet cause the function to
2366 reject the Base64 ASCII encoded data.
2368 @param[in] Source Array of CHAR8 elements containing the Base64
2369 ASCII encoding. May be NULL if SourceSize is
2372 @param[in] SourceSize Number of CHAR8 elements in Source.
2374 @param[out] Destination Array of UINT8 elements receiving the decoded
2375 8-bit binary representation. Allocated by the
2376 caller. May be NULL if DestinationSize is
2377 zero on input. If NULL, decoding is
2378 performed, but the 8-bit binary
2379 representation is not stored. If non-NULL and
2380 the function returns an error, the contents
2381 of Destination are indeterminate.
2383 @param[in,out] DestinationSize On input, the number of UINT8 elements that
2384 the caller allocated for Destination. On
2385 output, if the function returns
2386 RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL,
2387 the number of UINT8 elements that are
2388 required for decoding the Base64 ASCII
2389 representation. If the function returns a
2390 value different from both RETURN_SUCCESS and
2391 RETURN_BUFFER_TOO_SMALL, then DestinationSize
2392 is indeterminate on output.
2394 @retval RETURN_SUCCESS SourceSize CHAR8 elements at Source have
2395 been decoded to on-output DestinationSize
2396 UINT8 elements at Destination. Note that
2397 RETURN_SUCCESS covers the case when
2398 DestinationSize is zero on input, and
2399 Source decodes to zero bytes (due to
2400 containing at most ignored whitespace).
2402 @retval RETURN_BUFFER_TOO_SMALL The input value of DestinationSize is not
2403 large enough for decoding SourceSize CHAR8
2404 elements at Source. The required number of
2405 UINT8 elements has been stored to
2408 @retval RETURN_INVALID_PARAMETER DestinationSize is NULL.
2410 @retval RETURN_INVALID_PARAMETER Source is NULL, but SourceSize is not zero.
2412 @retval RETURN_INVALID_PARAMETER Destination is NULL, but DestinationSize is
2415 @retval RETURN_INVALID_PARAMETER Source is non-NULL, and (Source +
2416 SourceSize) would wrap around MAX_ADDRESS.
2418 @retval RETURN_INVALID_PARAMETER Destination is non-NULL, and (Destination +
2419 DestinationSize) would wrap around
2420 MAX_ADDRESS, as specified on input.
2422 @retval RETURN_INVALID_PARAMETER None of Source and Destination are NULL,
2423 and CHAR8[SourceSize] at Source overlaps
2424 UINT8[DestinationSize] at Destination, as
2427 @retval RETURN_INVALID_PARAMETER Invalid CHAR8 element encountered in
2433 IN CONST CHAR8
*Source OPTIONAL
,
2434 IN UINTN SourceSize
,
2435 OUT UINT8
*Destination OPTIONAL
,
2436 IN OUT UINTN
*DestinationSize
2440 Converts an 8-bit value to an 8-bit BCD value.
2442 Converts the 8-bit value specified by Value to BCD. The BCD value is
2445 If Value >= 100, then ASSERT().
2447 @param Value The 8-bit value to convert to BCD. Range 0..99.
2449 @return The BCD value.
2459 Converts an 8-bit BCD value to an 8-bit value.
2461 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2464 If Value >= 0xA0, then ASSERT().
2465 If (Value & 0x0F) >= 0x0A, then ASSERT().
2467 @param Value The 8-bit BCD value to convert to an 8-bit value.
2469 @return The 8-bit value is returned.
2479 // File Path Manipulation Functions
2483 Removes the last directory or file entry in a path.
2485 @param[in, out] Path The pointer to the path to modify.
2487 @retval FALSE Nothing was found to remove.
2488 @retval TRUE A directory or file was removed.
2492 PathRemoveLastItem (
2497 Function to clean up paths.
2498 - Single periods in the path are removed.
2499 - Double periods in the path are removed along with a single parent directory.
2500 - Forward slashes L'/' are converted to backward slashes L'\'.
2502 This will be done inline and the existing buffer may be larger than required
2505 @param[in] Path The pointer to the string containing the path.
2507 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2511 PathCleanUpDirectories (
2516 // Linked List Functions and Macros
2520 Initializes the head node of a doubly linked list that is declared as a
2521 global variable in a module.
2523 Initializes the forward and backward links of a new linked list. After
2524 initializing a linked list with this macro, the other linked list functions
2525 may be used to add and remove nodes from the linked list. This macro results
2526 in smaller executables by initializing the linked list in the data section,
2527 instead if calling the InitializeListHead() function to perform the
2528 equivalent operation.
2530 @param ListHead The head note of a list to initialize.
2533 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2536 Iterates over each node in a doubly linked list using each node's forward link.
2538 @param Entry A pointer to a list node used as a loop cursor during iteration
2539 @param ListHead The head node of the doubly linked list
2542 #define BASE_LIST_FOR_EACH(Entry, ListHead) \
2543 for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)
2546 Iterates over each node in a doubly linked list using each node's forward link
2547 with safety against node removal.
2549 This macro uses NextEntry to temporarily store the next list node so the node
2550 pointed to by Entry may be deleted in the current loop iteration step and
2551 iteration can continue from the node pointed to by NextEntry.
2553 @param Entry A pointer to a list node used as a loop cursor during iteration
2554 @param NextEntry A pointer to a list node used to temporarily store the next node
2555 @param ListHead The head node of the doubly linked list
2558 #define BASE_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \
2559 for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
2560 Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
2563 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2566 If FirstEntry is NULL, then ASSERT().
2567 If FirstEntry->ForwardLink is NULL, then ASSERT().
2568 If FirstEntry->BackLink is NULL, then ASSERT().
2569 If SecondEntry is NULL, then ASSERT();
2570 If PcdMaximumLinkedListLength is not zero, and List contains more than
2571 PcdMaximumLinkedListLength nodes, then ASSERT().
2573 @param FirstEntry A pointer to a node in a linked list.
2574 @param SecondEntry A pointer to the node to locate.
2576 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.
2577 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,
2578 or FirstEntry is invalid.
2584 IN CONST LIST_ENTRY
*FirstEntry
,
2585 IN CONST LIST_ENTRY
*SecondEntry
2589 Initializes the head node of a doubly linked list, and returns the pointer to
2590 the head node of the doubly linked list.
2592 Initializes the forward and backward links of a new linked list. After
2593 initializing a linked list with this function, the other linked list
2594 functions may be used to add and remove nodes from the linked list. It is up
2595 to the caller of this function to allocate the memory for ListHead.
2597 If ListHead is NULL, then ASSERT().
2599 @param ListHead A pointer to the head node of a new doubly linked list.
2606 InitializeListHead (
2607 IN OUT LIST_ENTRY
*ListHead
2611 Adds a node to the beginning of a doubly linked list, and returns the pointer
2612 to the head node of the doubly linked list.
2614 Adds the node Entry at the beginning of the doubly linked list denoted by
2615 ListHead, and returns ListHead.
2617 If ListHead is NULL, then ASSERT().
2618 If Entry is NULL, then ASSERT().
2619 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2620 InitializeListHead(), then ASSERT().
2621 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2622 of nodes in ListHead, including the ListHead node, is greater than or
2623 equal to PcdMaximumLinkedListLength, then ASSERT().
2625 @param ListHead A pointer to the head node of a doubly linked list.
2626 @param Entry A pointer to a node that is to be inserted at the beginning
2627 of a doubly linked list.
2635 IN OUT LIST_ENTRY
*ListHead
,
2636 IN OUT LIST_ENTRY
*Entry
2640 Adds a node to the end of a doubly linked list, and returns the pointer to
2641 the head node of the doubly linked list.
2643 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2644 and returns ListHead.
2646 If ListHead is NULL, then ASSERT().
2647 If Entry is NULL, then ASSERT().
2648 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2649 InitializeListHead(), then ASSERT().
2650 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2651 of nodes in ListHead, including the ListHead node, is greater than or
2652 equal to PcdMaximumLinkedListLength, then ASSERT().
2654 @param ListHead A pointer to the head node of a doubly linked list.
2655 @param Entry A pointer to a node that is to be added at the end of the
2664 IN OUT LIST_ENTRY
*ListHead
,
2665 IN OUT LIST_ENTRY
*Entry
2669 Retrieves the first node of a doubly linked list.
2671 Returns the first node of a doubly linked list. List must have been
2672 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2673 If List is empty, then List is returned.
2675 If List is NULL, then ASSERT().
2676 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2677 InitializeListHead(), then ASSERT().
2678 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2679 in List, including the List node, is greater than or equal to
2680 PcdMaximumLinkedListLength, then ASSERT().
2682 @param List A pointer to the head node of a doubly linked list.
2684 @return The first node of a doubly linked list.
2685 @retval List The list is empty.
2691 IN CONST LIST_ENTRY
*List
2695 Retrieves the next node of a doubly linked list.
2697 Returns the node of a doubly linked list that follows Node.
2698 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2699 or InitializeListHead(). If List is empty, then List is returned.
2701 If List is NULL, then ASSERT().
2702 If Node is NULL, then ASSERT().
2703 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2704 InitializeListHead(), then ASSERT().
2705 If PcdMaximumLinkedListLength is not zero, and List contains more than
2706 PcdMaximumLinkedListLength nodes, then ASSERT().
2707 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2709 @param List A pointer to the head node of a doubly linked list.
2710 @param Node A pointer to a node in the doubly linked list.
2712 @return The pointer to the next node if one exists. Otherwise List is returned.
2718 IN CONST LIST_ENTRY
*List
,
2719 IN CONST LIST_ENTRY
*Node
2723 Retrieves the previous node of a doubly linked list.
2725 Returns the node of a doubly linked list that precedes Node.
2726 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2727 or InitializeListHead(). If List is empty, then List is returned.
2729 If List is NULL, then ASSERT().
2730 If Node is NULL, then ASSERT().
2731 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2732 InitializeListHead(), then ASSERT().
2733 If PcdMaximumLinkedListLength is not zero, and List contains more than
2734 PcdMaximumLinkedListLength nodes, then ASSERT().
2735 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2737 @param List A pointer to the head node of a doubly linked list.
2738 @param Node A pointer to a node in the doubly linked list.
2740 @return The pointer to the previous node if one exists. Otherwise List is returned.
2746 IN CONST LIST_ENTRY
*List
,
2747 IN CONST LIST_ENTRY
*Node
2751 Checks to see if a doubly linked list is empty or not.
2753 Checks to see if the doubly linked list is empty. If the linked list contains
2754 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
2756 If ListHead is NULL, then ASSERT().
2757 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2758 InitializeListHead(), then ASSERT().
2759 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2760 in List, including the List node, is greater than or equal to
2761 PcdMaximumLinkedListLength, then ASSERT().
2763 @param ListHead A pointer to the head node of a doubly linked list.
2765 @retval TRUE The linked list is empty.
2766 @retval FALSE The linked list is not empty.
2772 IN CONST LIST_ENTRY
*ListHead
2776 Determines if a node in a doubly linked list is the head node of a the same
2777 doubly linked list. This function is typically used to terminate a loop that
2778 traverses all the nodes in a doubly linked list starting with the head node.
2780 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
2781 nodes in the doubly linked list specified by List. List must have been
2782 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2784 If List is NULL, then ASSERT().
2785 If Node is NULL, then ASSERT().
2786 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
2788 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2789 in List, including the List node, is greater than or equal to
2790 PcdMaximumLinkedListLength, then ASSERT().
2791 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
2792 to List, then ASSERT().
2794 @param List A pointer to the head node of a doubly linked list.
2795 @param Node A pointer to a node in the doubly linked list.
2797 @retval TRUE Node is the head of the doubly-linked list pointed by List.
2798 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
2804 IN CONST LIST_ENTRY
*List
,
2805 IN CONST LIST_ENTRY
*Node
2809 Determines if a node the last node in a doubly linked list.
2811 Returns TRUE if Node is the last node in the doubly linked list specified by
2812 List. Otherwise, FALSE is returned. List must have been initialized with
2813 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2815 If List is NULL, then ASSERT().
2816 If Node is NULL, then ASSERT().
2817 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2818 InitializeListHead(), then ASSERT().
2819 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2820 in List, including the List node, is greater than or equal to
2821 PcdMaximumLinkedListLength, then ASSERT().
2822 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2824 @param List A pointer to the head node of a doubly linked list.
2825 @param Node A pointer to a node in the doubly linked list.
2827 @retval TRUE Node is the last node in the linked list.
2828 @retval FALSE Node is not the last node in the linked list.
2834 IN CONST LIST_ENTRY
*List
,
2835 IN CONST LIST_ENTRY
*Node
2839 Swaps the location of two nodes in a doubly linked list, and returns the
2840 first node after the swap.
2842 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
2843 Otherwise, the location of the FirstEntry node is swapped with the location
2844 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
2845 same double linked list as FirstEntry and that double linked list must have
2846 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2847 SecondEntry is returned after the nodes are swapped.
2849 If FirstEntry is NULL, then ASSERT().
2850 If SecondEntry is NULL, then ASSERT().
2851 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
2852 same linked list, then ASSERT().
2853 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2854 linked list containing the FirstEntry and SecondEntry nodes, including
2855 the FirstEntry and SecondEntry nodes, is greater than or equal to
2856 PcdMaximumLinkedListLength, then ASSERT().
2858 @param FirstEntry A pointer to a node in a linked list.
2859 @param SecondEntry A pointer to another node in the same linked list.
2861 @return SecondEntry.
2867 IN OUT LIST_ENTRY
*FirstEntry
,
2868 IN OUT LIST_ENTRY
*SecondEntry
2872 Removes a node from a doubly linked list, and returns the node that follows
2875 Removes the node Entry from a doubly linked list. It is up to the caller of
2876 this function to release the memory used by this node if that is required. On
2877 exit, the node following Entry in the doubly linked list is returned. If
2878 Entry is the only node in the linked list, then the head node of the linked
2881 If Entry is NULL, then ASSERT().
2882 If Entry is the head node of an empty list, then ASSERT().
2883 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2884 linked list containing Entry, including the Entry node, is greater than
2885 or equal to PcdMaximumLinkedListLength, then ASSERT().
2887 @param Entry A pointer to a node in a linked list.
2895 IN CONST LIST_ENTRY
*Entry
2903 Prototype for comparison function for any two element types.
2905 @param[in] Buffer1 The pointer to first buffer.
2906 @param[in] Buffer2 The pointer to second buffer.
2908 @retval 0 Buffer1 equal to Buffer2.
2909 @return <0 Buffer1 is less than Buffer2.
2910 @return >0 Buffer1 is greater than Buffer2.
2914 (EFIAPI
*BASE_SORT_COMPARE
)(
2915 IN CONST VOID
*Buffer1
,
2916 IN CONST VOID
*Buffer2
2920 This function is identical to perform QuickSort,
2921 except that is uses the pre-allocated buffer so the in place sorting does not need to
2922 allocate and free buffers constantly.
2924 Each element must be equal sized.
2926 if BufferToSort is NULL, then ASSERT.
2927 if CompareFunction is NULL, then ASSERT.
2928 if BufferOneElement is NULL, then ASSERT.
2929 if ElementSize is < 1, then ASSERT.
2931 if Count is < 2 then perform no action.
2933 @param[in, out] BufferToSort on call a Buffer of (possibly sorted) elements
2934 on return a buffer of sorted elements
2935 @param[in] Count the number of elements in the buffer to sort
2936 @param[in] ElementSize Size of an element in bytes
2937 @param[in] CompareFunction The function to call to perform the comparison
2939 @param[out] BufferOneElement Caller provided buffer whose size equals to ElementSize.
2940 It's used by QuickSort() for swapping in sorting.
2945 IN OUT VOID
*BufferToSort
,
2946 IN CONST UINTN Count
,
2947 IN CONST UINTN ElementSize
,
2948 IN BASE_SORT_COMPARE CompareFunction
,
2949 OUT VOID
*BufferOneElement
2953 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
2954 with zeros. The shifted value is returned.
2956 This function shifts the 64-bit value Operand to the left by Count bits. The
2957 low Count bits are set to zero. The shifted value is returned.
2959 If Count is greater than 63, then ASSERT().
2961 @param Operand The 64-bit operand to shift left.
2962 @param Count The number of bits to shift left.
2964 @return Operand << Count.
2975 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
2976 filled with zeros. The shifted value is returned.
2978 This function shifts the 64-bit value Operand to the right by Count bits. The
2979 high Count bits are set to zero. The shifted value is returned.
2981 If Count is greater than 63, then ASSERT().
2983 @param Operand The 64-bit operand to shift right.
2984 @param Count The number of bits to shift right.
2986 @return Operand >> Count
2997 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
2998 with original integer's bit 63. The shifted value is returned.
3000 This function shifts the 64-bit value Operand to the right by Count bits. The
3001 high Count bits are set to bit 63 of Operand. The shifted value is returned.
3003 If Count is greater than 63, then ASSERT().
3005 @param Operand The 64-bit operand to shift right.
3006 @param Count The number of bits to shift right.
3008 @return Operand >> Count
3019 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
3020 with the high bits that were rotated.
3022 This function rotates the 32-bit value Operand to the left by Count bits. The
3023 low Count bits are fill with the high Count bits of Operand. The rotated
3026 If Count is greater than 31, then ASSERT().
3028 @param Operand The 32-bit operand to rotate left.
3029 @param Count The number of bits to rotate left.
3031 @return Operand << Count
3042 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
3043 with the low bits that were rotated.
3045 This function rotates the 32-bit value Operand to the right by Count bits.
3046 The high Count bits are fill with the low Count bits of Operand. The rotated
3049 If Count is greater than 31, then ASSERT().
3051 @param Operand The 32-bit operand to rotate right.
3052 @param Count The number of bits to rotate right.
3054 @return Operand >> Count
3065 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3066 with the high bits that were rotated.
3068 This function rotates the 64-bit value Operand to the left by Count bits. The
3069 low Count bits are fill with the high Count bits of Operand. The rotated
3072 If Count is greater than 63, then ASSERT().
3074 @param Operand The 64-bit operand to rotate left.
3075 @param Count The number of bits to rotate left.
3077 @return Operand << Count
3088 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3089 with the high low bits that were rotated.
3091 This function rotates the 64-bit value Operand to the right by Count bits.
3092 The high Count bits are fill with the low Count bits of Operand. The rotated
3095 If Count is greater than 63, then ASSERT().
3097 @param Operand The 64-bit operand to rotate right.
3098 @param Count The number of bits to rotate right.
3100 @return Operand >> Count
3111 Returns the bit position of the lowest bit set in a 32-bit value.
3113 This function computes the bit position of the lowest bit set in the 32-bit
3114 value specified by Operand. If Operand is zero, then -1 is returned.
3115 Otherwise, a value between 0 and 31 is returned.
3117 @param Operand The 32-bit operand to evaluate.
3119 @retval 0..31 The lowest bit set in Operand was found.
3120 @retval -1 Operand is zero.
3130 Returns the bit position of the lowest bit set in a 64-bit value.
3132 This function computes the bit position of the lowest bit set in the 64-bit
3133 value specified by Operand. If Operand is zero, then -1 is returned.
3134 Otherwise, a value between 0 and 63 is returned.
3136 @param Operand The 64-bit operand to evaluate.
3138 @retval 0..63 The lowest bit set in Operand was found.
3139 @retval -1 Operand is zero.
3150 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3153 This function computes the bit position of the highest bit set in the 32-bit
3154 value specified by Operand. If Operand is zero, then -1 is returned.
3155 Otherwise, a value between 0 and 31 is returned.
3157 @param Operand The 32-bit operand to evaluate.
3159 @retval 0..31 Position of the highest bit set in Operand if found.
3160 @retval -1 Operand is zero.
3170 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3173 This function computes the bit position of the highest bit set in the 64-bit
3174 value specified by Operand. If Operand is zero, then -1 is returned.
3175 Otherwise, a value between 0 and 63 is returned.
3177 @param Operand The 64-bit operand to evaluate.
3179 @retval 0..63 Position of the highest bit set in Operand if found.
3180 @retval -1 Operand is zero.
3190 Returns the value of the highest bit set in a 32-bit value. Equivalent to
3193 This function computes the value of the highest bit set in the 32-bit value
3194 specified by Operand. If Operand is zero, then zero is returned.
3196 @param Operand The 32-bit operand to evaluate.
3198 @return 1 << HighBitSet32(Operand)
3199 @retval 0 Operand is zero.
3209 Returns the value of the highest bit set in a 64-bit value. Equivalent to
3212 This function computes the value of the highest bit set in the 64-bit value
3213 specified by Operand. If Operand is zero, then zero is returned.
3215 @param Operand The 64-bit operand to evaluate.
3217 @return 1 << HighBitSet64(Operand)
3218 @retval 0 Operand is zero.
3228 Switches the endianness of a 16-bit integer.
3230 This function swaps the bytes in a 16-bit unsigned value to switch the value
3231 from little endian to big endian or vice versa. The byte swapped value is
3234 @param Value A 16-bit unsigned value.
3236 @return The byte swapped Value.
3246 Switches the endianness of a 32-bit integer.
3248 This function swaps the bytes in a 32-bit unsigned value to switch the value
3249 from little endian to big endian or vice versa. The byte swapped value is
3252 @param Value A 32-bit unsigned value.
3254 @return The byte swapped Value.
3264 Switches the endianness of a 64-bit integer.
3266 This function swaps the bytes in a 64-bit unsigned value to switch the value
3267 from little endian to big endian or vice versa. The byte swapped value is
3270 @param Value A 64-bit unsigned value.
3272 @return The byte swapped Value.
3282 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3283 generates a 64-bit unsigned result.
3285 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3286 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3287 bit unsigned result is returned.
3289 @param Multiplicand A 64-bit unsigned value.
3290 @param Multiplier A 32-bit unsigned value.
3292 @return Multiplicand * Multiplier
3298 IN UINT64 Multiplicand
,
3299 IN UINT32 Multiplier
3303 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3304 generates a 64-bit unsigned result.
3306 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3307 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3308 bit unsigned result is returned.
3310 @param Multiplicand A 64-bit unsigned value.
3311 @param Multiplier A 64-bit unsigned value.
3313 @return Multiplicand * Multiplier.
3319 IN UINT64 Multiplicand
,
3320 IN UINT64 Multiplier
3324 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3325 64-bit signed result.
3327 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3328 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3329 signed result is returned.
3331 @param Multiplicand A 64-bit signed value.
3332 @param Multiplier A 64-bit signed value.
3334 @return Multiplicand * Multiplier
3340 IN INT64 Multiplicand
,
3345 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3346 a 64-bit unsigned result.
3348 This function divides the 64-bit unsigned value Dividend by the 32-bit
3349 unsigned value Divisor and generates a 64-bit unsigned quotient. This
3350 function returns the 64-bit unsigned quotient.
3352 If Divisor is 0, then ASSERT().
3354 @param Dividend A 64-bit unsigned value.
3355 @param Divisor A 32-bit unsigned value.
3357 @return Dividend / Divisor.
3368 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3369 a 32-bit unsigned remainder.
3371 This function divides the 64-bit unsigned value Dividend by the 32-bit
3372 unsigned value Divisor and generates a 32-bit remainder. This function
3373 returns the 32-bit unsigned remainder.
3375 If Divisor is 0, then ASSERT().
3377 @param Dividend A 64-bit unsigned value.
3378 @param Divisor A 32-bit unsigned value.
3380 @return Dividend % Divisor.
3391 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3392 a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3394 This function divides the 64-bit unsigned value Dividend by the 32-bit
3395 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3396 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3397 This function returns the 64-bit unsigned quotient.
3399 If Divisor is 0, then ASSERT().
3401 @param Dividend A 64-bit unsigned value.
3402 @param Divisor A 32-bit unsigned value.
3403 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3404 optional and may be NULL.
3406 @return Dividend / Divisor.
3411 DivU64x32Remainder (
3414 OUT UINT32
*Remainder OPTIONAL
3418 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3419 a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3421 This function divides the 64-bit unsigned value Dividend by the 64-bit
3422 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3423 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3424 This function returns the 64-bit unsigned quotient.
3426 If Divisor is 0, then ASSERT().
3428 @param Dividend A 64-bit unsigned value.
3429 @param Divisor A 64-bit unsigned value.
3430 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3431 optional and may be NULL.
3433 @return Dividend / Divisor.
3438 DivU64x64Remainder (
3441 OUT UINT64
*Remainder OPTIONAL
3445 Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3446 64-bit signed result and a optional 64-bit signed remainder.
3448 This function divides the 64-bit signed value Dividend by the 64-bit signed
3449 value Divisor and generates a 64-bit signed quotient. If Remainder is not
3450 NULL, then the 64-bit signed remainder is returned in Remainder. This
3451 function returns the 64-bit signed quotient.
3453 It is the caller's responsibility to not call this function with a Divisor of 0.
3454 If Divisor is 0, then the quotient and remainder should be assumed to be
3455 the largest negative integer.
3457 If Divisor is 0, then ASSERT().
3459 @param Dividend A 64-bit signed value.
3460 @param Divisor A 64-bit signed value.
3461 @param Remainder A pointer to a 64-bit signed value. This parameter is
3462 optional and may be NULL.
3464 @return Dividend / Divisor.
3469 DivS64x64Remainder (
3472 OUT INT64
*Remainder OPTIONAL
3476 Reads a 16-bit value from memory that may be unaligned.
3478 This function returns the 16-bit value pointed to by Buffer. The function
3479 guarantees that the read operation does not produce an alignment fault.
3481 If the Buffer is NULL, then ASSERT().
3483 @param Buffer The pointer to a 16-bit value that may be unaligned.
3485 @return The 16-bit value read from Buffer.
3491 IN CONST UINT16
*Buffer
3495 Writes a 16-bit value to memory that may be unaligned.
3497 This function writes the 16-bit value specified by Value to Buffer. Value is
3498 returned. The function guarantees that the write operation does not produce
3501 If the Buffer is NULL, then ASSERT().
3503 @param Buffer The pointer to a 16-bit value that may be unaligned.
3504 @param Value 16-bit value to write to Buffer.
3506 @return The 16-bit value to write to Buffer.
3517 Reads a 24-bit value from memory that may be unaligned.
3519 This function returns the 24-bit value pointed to by Buffer. The function
3520 guarantees that the read operation does not produce an alignment fault.
3522 If the Buffer is NULL, then ASSERT().
3524 @param Buffer The pointer to a 24-bit value that may be unaligned.
3526 @return The 24-bit value read from Buffer.
3532 IN CONST UINT32
*Buffer
3536 Writes a 24-bit value to memory that may be unaligned.
3538 This function writes the 24-bit value specified by Value to Buffer. Value is
3539 returned. The function guarantees that the write operation does not produce
3542 If the Buffer is NULL, then ASSERT().
3544 @param Buffer The pointer to a 24-bit value that may be unaligned.
3545 @param Value 24-bit value to write to Buffer.
3547 @return The 24-bit value to write to Buffer.
3558 Reads a 32-bit value from memory that may be unaligned.
3560 This function returns the 32-bit value pointed to by Buffer. The function
3561 guarantees that the read operation does not produce an alignment fault.
3563 If the Buffer is NULL, then ASSERT().
3565 @param Buffer The pointer to a 32-bit value that may be unaligned.
3567 @return The 32-bit value read from Buffer.
3573 IN CONST UINT32
*Buffer
3577 Writes a 32-bit value to memory that may be unaligned.
3579 This function writes the 32-bit value specified by Value to Buffer. Value is
3580 returned. The function guarantees that the write operation does not produce
3583 If the Buffer is NULL, then ASSERT().
3585 @param Buffer The pointer to a 32-bit value that may be unaligned.
3586 @param Value 32-bit value to write to Buffer.
3588 @return The 32-bit value to write to Buffer.
3599 Reads a 64-bit value from memory that may be unaligned.
3601 This function returns the 64-bit value pointed to by Buffer. The function
3602 guarantees that the read operation does not produce an alignment fault.
3604 If the Buffer is NULL, then ASSERT().
3606 @param Buffer The pointer to a 64-bit value that may be unaligned.
3608 @return The 64-bit value read from Buffer.
3614 IN CONST UINT64
*Buffer
3618 Writes a 64-bit value to memory that may be unaligned.
3620 This function writes the 64-bit value specified by Value to Buffer. Value is
3621 returned. The function guarantees that the write operation does not produce
3624 If the Buffer is NULL, then ASSERT().
3626 @param Buffer The pointer to a 64-bit value that may be unaligned.
3627 @param Value 64-bit value to write to Buffer.
3629 @return The 64-bit value to write to Buffer.
3640 // Bit Field Functions
3644 Returns a bit field from an 8-bit value.
3646 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3648 If 8-bit operations are not supported, then ASSERT().
3649 If StartBit is greater than 7, then ASSERT().
3650 If EndBit is greater than 7, then ASSERT().
3651 If EndBit is less than StartBit, then ASSERT().
3653 @param Operand Operand on which to perform the bitfield operation.
3654 @param StartBit The ordinal of the least significant bit in the bit field.
3656 @param EndBit The ordinal of the most significant bit in the bit field.
3659 @return The bit field read.
3671 Writes a bit field to an 8-bit value, and returns the result.
3673 Writes Value to the bit field specified by the StartBit and the EndBit in
3674 Operand. All other bits in Operand are preserved. The new 8-bit value is
3677 If 8-bit operations are not supported, then ASSERT().
3678 If StartBit is greater than 7, then ASSERT().
3679 If EndBit is greater than 7, then ASSERT().
3680 If EndBit is less than StartBit, then ASSERT().
3681 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3683 @param Operand Operand on which to perform the bitfield operation.
3684 @param StartBit The ordinal of the least significant bit in the bit field.
3686 @param EndBit The ordinal of the most significant bit in the bit field.
3688 @param Value New value of the bit field.
3690 @return The new 8-bit value.
3703 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
3706 Performs a bitwise OR between the bit field specified by StartBit
3707 and EndBit in Operand and the value specified by OrData. All other bits in
3708 Operand are preserved. The new 8-bit value is returned.
3710 If 8-bit operations are not supported, then ASSERT().
3711 If StartBit is greater than 7, then ASSERT().
3712 If EndBit is greater than 7, then ASSERT().
3713 If EndBit is less than StartBit, then ASSERT().
3714 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3716 @param Operand Operand on which to perform the bitfield operation.
3717 @param StartBit The ordinal of the least significant bit in the bit field.
3719 @param EndBit The ordinal of the most significant bit in the bit field.
3721 @param OrData The value to OR with the read value from the value
3723 @return The new 8-bit value.
3736 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
3739 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3740 in Operand and the value specified by AndData. All other bits in Operand are
3741 preserved. The new 8-bit value is returned.
3743 If 8-bit operations are not supported, then ASSERT().
3744 If StartBit is greater than 7, then ASSERT().
3745 If EndBit is greater than 7, then ASSERT().
3746 If EndBit is less than StartBit, then ASSERT().
3747 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3749 @param Operand Operand on which to perform the bitfield operation.
3750 @param StartBit The ordinal of the least significant bit in the bit field.
3752 @param EndBit The ordinal of the most significant bit in the bit field.
3754 @param AndData The value to AND with the read value from the value.
3756 @return The new 8-bit value.
3769 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
3770 bitwise OR, and returns the result.
3772 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3773 in Operand and the value specified by AndData, followed by a bitwise
3774 OR with value specified by OrData. All other bits in Operand are
3775 preserved. The new 8-bit value is returned.
3777 If 8-bit operations are not supported, then ASSERT().
3778 If StartBit is greater than 7, then ASSERT().
3779 If EndBit is greater than 7, then ASSERT().
3780 If EndBit is less than StartBit, then ASSERT().
3781 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3782 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3784 @param Operand Operand on which to perform the bitfield operation.
3785 @param StartBit The ordinal of the least significant bit in the bit field.
3787 @param EndBit The ordinal of the most significant bit in the bit field.
3789 @param AndData The value to AND with the read value from the value.
3790 @param OrData The value to OR with the result of the AND operation.
3792 @return The new 8-bit value.
3797 BitFieldAndThenOr8 (
3806 Returns a bit field from a 16-bit value.
3808 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3810 If 16-bit operations are not supported, then ASSERT().
3811 If StartBit is greater than 15, then ASSERT().
3812 If EndBit is greater than 15, then ASSERT().
3813 If EndBit is less than StartBit, then ASSERT().
3815 @param Operand Operand on which to perform the bitfield operation.
3816 @param StartBit The ordinal of the least significant bit in the bit field.
3818 @param EndBit The ordinal of the most significant bit in the bit field.
3821 @return The bit field read.
3833 Writes a bit field to a 16-bit value, and returns the result.
3835 Writes Value to the bit field specified by the StartBit and the EndBit in
3836 Operand. All other bits in Operand are preserved. The new 16-bit value is
3839 If 16-bit operations are not supported, then ASSERT().
3840 If StartBit is greater than 15, then ASSERT().
3841 If EndBit is greater than 15, then ASSERT().
3842 If EndBit is less than StartBit, then ASSERT().
3843 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3845 @param Operand Operand on which to perform the bitfield operation.
3846 @param StartBit The ordinal of the least significant bit in the bit field.
3848 @param EndBit The ordinal of the most significant bit in the bit field.
3850 @param Value New value of the bit field.
3852 @return The new 16-bit value.
3865 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
3868 Performs a bitwise OR between the bit field specified by StartBit
3869 and EndBit in Operand and the value specified by OrData. All other bits in
3870 Operand are preserved. The new 16-bit value is returned.
3872 If 16-bit operations are not supported, then ASSERT().
3873 If StartBit is greater than 15, then ASSERT().
3874 If EndBit is greater than 15, then ASSERT().
3875 If EndBit is less than StartBit, then ASSERT().
3876 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3878 @param Operand Operand on which to perform the bitfield operation.
3879 @param StartBit The ordinal of the least significant bit in the bit field.
3881 @param EndBit The ordinal of the most significant bit in the bit field.
3883 @param OrData The value to OR with the read value from the value
3885 @return The new 16-bit value.
3898 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
3901 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3902 in Operand and the value specified by AndData. All other bits in Operand are
3903 preserved. The new 16-bit value is returned.
3905 If 16-bit operations are not supported, then ASSERT().
3906 If StartBit is greater than 15, then ASSERT().
3907 If EndBit is greater than 15, then ASSERT().
3908 If EndBit is less than StartBit, then ASSERT().
3909 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3911 @param Operand Operand on which to perform the bitfield operation.
3912 @param StartBit The ordinal of the least significant bit in the bit field.
3914 @param EndBit The ordinal of the most significant bit in the bit field.
3916 @param AndData The value to AND with the read value from the value
3918 @return The new 16-bit value.
3931 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
3932 bitwise OR, and returns the result.
3934 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3935 in Operand and the value specified by AndData, followed by a bitwise
3936 OR with value specified by OrData. All other bits in Operand are
3937 preserved. The new 16-bit value is returned.
3939 If 16-bit operations are not supported, then ASSERT().
3940 If StartBit is greater than 15, then ASSERT().
3941 If EndBit is greater than 15, then ASSERT().
3942 If EndBit is less than StartBit, then ASSERT().
3943 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3944 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3946 @param Operand Operand on which to perform the bitfield operation.
3947 @param StartBit The ordinal of the least significant bit in the bit field.
3949 @param EndBit The ordinal of the most significant bit in the bit field.
3951 @param AndData The value to AND with the read value from the value.
3952 @param OrData The value to OR with the result of the AND operation.
3954 @return The new 16-bit value.
3959 BitFieldAndThenOr16 (
3968 Returns a bit field from a 32-bit value.
3970 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3972 If 32-bit operations are not supported, then ASSERT().
3973 If StartBit is greater than 31, then ASSERT().
3974 If EndBit is greater than 31, then ASSERT().
3975 If EndBit is less than StartBit, then ASSERT().
3977 @param Operand Operand on which to perform the bitfield operation.
3978 @param StartBit The ordinal of the least significant bit in the bit field.
3980 @param EndBit The ordinal of the most significant bit in the bit field.
3983 @return The bit field read.
3995 Writes a bit field to a 32-bit value, and returns the result.
3997 Writes Value to the bit field specified by the StartBit and the EndBit in
3998 Operand. All other bits in Operand are preserved. The new 32-bit value is
4001 If 32-bit operations are not supported, then ASSERT().
4002 If StartBit is greater than 31, then ASSERT().
4003 If EndBit is greater than 31, then ASSERT().
4004 If EndBit is less than StartBit, then ASSERT().
4005 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4007 @param Operand Operand on which to perform the bitfield operation.
4008 @param StartBit The ordinal of the least significant bit in the bit field.
4010 @param EndBit The ordinal of the most significant bit in the bit field.
4012 @param Value New value of the bit field.
4014 @return The new 32-bit value.
4027 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
4030 Performs a bitwise OR between the bit field specified by StartBit
4031 and EndBit in Operand and the value specified by OrData. All other bits in
4032 Operand are preserved. The new 32-bit value is returned.
4034 If 32-bit operations are not supported, then ASSERT().
4035 If StartBit is greater than 31, then ASSERT().
4036 If EndBit is greater than 31, then ASSERT().
4037 If EndBit is less than StartBit, then ASSERT().
4038 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4040 @param Operand Operand on which to perform the bitfield operation.
4041 @param StartBit The ordinal of the least significant bit in the bit field.
4043 @param EndBit The ordinal of the most significant bit in the bit field.
4045 @param OrData The value to OR with the read value from the value.
4047 @return The new 32-bit value.
4060 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
4063 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4064 in Operand and the value specified by AndData. All other bits in Operand are
4065 preserved. The new 32-bit value is returned.
4067 If 32-bit operations are not supported, then ASSERT().
4068 If StartBit is greater than 31, then ASSERT().
4069 If EndBit is greater than 31, then ASSERT().
4070 If EndBit is less than StartBit, then ASSERT().
4071 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4073 @param Operand Operand on which to perform the bitfield operation.
4074 @param StartBit The ordinal of the least significant bit in the bit field.
4076 @param EndBit The ordinal of the most significant bit in the bit field.
4078 @param AndData The value to AND with the read value from the value
4080 @return The new 32-bit value.
4093 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4094 bitwise OR, and returns the result.
4096 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4097 in Operand and the value specified by AndData, followed by a bitwise
4098 OR with value specified by OrData. All other bits in Operand are
4099 preserved. The new 32-bit value is returned.
4101 If 32-bit operations are not supported, then ASSERT().
4102 If StartBit is greater than 31, then ASSERT().
4103 If EndBit is greater than 31, then ASSERT().
4104 If EndBit is less than StartBit, then ASSERT().
4105 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4106 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4108 @param Operand Operand on which to perform the bitfield operation.
4109 @param StartBit The ordinal of the least significant bit in the bit field.
4111 @param EndBit The ordinal of the most significant bit in the bit field.
4113 @param AndData The value to AND with the read value from the value.
4114 @param OrData The value to OR with the result of the AND operation.
4116 @return The new 32-bit value.
4121 BitFieldAndThenOr32 (
4130 Returns a bit field from a 64-bit value.
4132 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4134 If 64-bit operations are not supported, then ASSERT().
4135 If StartBit is greater than 63, then ASSERT().
4136 If EndBit is greater than 63, then ASSERT().
4137 If EndBit is less than StartBit, then ASSERT().
4139 @param Operand Operand on which to perform the bitfield operation.
4140 @param StartBit The ordinal of the least significant bit in the bit field.
4142 @param EndBit The ordinal of the most significant bit in the bit field.
4145 @return The bit field read.
4157 Writes a bit field to a 64-bit value, and returns the result.
4159 Writes Value to the bit field specified by the StartBit and the EndBit in
4160 Operand. All other bits in Operand are preserved. The new 64-bit value is
4163 If 64-bit operations are not supported, then ASSERT().
4164 If StartBit is greater than 63, then ASSERT().
4165 If EndBit is greater than 63, then ASSERT().
4166 If EndBit is less than StartBit, then ASSERT().
4167 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4169 @param Operand Operand on which to perform the bitfield operation.
4170 @param StartBit The ordinal of the least significant bit in the bit field.
4172 @param EndBit The ordinal of the most significant bit in the bit field.
4174 @param Value New value of the bit field.
4176 @return The new 64-bit value.
4189 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4192 Performs a bitwise OR between the bit field specified by StartBit
4193 and EndBit in Operand and the value specified by OrData. All other bits in
4194 Operand are preserved. The new 64-bit value is returned.
4196 If 64-bit operations are not supported, then ASSERT().
4197 If StartBit is greater than 63, then ASSERT().
4198 If EndBit is greater than 63, then ASSERT().
4199 If EndBit is less than StartBit, then ASSERT().
4200 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4202 @param Operand Operand on which to perform the bitfield operation.
4203 @param StartBit The ordinal of the least significant bit in the bit field.
4205 @param EndBit The ordinal of the most significant bit in the bit field.
4207 @param OrData The value to OR with the read value from the value
4209 @return The new 64-bit value.
4222 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4225 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4226 in Operand and the value specified by AndData. All other bits in Operand are
4227 preserved. The new 64-bit value is returned.
4229 If 64-bit operations are not supported, then ASSERT().
4230 If StartBit is greater than 63, then ASSERT().
4231 If EndBit is greater than 63, then ASSERT().
4232 If EndBit is less than StartBit, then ASSERT().
4233 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4235 @param Operand Operand on which to perform the bitfield operation.
4236 @param StartBit The ordinal of the least significant bit in the bit field.
4238 @param EndBit The ordinal of the most significant bit in the bit field.
4240 @param AndData The value to AND with the read value from the value
4242 @return The new 64-bit value.
4255 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4256 bitwise OR, and returns the result.
4258 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4259 in Operand and the value specified by AndData, followed by a bitwise
4260 OR with value specified by OrData. All other bits in Operand are
4261 preserved. The new 64-bit value is returned.
4263 If 64-bit operations are not supported, then ASSERT().
4264 If StartBit is greater than 63, then ASSERT().
4265 If EndBit is greater than 63, then ASSERT().
4266 If EndBit is less than StartBit, then ASSERT().
4267 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4268 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4270 @param Operand Operand on which to perform the bitfield operation.
4271 @param StartBit The ordinal of the least significant bit in the bit field.
4273 @param EndBit The ordinal of the most significant bit in the bit field.
4275 @param AndData The value to AND with the read value from the value.
4276 @param OrData The value to OR with the result of the AND operation.
4278 @return The new 64-bit value.
4283 BitFieldAndThenOr64 (
4292 Reads a bit field from a 32-bit value, counts and returns
4293 the number of set bits.
4295 Counts the number of set bits in the bit field specified by
4296 StartBit and EndBit in Operand. The count is returned.
4298 If StartBit is greater than 31, then ASSERT().
4299 If EndBit is greater than 31, then ASSERT().
4300 If EndBit is less than StartBit, then ASSERT().
4302 @param Operand Operand on which to perform the bitfield operation.
4303 @param StartBit The ordinal of the least significant bit in the bit field.
4305 @param EndBit The ordinal of the most significant bit in the bit field.
4308 @return The number of bits set between StartBit and EndBit.
4313 BitFieldCountOnes32 (
4320 Reads a bit field from a 64-bit value, counts and returns
4321 the number of set bits.
4323 Counts the number of set bits in the bit field specified by
4324 StartBit and EndBit in Operand. The count is returned.
4326 If StartBit is greater than 63, then ASSERT().
4327 If EndBit is greater than 63, then ASSERT().
4328 If EndBit is less than StartBit, then ASSERT().
4330 @param Operand Operand on which to perform the bitfield operation.
4331 @param StartBit The ordinal of the least significant bit in the bit field.
4333 @param EndBit The ordinal of the most significant bit in the bit field.
4336 @return The number of bits set between StartBit and EndBit.
4341 BitFieldCountOnes64 (
4348 // Base Library Checksum Functions
4352 Returns the sum of all elements in a buffer in unit of UINT8.
4353 During calculation, the carry bits are dropped.
4355 This function calculates the sum of all elements in a buffer
4356 in unit of UINT8. The carry bits in result of addition are dropped.
4357 The result is returned as UINT8. If Length is Zero, then Zero is
4360 If Buffer is NULL, then ASSERT().
4361 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4363 @param Buffer The pointer to the buffer to carry out the sum operation.
4364 @param Length The size, in bytes, of Buffer.
4366 @return Sum The sum of Buffer with carry bits dropped during additions.
4372 IN CONST UINT8
*Buffer
,
4377 Returns the two's complement checksum of all elements in a buffer
4380 This function first calculates the sum of the 8-bit values in the
4381 buffer specified by Buffer and Length. The carry bits in the result
4382 of addition are dropped. Then, the two's complement of the sum is
4383 returned. If Length is 0, then 0 is returned.
4385 If Buffer is NULL, then ASSERT().
4386 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4388 @param Buffer The pointer to the buffer to carry out the checksum operation.
4389 @param Length The size, in bytes, of Buffer.
4391 @return Checksum The two's complement checksum of Buffer.
4396 CalculateCheckSum8 (
4397 IN CONST UINT8
*Buffer
,
4402 Returns the sum of all elements in a buffer of 16-bit values. During
4403 calculation, the carry bits are dropped.
4405 This function calculates the sum of the 16-bit values in the buffer
4406 specified by Buffer and Length. The carry bits in result of addition are dropped.
4407 The 16-bit result is returned. If Length is 0, then 0 is returned.
4409 If Buffer is NULL, then ASSERT().
4410 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4411 If Length is not aligned on a 16-bit boundary, then ASSERT().
4412 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4414 @param Buffer The pointer to the buffer to carry out the sum operation.
4415 @param Length The size, in bytes, of Buffer.
4417 @return Sum The sum of Buffer with carry bits dropped during additions.
4423 IN CONST UINT16
*Buffer
,
4428 Returns the two's complement checksum of all elements in a buffer of
4431 This function first calculates the sum of the 16-bit values in the buffer
4432 specified by Buffer and Length. The carry bits in the result of addition
4433 are dropped. Then, the two's complement of the sum is returned. If Length
4434 is 0, then 0 is returned.
4436 If Buffer is NULL, then ASSERT().
4437 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4438 If Length is not aligned on a 16-bit boundary, then ASSERT().
4439 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4441 @param Buffer The pointer to the buffer to carry out the checksum operation.
4442 @param Length The size, in bytes, of Buffer.
4444 @return Checksum The two's complement checksum of Buffer.
4449 CalculateCheckSum16 (
4450 IN CONST UINT16
*Buffer
,
4455 Returns the sum of all elements in a buffer of 32-bit values. During
4456 calculation, the carry bits are dropped.
4458 This function calculates the sum of the 32-bit values in the buffer
4459 specified by Buffer and Length. The carry bits in result of addition are dropped.
4460 The 32-bit result is returned. If Length is 0, then 0 is returned.
4462 If Buffer is NULL, then ASSERT().
4463 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4464 If Length is not aligned on a 32-bit boundary, then ASSERT().
4465 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4467 @param Buffer The pointer to the buffer to carry out the sum operation.
4468 @param Length The size, in bytes, of Buffer.
4470 @return Sum The sum of Buffer with carry bits dropped during additions.
4476 IN CONST UINT32
*Buffer
,
4481 Returns the two's complement checksum of all elements in a buffer of
4484 This function first calculates the sum of the 32-bit values in the buffer
4485 specified by Buffer and Length. The carry bits in the result of addition
4486 are dropped. Then, the two's complement of the sum is returned. If Length
4487 is 0, then 0 is returned.
4489 If Buffer is NULL, then ASSERT().
4490 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4491 If Length is not aligned on a 32-bit boundary, then ASSERT().
4492 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4494 @param Buffer The pointer to the buffer to carry out the checksum operation.
4495 @param Length The size, in bytes, of Buffer.
4497 @return Checksum The two's complement checksum of Buffer.
4502 CalculateCheckSum32 (
4503 IN CONST UINT32
*Buffer
,
4508 Returns the sum of all elements in a buffer of 64-bit values. During
4509 calculation, the carry bits are dropped.
4511 This function calculates the sum of the 64-bit values in the buffer
4512 specified by Buffer and Length. The carry bits in result of addition are dropped.
4513 The 64-bit result is returned. If Length is 0, then 0 is returned.
4515 If Buffer is NULL, then ASSERT().
4516 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4517 If Length is not aligned on a 64-bit boundary, then ASSERT().
4518 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4520 @param Buffer The pointer to the buffer to carry out the sum operation.
4521 @param Length The size, in bytes, of Buffer.
4523 @return Sum The sum of Buffer with carry bits dropped during additions.
4529 IN CONST UINT64
*Buffer
,
4534 Returns the two's complement checksum of all elements in a buffer of
4537 This function first calculates the sum of the 64-bit values in the buffer
4538 specified by Buffer and Length. The carry bits in the result of addition
4539 are dropped. Then, the two's complement of the sum is returned. If Length
4540 is 0, then 0 is returned.
4542 If Buffer is NULL, then ASSERT().
4543 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4544 If Length is not aligned on a 64-bit boundary, then ASSERT().
4545 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4547 @param Buffer The pointer to the buffer to carry out the checksum operation.
4548 @param Length The size, in bytes, of Buffer.
4550 @return Checksum The two's complement checksum of Buffer.
4555 CalculateCheckSum64 (
4556 IN CONST UINT64
*Buffer
,
4561 Computes and returns a 32-bit CRC for a data buffer.
4562 CRC32 value bases on ITU-T V.42.
4564 If Buffer is NULL, then ASSERT().
4565 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4567 @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed.
4568 @param[in] Length The number of bytes in the buffer Data.
4570 @retval Crc32 The 32-bit CRC was computed for the data buffer.
4581 Calculates the CRC16-ANSI checksum of the given buffer.
4583 @param[in] Buffer Pointer to the buffer.
4584 @param[in] Length Length of the buffer, in bytes.
4585 @param[in] InitialValue Initial value of the CRC.
4587 @return The CRC16-ANSI checksum.
4591 CalculateCrc16Ansi (
4592 IN CONST VOID
*Buffer
,
4594 IN UINT16 InitialValue
4598 Calculates the CRC32c checksum of the given buffer.
4600 @param[in] Buffer Pointer to the buffer.
4601 @param[in] Length Length of the buffer, in bytes.
4602 @param[in] InitialValue Initial value of the CRC.
4604 @return The CRC32c checksum.
4609 IN CONST VOID
*Buffer
,
4611 IN UINT32 InitialValue
4615 // Base Library CPU Functions
4619 Function entry point used when a stack switch is requested with SwitchStack()
4621 @param Context1 Context1 parameter passed into SwitchStack().
4622 @param Context2 Context2 parameter passed into SwitchStack().
4626 (EFIAPI
*SWITCH_STACK_ENTRY_POINT
)(
4627 IN VOID
*Context1 OPTIONAL
,
4628 IN VOID
*Context2 OPTIONAL
4632 Used to serialize load and store operations.
4634 All loads and stores that proceed calls to this function are guaranteed to be
4635 globally visible when this function returns.
4645 Saves the current CPU context that can be restored with a call to LongJump()
4648 Saves the current CPU context in the buffer specified by JumpBuffer and
4649 returns 0. The initial call to SetJump() must always return 0. Subsequent
4650 calls to LongJump() cause a non-zero value to be returned by SetJump().
4652 If JumpBuffer is NULL, then ASSERT().
4653 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4655 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
4656 The same structure must never be used for more than one CPU architecture context.
4657 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
4658 SetJump()/LongJump() is not currently supported for the EBC processor type.
4660 @param JumpBuffer A pointer to CPU context buffer.
4662 @retval 0 Indicates a return from SetJump().
4669 OUT BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
4673 Restores the CPU context that was saved with SetJump().
4675 Restores the CPU context from the buffer specified by JumpBuffer. This
4676 function never returns to the caller. Instead is resumes execution based on
4677 the state of JumpBuffer.
4679 If JumpBuffer is NULL, then ASSERT().
4680 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4681 If Value is 0, then ASSERT().
4683 @param JumpBuffer A pointer to CPU context buffer.
4684 @param Value The value to return when the SetJump() context is
4685 restored and must be non-zero.
4691 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
4696 Enables CPU interrupts.
4706 Disables CPU interrupts.
4716 Disables CPU interrupts and returns the interrupt state prior to the disable
4719 @retval TRUE CPU interrupts were enabled on entry to this call.
4720 @retval FALSE CPU interrupts were disabled on entry to this call.
4725 SaveAndDisableInterrupts (
4730 Enables CPU interrupts for the smallest window required to capture any
4736 EnableDisableInterrupts (
4741 Retrieves the current CPU interrupt state.
4743 Returns TRUE if interrupts are currently enabled. Otherwise
4746 @retval TRUE CPU interrupts are enabled.
4747 @retval FALSE CPU interrupts are disabled.
4757 Set the current CPU interrupt state.
4759 Sets the current CPU interrupt state to the state specified by
4760 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
4761 InterruptState is FALSE, then interrupts are disabled. InterruptState is
4764 @param InterruptState TRUE if interrupts should enabled. FALSE if
4765 interrupts should be disabled.
4767 @return InterruptState
4773 IN BOOLEAN InterruptState
4777 Requests CPU to pause for a short period of time.
4779 Requests CPU to pause for a short period of time. Typically used in MP
4780 systems to prevent memory starvation while waiting for a spin lock.
4790 Transfers control to a function starting with a new stack.
4792 Transfers control to the function specified by EntryPoint using the
4793 new stack specified by NewStack and passing in the parameters specified
4794 by Context1 and Context2. Context1 and Context2 are optional and may
4795 be NULL. The function EntryPoint must never return. This function
4796 supports a variable number of arguments following the NewStack parameter.
4797 These additional arguments are ignored on IA-32, x64, and EBC architectures.
4798 Itanium processors expect one additional parameter of type VOID * that specifies
4799 the new backing store pointer.
4801 If EntryPoint is NULL, then ASSERT().
4802 If NewStack is NULL, then ASSERT().
4804 @param EntryPoint A pointer to function to call with the new stack.
4805 @param Context1 A pointer to the context to pass into the EntryPoint
4807 @param Context2 A pointer to the context to pass into the EntryPoint
4809 @param NewStack A pointer to the new stack to use for the EntryPoint
4811 @param ... This variable argument list is ignored for IA-32, x64, and
4812 EBC architectures. For Itanium processors, this variable
4813 argument list is expected to contain a single parameter of
4814 type VOID * that specifies the new backing store pointer.
4821 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
4822 IN VOID
*Context1 OPTIONAL
,
4823 IN VOID
*Context2 OPTIONAL
,
4829 Generates a breakpoint on the CPU.
4831 Generates a breakpoint on the CPU. The breakpoint must be implemented such
4832 that code can resume normal execution after the breakpoint.
4842 Executes an infinite loop.
4844 Forces the CPU to execute an infinite loop. A debugger may be used to skip
4845 past the loop and the code that follows the loop must execute properly. This
4846 implies that the infinite loop must not cause the code that follow it to be
4857 Uses as a barrier to stop speculative execution.
4859 Ensures that no later instruction will execute speculatively, until all prior
4860 instructions have completed.
4865 SpeculationBarrier (
4869 #if defined (MDE_CPU_X64) || defined (MDE_CPU_IA32)
4872 The TDCALL instruction causes a VM exit to the Intel TDX module. It is
4873 used to call guest-side Intel TDX functions, either local or a TD exit
4874 to the host VMM, as selected by Leaf.
4876 @param[in] Leaf Leaf number of TDCALL instruction
4877 @param[in] Arg1 Arg1
4878 @param[in] Arg2 Arg2
4879 @param[in] Arg3 Arg3
4880 @param[in,out] Results Returned result of the Leaf function
4882 @return 0 A successful call
4883 @return Other See individual leaf functions
4892 IN OUT VOID
*Results
4896 TDVMALL is a leaf function 0 for TDCALL. It helps invoke services from the
4897 host VMM to pass/receive information.
4899 @param[in] Leaf Number of sub-functions
4900 @param[in] Arg1 Arg1
4901 @param[in] Arg2 Arg2
4902 @param[in] Arg3 Arg3
4903 @param[in] Arg4 Arg4
4904 @param[in,out] Results Returned result of the sub-function
4906 @return 0 A successful call
4907 @return Other See individual sub-functions
4918 IN OUT VOID
*Results
4922 Probe if TD is enabled.
4924 @return TRUE TD is enabled.
4925 @return FALSE TD is not enabled.
4935 #if defined (MDE_CPU_X64)
4937 // The page size for the PVALIDATE instruction
4940 PvalidatePageSize4K
= 0,
4941 PvalidatePageSize2MB
,
4942 } PVALIDATE_PAGE_SIZE
;
4945 // PVALIDATE Return Code.
4947 #define PVALIDATE_RET_SUCCESS 0
4948 #define PVALIDATE_RET_FAIL_INPUT 1
4949 #define PVALIDATE_RET_SIZE_MISMATCH 6
4952 // The PVALIDATE instruction did not make any changes to the RMP entry.
4954 #define PVALIDATE_RET_NO_RMPUPDATE 255
4957 Execute a PVALIDATE instruction to validate or to rescinds validation of a guest
4960 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
4962 The function is available on X64.
4964 @param[in] PageSize The page size to use.
4965 @param[in] Validate If TRUE, validate the guest virtual address
4966 otherwise invalidate the guest virtual address.
4967 @param[in] Address The guest virtual address.
4969 @retval PVALIDATE_RET_SUCCESS The PVALIDATE instruction succeeded, and
4970 updated the RMP entry.
4971 @retval PVALIDATE_RET_NO_RMPUPDATE The PVALIDATE instruction succeeded, but
4972 did not update the RMP entry.
4973 @return Failure code from the PVALIDATE
4979 IN PVALIDATE_PAGE_SIZE PageSize
,
4980 IN BOOLEAN Validate
,
4981 IN PHYSICAL_ADDRESS Address
4985 // RDX settings for RMPADJUST
4987 #define RMPADJUST_VMPL_MAX 3
4988 #define RMPADJUST_VMPL_MASK 0xFF
4989 #define RMPADJUST_VMPL_SHIFT 0
4990 #define RMPADJUST_PERMISSION_MASK_MASK 0xFF
4991 #define RMPADJUST_PERMISSION_MASK_SHIFT 8
4992 #define RMPADJUST_VMSA_PAGE_BIT BIT16
4995 Adjusts the permissions of an SEV-SNP guest page.
4997 Executes a RMPADJUST instruction with the register state specified by Rax,
4998 Rcx, and Rdx. Returns Eax. This function is only available on X64.
5000 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
5002 @param[in] Rax The value to load into RAX before executing the RMPADJUST
5004 @param[in] Rcx The value to load into RCX before executing the RMPADJUST
5006 @param[in] Rdx The value to load into RDX before executing the RMPADJUST
5021 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
5023 /// IA32 and x64 Specific Functions.
5024 /// Byte packed structure for 16-bit Real Mode EFLAGS.
5028 UINT32 CF
: 1; ///< Carry Flag.
5029 UINT32 Reserved_0
: 1; ///< Reserved.
5030 UINT32 PF
: 1; ///< Parity Flag.
5031 UINT32 Reserved_1
: 1; ///< Reserved.
5032 UINT32 AF
: 1; ///< Auxiliary Carry Flag.
5033 UINT32 Reserved_2
: 1; ///< Reserved.
5034 UINT32 ZF
: 1; ///< Zero Flag.
5035 UINT32 SF
: 1; ///< Sign Flag.
5036 UINT32 TF
: 1; ///< Trap Flag.
5037 UINT32 IF
: 1; ///< Interrupt Enable Flag.
5038 UINT32 DF
: 1; ///< Direction Flag.
5039 UINT32 OF
: 1; ///< Overflow Flag.
5040 UINT32 IOPL
: 2; ///< I/O Privilege Level.
5041 UINT32 NT
: 1; ///< Nested Task.
5042 UINT32 Reserved_3
: 1; ///< Reserved.
5048 /// Byte packed structure for EFLAGS/RFLAGS.
5049 /// 32-bits on IA-32.
5050 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5054 UINT32 CF
: 1; ///< Carry Flag.
5055 UINT32 Reserved_0
: 1; ///< Reserved.
5056 UINT32 PF
: 1; ///< Parity Flag.
5057 UINT32 Reserved_1
: 1; ///< Reserved.
5058 UINT32 AF
: 1; ///< Auxiliary Carry Flag.
5059 UINT32 Reserved_2
: 1; ///< Reserved.
5060 UINT32 ZF
: 1; ///< Zero Flag.
5061 UINT32 SF
: 1; ///< Sign Flag.
5062 UINT32 TF
: 1; ///< Trap Flag.
5063 UINT32 IF
: 1; ///< Interrupt Enable Flag.
5064 UINT32 DF
: 1; ///< Direction Flag.
5065 UINT32 OF
: 1; ///< Overflow Flag.
5066 UINT32 IOPL
: 2; ///< I/O Privilege Level.
5067 UINT32 NT
: 1; ///< Nested Task.
5068 UINT32 Reserved_3
: 1; ///< Reserved.
5069 UINT32 RF
: 1; ///< Resume Flag.
5070 UINT32 VM
: 1; ///< Virtual 8086 Mode.
5071 UINT32 AC
: 1; ///< Alignment Check.
5072 UINT32 VIF
: 1; ///< Virtual Interrupt Flag.
5073 UINT32 VIP
: 1; ///< Virtual Interrupt Pending.
5074 UINT32 ID
: 1; ///< ID Flag.
5075 UINT32 Reserved_4
: 10; ///< Reserved.
5081 /// Byte packed structure for Control Register 0 (CR0).
5082 /// 32-bits on IA-32.
5083 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5087 UINT32 PE
: 1; ///< Protection Enable.
5088 UINT32 MP
: 1; ///< Monitor Coprocessor.
5089 UINT32 EM
: 1; ///< Emulation.
5090 UINT32 TS
: 1; ///< Task Switched.
5091 UINT32 ET
: 1; ///< Extension Type.
5092 UINT32 NE
: 1; ///< Numeric Error.
5093 UINT32 Reserved_0
: 10; ///< Reserved.
5094 UINT32 WP
: 1; ///< Write Protect.
5095 UINT32 Reserved_1
: 1; ///< Reserved.
5096 UINT32 AM
: 1; ///< Alignment Mask.
5097 UINT32 Reserved_2
: 10; ///< Reserved.
5098 UINT32 NW
: 1; ///< Mot Write-through.
5099 UINT32 CD
: 1; ///< Cache Disable.
5100 UINT32 PG
: 1; ///< Paging.
5106 /// Byte packed structure for Control Register 4 (CR4).
5107 /// 32-bits on IA-32.
5108 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5112 UINT32 VME
: 1; ///< Virtual-8086 Mode Extensions.
5113 UINT32 PVI
: 1; ///< Protected-Mode Virtual Interrupts.
5114 UINT32 TSD
: 1; ///< Time Stamp Disable.
5115 UINT32 DE
: 1; ///< Debugging Extensions.
5116 UINT32 PSE
: 1; ///< Page Size Extensions.
5117 UINT32 PAE
: 1; ///< Physical Address Extension.
5118 UINT32 MCE
: 1; ///< Machine Check Enable.
5119 UINT32 PGE
: 1; ///< Page Global Enable.
5120 UINT32 PCE
: 1; ///< Performance Monitoring Counter
5122 UINT32 OSFXSR
: 1; ///< Operating System Support for
5123 ///< FXSAVE and FXRSTOR instructions
5124 UINT32 OSXMMEXCPT
: 1; ///< Operating System Support for
5125 ///< Unmasked SIMD Floating Point
5127 UINT32 UMIP
: 1; ///< User-Mode Instruction Prevention.
5128 UINT32 LA57
: 1; ///< Linear Address 57bit.
5129 UINT32 VMXE
: 1; ///< VMX Enable.
5130 UINT32 SMXE
: 1; ///< SMX Enable.
5131 UINT32 Reserved_3
: 1; ///< Reserved.
5132 UINT32 FSGSBASE
: 1; ///< FSGSBASE Enable.
5133 UINT32 PCIDE
: 1; ///< PCID Enable.
5134 UINT32 OSXSAVE
: 1; ///< XSAVE and Processor Extended States Enable.
5135 UINT32 Reserved_4
: 1; ///< Reserved.
5136 UINT32 SMEP
: 1; ///< SMEP Enable.
5137 UINT32 SMAP
: 1; ///< SMAP Enable.
5138 UINT32 PKE
: 1; ///< Protection-Key Enable.
5139 UINT32 Reserved_5
: 9; ///< Reserved.
5145 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5149 UINT32 LimitLow
: 16;
5150 UINT32 BaseLow
: 16;
5156 UINT32 LimitHigh
: 4;
5161 UINT32 BaseHigh
: 8;
5164 } IA32_SEGMENT_DESCRIPTOR
;
5167 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5176 #define IA32_IDT_GATE_TYPE_TASK 0x85
5177 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5178 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5179 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5180 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5182 #define IA32_GDT_TYPE_TSS 0x9
5183 #define IA32_GDT_ALIGNMENT 8
5185 #if defined (MDE_CPU_IA32)
5187 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5191 UINT32 OffsetLow
: 16; ///< Offset bits 15..0.
5192 UINT32 Selector
: 16; ///< Selector.
5193 UINT32 Reserved_0
: 8; ///< Reserved.
5194 UINT32 GateType
: 8; ///< Gate Type. See #defines above.
5195 UINT32 OffsetHigh
: 16; ///< Offset bits 31..16.
5198 } IA32_IDT_GATE_DESCRIPTOR
;
5202 // IA32 Task-State Segment Definition
5205 UINT16 PreviousTaskLink
;
5239 UINT16 LDTSegmentSelector
;
5242 UINT16 IOMapBaseAddress
;
5243 } IA32_TASK_STATE_SEGMENT
;
5247 UINT32 LimitLow
: 16; ///< Segment Limit 15..00
5248 UINT32 BaseLow
: 16; ///< Base Address 15..00
5249 UINT32 BaseMid
: 8; ///< Base Address 23..16
5250 UINT32 Type
: 4; ///< Type (1 0 B 1)
5251 UINT32 Reserved_43
: 1; ///< 0
5252 UINT32 DPL
: 2; ///< Descriptor Privilege Level
5253 UINT32 P
: 1; ///< Segment Present
5254 UINT32 LimitHigh
: 4; ///< Segment Limit 19..16
5255 UINT32 AVL
: 1; ///< Available for use by system software
5256 UINT32 Reserved_52
: 2; ///< 0 0
5257 UINT32 G
: 1; ///< Granularity
5258 UINT32 BaseHigh
: 8; ///< Base Address 31..24
5261 } IA32_TSS_DESCRIPTOR
;
5264 #endif // defined (MDE_CPU_IA32)
5266 #if defined (MDE_CPU_X64)
5268 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5272 UINT32 OffsetLow
: 16; ///< Offset bits 15..0.
5273 UINT32 Selector
: 16; ///< Selector.
5274 UINT32 Reserved_0
: 8; ///< Reserved.
5275 UINT32 GateType
: 8; ///< Gate Type. See #defines above.
5276 UINT32 OffsetHigh
: 16; ///< Offset bits 31..16.
5277 UINT32 OffsetUpper
: 32; ///< Offset bits 63..32.
5278 UINT32 Reserved_1
: 32; ///< Reserved.
5284 } IA32_IDT_GATE_DESCRIPTOR
;
5288 // IA32 Task-State Segment Definition
5298 UINT16 Reserved_100
;
5299 UINT16 IOMapBaseAddress
;
5300 } IA32_TASK_STATE_SEGMENT
;
5304 UINT32 LimitLow
: 16; ///< Segment Limit 15..00
5305 UINT32 BaseLow
: 16; ///< Base Address 15..00
5306 UINT32 BaseMidl
: 8; ///< Base Address 23..16
5307 UINT32 Type
: 4; ///< Type (1 0 B 1)
5308 UINT32 Reserved_43
: 1; ///< 0
5309 UINT32 DPL
: 2; ///< Descriptor Privilege Level
5310 UINT32 P
: 1; ///< Segment Present
5311 UINT32 LimitHigh
: 4; ///< Segment Limit 19..16
5312 UINT32 AVL
: 1; ///< Available for use by system software
5313 UINT32 Reserved_52
: 2; ///< 0 0
5314 UINT32 G
: 1; ///< Granularity
5315 UINT32 BaseMidh
: 8; ///< Base Address 31..24
5316 UINT32 BaseHigh
: 32; ///< Base Address 63..32
5317 UINT32 Reserved_96
: 32; ///< Reserved
5323 } IA32_TSS_DESCRIPTOR
;
5326 #endif // defined (MDE_CPU_X64)
5329 /// Byte packed structure for an FP/SSE/SSE2 context.
5336 /// Structures for the 16-bit real mode thunks.
5389 IA32_EFLAGS32 EFLAGS
;
5399 } IA32_REGISTER_SET
;
5402 /// Byte packed structure for an 16-bit real mode thunks.
5405 IA32_REGISTER_SET
*RealModeState
;
5406 VOID
*RealModeBuffer
;
5407 UINT32 RealModeBufferSize
;
5408 UINT32 ThunkAttributes
;
5411 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5412 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5413 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5416 /// Type definition for representing labels in NASM source code that allow for
5417 /// the patching of immediate operands of IA32 and X64 instructions.
5419 /// While the type is technically defined as a function type (note: not a
5420 /// pointer-to-function type), such labels in NASM source code never stand for
5421 /// actual functions, and identifiers declared with this function type should
5422 /// never be called. This is also why the EFIAPI calling convention specifier
5423 /// is missing from the typedef, and why the typedef does not follow the usual
5424 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5425 /// return type and the VOID argument list are merely artifacts.
5427 typedef VOID (X86_ASSEMBLY_PATCH_LABEL
) (
5432 Retrieves CPUID information.
5434 Executes the CPUID instruction with EAX set to the value specified by Index.
5435 This function always returns Index.
5436 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5437 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5438 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5439 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5440 This function is only available on IA-32 and x64.
5442 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5444 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5445 instruction. This is an optional parameter that may be NULL.
5446 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5447 instruction. This is an optional parameter that may be NULL.
5448 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5449 instruction. This is an optional parameter that may be NULL.
5450 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5451 instruction. This is an optional parameter that may be NULL.
5460 OUT UINT32
*Eax OPTIONAL
,
5461 OUT UINT32
*Ebx OPTIONAL
,
5462 OUT UINT32
*Ecx OPTIONAL
,
5463 OUT UINT32
*Edx OPTIONAL
5467 Retrieves CPUID information using an extended leaf identifier.
5469 Executes the CPUID instruction with EAX set to the value specified by Index
5470 and ECX set to the value specified by SubIndex. This function always returns
5471 Index. This function is only available on IA-32 and x64.
5473 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5474 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5475 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5476 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5478 @param Index The 32-bit value to load into EAX prior to invoking the
5480 @param SubIndex The 32-bit value to load into ECX prior to invoking the
5482 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5483 instruction. This is an optional parameter that may be
5485 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5486 instruction. This is an optional parameter that may be
5488 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5489 instruction. This is an optional parameter that may be
5491 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5492 instruction. This is an optional parameter that may be
5503 OUT UINT32
*Eax OPTIONAL
,
5504 OUT UINT32
*Ebx OPTIONAL
,
5505 OUT UINT32
*Ecx OPTIONAL
,
5506 OUT UINT32
*Edx OPTIONAL
5510 Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5512 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5513 and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5523 Perform a WBINVD and clear both the CD and NW bits of CR0.
5525 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5526 bits of CR0 to 0. This function is only available on IA-32 and x64.
5536 Returns the lower 32-bits of a Machine Specific Register(MSR).
5538 Reads and returns the lower 32-bits of the MSR specified by Index.
5539 No parameter checking is performed on Index, and some Index values may cause
5540 CPU exceptions. The caller must either guarantee that Index is valid, or the
5541 caller must set up exception handlers to catch the exceptions. This function
5542 is only available on IA-32 and x64.
5544 @param Index The 32-bit MSR index to read.
5546 @return The lower 32 bits of the MSR identified by Index.
5556 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5557 The upper 32-bits of the MSR are set to zero.
5559 Writes the 32-bit value specified by Value to the MSR specified by Index. The
5560 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5561 the MSR is returned. No parameter checking is performed on Index or Value,
5562 and some of these may cause CPU exceptions. The caller must either guarantee
5563 that Index and Value are valid, or the caller must establish proper exception
5564 handlers. This function is only available on IA-32 and x64.
5566 @param Index The 32-bit MSR index to write.
5567 @param Value The 32-bit value to write to the MSR.
5580 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5581 writes the result back to the 64-bit MSR.
5583 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5584 between the lower 32-bits of the read result and the value specified by
5585 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5586 32-bits of the value written to the MSR is returned. No parameter checking is
5587 performed on Index or OrData, and some of these may cause CPU exceptions. The
5588 caller must either guarantee that Index and OrData are valid, or the caller
5589 must establish proper exception handlers. This function is only available on
5592 @param Index The 32-bit MSR index to write.
5593 @param OrData The value to OR with the read value from the MSR.
5595 @return The lower 32-bit value written to the MSR.
5606 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5607 the result back to the 64-bit MSR.
5609 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5610 lower 32-bits of the read result and the value specified by AndData, and
5611 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5612 the value written to the MSR is returned. No parameter checking is performed
5613 on Index or AndData, and some of these may cause CPU exceptions. The caller
5614 must either guarantee that Index and AndData are valid, or the caller must
5615 establish proper exception handlers. This function is only available on IA-32
5618 @param Index The 32-bit MSR index to write.
5619 @param AndData The value to AND with the read value from the MSR.
5621 @return The lower 32-bit value written to the MSR.
5632 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5633 on the lower 32-bits, and writes the result back to the 64-bit MSR.
5635 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5636 lower 32-bits of the read result and the value specified by AndData
5637 preserving the upper 32-bits, performs a bitwise OR between the
5638 result of the AND operation and the value specified by OrData, and writes the
5639 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5640 written to the MSR is returned. No parameter checking is performed on Index,
5641 AndData, or OrData, and some of these may cause CPU exceptions. The caller
5642 must either guarantee that Index, AndData, and OrData are valid, or the
5643 caller must establish proper exception handlers. This function is only
5644 available on IA-32 and x64.
5646 @param Index The 32-bit MSR index to write.
5647 @param AndData The value to AND with the read value from the MSR.
5648 @param OrData The value to OR with the result of the AND operation.
5650 @return The lower 32-bit value written to the MSR.
5662 Reads a bit field of an MSR.
5664 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5665 specified by the StartBit and the EndBit. The value of the bit field is
5666 returned. The caller must either guarantee that Index is valid, or the caller
5667 must set up exception handlers to catch the exceptions. This function is only
5668 available on IA-32 and x64.
5670 If StartBit is greater than 31, then ASSERT().
5671 If EndBit is greater than 31, then ASSERT().
5672 If EndBit is less than StartBit, then ASSERT().
5674 @param Index The 32-bit MSR index to read.
5675 @param StartBit The ordinal of the least significant bit in the bit field.
5677 @param EndBit The ordinal of the most significant bit in the bit field.
5680 @return The bit field read from the MSR.
5685 AsmMsrBitFieldRead32 (
5692 Writes a bit field to an MSR.
5694 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5695 field is specified by the StartBit and the EndBit. All other bits in the
5696 destination MSR are preserved. The lower 32-bits of the MSR written is
5697 returned. The caller must either guarantee that Index and the data written
5698 is valid, or the caller must set up exception handlers to catch the exceptions.
5699 This function is only available on IA-32 and x64.
5701 If StartBit is greater than 31, then ASSERT().
5702 If EndBit is greater than 31, then ASSERT().
5703 If EndBit is less than StartBit, then ASSERT().
5704 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5706 @param Index The 32-bit MSR index to write.
5707 @param StartBit The ordinal of the least significant bit in the bit field.
5709 @param EndBit The ordinal of the most significant bit in the bit field.
5711 @param Value New value of the bit field.
5713 @return The lower 32-bit of the value written to the MSR.
5718 AsmMsrBitFieldWrite32 (
5726 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5727 result back to the bit field in the 64-bit MSR.
5729 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5730 between the read result and the value specified by OrData, and writes the
5731 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
5732 written to the MSR are returned. Extra left bits in OrData are stripped. The
5733 caller must either guarantee that Index and the data written is valid, or
5734 the caller must set up exception handlers to catch the exceptions. This
5735 function is only available on IA-32 and x64.
5737 If StartBit is greater than 31, then ASSERT().
5738 If EndBit is greater than 31, then ASSERT().
5739 If EndBit is less than StartBit, then ASSERT().
5740 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5742 @param Index The 32-bit MSR index to write.
5743 @param StartBit The ordinal of the least significant bit in the bit field.
5745 @param EndBit The ordinal of the most significant bit in the bit field.
5747 @param OrData The value to OR with the read value from the MSR.
5749 @return The lower 32-bit of the value written to the MSR.
5754 AsmMsrBitFieldOr32 (
5762 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5763 result back to the bit field in the 64-bit MSR.
5765 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5766 read result and the value specified by AndData, and writes the result to the
5767 64-bit MSR specified by Index. The lower 32-bits of the value written to the
5768 MSR are returned. Extra left bits in AndData are stripped. The caller must
5769 either guarantee that Index and the data written is valid, or the caller must
5770 set up exception handlers to catch the exceptions. This function is only
5771 available on IA-32 and x64.
5773 If StartBit is greater than 31, then ASSERT().
5774 If EndBit is greater than 31, then ASSERT().
5775 If EndBit is less than StartBit, then ASSERT().
5776 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5778 @param Index The 32-bit MSR index to write.
5779 @param StartBit The ordinal of the least significant bit in the bit field.
5781 @param EndBit The ordinal of the most significant bit in the bit field.
5783 @param AndData The value to AND with the read value from the MSR.
5785 @return The lower 32-bit of the value written to the MSR.
5790 AsmMsrBitFieldAnd32 (
5798 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
5799 bitwise OR, and writes the result back to the bit field in the
5802 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
5803 bitwise OR between the read result and the value specified by
5804 AndData, and writes the result to the 64-bit MSR specified by Index. The
5805 lower 32-bits of the value written to the MSR are returned. Extra left bits
5806 in both AndData and OrData are stripped. The caller must either guarantee
5807 that Index and the data written is valid, or the caller must set up exception
5808 handlers to catch the exceptions. This function is only available on IA-32
5811 If StartBit is greater than 31, then ASSERT().
5812 If EndBit is greater than 31, then ASSERT().
5813 If EndBit is less than StartBit, then ASSERT().
5814 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5815 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5817 @param Index The 32-bit MSR index to write.
5818 @param StartBit The ordinal of the least significant bit in the bit field.
5820 @param EndBit The ordinal of the most significant bit in the bit field.
5822 @param AndData The value to AND with the read value from the MSR.
5823 @param OrData The value to OR with the result of the AND operation.
5825 @return The lower 32-bit of the value written to the MSR.
5830 AsmMsrBitFieldAndThenOr32 (
5839 Returns a 64-bit Machine Specific Register(MSR).
5841 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
5842 performed on Index, and some Index values may cause CPU exceptions. The
5843 caller must either guarantee that Index is valid, or the caller must set up
5844 exception handlers to catch the exceptions. This function is only available
5847 @param Index The 32-bit MSR index to read.
5849 @return The value of the MSR identified by Index.
5859 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
5862 Writes the 64-bit value specified by Value to the MSR specified by Index. The
5863 64-bit value written to the MSR is returned. No parameter checking is
5864 performed on Index or Value, and some of these may cause CPU exceptions. The
5865 caller must either guarantee that Index and Value are valid, or the caller
5866 must establish proper exception handlers. This function is only available on
5869 @param Index The 32-bit MSR index to write.
5870 @param Value The 64-bit value to write to the MSR.
5883 Reads a 64-bit MSR, performs a bitwise OR, and writes the result
5884 back to the 64-bit MSR.
5886 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5887 between the read result and the value specified by OrData, and writes the
5888 result to the 64-bit MSR specified by Index. The value written to the MSR is
5889 returned. No parameter checking is performed on Index or OrData, and some of
5890 these may cause CPU exceptions. The caller must either guarantee that Index
5891 and OrData are valid, or the caller must establish proper exception handlers.
5892 This function is only available on IA-32 and x64.
5894 @param Index The 32-bit MSR index to write.
5895 @param OrData The value to OR with the read value from the MSR.
5897 @return The value written back to the MSR.
5908 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
5911 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5912 read result and the value specified by OrData, and writes the result to the
5913 64-bit MSR specified by Index. The value written to the MSR is returned. No
5914 parameter checking is performed on Index or OrData, and some of these may
5915 cause CPU exceptions. The caller must either guarantee that Index and OrData
5916 are valid, or the caller must establish proper exception handlers. This
5917 function is only available on IA-32 and x64.
5919 @param Index The 32-bit MSR index to write.
5920 @param AndData The value to AND with the read value from the MSR.
5922 @return The value written back to the MSR.
5933 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
5934 OR, and writes the result back to the 64-bit MSR.
5936 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
5937 result and the value specified by AndData, performs a bitwise OR
5938 between the result of the AND operation and the value specified by OrData,
5939 and writes the result to the 64-bit MSR specified by Index. The value written
5940 to the MSR is returned. No parameter checking is performed on Index, AndData,
5941 or OrData, and some of these may cause CPU exceptions. The caller must either
5942 guarantee that Index, AndData, and OrData are valid, or the caller must
5943 establish proper exception handlers. This function is only available on IA-32
5946 @param Index The 32-bit MSR index to write.
5947 @param AndData The value to AND with the read value from the MSR.
5948 @param OrData The value to OR with the result of the AND operation.
5950 @return The value written back to the MSR.
5962 Reads a bit field of an MSR.
5964 Reads the bit field in the 64-bit MSR. The bit field is specified by the
5965 StartBit and the EndBit. The value of the bit field is returned. The caller
5966 must either guarantee that Index is valid, or the caller must set up
5967 exception handlers to catch the exceptions. This function is only available
5970 If StartBit is greater than 63, then ASSERT().
5971 If EndBit is greater than 63, then ASSERT().
5972 If EndBit is less than StartBit, then ASSERT().
5974 @param Index The 32-bit MSR index to read.
5975 @param StartBit The ordinal of the least significant bit in the bit field.
5977 @param EndBit The ordinal of the most significant bit in the bit field.
5980 @return The value read from the MSR.
5985 AsmMsrBitFieldRead64 (
5992 Writes a bit field to an MSR.
5994 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
5995 the StartBit and the EndBit. All other bits in the destination MSR are
5996 preserved. The MSR written is returned. The caller must either guarantee
5997 that Index and the data written is valid, or the caller must set up exception
5998 handlers to catch the exceptions. This function is only available on IA-32 and x64.
6000 If StartBit is greater than 63, then ASSERT().
6001 If EndBit is greater than 63, then ASSERT().
6002 If EndBit is less than StartBit, then ASSERT().
6003 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6005 @param Index The 32-bit MSR index to write.
6006 @param StartBit The ordinal of the least significant bit in the bit field.
6008 @param EndBit The ordinal of the most significant bit in the bit field.
6010 @param Value New value of the bit field.
6012 @return The value written back to the MSR.
6017 AsmMsrBitFieldWrite64 (
6025 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
6026 writes the result back to the bit field in the 64-bit MSR.
6028 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6029 between the read result and the value specified by OrData, and writes the
6030 result to the 64-bit MSR specified by Index. The value written to the MSR is
6031 returned. Extra left bits in OrData are stripped. The caller must either
6032 guarantee that Index and the data written is valid, or the caller must set up
6033 exception handlers to catch the exceptions. This function is only available
6036 If StartBit is greater than 63, then ASSERT().
6037 If EndBit is greater than 63, then ASSERT().
6038 If EndBit is less than StartBit, then ASSERT().
6039 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6041 @param Index The 32-bit MSR index to write.
6042 @param StartBit The ordinal of the least significant bit in the bit field.
6044 @param EndBit The ordinal of the most significant bit in the bit field.
6046 @param OrData The value to OR with the read value from the bit field.
6048 @return The value written back to the MSR.
6053 AsmMsrBitFieldOr64 (
6061 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6062 result back to the bit field in the 64-bit MSR.
6064 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6065 read result and the value specified by AndData, and writes the result to the
6066 64-bit MSR specified by Index. The value written to the MSR is returned.
6067 Extra left bits in AndData are stripped. The caller must either guarantee
6068 that Index and the data written is valid, or the caller must set up exception
6069 handlers to catch the exceptions. This function is only available on IA-32
6072 If StartBit is greater than 63, then ASSERT().
6073 If EndBit is greater than 63, then ASSERT().
6074 If EndBit is less than StartBit, then ASSERT().
6075 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6077 @param Index The 32-bit MSR index to write.
6078 @param StartBit The ordinal of the least significant bit in the bit field.
6080 @param EndBit The ordinal of the most significant bit in the bit field.
6082 @param AndData The value to AND with the read value from the bit field.
6084 @return The value written back to the MSR.
6089 AsmMsrBitFieldAnd64 (
6097 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6098 bitwise OR, and writes the result back to the bit field in the
6101 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6102 a bitwise OR between the read result and the value specified by
6103 AndData, and writes the result to the 64-bit MSR specified by Index. The
6104 value written to the MSR is returned. Extra left bits in both AndData and
6105 OrData are stripped. The caller must either guarantee that Index and the data
6106 written is valid, or the caller must set up exception handlers to catch the
6107 exceptions. This function is only available on IA-32 and x64.
6109 If StartBit is greater than 63, then ASSERT().
6110 If EndBit is greater than 63, then ASSERT().
6111 If EndBit is less than StartBit, then ASSERT().
6112 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6113 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6115 @param Index The 32-bit MSR index to write.
6116 @param StartBit The ordinal of the least significant bit in the bit field.
6118 @param EndBit The ordinal of the most significant bit in the bit field.
6120 @param AndData The value to AND with the read value from the bit field.
6121 @param OrData The value to OR with the result of the AND operation.
6123 @return The value written back to the MSR.
6128 AsmMsrBitFieldAndThenOr64 (
6137 Reads the current value of the EFLAGS register.
6139 Reads and returns the current value of the EFLAGS register. This function is
6140 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6141 64-bit value on x64.
6143 @return EFLAGS on IA-32 or RFLAGS on x64.
6153 Reads the current value of the Control Register 0 (CR0).
6155 Reads and returns the current value of CR0. This function is only available
6156 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6159 @return The value of the Control Register 0 (CR0).
6169 Reads the current value of the Control Register 2 (CR2).
6171 Reads and returns the current value of CR2. This function is only available
6172 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6175 @return The value of the Control Register 2 (CR2).
6185 Reads the current value of the Control Register 3 (CR3).
6187 Reads and returns the current value of CR3. This function is only available
6188 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6191 @return The value of the Control Register 3 (CR3).
6201 Reads the current value of the Control Register 4 (CR4).
6203 Reads and returns the current value of CR4. This function is only available
6204 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6207 @return The value of the Control Register 4 (CR4).
6217 Writes a value to Control Register 0 (CR0).
6219 Writes and returns a new value to CR0. This function is only available on
6220 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6222 @param Cr0 The value to write to CR0.
6224 @return The value written to CR0.
6234 Writes a value to Control Register 2 (CR2).
6236 Writes and returns a new value to CR2. This function is only available on
6237 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6239 @param Cr2 The value to write to CR2.
6241 @return The value written to CR2.
6251 Writes a value to Control Register 3 (CR3).
6253 Writes and returns a new value to CR3. This function is only available on
6254 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6256 @param Cr3 The value to write to CR3.
6258 @return The value written to CR3.
6268 Writes a value to Control Register 4 (CR4).
6270 Writes and returns a new value to CR4. This function is only available on
6271 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6273 @param Cr4 The value to write to CR4.
6275 @return The value written to CR4.
6285 Reads the current value of Debug Register 0 (DR0).
6287 Reads and returns the current value of DR0. This function is only available
6288 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6291 @return The value of Debug Register 0 (DR0).
6301 Reads the current value of Debug Register 1 (DR1).
6303 Reads and returns the current value of DR1. This function is only available
6304 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6307 @return The value of Debug Register 1 (DR1).
6317 Reads the current value of Debug Register 2 (DR2).
6319 Reads and returns the current value of DR2. This function is only available
6320 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6323 @return The value of Debug Register 2 (DR2).
6333 Reads the current value of Debug Register 3 (DR3).
6335 Reads and returns the current value of DR3. This function is only available
6336 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6339 @return The value of Debug Register 3 (DR3).
6349 Reads the current value of Debug Register 4 (DR4).
6351 Reads and returns the current value of DR4. This function is only available
6352 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6355 @return The value of Debug Register 4 (DR4).
6365 Reads the current value of Debug Register 5 (DR5).
6367 Reads and returns the current value of DR5. This function is only available
6368 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6371 @return The value of Debug Register 5 (DR5).
6381 Reads the current value of Debug Register 6 (DR6).
6383 Reads and returns the current value of DR6. This function is only available
6384 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6387 @return The value of Debug Register 6 (DR6).
6397 Reads the current value of Debug Register 7 (DR7).
6399 Reads and returns the current value of DR7. This function is only available
6400 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6403 @return The value of Debug Register 7 (DR7).
6413 Writes a value to Debug Register 0 (DR0).
6415 Writes and returns a new value to DR0. This function is only available on
6416 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6418 @param Dr0 The value to write to Dr0.
6420 @return The value written to Debug Register 0 (DR0).
6430 Writes a value to Debug Register 1 (DR1).
6432 Writes and returns a new value to DR1. This function is only available on
6433 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6435 @param Dr1 The value to write to Dr1.
6437 @return The value written to Debug Register 1 (DR1).
6447 Writes a value to Debug Register 2 (DR2).
6449 Writes and returns a new value to DR2. This function is only available on
6450 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6452 @param Dr2 The value to write to Dr2.
6454 @return The value written to Debug Register 2 (DR2).
6464 Writes a value to Debug Register 3 (DR3).
6466 Writes and returns a new value to DR3. This function is only available on
6467 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6469 @param Dr3 The value to write to Dr3.
6471 @return The value written to Debug Register 3 (DR3).
6481 Writes a value to Debug Register 4 (DR4).
6483 Writes and returns a new value to DR4. This function is only available on
6484 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6486 @param Dr4 The value to write to Dr4.
6488 @return The value written to Debug Register 4 (DR4).
6498 Writes a value to Debug Register 5 (DR5).
6500 Writes and returns a new value to DR5. This function is only available on
6501 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6503 @param Dr5 The value to write to Dr5.
6505 @return The value written to Debug Register 5 (DR5).
6515 Writes a value to Debug Register 6 (DR6).
6517 Writes and returns a new value to DR6. This function is only available on
6518 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6520 @param Dr6 The value to write to Dr6.
6522 @return The value written to Debug Register 6 (DR6).
6532 Writes a value to Debug Register 7 (DR7).
6534 Writes and returns a new value to DR7. This function is only available on
6535 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6537 @param Dr7 The value to write to Dr7.
6539 @return The value written to Debug Register 7 (DR7).
6549 Reads the current value of Code Segment Register (CS).
6551 Reads and returns the current value of CS. This function is only available on
6554 @return The current value of CS.
6564 Reads the current value of Data Segment Register (DS).
6566 Reads and returns the current value of DS. This function is only available on
6569 @return The current value of DS.
6579 Reads the current value of Extra Segment Register (ES).
6581 Reads and returns the current value of ES. This function is only available on
6584 @return The current value of ES.
6594 Reads the current value of FS Data Segment Register (FS).
6596 Reads and returns the current value of FS. This function is only available on
6599 @return The current value of FS.
6609 Reads the current value of GS Data Segment Register (GS).
6611 Reads and returns the current value of GS. This function is only available on
6614 @return The current value of GS.
6624 Reads the current value of Stack Segment Register (SS).
6626 Reads and returns the current value of SS. This function is only available on
6629 @return The current value of SS.
6639 Reads the current value of Task Register (TR).
6641 Reads and returns the current value of TR. This function is only available on
6644 @return The current value of TR.
6654 Reads the current Global Descriptor Table Register(GDTR) descriptor.
6656 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6657 function is only available on IA-32 and x64.
6659 If Gdtr is NULL, then ASSERT().
6661 @param Gdtr The pointer to a GDTR descriptor.
6667 OUT IA32_DESCRIPTOR
*Gdtr
6671 Writes the current Global Descriptor Table Register (GDTR) descriptor.
6673 Writes and the current GDTR descriptor specified by Gdtr. This function is
6674 only available on IA-32 and x64.
6676 If Gdtr is NULL, then ASSERT().
6678 @param Gdtr The pointer to a GDTR descriptor.
6684 IN CONST IA32_DESCRIPTOR
*Gdtr
6688 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
6690 Reads and returns the current IDTR descriptor and returns it in Idtr. This
6691 function is only available on IA-32 and x64.
6693 If Idtr is NULL, then ASSERT().
6695 @param Idtr The pointer to a IDTR descriptor.
6701 OUT IA32_DESCRIPTOR
*Idtr
6705 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
6707 Writes the current IDTR descriptor and returns it in Idtr. This function is
6708 only available on IA-32 and x64.
6710 If Idtr is NULL, then ASSERT().
6712 @param Idtr The pointer to a IDTR descriptor.
6718 IN CONST IA32_DESCRIPTOR
*Idtr
6722 Reads the current Local Descriptor Table Register(LDTR) selector.
6724 Reads and returns the current 16-bit LDTR descriptor value. This function is
6725 only available on IA-32 and x64.
6727 @return The current selector of LDT.
6737 Writes the current Local Descriptor Table Register (LDTR) selector.
6739 Writes and the current LDTR descriptor specified by Ldtr. This function is
6740 only available on IA-32 and x64.
6742 @param Ldtr 16-bit LDTR selector value.
6752 Save the current floating point/SSE/SSE2 context to a buffer.
6754 Saves the current floating point/SSE/SSE2 state to the buffer specified by
6755 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
6756 available on IA-32 and x64.
6758 If Buffer is NULL, then ASSERT().
6759 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6761 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
6767 OUT IA32_FX_BUFFER
*Buffer
6771 Restores the current floating point/SSE/SSE2 context from a buffer.
6773 Restores the current floating point/SSE/SSE2 state from the buffer specified
6774 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
6775 only available on IA-32 and x64.
6777 If Buffer is NULL, then ASSERT().
6778 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6779 If Buffer was not saved with AsmFxSave(), then ASSERT().
6781 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
6787 IN CONST IA32_FX_BUFFER
*Buffer
6791 Reads the current value of 64-bit MMX Register #0 (MM0).
6793 Reads and returns the current value of MM0. This function is only available
6796 @return The current value of MM0.
6806 Reads the current value of 64-bit MMX Register #1 (MM1).
6808 Reads and returns the current value of MM1. This function is only available
6811 @return The current value of MM1.
6821 Reads the current value of 64-bit MMX Register #2 (MM2).
6823 Reads and returns the current value of MM2. This function is only available
6826 @return The current value of MM2.
6836 Reads the current value of 64-bit MMX Register #3 (MM3).
6838 Reads and returns the current value of MM3. This function is only available
6841 @return The current value of MM3.
6851 Reads the current value of 64-bit MMX Register #4 (MM4).
6853 Reads and returns the current value of MM4. This function is only available
6856 @return The current value of MM4.
6866 Reads the current value of 64-bit MMX Register #5 (MM5).
6868 Reads and returns the current value of MM5. This function is only available
6871 @return The current value of MM5.
6881 Reads the current value of 64-bit MMX Register #6 (MM6).
6883 Reads and returns the current value of MM6. This function is only available
6886 @return The current value of MM6.
6896 Reads the current value of 64-bit MMX Register #7 (MM7).
6898 Reads and returns the current value of MM7. This function is only available
6901 @return The current value of MM7.
6911 Writes the current value of 64-bit MMX Register #0 (MM0).
6913 Writes the current value of MM0. This function is only available on IA32 and
6916 @param Value The 64-bit value to write to MM0.
6926 Writes the current value of 64-bit MMX Register #1 (MM1).
6928 Writes the current value of MM1. This function is only available on IA32 and
6931 @param Value The 64-bit value to write to MM1.
6941 Writes the current value of 64-bit MMX Register #2 (MM2).
6943 Writes the current value of MM2. This function is only available on IA32 and
6946 @param Value The 64-bit value to write to MM2.
6956 Writes the current value of 64-bit MMX Register #3 (MM3).
6958 Writes the current value of MM3. This function is only available on IA32 and
6961 @param Value The 64-bit value to write to MM3.
6971 Writes the current value of 64-bit MMX Register #4 (MM4).
6973 Writes the current value of MM4. This function is only available on IA32 and
6976 @param Value The 64-bit value to write to MM4.
6986 Writes the current value of 64-bit MMX Register #5 (MM5).
6988 Writes the current value of MM5. This function is only available on IA32 and
6991 @param Value The 64-bit value to write to MM5.
7001 Writes the current value of 64-bit MMX Register #6 (MM6).
7003 Writes the current value of MM6. This function is only available on IA32 and
7006 @param Value The 64-bit value to write to MM6.
7016 Writes the current value of 64-bit MMX Register #7 (MM7).
7018 Writes the current value of MM7. This function is only available on IA32 and
7021 @param Value The 64-bit value to write to MM7.
7031 Reads the current value of Time Stamp Counter (TSC).
7033 Reads and returns the current value of TSC. This function is only available
7036 @return The current value of TSC
7046 Reads the current value of a Performance Counter (PMC).
7048 Reads and returns the current value of performance counter specified by
7049 Index. This function is only available on IA-32 and x64.
7051 @param Index The 32-bit Performance Counter index to read.
7053 @return The value of the PMC specified by Index.
7063 Sets up a monitor buffer that is used by AsmMwait().
7065 Executes a MONITOR instruction with the register state specified by Eax, Ecx
7066 and Edx. Returns Eax. This function is only available on IA-32 and x64.
7068 @param Eax The value to load into EAX or RAX before executing the MONITOR
7070 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7072 @param Edx The value to load into EDX or RDX before executing the MONITOR
7087 Executes an MWAIT instruction.
7089 Executes an MWAIT instruction with the register state specified by Eax and
7090 Ecx. Returns Eax. This function is only available on IA-32 and x64.
7092 @param Eax The value to load into EAX or RAX before executing the MONITOR
7094 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7108 Executes a WBINVD instruction.
7110 Executes a WBINVD instruction. This function is only available on IA-32 and
7121 Executes a INVD instruction.
7123 Executes a INVD instruction. This function is only available on IA-32 and
7134 Flushes a cache line from all the instruction and data caches within the
7135 coherency domain of the CPU.
7137 Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7138 This function is only available on IA-32 and x64.
7140 @param LinearAddress The address of the cache line to flush. If the CPU is
7141 in a physical addressing mode, then LinearAddress is a
7142 physical address. If the CPU is in a virtual
7143 addressing mode, then LinearAddress is a virtual
7146 @return LinearAddress.
7151 IN VOID
*LinearAddress
7155 Enables the 32-bit paging mode on the CPU.
7157 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7158 must be properly initialized prior to calling this service. This function
7159 assumes the current execution mode is 32-bit protected mode. This function is
7160 only available on IA-32. After the 32-bit paging mode is enabled, control is
7161 transferred to the function specified by EntryPoint using the new stack
7162 specified by NewStack and passing in the parameters specified by Context1 and
7163 Context2. Context1 and Context2 are optional and may be NULL. The function
7164 EntryPoint must never return.
7166 If the current execution mode is not 32-bit protected mode, then ASSERT().
7167 If EntryPoint is NULL, then ASSERT().
7168 If NewStack is NULL, then ASSERT().
7170 There are a number of constraints that must be followed before calling this
7172 1) Interrupts must be disabled.
7173 2) The caller must be in 32-bit protected mode with flat descriptors. This
7174 means all descriptors must have a base of 0 and a limit of 4GB.
7175 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
7177 4) CR3 must point to valid page tables that will be used once the transition
7178 is complete, and those page tables must guarantee that the pages for this
7179 function and the stack are identity mapped.
7181 @param EntryPoint A pointer to function to call with the new stack after
7183 @param Context1 A pointer to the context to pass into the EntryPoint
7184 function as the first parameter after paging is enabled.
7185 @param Context2 A pointer to the context to pass into the EntryPoint
7186 function as the second parameter after paging is enabled.
7187 @param NewStack A pointer to the new stack to use for the EntryPoint
7188 function after paging is enabled.
7194 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7195 IN VOID
*Context1 OPTIONAL
,
7196 IN VOID
*Context2 OPTIONAL
,
7201 Disables the 32-bit paging mode on the CPU.
7203 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7204 mode. This function assumes the current execution mode is 32-paged protected
7205 mode. This function is only available on IA-32. After the 32-bit paging mode
7206 is disabled, control is transferred to the function specified by EntryPoint
7207 using the new stack specified by NewStack and passing in the parameters
7208 specified by Context1 and Context2. Context1 and Context2 are optional and
7209 may be NULL. The function EntryPoint must never return.
7211 If the current execution mode is not 32-bit paged mode, then ASSERT().
7212 If EntryPoint is NULL, then ASSERT().
7213 If NewStack is NULL, then ASSERT().
7215 There are a number of constraints that must be followed before calling this
7217 1) Interrupts must be disabled.
7218 2) The caller must be in 32-bit paged mode.
7219 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7220 4) CR3 must point to valid page tables that guarantee that the pages for
7221 this function and the stack are identity mapped.
7223 @param EntryPoint A pointer to function to call with the new stack after
7225 @param Context1 A pointer to the context to pass into the EntryPoint
7226 function as the first parameter after paging is disabled.
7227 @param Context2 A pointer to the context to pass into the EntryPoint
7228 function as the second parameter after paging is
7230 @param NewStack A pointer to the new stack to use for the EntryPoint
7231 function after paging is disabled.
7236 AsmDisablePaging32 (
7237 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7238 IN VOID
*Context1 OPTIONAL
,
7239 IN VOID
*Context2 OPTIONAL
,
7244 Enables the 64-bit paging mode on the CPU.
7246 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7247 must be properly initialized prior to calling this service. This function
7248 assumes the current execution mode is 32-bit protected mode with flat
7249 descriptors. This function is only available on IA-32. After the 64-bit
7250 paging mode is enabled, control is transferred to the function specified by
7251 EntryPoint using the new stack specified by NewStack and passing in the
7252 parameters specified by Context1 and Context2. Context1 and Context2 are
7253 optional and may be 0. The function EntryPoint must never return.
7255 If the current execution mode is not 32-bit protected mode with flat
7256 descriptors, then ASSERT().
7257 If EntryPoint is 0, then ASSERT().
7258 If NewStack is 0, then ASSERT().
7260 @param Cs The 16-bit selector to load in the CS before EntryPoint
7261 is called. The descriptor in the GDT that this selector
7262 references must be setup for long mode.
7263 @param EntryPoint The 64-bit virtual address of the function to call with
7264 the new stack after paging is enabled.
7265 @param Context1 The 64-bit virtual address of the context to pass into
7266 the EntryPoint function as the first parameter after
7268 @param Context2 The 64-bit virtual address of the context to pass into
7269 the EntryPoint function as the second parameter after
7271 @param NewStack The 64-bit virtual address of the new stack to use for
7272 the EntryPoint function after paging is enabled.
7279 IN UINT64 EntryPoint
,
7280 IN UINT64 Context1 OPTIONAL
,
7281 IN UINT64 Context2 OPTIONAL
,
7286 Disables the 64-bit paging mode on the CPU.
7288 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7289 mode. This function assumes the current execution mode is 64-paging mode.
7290 This function is only available on x64. After the 64-bit paging mode is
7291 disabled, control is transferred to the function specified by EntryPoint
7292 using the new stack specified by NewStack and passing in the parameters
7293 specified by Context1 and Context2. Context1 and Context2 are optional and
7294 may be 0. The function EntryPoint must never return.
7296 If the current execution mode is not 64-bit paged mode, then ASSERT().
7297 If EntryPoint is 0, then ASSERT().
7298 If NewStack is 0, then ASSERT().
7300 @param Cs The 16-bit selector to load in the CS before EntryPoint
7301 is called. The descriptor in the GDT that this selector
7302 references must be setup for 32-bit protected mode.
7303 @param EntryPoint The 64-bit virtual address of the function to call with
7304 the new stack after paging is disabled.
7305 @param Context1 The 64-bit virtual address of the context to pass into
7306 the EntryPoint function as the first parameter after
7308 @param Context2 The 64-bit virtual address of the context to pass into
7309 the EntryPoint function as the second parameter after
7311 @param NewStack The 64-bit virtual address of the new stack to use for
7312 the EntryPoint function after paging is disabled.
7317 AsmDisablePaging64 (
7319 IN UINT32 EntryPoint
,
7320 IN UINT32 Context1 OPTIONAL
,
7321 IN UINT32 Context2 OPTIONAL
,
7326 // 16-bit thunking services
7330 Retrieves the properties for 16-bit thunk functions.
7332 Computes the size of the buffer and stack below 1MB required to use the
7333 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7334 buffer size is returned in RealModeBufferSize, and the stack size is returned
7335 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7336 then the actual minimum stack size is ExtraStackSize plus the maximum number
7337 of bytes that need to be passed to the 16-bit real mode code.
7339 If RealModeBufferSize is NULL, then ASSERT().
7340 If ExtraStackSize is NULL, then ASSERT().
7342 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
7343 required to use the 16-bit thunk functions.
7344 @param ExtraStackSize A pointer to the extra size of stack below 1MB
7345 that the 16-bit thunk functions require for
7346 temporary storage in the transition to and from
7352 AsmGetThunk16Properties (
7353 OUT UINT32
*RealModeBufferSize
,
7354 OUT UINT32
*ExtraStackSize
7358 Prepares all structures a code required to use AsmThunk16().
7360 Prepares all structures and code required to use AsmThunk16().
7362 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7363 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7365 If ThunkContext is NULL, then ASSERT().
7367 @param ThunkContext A pointer to the context structure that describes the
7368 16-bit real mode code to call.
7374 IN OUT THUNK_CONTEXT
*ThunkContext
7378 Transfers control to a 16-bit real mode entry point and returns the results.
7380 Transfers control to a 16-bit real mode entry point and returns the results.
7381 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7382 This function must be called with interrupts disabled.
7384 The register state from the RealModeState field of ThunkContext is restored just prior
7385 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
7386 which is used to set the interrupt state when a 16-bit real mode entry point is called.
7387 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7388 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
7389 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7390 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7391 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7392 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7393 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7394 after the RETF instruction is executed.
7396 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7397 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7398 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7400 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7401 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7402 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7404 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7405 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7407 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7408 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7409 disable the A20 mask.
7411 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7412 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
7413 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7415 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7416 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7418 If ThunkContext is NULL, then ASSERT().
7419 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7420 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7421 ThunkAttributes, then ASSERT().
7423 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7424 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7426 @param ThunkContext A pointer to the context structure that describes the
7427 16-bit real mode code to call.
7433 IN OUT THUNK_CONTEXT
*ThunkContext
7437 Prepares all structures and code for a 16-bit real mode thunk, transfers
7438 control to a 16-bit real mode entry point, and returns the results.
7440 Prepares all structures and code for a 16-bit real mode thunk, transfers
7441 control to a 16-bit real mode entry point, and returns the results. If the
7442 caller only need to perform a single 16-bit real mode thunk, then this
7443 service should be used. If the caller intends to make more than one 16-bit
7444 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7445 once and AsmThunk16() can be called for each 16-bit real mode thunk.
7447 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7448 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7450 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7452 @param ThunkContext A pointer to the context structure that describes the
7453 16-bit real mode code to call.
7458 AsmPrepareAndThunk16 (
7459 IN OUT THUNK_CONTEXT
*ThunkContext
7463 Generates a 16-bit random number through RDRAND instruction.
7465 if Rand is NULL, then ASSERT().
7467 @param[out] Rand Buffer pointer to store the random result.
7469 @retval TRUE RDRAND call was successful.
7470 @retval FALSE Failed attempts to call RDRAND.
7480 Generates a 32-bit random number through RDRAND instruction.
7482 if Rand is NULL, then ASSERT().
7484 @param[out] Rand Buffer pointer to store the random result.
7486 @retval TRUE RDRAND call was successful.
7487 @retval FALSE Failed attempts to call RDRAND.
7497 Generates a 64-bit random number through RDRAND instruction.
7499 if Rand is NULL, then ASSERT().
7501 @param[out] Rand Buffer pointer to store the random result.
7503 @retval TRUE RDRAND call was successful.
7504 @retval FALSE Failed attempts to call RDRAND.
7514 Load given selector into TR register.
7516 @param[in] Selector Task segment selector
7525 Performs a serializing operation on all load-from-memory instructions that
7526 were issued prior the AsmLfence function.
7528 Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7538 Executes a XGETBV instruction
7540 Executes a XGETBV instruction. This function is only available on IA-32 and
7543 @param[in] Index Extended control register index
7545 @return The current value of the extended control register
7554 Executes a XSETBV instruction to write a 64-bit value to a Extended Control
7555 Register(XCR), and returns the value.
7557 Writes the 64-bit value specified by Value to the XCR specified by Index. The
7558 64-bit value written to the XCR is returned. No parameter checking is
7559 performed on Index or Value, and some of these may cause CPU exceptions. The
7560 caller must either guarantee that Index and Value are valid, or the caller
7561 must establish proper exception handlers. This function is only available on
7564 @param Index The 32-bit XCR index to write.
7565 @param Value The 64-bit value to write to the XCR.
7578 Executes a VMGEXIT instruction (VMMCALL with a REP prefix)
7580 Executes a VMGEXIT instruction. This function is only available on IA-32 and
7591 Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7592 word, dword or qword operand is encoded at the end of the instruction's
7593 binary representation.
7595 This function should be used to update object code that was compiled with
7596 NASM from assembly source code. Example:
7600 mov eax, strict dword 0 ; the imm32 zero operand will be patched
7606 X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7607 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7609 @param[out] InstructionEnd Pointer right past the instruction to patch. The
7610 immediate operand to patch is expected to
7611 comprise the trailing bytes of the instruction.
7612 If InstructionEnd is closer to address 0 than
7613 ValueSize permits, then ASSERT().
7615 @param[in] PatchValue The constant to write to the immediate operand.
7616 The caller is responsible for ensuring that
7617 PatchValue can be represented in the byte, word,
7618 dword or qword operand (as indicated through
7619 ValueSize); otherwise ASSERT().
7621 @param[in] ValueSize The size of the operand in bytes; must be 1, 2,
7622 4, or 8. ASSERT() otherwise.
7626 PatchInstructionX86 (
7627 OUT X86_ASSEMBLY_PATCH_LABEL
*InstructionEnd
,
7628 IN UINT64 PatchValue
,
7632 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7633 #endif // !defined (__BASE_LIB__)