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>
10 SPDX-License-Identifier: BSD-2-Clause-Patent
18 // Definitions for architecture-specific types
20 #if defined (MDE_CPU_IA32)
22 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
32 } BASE_LIBRARY_JUMP_BUFFER
;
34 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
36 #endif // defined (MDE_CPU_IA32)
38 #if defined (MDE_CPU_X64)
40 /// The x64 architecture context buffer used by SetJump() and LongJump().
54 UINT8 XmmBuffer
[160]; ///< XMM6-XMM15.
56 } BASE_LIBRARY_JUMP_BUFFER
;
58 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
60 #endif // defined (MDE_CPU_X64)
62 #if defined (MDE_CPU_EBC)
64 /// The EBC context buffer used by SetJump() and LongJump().
72 } BASE_LIBRARY_JUMP_BUFFER
;
74 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
76 #endif // defined (MDE_CPU_EBC)
78 #if defined (MDE_CPU_ARM)
81 UINT32 R3
; ///< A copy of R13.
92 } BASE_LIBRARY_JUMP_BUFFER
;
94 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
96 #endif // defined (MDE_CPU_ARM)
98 #if defined (MDE_CPU_AARCH64)
124 } BASE_LIBRARY_JUMP_BUFFER
;
126 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
128 #endif // defined (MDE_CPU_AARCH64)
130 #if defined (MDE_CPU_RISCV64)
132 /// The RISC-V architecture context buffer used by SetJump() and LongJump().
149 } BASE_LIBRARY_JUMP_BUFFER
;
151 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
153 #endif // defined (MDE_CPU_RISCV64)
160 Returns the length of a Null-terminated Unicode string.
162 This function is similar as strlen_s defined in C11.
164 If String is not aligned on a 16-bit boundary, then ASSERT().
166 @param String A pointer to a Null-terminated Unicode string.
167 @param MaxSize The maximum number of Destination Unicode
168 char, including terminating null char.
170 @retval 0 If String is NULL.
171 @retval MaxSize If there is no null character in the first MaxSize characters of String.
172 @return The number of characters that percede the terminating null character.
178 IN CONST CHAR16
*String
,
183 Returns the size of a Null-terminated Unicode string in bytes, including the
186 This function returns the size of the Null-terminated Unicode string
187 specified by String in bytes, including the Null terminator.
189 If String is not aligned on a 16-bit boundary, then ASSERT().
191 @param String A pointer to a Null-terminated Unicode string.
192 @param MaxSize The maximum number of Destination Unicode
193 char, including the Null terminator.
195 @retval 0 If String is NULL.
196 @retval (sizeof (CHAR16) * (MaxSize + 1))
197 If there is no Null terminator in the first MaxSize characters of
199 @return The size of the Null-terminated Unicode string in bytes, including
206 IN CONST CHAR16
*String
,
211 Copies the string pointed to by Source (including the terminating null char)
212 to the array pointed to by Destination.
214 This function is similar as strcpy_s defined in C11.
216 If Destination is not aligned on a 16-bit boundary, then ASSERT().
217 If Source is not aligned on a 16-bit boundary, then ASSERT().
219 If an error is returned, then the Destination is unmodified.
221 @param Destination A pointer to a Null-terminated Unicode string.
222 @param DestMax The maximum number of Destination Unicode
223 char, including terminating null char.
224 @param Source A pointer to a Null-terminated Unicode string.
226 @retval RETURN_SUCCESS String is copied.
227 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
228 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
230 If PcdMaximumUnicodeStringLength is not zero,
231 and DestMax is greater than
232 PcdMaximumUnicodeStringLength.
234 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
239 OUT CHAR16
*Destination
,
241 IN CONST CHAR16
*Source
245 Copies not more than Length successive char from the string pointed to by
246 Source to the array pointed to by Destination. If no null char is copied from
247 Source, then Destination[Length] is always set to null.
249 This function is similar as strncpy_s defined in C11.
251 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
252 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
254 If an error is returned, then the Destination is unmodified.
256 @param Destination A pointer to a Null-terminated Unicode string.
257 @param DestMax The maximum number of Destination Unicode
258 char, including terminating null char.
259 @param Source A pointer to a Null-terminated Unicode string.
260 @param Length The maximum number of Unicode characters to copy.
262 @retval RETURN_SUCCESS String is copied.
263 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
264 MIN(StrLen(Source), Length).
265 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
267 If PcdMaximumUnicodeStringLength is not zero,
268 and DestMax is greater than
269 PcdMaximumUnicodeStringLength.
271 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
276 OUT CHAR16
*Destination
,
278 IN CONST CHAR16
*Source
,
283 Appends a copy of the string pointed to by Source (including the terminating
284 null char) to the end of the string pointed to by Destination.
286 This function is similar as strcat_s defined in C11.
288 If Destination is not aligned on a 16-bit boundary, then ASSERT().
289 If Source is not aligned on a 16-bit boundary, then ASSERT().
291 If an error is returned, then the Destination is unmodified.
293 @param Destination A pointer to a Null-terminated Unicode string.
294 @param DestMax The maximum number of Destination Unicode
295 char, including terminating null char.
296 @param Source A pointer to a Null-terminated Unicode string.
298 @retval RETURN_SUCCESS String is appended.
299 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
301 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
302 greater than StrLen(Source).
303 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
305 If PcdMaximumUnicodeStringLength is not zero,
306 and DestMax is greater than
307 PcdMaximumUnicodeStringLength.
309 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
314 IN OUT CHAR16
*Destination
,
316 IN CONST CHAR16
*Source
320 Appends not more than Length successive char from the string pointed to by
321 Source to the end of the string pointed to by Destination. If no null char is
322 copied from Source, then Destination[StrLen(Destination) + Length] is always
325 This function is similar as strncat_s defined in C11.
327 If Destination is not aligned on a 16-bit boundary, then ASSERT().
328 If Source is not aligned on a 16-bit boundary, then ASSERT().
330 If an error is returned, then the Destination is unmodified.
332 @param Destination A pointer to a Null-terminated Unicode string.
333 @param DestMax The maximum number of Destination Unicode
334 char, including terminating null char.
335 @param Source A pointer to a Null-terminated Unicode string.
336 @param Length The maximum number of Unicode characters to copy.
338 @retval RETURN_SUCCESS String is appended.
339 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
341 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
342 greater than MIN(StrLen(Source), Length).
343 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
345 If PcdMaximumUnicodeStringLength is not zero,
346 and DestMax is greater than
347 PcdMaximumUnicodeStringLength.
349 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
354 IN OUT CHAR16
*Destination
,
356 IN CONST CHAR16
*Source
,
361 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
363 This function outputs a value of type UINTN by interpreting the contents of
364 the Unicode string specified by String as a decimal number. The format of the
365 input Unicode string String is:
367 [spaces] [decimal digits].
369 The valid decimal digit character is in the range [0-9]. The function will
370 ignore the pad space, which includes spaces or tab characters, before
371 [decimal digits]. The running zero in the beginning of [decimal digits] will
372 be ignored. Then, the function stops at the first character that is a not a
373 valid decimal character or a Null-terminator, whichever one comes first.
375 If String is not aligned in a 16-bit boundary, then ASSERT().
377 If String has no valid decimal digits in the above format, then 0 is stored
378 at the location pointed to by Data.
379 If the number represented by String exceeds the range defined by UINTN, then
380 MAX_UINTN is stored at the location pointed to by Data.
382 If EndPointer is not NULL, a pointer to the character that stopped the scan
383 is stored at the location pointed to by EndPointer. If String has no valid
384 decimal digits right after the optional pad spaces, the value of String is
385 stored at the location pointed to by EndPointer.
387 @param String Pointer to a Null-terminated Unicode string.
388 @param EndPointer Pointer to character that stops scan.
389 @param Data Pointer to the converted value.
391 @retval RETURN_SUCCESS Value is translated from String.
392 @retval RETURN_INVALID_PARAMETER If String is NULL.
394 If PcdMaximumUnicodeStringLength is not
395 zero, and String contains more than
396 PcdMaximumUnicodeStringLength Unicode
397 characters, not including the
399 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
400 the range defined by UINTN.
406 IN CONST CHAR16
*String
,
407 OUT CHAR16
**EndPointer OPTIONAL
,
412 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
414 This function outputs a value of type UINT64 by interpreting the contents of
415 the Unicode string specified by String as a decimal number. The format of the
416 input Unicode string String is:
418 [spaces] [decimal digits].
420 The valid decimal digit character is in the range [0-9]. The function will
421 ignore the pad space, which includes spaces or tab characters, before
422 [decimal digits]. The running zero in the beginning of [decimal digits] will
423 be ignored. Then, the function stops at the first character that is a not a
424 valid decimal character or a Null-terminator, whichever one comes first.
426 If String is not aligned in a 16-bit boundary, then ASSERT().
428 If String has no valid decimal digits in the above format, then 0 is stored
429 at the location pointed to by Data.
430 If the number represented by String exceeds the range defined by UINT64, then
431 MAX_UINT64 is stored at the location pointed to by Data.
433 If EndPointer is not NULL, a pointer to the character that stopped the scan
434 is stored at the location pointed to by EndPointer. If String has no valid
435 decimal digits right after the optional pad spaces, the value of String is
436 stored at the location pointed to by EndPointer.
438 @param String Pointer to a Null-terminated Unicode string.
439 @param EndPointer Pointer to character that stops scan.
440 @param Data Pointer to the converted value.
442 @retval RETURN_SUCCESS Value is translated from String.
443 @retval RETURN_INVALID_PARAMETER If String is NULL.
445 If PcdMaximumUnicodeStringLength is not
446 zero, and String contains more than
447 PcdMaximumUnicodeStringLength Unicode
448 characters, not including the
450 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
451 the range defined by UINT64.
456 StrDecimalToUint64S (
457 IN CONST CHAR16
*String
,
458 OUT CHAR16
**EndPointer OPTIONAL
,
463 Convert a Null-terminated Unicode hexadecimal string to a value of type
466 This function outputs a value of type UINTN by interpreting the contents of
467 the Unicode string specified by String as a hexadecimal number. The format of
468 the input Unicode string String is:
470 [spaces][zeros][x][hexadecimal digits].
472 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
473 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
474 If "x" appears in the input string, it must be prefixed with at least one 0.
475 The function will ignore the pad space, which includes spaces or tab
476 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
477 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
478 after [x] or the first valid hexadecimal digit. Then, the function stops at
479 the first character that is a not a valid hexadecimal character or NULL,
480 whichever one comes first.
482 If String is not aligned in a 16-bit boundary, then ASSERT().
484 If String has no valid hexadecimal digits in the above format, then 0 is
485 stored at the location pointed to by Data.
486 If the number represented by String exceeds the range defined by UINTN, then
487 MAX_UINTN is stored at the location pointed to by Data.
489 If EndPointer is not NULL, a pointer to the character that stopped the scan
490 is stored at the location pointed to by EndPointer. If String has no valid
491 hexadecimal digits right after the optional pad spaces, the value of String
492 is stored at the location pointed to by EndPointer.
494 @param String Pointer to a Null-terminated Unicode string.
495 @param EndPointer Pointer to character that stops scan.
496 @param Data Pointer to the converted value.
498 @retval RETURN_SUCCESS Value is translated from String.
499 @retval RETURN_INVALID_PARAMETER If String is NULL.
501 If PcdMaximumUnicodeStringLength is not
502 zero, and String contains more than
503 PcdMaximumUnicodeStringLength Unicode
504 characters, not including the
506 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
507 the range defined by UINTN.
513 IN CONST CHAR16
*String
,
514 OUT CHAR16
**EndPointer OPTIONAL
,
519 Convert a Null-terminated Unicode hexadecimal string to a value of type
522 This function outputs a value of type UINT64 by interpreting the contents of
523 the Unicode string specified by String as a hexadecimal number. The format of
524 the input Unicode string String is:
526 [spaces][zeros][x][hexadecimal digits].
528 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
529 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
530 If "x" appears in the input string, it must be prefixed with at least one 0.
531 The function will ignore the pad space, which includes spaces or tab
532 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
533 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
534 after [x] or the first valid hexadecimal digit. Then, the function stops at
535 the first character that is a not a valid hexadecimal character or NULL,
536 whichever one comes first.
538 If String is not aligned in a 16-bit boundary, then ASSERT().
540 If String has no valid hexadecimal digits in the above format, then 0 is
541 stored at the location pointed to by Data.
542 If the number represented by String exceeds the range defined by UINT64, then
543 MAX_UINT64 is stored at the location pointed to by Data.
545 If EndPointer is not NULL, a pointer to the character that stopped the scan
546 is stored at the location pointed to by EndPointer. If String has no valid
547 hexadecimal digits right after the optional pad spaces, the value of String
548 is stored at the location pointed to by EndPointer.
550 @param String Pointer to a Null-terminated Unicode string.
551 @param EndPointer Pointer to character that stops scan.
552 @param Data Pointer to the converted value.
554 @retval RETURN_SUCCESS Value is translated from String.
555 @retval RETURN_INVALID_PARAMETER If String is NULL.
557 If PcdMaximumUnicodeStringLength is not
558 zero, and String contains more than
559 PcdMaximumUnicodeStringLength Unicode
560 characters, not including the
562 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
563 the range defined by UINT64.
569 IN CONST CHAR16
*String
,
570 OUT CHAR16
**EndPointer OPTIONAL
,
575 Returns the length of a Null-terminated Ascii string.
577 This function is similar as strlen_s defined in C11.
579 @param String A pointer to a Null-terminated Ascii string.
580 @param MaxSize The maximum number of Destination Ascii
581 char, including terminating null char.
583 @retval 0 If String is NULL.
584 @retval MaxSize If there is no null character in the first MaxSize characters of String.
585 @return The number of characters that percede the terminating null character.
591 IN CONST CHAR8
*String
,
596 Returns the size of a Null-terminated Ascii string in bytes, including the
599 This function returns the size of the Null-terminated Ascii string specified
600 by String in bytes, including the Null terminator.
602 @param String A pointer to a Null-terminated Ascii string.
603 @param MaxSize The maximum number of Destination Ascii
604 char, including the Null terminator.
606 @retval 0 If String is NULL.
607 @retval (sizeof (CHAR8) * (MaxSize + 1))
608 If there is no Null terminator in the first MaxSize characters of
610 @return The size of the Null-terminated Ascii string in bytes, including the
617 IN CONST CHAR8
*String
,
622 Copies the string pointed to by Source (including the terminating null char)
623 to the array pointed to by Destination.
625 This function is similar as strcpy_s defined in C11.
627 If an error is returned, then the Destination is unmodified.
629 @param Destination A pointer to a Null-terminated Ascii string.
630 @param DestMax The maximum number of Destination Ascii
631 char, including terminating null char.
632 @param Source A pointer to a Null-terminated Ascii string.
634 @retval RETURN_SUCCESS String is copied.
635 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
636 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
638 If PcdMaximumAsciiStringLength is not zero,
639 and DestMax is greater than
640 PcdMaximumAsciiStringLength.
642 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
647 OUT CHAR8
*Destination
,
649 IN CONST CHAR8
*Source
653 Copies not more than Length successive char from the string pointed to by
654 Source to the array pointed to by Destination. If no null char is copied from
655 Source, then Destination[Length] is always set to null.
657 This function is similar as strncpy_s defined in C11.
659 If an error is returned, then the Destination is unmodified.
661 @param Destination A pointer to a Null-terminated Ascii string.
662 @param DestMax The maximum number of Destination Ascii
663 char, including terminating null char.
664 @param Source A pointer to a Null-terminated Ascii string.
665 @param Length The maximum number of Ascii characters to copy.
667 @retval RETURN_SUCCESS String is copied.
668 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
669 MIN(StrLen(Source), Length).
670 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
672 If PcdMaximumAsciiStringLength is not zero,
673 and DestMax is greater than
674 PcdMaximumAsciiStringLength.
676 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
681 OUT CHAR8
*Destination
,
683 IN CONST CHAR8
*Source
,
688 Appends a copy of the string pointed to by Source (including the terminating
689 null char) to the end of the string pointed to by Destination.
691 This function is similar as strcat_s defined in C11.
693 If an error is returned, then the Destination is unmodified.
695 @param Destination A pointer to a Null-terminated Ascii string.
696 @param DestMax The maximum number of Destination Ascii
697 char, including terminating null char.
698 @param Source A pointer to a Null-terminated Ascii string.
700 @retval RETURN_SUCCESS String is appended.
701 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
703 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
704 greater than StrLen(Source).
705 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
707 If PcdMaximumAsciiStringLength is not zero,
708 and DestMax is greater than
709 PcdMaximumAsciiStringLength.
711 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
716 IN OUT CHAR8
*Destination
,
718 IN CONST CHAR8
*Source
722 Appends not more than Length successive char from the string pointed to by
723 Source to the end of the string pointed to by Destination. If no null char is
724 copied from Source, then Destination[StrLen(Destination) + Length] is always
727 This function is similar as strncat_s defined in C11.
729 If an error is returned, then the Destination is unmodified.
731 @param Destination A pointer to a Null-terminated Ascii string.
732 @param DestMax The maximum number of Destination Ascii
733 char, including terminating null char.
734 @param Source A pointer to a Null-terminated Ascii string.
735 @param Length The maximum number of Ascii characters to copy.
737 @retval RETURN_SUCCESS String is appended.
738 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
740 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
741 greater than MIN(StrLen(Source), Length).
742 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
744 If PcdMaximumAsciiStringLength is not zero,
745 and DestMax is greater than
746 PcdMaximumAsciiStringLength.
748 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
753 IN OUT CHAR8
*Destination
,
755 IN CONST CHAR8
*Source
,
760 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
762 This function outputs a value of type UINTN by interpreting the contents of
763 the Ascii string specified by String as a decimal number. The format of the
764 input Ascii string String is:
766 [spaces] [decimal digits].
768 The valid decimal digit character is in the range [0-9]. The function will
769 ignore the pad space, which includes spaces or tab characters, before
770 [decimal digits]. The running zero in the beginning of [decimal digits] will
771 be ignored. Then, the function stops at the first character that is a not a
772 valid decimal character or a Null-terminator, whichever one comes first.
774 If String has no valid decimal digits in the above format, then 0 is stored
775 at the location pointed to by Data.
776 If the number represented by String exceeds the range defined by UINTN, then
777 MAX_UINTN is stored at the location pointed to by Data.
779 If EndPointer is not NULL, a pointer to the character that stopped the scan
780 is stored at the location pointed to by EndPointer. If String has no valid
781 decimal digits right after the optional pad spaces, the value of String is
782 stored at the location pointed to by EndPointer.
784 @param String Pointer to a Null-terminated Ascii string.
785 @param EndPointer Pointer to character that stops scan.
786 @param Data Pointer to the converted value.
788 @retval RETURN_SUCCESS Value is translated from String.
789 @retval RETURN_INVALID_PARAMETER If String is NULL.
791 If PcdMaximumAsciiStringLength is not zero,
792 and String contains more than
793 PcdMaximumAsciiStringLength Ascii
794 characters, not including the
796 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
797 the range defined by UINTN.
802 AsciiStrDecimalToUintnS (
803 IN CONST CHAR8
*String
,
804 OUT CHAR8
**EndPointer OPTIONAL
,
809 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
811 This function outputs a value of type UINT64 by interpreting the contents of
812 the Ascii string specified by String as a decimal number. The format of the
813 input Ascii string String is:
815 [spaces] [decimal digits].
817 The valid decimal digit character is in the range [0-9]. The function will
818 ignore the pad space, which includes spaces or tab characters, before
819 [decimal digits]. The running zero in the beginning of [decimal digits] will
820 be ignored. Then, the function stops at the first character that is a not a
821 valid decimal character or a Null-terminator, whichever one comes first.
823 If String has no valid decimal digits in the above format, then 0 is stored
824 at the location pointed to by Data.
825 If the number represented by String exceeds the range defined by UINT64, then
826 MAX_UINT64 is stored at the location pointed to by Data.
828 If EndPointer is not NULL, a pointer to the character that stopped the scan
829 is stored at the location pointed to by EndPointer. If String has no valid
830 decimal digits right after the optional pad spaces, the value of String is
831 stored at the location pointed to by EndPointer.
833 @param String Pointer to a Null-terminated Ascii string.
834 @param EndPointer Pointer to character that stops scan.
835 @param Data Pointer to the converted value.
837 @retval RETURN_SUCCESS Value is translated from String.
838 @retval RETURN_INVALID_PARAMETER If String is NULL.
840 If PcdMaximumAsciiStringLength is not zero,
841 and String contains more than
842 PcdMaximumAsciiStringLength Ascii
843 characters, not including the
845 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
846 the range defined by UINT64.
851 AsciiStrDecimalToUint64S (
852 IN CONST CHAR8
*String
,
853 OUT CHAR8
**EndPointer OPTIONAL
,
858 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
860 This function outputs a value of type UINTN by interpreting the contents of
861 the Ascii string specified by String as a hexadecimal number. The format of
862 the input Ascii string String is:
864 [spaces][zeros][x][hexadecimal digits].
866 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
867 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
868 "x" appears in the input string, it must be prefixed with at least one 0. The
869 function will ignore the pad space, which includes spaces or tab characters,
870 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
871 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
872 the first valid hexadecimal digit. Then, the function stops at the first
873 character that is a not a valid hexadecimal character or Null-terminator,
874 whichever on comes first.
876 If String has no valid hexadecimal digits in the above format, then 0 is
877 stored at the location pointed to by Data.
878 If the number represented by String exceeds the range defined by UINTN, then
879 MAX_UINTN is stored at the location pointed to by Data.
881 If EndPointer is not NULL, a pointer to the character that stopped the scan
882 is stored at the location pointed to by EndPointer. If String has no valid
883 hexadecimal digits right after the optional pad spaces, the value of String
884 is stored at the location pointed to by EndPointer.
886 @param String Pointer to a Null-terminated Ascii string.
887 @param EndPointer Pointer to character that stops scan.
888 @param Data Pointer to the converted value.
890 @retval RETURN_SUCCESS Value is translated from String.
891 @retval RETURN_INVALID_PARAMETER If String is NULL.
893 If PcdMaximumAsciiStringLength is not zero,
894 and String contains more than
895 PcdMaximumAsciiStringLength Ascii
896 characters, not including the
898 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
899 the range defined by UINTN.
904 AsciiStrHexToUintnS (
905 IN CONST CHAR8
*String
,
906 OUT CHAR8
**EndPointer OPTIONAL
,
911 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
913 This function outputs a value of type UINT64 by interpreting the contents of
914 the Ascii string specified by String as a hexadecimal number. The format of
915 the input Ascii string String is:
917 [spaces][zeros][x][hexadecimal digits].
919 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
920 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
921 "x" appears in the input string, it must be prefixed with at least one 0. The
922 function will ignore the pad space, which includes spaces or tab characters,
923 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
924 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
925 the first valid hexadecimal digit. Then, the function stops at the first
926 character that is a not a valid hexadecimal character or Null-terminator,
927 whichever on comes first.
929 If String has no valid hexadecimal digits in the above format, then 0 is
930 stored at the location pointed to by Data.
931 If the number represented by String exceeds the range defined by UINT64, then
932 MAX_UINT64 is stored at the location pointed to by Data.
934 If EndPointer is not NULL, a pointer to the character that stopped the scan
935 is stored at the location pointed to by EndPointer. If String has no valid
936 hexadecimal digits right after the optional pad spaces, the value of String
937 is stored at the location pointed to by EndPointer.
939 @param String Pointer to a Null-terminated Ascii string.
940 @param EndPointer Pointer to character that stops scan.
941 @param Data Pointer to the converted value.
943 @retval RETURN_SUCCESS Value is translated from String.
944 @retval RETURN_INVALID_PARAMETER If String is NULL.
946 If PcdMaximumAsciiStringLength is not zero,
947 and String contains more than
948 PcdMaximumAsciiStringLength Ascii
949 characters, not including the
951 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
952 the range defined by UINT64.
957 AsciiStrHexToUint64S (
958 IN CONST CHAR8
*String
,
959 OUT CHAR8
**EndPointer OPTIONAL
,
964 Returns the length of a Null-terminated Unicode string.
966 This function returns the number of Unicode characters in the Null-terminated
967 Unicode string specified by String.
969 If String is NULL, then ASSERT().
970 If String is not aligned on a 16-bit boundary, then ASSERT().
971 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
972 PcdMaximumUnicodeStringLength Unicode characters not including the
973 Null-terminator, then ASSERT().
975 @param String Pointer to a Null-terminated Unicode string.
977 @return The length of String.
983 IN CONST CHAR16
*String
987 Returns the size of a Null-terminated Unicode string in bytes, including the
990 This function returns the size, in bytes, of the Null-terminated Unicode string
993 If String is NULL, then ASSERT().
994 If String is not aligned on a 16-bit boundary, then ASSERT().
995 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
996 PcdMaximumUnicodeStringLength Unicode characters not including the
997 Null-terminator, then ASSERT().
999 @param String The pointer to a Null-terminated Unicode string.
1001 @return The size of String.
1007 IN CONST CHAR16
*String
1011 Compares two Null-terminated Unicode strings, and returns the difference
1012 between the first mismatched Unicode characters.
1014 This function compares the Null-terminated Unicode string FirstString to the
1015 Null-terminated Unicode string SecondString. If FirstString is identical to
1016 SecondString, then 0 is returned. Otherwise, the value returned is the first
1017 mismatched Unicode character in SecondString subtracted from the first
1018 mismatched Unicode character in FirstString.
1020 If FirstString is NULL, then ASSERT().
1021 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1022 If SecondString is NULL, then ASSERT().
1023 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1024 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1025 than PcdMaximumUnicodeStringLength Unicode characters not including the
1026 Null-terminator, then ASSERT().
1027 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1028 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1029 Null-terminator, then ASSERT().
1031 @param FirstString The pointer to a Null-terminated Unicode string.
1032 @param SecondString The pointer to a Null-terminated Unicode string.
1034 @retval 0 FirstString is identical to SecondString.
1035 @return others FirstString is not identical to SecondString.
1041 IN CONST CHAR16
*FirstString
,
1042 IN CONST CHAR16
*SecondString
1046 Compares up to a specified length the contents of two Null-terminated Unicode strings,
1047 and returns the difference between the first mismatched Unicode characters.
1049 This function compares the Null-terminated Unicode string FirstString to the
1050 Null-terminated Unicode string SecondString. At most, Length Unicode
1051 characters will be compared. If Length is 0, then 0 is returned. If
1052 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1053 value returned is the first mismatched Unicode character in SecondString
1054 subtracted from the first mismatched Unicode character in FirstString.
1056 If Length > 0 and FirstString is NULL, then ASSERT().
1057 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1058 If Length > 0 and SecondString is NULL, then ASSERT().
1059 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1060 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1061 PcdMaximumUnicodeStringLength, then ASSERT().
1062 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1063 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1065 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1066 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1069 @param FirstString The pointer to a Null-terminated Unicode string.
1070 @param SecondString The pointer to a Null-terminated Unicode string.
1071 @param Length The maximum number of Unicode characters to compare.
1073 @retval 0 FirstString is identical to SecondString.
1074 @return others FirstString is not identical to SecondString.
1080 IN CONST CHAR16
*FirstString
,
1081 IN CONST CHAR16
*SecondString
,
1086 Returns the first occurrence of a Null-terminated Unicode sub-string
1087 in a Null-terminated Unicode string.
1089 This function scans the contents of the Null-terminated Unicode string
1090 specified by String and returns the first occurrence of SearchString.
1091 If SearchString is not found in String, then NULL is returned. If
1092 the length of SearchString is zero, then String is returned.
1094 If String is NULL, then ASSERT().
1095 If String is not aligned on a 16-bit boundary, then ASSERT().
1096 If SearchString is NULL, then ASSERT().
1097 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1099 If PcdMaximumUnicodeStringLength is not zero, and SearchString
1100 or String contains more than PcdMaximumUnicodeStringLength Unicode
1101 characters, not including the Null-terminator, then ASSERT().
1103 @param String The pointer to a Null-terminated Unicode string.
1104 @param SearchString The pointer to a Null-terminated Unicode string to search for.
1106 @retval NULL If the SearchString does not appear in String.
1107 @return others If there is a match.
1113 IN CONST CHAR16
*String
,
1114 IN CONST CHAR16
*SearchString
1118 Convert a Null-terminated Unicode decimal string to a value of
1121 This function returns a value of type UINTN by interpreting the contents
1122 of the Unicode string specified by String as a decimal number. The format
1123 of the input Unicode string String is:
1125 [spaces] [decimal digits].
1127 The valid decimal digit character is in the range [0-9]. The
1128 function will ignore the pad space, which includes spaces or
1129 tab characters, before [decimal digits]. The running zero in the
1130 beginning of [decimal digits] will be ignored. Then, the function
1131 stops at the first character that is a not a valid decimal character
1132 or a Null-terminator, whichever one comes first.
1134 If String is NULL, then ASSERT().
1135 If String is not aligned in a 16-bit boundary, then ASSERT().
1136 If String has only pad spaces, then 0 is returned.
1137 If String has no pad spaces or valid decimal digits,
1139 If the number represented by String overflows according
1140 to the range defined by UINTN, then MAX_UINTN is returned.
1142 If PcdMaximumUnicodeStringLength is not zero, and String contains
1143 more than PcdMaximumUnicodeStringLength Unicode characters not including
1144 the Null-terminator, then ASSERT().
1146 @param String The pointer to a Null-terminated Unicode string.
1148 @retval Value translated from String.
1154 IN CONST CHAR16
*String
1158 Convert a Null-terminated Unicode decimal string to a value of
1161 This function returns a value of type UINT64 by interpreting the contents
1162 of the Unicode string specified by String as a decimal number. The format
1163 of the input Unicode string String is:
1165 [spaces] [decimal digits].
1167 The valid decimal digit character is in the range [0-9]. The
1168 function will ignore the pad space, which includes spaces or
1169 tab characters, before [decimal digits]. The running zero in the
1170 beginning of [decimal digits] will be ignored. Then, the function
1171 stops at the first character that is a not a valid decimal character
1172 or a Null-terminator, whichever one comes first.
1174 If String is NULL, then ASSERT().
1175 If String is not aligned in a 16-bit boundary, then ASSERT().
1176 If String has only pad spaces, then 0 is returned.
1177 If String has no pad spaces or valid decimal digits,
1179 If the number represented by String overflows according
1180 to the range defined by UINT64, then MAX_UINT64 is returned.
1182 If PcdMaximumUnicodeStringLength is not zero, and String contains
1183 more than PcdMaximumUnicodeStringLength Unicode characters not including
1184 the Null-terminator, then ASSERT().
1186 @param String The pointer to a Null-terminated Unicode string.
1188 @retval Value translated from String.
1193 StrDecimalToUint64 (
1194 IN CONST CHAR16
*String
1198 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1200 This function returns a value of type UINTN by interpreting the contents
1201 of the Unicode string specified by String as a hexadecimal number.
1202 The format of the input Unicode string String is:
1204 [spaces][zeros][x][hexadecimal digits].
1206 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1207 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1208 If "x" appears in the input string, it must be prefixed with at least one 0.
1209 The function will ignore the pad space, which includes spaces or tab characters,
1210 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1211 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1212 first valid hexadecimal digit. Then, the function stops at the first character
1213 that is a not a valid hexadecimal character or NULL, whichever one comes first.
1215 If String is NULL, then ASSERT().
1216 If String is not aligned in a 16-bit boundary, then ASSERT().
1217 If String has only pad spaces, then zero is returned.
1218 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1219 then zero is returned.
1220 If the number represented by String overflows according to the range defined by
1221 UINTN, then MAX_UINTN is returned.
1223 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1224 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1227 @param String The pointer to a Null-terminated Unicode string.
1229 @retval Value translated from String.
1235 IN CONST CHAR16
*String
1239 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1241 This function returns a value of type UINT64 by interpreting the contents
1242 of the Unicode string specified by String as a hexadecimal number.
1243 The format of the input Unicode string String is
1245 [spaces][zeros][x][hexadecimal digits].
1247 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1248 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1249 If "x" appears in the input string, it must be prefixed with at least one 0.
1250 The function will ignore the pad space, which includes spaces or tab characters,
1251 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1252 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1253 first valid hexadecimal digit. Then, the function stops at the first character that is
1254 a not a valid hexadecimal character or NULL, whichever one comes first.
1256 If String is NULL, then ASSERT().
1257 If String is not aligned in a 16-bit boundary, then ASSERT().
1258 If String has only pad spaces, then zero is returned.
1259 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1260 then zero is returned.
1261 If the number represented by String overflows according to the range defined by
1262 UINT64, then MAX_UINT64 is returned.
1264 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1265 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1268 @param String The pointer to a Null-terminated Unicode string.
1270 @retval Value translated from String.
1276 IN CONST CHAR16
*String
1280 Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1282 This function outputs a value of type IPv6_ADDRESS and may output a value
1283 of type UINT8 by interpreting the contents of the Unicode string specified
1284 by String. The format of the input Unicode string String is as follows:
1288 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1289 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1290 memory address and high byte is stored in high memory address. P contains decimal
1291 digit characters in the range [0-9]. The running zero in the beginning of P will
1292 be ignored. /P is optional.
1294 When /P is not in the String, the function stops at the first character that is
1295 not a valid hexadecimal digit character after eight X's are converted.
1297 When /P is in the String, the function stops at the first character that is not
1298 a valid decimal digit character after P is converted.
1300 "::" can be used to compress one or more groups of X when X contains only 0.
1301 The "::" can only appear once in the String.
1303 If String is not aligned in a 16-bit boundary, then ASSERT().
1305 If EndPointer is not NULL and Address is translated from String, a pointer
1306 to the character that stopped the scan is stored at the location pointed to
1309 @param String Pointer to a Null-terminated Unicode string.
1310 @param EndPointer Pointer to character that stops scan.
1311 @param Address Pointer to the converted IPv6 address.
1312 @param PrefixLength Pointer to the converted IPv6 address prefix
1313 length. MAX_UINT8 is returned when /P is
1316 @retval RETURN_SUCCESS Address is translated from String.
1317 @retval RETURN_INVALID_PARAMETER If String is NULL.
1319 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1321 If String contains "::" and number of X
1323 If P starts with character that is not a
1324 valid decimal digit character.
1325 If the decimal number converted from P
1332 IN CONST CHAR16
*String
,
1333 OUT CHAR16
**EndPointer OPTIONAL
,
1334 OUT IPv6_ADDRESS
*Address
,
1335 OUT UINT8
*PrefixLength OPTIONAL
1339 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1341 This function outputs a value of type IPv4_ADDRESS and may output a value
1342 of type UINT8 by interpreting the contents of the Unicode string specified
1343 by String. The format of the input Unicode string String is as follows:
1347 D and P are decimal digit characters in the range [0-9]. The running zero in
1348 the beginning of D and P will be ignored. /P is optional.
1350 When /P is not in the String, the function stops at the first character that is
1351 not a valid decimal digit character after four D's are converted.
1353 When /P is in the String, the function stops at the first character that is not
1354 a valid decimal digit character after P is converted.
1356 If String is not aligned in a 16-bit boundary, then ASSERT().
1358 If EndPointer is not NULL and Address is translated from String, a pointer
1359 to the character that stopped the scan is stored at the location pointed to
1362 @param String Pointer to a Null-terminated Unicode string.
1363 @param EndPointer Pointer to character that stops scan.
1364 @param Address Pointer to the converted IPv4 address.
1365 @param PrefixLength Pointer to the converted IPv4 address prefix
1366 length. MAX_UINT8 is returned when /P is
1369 @retval RETURN_SUCCESS Address is translated from String.
1370 @retval RETURN_INVALID_PARAMETER If String is NULL.
1372 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1373 If any decimal number converted from D
1375 If the decimal number converted from P
1382 IN CONST CHAR16
*String
,
1383 OUT CHAR16
**EndPointer OPTIONAL
,
1384 OUT IPv4_ADDRESS
*Address
,
1385 OUT UINT8
*PrefixLength OPTIONAL
1388 #define GUID_STRING_LENGTH 36
1391 Convert a Null-terminated Unicode GUID string to a value of type
1394 This function outputs a GUID value by interpreting the contents of
1395 the Unicode string specified by String. The format of the input
1396 Unicode string String consists of 36 characters, as follows:
1398 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1400 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1401 [A-F], with each pair representing a single byte hexadecimal value.
1403 The mapping between String and the EFI_GUID structure is as follows:
1421 If String is not aligned in a 16-bit boundary, then ASSERT().
1423 @param String Pointer to a Null-terminated Unicode string.
1424 @param Guid Pointer to the converted GUID.
1426 @retval RETURN_SUCCESS Guid is translated from String.
1427 @retval RETURN_INVALID_PARAMETER If String is NULL.
1429 @retval RETURN_UNSUPPORTED If String is not as the above format.
1435 IN CONST CHAR16
*String
,
1440 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1442 This function outputs a byte array by interpreting the contents of
1443 the Unicode string specified by String in hexadecimal format. The format of
1444 the input Unicode string String is:
1448 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1449 The function decodes every two hexadecimal digit characters as one byte. The
1450 decoding stops after Length of characters and outputs Buffer containing
1453 If String is not aligned in a 16-bit boundary, then ASSERT().
1455 @param String Pointer to a Null-terminated Unicode string.
1456 @param Length The number of Unicode characters to decode.
1457 @param Buffer Pointer to the converted bytes array.
1458 @param MaxBufferSize The maximum size of Buffer.
1460 @retval RETURN_SUCCESS Buffer is translated from String.
1461 @retval RETURN_INVALID_PARAMETER If String is NULL.
1463 If Length is not multiple of 2.
1464 If PcdMaximumUnicodeStringLength is not zero,
1465 and Length is greater than
1466 PcdMaximumUnicodeStringLength.
1467 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1468 a character that is not valid hexadecimal
1469 digit characters, or a Null-terminator.
1470 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1475 IN CONST CHAR16
*String
,
1478 IN UINTN MaxBufferSize
1482 Convert a Null-terminated Unicode string to a Null-terminated
1485 This function is similar to AsciiStrCpyS.
1487 This function converts the content of the Unicode string Source
1488 to the ASCII string Destination by copying the lower 8 bits of
1489 each Unicode character. The function terminates the ASCII string
1490 Destination by appending a Null-terminator character at the end.
1492 The caller is responsible to make sure Destination points to a buffer with size
1493 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1495 If any Unicode characters in Source contain non-zero value in
1496 the upper 8 bits, then ASSERT().
1498 If Source is not aligned on a 16-bit boundary, then ASSERT().
1500 If an error is returned, then the Destination is unmodified.
1502 @param Source The pointer to a Null-terminated Unicode string.
1503 @param Destination The pointer to a Null-terminated ASCII string.
1504 @param DestMax The maximum number of Destination Ascii
1505 char, including terminating null char.
1507 @retval RETURN_SUCCESS String is converted.
1508 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1509 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1511 If PcdMaximumAsciiStringLength is not zero,
1512 and DestMax is greater than
1513 PcdMaximumAsciiStringLength.
1514 If PcdMaximumUnicodeStringLength is not zero,
1515 and DestMax is greater than
1516 PcdMaximumUnicodeStringLength.
1518 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1523 UnicodeStrToAsciiStrS (
1524 IN CONST CHAR16
*Source
,
1525 OUT CHAR8
*Destination
,
1530 Convert not more than Length successive characters from a Null-terminated
1531 Unicode string to a Null-terminated Ascii string. If no null char is copied
1532 from Source, then Destination[Length] is always set to null.
1534 This function converts not more than Length successive characters from the
1535 Unicode string Source to the Ascii string Destination by copying the lower 8
1536 bits of each Unicode character. The function terminates the Ascii string
1537 Destination by appending a Null-terminator character at the end.
1539 The caller is responsible to make sure Destination points to a buffer with size
1540 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1542 If any Unicode characters in Source contain non-zero value in the upper 8
1543 bits, then ASSERT().
1544 If Source is not aligned on a 16-bit boundary, then ASSERT().
1546 If an error is returned, then the Destination is unmodified.
1548 @param Source The pointer to a Null-terminated Unicode string.
1549 @param Length The maximum number of Unicode characters to
1551 @param Destination The pointer to a Null-terminated Ascii string.
1552 @param DestMax The maximum number of Destination Ascii
1553 char, including terminating null char.
1554 @param DestinationLength The number of Unicode characters converted.
1556 @retval RETURN_SUCCESS String is converted.
1557 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1559 If DestinationLength is NULL.
1560 If PcdMaximumAsciiStringLength is not zero,
1561 and Length or DestMax is greater than
1562 PcdMaximumAsciiStringLength.
1563 If PcdMaximumUnicodeStringLength is not
1564 zero, and Length or DestMax is greater than
1565 PcdMaximumUnicodeStringLength.
1567 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1568 MIN(StrLen(Source), Length).
1569 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1574 UnicodeStrnToAsciiStrS (
1575 IN CONST CHAR16
*Source
,
1577 OUT CHAR8
*Destination
,
1579 OUT UINTN
*DestinationLength
1583 Returns the length of a Null-terminated ASCII string.
1585 This function returns the number of ASCII characters in the Null-terminated
1586 ASCII string specified by String.
1588 If Length > 0 and Destination is NULL, then ASSERT().
1589 If Length > 0 and Source is NULL, then ASSERT().
1590 If PcdMaximumAsciiStringLength is not zero and String contains more than
1591 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1594 @param String The pointer to a Null-terminated ASCII string.
1596 @return The length of String.
1602 IN CONST CHAR8
*String
1606 Returns the size of a Null-terminated ASCII string in bytes, including the
1609 This function returns the size, in bytes, of the Null-terminated ASCII string
1610 specified by String.
1612 If String is NULL, then ASSERT().
1613 If PcdMaximumAsciiStringLength is not zero and String contains more than
1614 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1617 @param String The pointer to a Null-terminated ASCII string.
1619 @return The size of String.
1625 IN CONST CHAR8
*String
1629 Compares two Null-terminated ASCII strings, and returns the difference
1630 between the first mismatched ASCII characters.
1632 This function compares the Null-terminated ASCII string FirstString to the
1633 Null-terminated ASCII string SecondString. If FirstString is identical to
1634 SecondString, then 0 is returned. Otherwise, the value returned is the first
1635 mismatched ASCII character in SecondString subtracted from the first
1636 mismatched ASCII character in FirstString.
1638 If FirstString is NULL, then ASSERT().
1639 If SecondString is NULL, then ASSERT().
1640 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1641 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1643 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1644 than PcdMaximumAsciiStringLength ASCII characters not including the
1645 Null-terminator, then ASSERT().
1647 @param FirstString The pointer to a Null-terminated ASCII string.
1648 @param SecondString The pointer to a Null-terminated ASCII string.
1650 @retval ==0 FirstString is identical to SecondString.
1651 @retval !=0 FirstString is not identical to SecondString.
1657 IN CONST CHAR8
*FirstString
,
1658 IN CONST CHAR8
*SecondString
1662 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1663 and returns the difference between the first mismatched ASCII characters.
1665 This function performs a case insensitive comparison of the Null-terminated
1666 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1667 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1668 value returned is the first mismatched lower case ASCII character in
1669 SecondString subtracted from the first mismatched lower case ASCII character
1672 If FirstString is NULL, then ASSERT().
1673 If SecondString is NULL, then ASSERT().
1674 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1675 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1677 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1678 than PcdMaximumAsciiStringLength ASCII characters not including the
1679 Null-terminator, then ASSERT().
1681 @param FirstString The pointer to a Null-terminated ASCII string.
1682 @param SecondString The pointer to a Null-terminated ASCII string.
1684 @retval ==0 FirstString is identical to SecondString using case insensitive
1686 @retval !=0 FirstString is not identical to SecondString using case
1687 insensitive comparisons.
1693 IN CONST CHAR8
*FirstString
,
1694 IN CONST CHAR8
*SecondString
1698 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1699 the difference between the first mismatched ASCII characters.
1701 This function compares the Null-terminated ASCII string FirstString to the
1702 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1703 will be compared. If Length is 0, then 0 is returned. If FirstString is
1704 identical to SecondString, then 0 is returned. Otherwise, the value returned
1705 is the first mismatched ASCII character in SecondString subtracted from the
1706 first mismatched ASCII character in FirstString.
1708 If Length > 0 and FirstString is NULL, then ASSERT().
1709 If Length > 0 and SecondString is NULL, then ASSERT().
1710 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1711 PcdMaximumAsciiStringLength, then ASSERT().
1712 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
1713 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1715 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
1716 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1719 @param FirstString The pointer to a Null-terminated ASCII string.
1720 @param SecondString The pointer to a Null-terminated ASCII string.
1721 @param Length The maximum number of ASCII characters for compare.
1723 @retval ==0 FirstString is identical to SecondString.
1724 @retval !=0 FirstString is not identical to SecondString.
1730 IN CONST CHAR8
*FirstString
,
1731 IN CONST CHAR8
*SecondString
,
1736 Returns the first occurrence of a Null-terminated ASCII sub-string
1737 in a Null-terminated ASCII string.
1739 This function scans the contents of the ASCII string specified by String
1740 and returns the first occurrence of SearchString. If SearchString is not
1741 found in String, then NULL is returned. If the length of SearchString is zero,
1742 then String is returned.
1744 If String is NULL, then ASSERT().
1745 If SearchString is NULL, then ASSERT().
1747 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1748 String contains more than PcdMaximumAsciiStringLength Unicode characters
1749 not including the Null-terminator, then ASSERT().
1751 @param String The pointer to a Null-terminated ASCII string.
1752 @param SearchString The pointer to a Null-terminated ASCII string to search for.
1754 @retval NULL If the SearchString does not appear in String.
1755 @retval others If there is a match return the first occurrence of SearchingString.
1756 If the length of SearchString is zero,return String.
1762 IN CONST CHAR8
*String
,
1763 IN CONST CHAR8
*SearchString
1767 Convert a Null-terminated ASCII decimal string to a value of type
1770 This function returns a value of type UINTN by interpreting the contents
1771 of the ASCII string String as a decimal number. The format of the input
1772 ASCII string String is:
1774 [spaces] [decimal digits].
1776 The valid decimal digit character is in the range [0-9]. The function will
1777 ignore the pad space, which includes spaces or tab characters, before the digits.
1778 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1779 function stops at the first character that is a not a valid decimal character or
1780 Null-terminator, whichever on comes first.
1782 If String has only pad spaces, then 0 is returned.
1783 If String has no pad spaces or valid decimal digits, then 0 is returned.
1784 If the number represented by String overflows according to the range defined by
1785 UINTN, then MAX_UINTN is returned.
1786 If String is NULL, then ASSERT().
1787 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1788 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1791 @param String The pointer to a Null-terminated ASCII string.
1793 @retval The value translated from String.
1798 AsciiStrDecimalToUintn (
1799 IN CONST CHAR8
*String
1803 Convert a Null-terminated ASCII decimal string to a value of type
1806 This function returns a value of type UINT64 by interpreting the contents
1807 of the ASCII string String as a decimal number. The format of the input
1808 ASCII string String is:
1810 [spaces] [decimal digits].
1812 The valid decimal digit character is in the range [0-9]. The function will
1813 ignore the pad space, which includes spaces or tab characters, before the digits.
1814 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1815 function stops at the first character that is a not a valid decimal character or
1816 Null-terminator, whichever on comes first.
1818 If String has only pad spaces, then 0 is returned.
1819 If String has no pad spaces or valid decimal digits, then 0 is returned.
1820 If the number represented by String overflows according to the range defined by
1821 UINT64, then MAX_UINT64 is returned.
1822 If String is NULL, then ASSERT().
1823 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1824 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1827 @param String The pointer to a Null-terminated ASCII string.
1829 @retval Value translated from String.
1834 AsciiStrDecimalToUint64 (
1835 IN CONST CHAR8
*String
1839 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1841 This function returns a value of type UINTN by interpreting the contents of
1842 the ASCII string String as a hexadecimal number. The format of the input ASCII
1845 [spaces][zeros][x][hexadecimal digits].
1847 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1848 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1849 appears in the input string, it must be prefixed with at least one 0. The function
1850 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1851 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1852 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1853 digit. Then, the function stops at the first character that is a not a valid
1854 hexadecimal character or Null-terminator, whichever on comes first.
1856 If String has only pad spaces, then 0 is returned.
1857 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1860 If the number represented by String overflows according to the range defined by UINTN,
1861 then MAX_UINTN is returned.
1862 If String is NULL, then ASSERT().
1863 If PcdMaximumAsciiStringLength is not zero,
1864 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1865 the Null-terminator, then ASSERT().
1867 @param String The pointer to a Null-terminated ASCII string.
1869 @retval Value translated from String.
1874 AsciiStrHexToUintn (
1875 IN CONST CHAR8
*String
1879 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1881 This function returns a value of type UINT64 by interpreting the contents of
1882 the ASCII string String as a hexadecimal number. The format of the input ASCII
1885 [spaces][zeros][x][hexadecimal digits].
1887 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1888 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1889 appears in the input string, it must be prefixed with at least one 0. The function
1890 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1891 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1892 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1893 digit. Then, the function stops at the first character that is a not a valid
1894 hexadecimal character or Null-terminator, whichever on comes first.
1896 If String has only pad spaces, then 0 is returned.
1897 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1900 If the number represented by String overflows according to the range defined by UINT64,
1901 then MAX_UINT64 is returned.
1902 If String is NULL, then ASSERT().
1903 If PcdMaximumAsciiStringLength is not zero,
1904 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1905 the Null-terminator, then ASSERT().
1907 @param String The pointer to a Null-terminated ASCII string.
1909 @retval Value translated from String.
1914 AsciiStrHexToUint64 (
1915 IN CONST CHAR8
*String
1919 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
1921 This function outputs a value of type IPv6_ADDRESS and may output a value
1922 of type UINT8 by interpreting the contents of the ASCII string specified
1923 by String. The format of the input ASCII string String is as follows:
1927 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1928 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1929 memory address and high byte is stored in high memory address. P contains decimal
1930 digit characters in the range [0-9]. The running zero in the beginning of P will
1931 be ignored. /P is optional.
1933 When /P is not in the String, the function stops at the first character that is
1934 not a valid hexadecimal digit character after eight X's are converted.
1936 When /P is in the String, the function stops at the first character that is not
1937 a valid decimal digit character after P is converted.
1939 "::" can be used to compress one or more groups of X when X contains only 0.
1940 The "::" can only appear once in the String.
1942 If EndPointer is not NULL and Address is translated from String, a pointer
1943 to the character that stopped the scan is stored at the location pointed to
1946 @param String Pointer to a Null-terminated ASCII string.
1947 @param EndPointer Pointer to character that stops scan.
1948 @param Address Pointer to the converted IPv6 address.
1949 @param PrefixLength Pointer to the converted IPv6 address prefix
1950 length. MAX_UINT8 is returned when /P is
1953 @retval RETURN_SUCCESS Address is translated from String.
1954 @retval RETURN_INVALID_PARAMETER If String is NULL.
1956 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1958 If String contains "::" and number of X
1960 If P starts with character that is not a
1961 valid decimal digit character.
1962 If the decimal number converted from P
1968 AsciiStrToIpv6Address (
1969 IN CONST CHAR8
*String
,
1970 OUT CHAR8
**EndPointer OPTIONAL
,
1971 OUT IPv6_ADDRESS
*Address
,
1972 OUT UINT8
*PrefixLength OPTIONAL
1976 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
1978 This function outputs a value of type IPv4_ADDRESS and may output a value
1979 of type UINT8 by interpreting the contents of the ASCII string specified
1980 by String. The format of the input ASCII string String is as follows:
1984 D and P are decimal digit characters in the range [0-9]. The running zero in
1985 the beginning of D and P will be ignored. /P is optional.
1987 When /P is not in the String, the function stops at the first character that is
1988 not a valid decimal digit character after four D's are converted.
1990 When /P is in the String, the function stops at the first character that is not
1991 a valid decimal digit character after P is converted.
1993 If EndPointer is not NULL and Address is translated from String, a pointer
1994 to the character that stopped the scan is stored at the location pointed to
1997 @param String Pointer to a Null-terminated ASCII string.
1998 @param EndPointer Pointer to character that stops scan.
1999 @param Address Pointer to the converted IPv4 address.
2000 @param PrefixLength Pointer to the converted IPv4 address prefix
2001 length. MAX_UINT8 is returned when /P is
2004 @retval RETURN_SUCCESS Address is translated from String.
2005 @retval RETURN_INVALID_PARAMETER If String is NULL.
2007 @retval RETURN_UNSUPPORTED If String is not in the correct format.
2008 If any decimal number converted from D
2010 If the decimal number converted from P
2016 AsciiStrToIpv4Address (
2017 IN CONST CHAR8
*String
,
2018 OUT CHAR8
**EndPointer OPTIONAL
,
2019 OUT IPv4_ADDRESS
*Address
,
2020 OUT UINT8
*PrefixLength OPTIONAL
2024 Convert a Null-terminated ASCII GUID string to a value of type
2027 This function outputs a GUID value by interpreting the contents of
2028 the ASCII string specified by String. The format of the input
2029 ASCII string String consists of 36 characters, as follows:
2031 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
2033 The pairs aa - pp are two characters in the range [0-9], [a-f] and
2034 [A-F], with each pair representing a single byte hexadecimal value.
2036 The mapping between String and the EFI_GUID structure is as follows:
2054 @param String Pointer to a Null-terminated ASCII string.
2055 @param Guid Pointer to the converted GUID.
2057 @retval RETURN_SUCCESS Guid is translated from String.
2058 @retval RETURN_INVALID_PARAMETER If String is NULL.
2060 @retval RETURN_UNSUPPORTED If String is not as the above format.
2066 IN CONST CHAR8
*String
,
2071 Convert a Null-terminated ASCII hexadecimal string to a byte array.
2073 This function outputs a byte array by interpreting the contents of
2074 the ASCII string specified by String in hexadecimal format. The format of
2075 the input ASCII string String is:
2079 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
2080 The function decodes every two hexadecimal digit characters as one byte. The
2081 decoding stops after Length of characters and outputs Buffer containing
2084 @param String Pointer to a Null-terminated ASCII string.
2085 @param Length The number of ASCII characters to decode.
2086 @param Buffer Pointer to the converted bytes array.
2087 @param MaxBufferSize The maximum size of Buffer.
2089 @retval RETURN_SUCCESS Buffer is translated from String.
2090 @retval RETURN_INVALID_PARAMETER If String is NULL.
2092 If Length is not multiple of 2.
2093 If PcdMaximumAsciiStringLength is not zero,
2094 and Length is greater than
2095 PcdMaximumAsciiStringLength.
2096 @retval RETURN_UNSUPPORTED If Length of characters from String contain
2097 a character that is not valid hexadecimal
2098 digit characters, or a Null-terminator.
2099 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
2103 AsciiStrHexToBytes (
2104 IN CONST CHAR8
*String
,
2107 IN UINTN MaxBufferSize
2111 Convert one Null-terminated ASCII string to a Null-terminated
2114 This function is similar to StrCpyS.
2116 This function converts the contents of the ASCII string Source to the Unicode
2117 string Destination. The function terminates the Unicode string Destination by
2118 appending a Null-terminator character at the end.
2120 The caller is responsible to make sure Destination points to a buffer with size
2121 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2123 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2125 If an error is returned, then the Destination is unmodified.
2127 @param Source The pointer to a Null-terminated ASCII string.
2128 @param Destination The pointer to a Null-terminated Unicode string.
2129 @param DestMax The maximum number of Destination Unicode
2130 char, including terminating null char.
2132 @retval RETURN_SUCCESS String is converted.
2133 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2134 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2136 If PcdMaximumUnicodeStringLength is not zero,
2137 and DestMax is greater than
2138 PcdMaximumUnicodeStringLength.
2139 If PcdMaximumAsciiStringLength is not zero,
2140 and DestMax is greater than
2141 PcdMaximumAsciiStringLength.
2143 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2148 AsciiStrToUnicodeStrS (
2149 IN CONST CHAR8
*Source
,
2150 OUT CHAR16
*Destination
,
2155 Convert not more than Length successive characters from a Null-terminated
2156 Ascii string to a Null-terminated Unicode string. If no null char is copied
2157 from Source, then Destination[Length] is always set to null.
2159 This function converts not more than Length successive characters from the
2160 Ascii string Source to the Unicode string Destination. The function
2161 terminates the Unicode string Destination by appending a Null-terminator
2162 character at the end.
2164 The caller is responsible to make sure Destination points to a buffer with
2165 size not smaller than
2166 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2168 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2170 If an error is returned, then Destination and DestinationLength are
2173 @param Source The pointer to a Null-terminated Ascii string.
2174 @param Length The maximum number of Ascii characters to convert.
2175 @param Destination The pointer to a Null-terminated Unicode string.
2176 @param DestMax The maximum number of Destination Unicode char,
2177 including terminating null char.
2178 @param DestinationLength The number of Ascii characters converted.
2180 @retval RETURN_SUCCESS String is converted.
2181 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2183 If DestinationLength is NULL.
2184 If PcdMaximumUnicodeStringLength is not
2185 zero, and Length or DestMax is greater than
2186 PcdMaximumUnicodeStringLength.
2187 If PcdMaximumAsciiStringLength is not zero,
2188 and Length or DestMax is greater than
2189 PcdMaximumAsciiStringLength.
2191 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2192 MIN(AsciiStrLen(Source), Length).
2193 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2198 AsciiStrnToUnicodeStrS (
2199 IN CONST CHAR8
*Source
,
2201 OUT CHAR16
*Destination
,
2203 OUT UINTN
*DestinationLength
2207 Convert a Unicode character to upper case only if
2208 it maps to a valid small-case ASCII character.
2210 This internal function only deal with Unicode character
2211 which maps to a valid small-case ASCII character, i.e.
2212 L'a' to L'z'. For other Unicode character, the input character
2213 is returned directly.
2215 @param Char The character to convert.
2217 @retval LowerCharacter If the Char is with range L'a' to L'z'.
2218 @retval Unchanged Otherwise.
2228 Converts a lowercase Ascii character to upper one.
2230 If Chr is lowercase Ascii character, then converts it to upper one.
2232 If Value >= 0xA0, then ASSERT().
2233 If (Value & 0x0F) >= 0x0A, then ASSERT().
2235 @param Chr one Ascii character
2237 @return The uppercase value of Ascii character
2247 Convert binary data to a Base64 encoded ascii string based on RFC4648.
2249 Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
2250 The Ascii string is produced by converting the data string specified by Source and SourceLength.
2252 @param Source Input UINT8 data
2253 @param SourceLength Number of UINT8 bytes of data
2254 @param Destination Pointer to output string buffer
2255 @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed.
2256 Caller is responsible for passing in buffer of DestinationSize
2258 @retval RETURN_SUCCESS When ascii buffer is filled in.
2259 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
2260 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
2261 @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1.
2262 @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize.
2268 IN CONST UINT8
*Source
,
2269 IN UINTN SourceLength
,
2270 OUT CHAR8
*Destination OPTIONAL
,
2271 IN OUT UINTN
*DestinationSize
2275 Decode Base64 ASCII encoded data to 8-bit binary representation, based on
2278 Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648.
2280 Whitespace is ignored at all positions:
2281 - 0x09 ('\t') horizontal tab
2282 - 0x0A ('\n') new line
2283 - 0x0B ('\v') vertical tab
2284 - 0x0C ('\f') form feed
2285 - 0x0D ('\r') carriage return
2288 The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated
2289 and enforced at the end of the Base64 ASCII encoded data, and only there.
2291 Other characters outside of the encoding alphabet cause the function to
2292 reject the Base64 ASCII encoded data.
2294 @param[in] Source Array of CHAR8 elements containing the Base64
2295 ASCII encoding. May be NULL if SourceSize is
2298 @param[in] SourceSize Number of CHAR8 elements in Source.
2300 @param[out] Destination Array of UINT8 elements receiving the decoded
2301 8-bit binary representation. Allocated by the
2302 caller. May be NULL if DestinationSize is
2303 zero on input. If NULL, decoding is
2304 performed, but the 8-bit binary
2305 representation is not stored. If non-NULL and
2306 the function returns an error, the contents
2307 of Destination are indeterminate.
2309 @param[in,out] DestinationSize On input, the number of UINT8 elements that
2310 the caller allocated for Destination. On
2311 output, if the function returns
2312 RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL,
2313 the number of UINT8 elements that are
2314 required for decoding the Base64 ASCII
2315 representation. If the function returns a
2316 value different from both RETURN_SUCCESS and
2317 RETURN_BUFFER_TOO_SMALL, then DestinationSize
2318 is indeterminate on output.
2320 @retval RETURN_SUCCESS SourceSize CHAR8 elements at Source have
2321 been decoded to on-output DestinationSize
2322 UINT8 elements at Destination. Note that
2323 RETURN_SUCCESS covers the case when
2324 DestinationSize is zero on input, and
2325 Source decodes to zero bytes (due to
2326 containing at most ignored whitespace).
2328 @retval RETURN_BUFFER_TOO_SMALL The input value of DestinationSize is not
2329 large enough for decoding SourceSize CHAR8
2330 elements at Source. The required number of
2331 UINT8 elements has been stored to
2334 @retval RETURN_INVALID_PARAMETER DestinationSize is NULL.
2336 @retval RETURN_INVALID_PARAMETER Source is NULL, but SourceSize is not zero.
2338 @retval RETURN_INVALID_PARAMETER Destination is NULL, but DestinationSize is
2341 @retval RETURN_INVALID_PARAMETER Source is non-NULL, and (Source +
2342 SourceSize) would wrap around MAX_ADDRESS.
2344 @retval RETURN_INVALID_PARAMETER Destination is non-NULL, and (Destination +
2345 DestinationSize) would wrap around
2346 MAX_ADDRESS, as specified on input.
2348 @retval RETURN_INVALID_PARAMETER None of Source and Destination are NULL,
2349 and CHAR8[SourceSize] at Source overlaps
2350 UINT8[DestinationSize] at Destination, as
2353 @retval RETURN_INVALID_PARAMETER Invalid CHAR8 element encountered in
2359 IN CONST CHAR8
*Source OPTIONAL
,
2360 IN UINTN SourceSize
,
2361 OUT UINT8
*Destination OPTIONAL
,
2362 IN OUT UINTN
*DestinationSize
2366 Converts an 8-bit value to an 8-bit BCD value.
2368 Converts the 8-bit value specified by Value to BCD. The BCD value is
2371 If Value >= 100, then ASSERT().
2373 @param Value The 8-bit value to convert to BCD. Range 0..99.
2375 @return The BCD value.
2385 Converts an 8-bit BCD value to an 8-bit value.
2387 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2390 If Value >= 0xA0, then ASSERT().
2391 If (Value & 0x0F) >= 0x0A, then ASSERT().
2393 @param Value The 8-bit BCD value to convert to an 8-bit value.
2395 @return The 8-bit value is returned.
2405 // File Path Manipulation Functions
2409 Removes the last directory or file entry in a path.
2411 @param[in, out] Path The pointer to the path to modify.
2413 @retval FALSE Nothing was found to remove.
2414 @retval TRUE A directory or file was removed.
2418 PathRemoveLastItem (
2423 Function to clean up paths.
2424 - Single periods in the path are removed.
2425 - Double periods in the path are removed along with a single parent directory.
2426 - Forward slashes L'/' are converted to backward slashes L'\'.
2428 This will be done inline and the existing buffer may be larger than required
2431 @param[in] Path The pointer to the string containing the path.
2433 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2437 PathCleanUpDirectories (
2442 // Linked List Functions and Macros
2446 Initializes the head node of a doubly linked list that is declared as a
2447 global variable in a module.
2449 Initializes the forward and backward links of a new linked list. After
2450 initializing a linked list with this macro, the other linked list functions
2451 may be used to add and remove nodes from the linked list. This macro results
2452 in smaller executables by initializing the linked list in the data section,
2453 instead if calling the InitializeListHead() function to perform the
2454 equivalent operation.
2456 @param ListHead The head note of a list to initialize.
2459 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2462 Iterates over each node in a doubly linked list using each node's forward link.
2464 @param Entry A pointer to a list node used as a loop cursor during iteration
2465 @param ListHead The head node of the doubly linked list
2468 #define BASE_LIST_FOR_EACH(Entry, ListHead) \
2469 for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)
2472 Iterates over each node in a doubly linked list using each node's forward link
2473 with safety against node removal.
2475 This macro uses NextEntry to temporarily store the next list node so the node
2476 pointed to by Entry may be deleted in the current loop iteration step and
2477 iteration can continue from the node pointed to by NextEntry.
2479 @param Entry A pointer to a list node used as a loop cursor during iteration
2480 @param NextEntry A pointer to a list node used to temporarily store the next node
2481 @param ListHead The head node of the doubly linked list
2484 #define BASE_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \
2485 for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
2486 Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
2489 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2492 If FirstEntry is NULL, then ASSERT().
2493 If FirstEntry->ForwardLink is NULL, then ASSERT().
2494 If FirstEntry->BackLink is NULL, then ASSERT().
2495 If SecondEntry is NULL, then ASSERT();
2496 If PcdMaximumLinkedListLength is not zero, and List contains more than
2497 PcdMaximumLinkedListLength nodes, then ASSERT().
2499 @param FirstEntry A pointer to a node in a linked list.
2500 @param SecondEntry A pointer to the node to locate.
2502 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.
2503 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,
2504 or FirstEntry is invalid.
2510 IN CONST LIST_ENTRY
*FirstEntry
,
2511 IN CONST LIST_ENTRY
*SecondEntry
2515 Initializes the head node of a doubly linked list, and returns the pointer to
2516 the head node of the doubly linked list.
2518 Initializes the forward and backward links of a new linked list. After
2519 initializing a linked list with this function, the other linked list
2520 functions may be used to add and remove nodes from the linked list. It is up
2521 to the caller of this function to allocate the memory for ListHead.
2523 If ListHead is NULL, then ASSERT().
2525 @param ListHead A pointer to the head node of a new doubly linked list.
2532 InitializeListHead (
2533 IN OUT LIST_ENTRY
*ListHead
2537 Adds a node to the beginning of a doubly linked list, and returns the pointer
2538 to the head node of the doubly linked list.
2540 Adds the node Entry at the beginning of the doubly linked list denoted by
2541 ListHead, and returns ListHead.
2543 If ListHead is NULL, then ASSERT().
2544 If Entry is NULL, then ASSERT().
2545 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2546 InitializeListHead(), then ASSERT().
2547 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2548 of nodes in ListHead, including the ListHead node, is greater than or
2549 equal to PcdMaximumLinkedListLength, then ASSERT().
2551 @param ListHead A pointer to the head node of a doubly linked list.
2552 @param Entry A pointer to a node that is to be inserted at the beginning
2553 of a doubly linked list.
2561 IN OUT LIST_ENTRY
*ListHead
,
2562 IN OUT LIST_ENTRY
*Entry
2566 Adds a node to the end of a doubly linked list, and returns the pointer to
2567 the head node of the doubly linked list.
2569 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2570 and returns ListHead.
2572 If ListHead is NULL, then ASSERT().
2573 If Entry is NULL, then ASSERT().
2574 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2575 InitializeListHead(), then ASSERT().
2576 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2577 of nodes in ListHead, including the ListHead node, is greater than or
2578 equal to PcdMaximumLinkedListLength, then ASSERT().
2580 @param ListHead A pointer to the head node of a doubly linked list.
2581 @param Entry A pointer to a node that is to be added at the end of the
2590 IN OUT LIST_ENTRY
*ListHead
,
2591 IN OUT LIST_ENTRY
*Entry
2595 Retrieves the first node of a doubly linked list.
2597 Returns the first node of a doubly linked list. List must have been
2598 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2599 If List is empty, then List is returned.
2601 If List is NULL, then ASSERT().
2602 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2603 InitializeListHead(), then ASSERT().
2604 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2605 in List, including the List node, is greater than or equal to
2606 PcdMaximumLinkedListLength, then ASSERT().
2608 @param List A pointer to the head node of a doubly linked list.
2610 @return The first node of a doubly linked list.
2611 @retval List The list is empty.
2617 IN CONST LIST_ENTRY
*List
2621 Retrieves the next node of a doubly linked list.
2623 Returns the node of a doubly linked list that follows Node.
2624 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2625 or InitializeListHead(). If List is empty, then List is returned.
2627 If List is NULL, then ASSERT().
2628 If Node is NULL, then ASSERT().
2629 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2630 InitializeListHead(), then ASSERT().
2631 If PcdMaximumLinkedListLength is not zero, and List contains more than
2632 PcdMaximumLinkedListLength nodes, then ASSERT().
2633 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2635 @param List A pointer to the head node of a doubly linked list.
2636 @param Node A pointer to a node in the doubly linked list.
2638 @return The pointer to the next node if one exists. Otherwise List is returned.
2644 IN CONST LIST_ENTRY
*List
,
2645 IN CONST LIST_ENTRY
*Node
2649 Retrieves the previous node of a doubly linked list.
2651 Returns the node of a doubly linked list that precedes Node.
2652 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2653 or InitializeListHead(). If List is empty, then List is returned.
2655 If List is NULL, then ASSERT().
2656 If Node is NULL, then ASSERT().
2657 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2658 InitializeListHead(), then ASSERT().
2659 If PcdMaximumLinkedListLength is not zero, and List contains more than
2660 PcdMaximumLinkedListLength nodes, then ASSERT().
2661 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2663 @param List A pointer to the head node of a doubly linked list.
2664 @param Node A pointer to a node in the doubly linked list.
2666 @return The pointer to the previous node if one exists. Otherwise List is returned.
2672 IN CONST LIST_ENTRY
*List
,
2673 IN CONST LIST_ENTRY
*Node
2677 Checks to see if a doubly linked list is empty or not.
2679 Checks to see if the doubly linked list is empty. If the linked list contains
2680 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
2682 If ListHead is NULL, then ASSERT().
2683 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2684 InitializeListHead(), then ASSERT().
2685 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2686 in List, including the List node, is greater than or equal to
2687 PcdMaximumLinkedListLength, then ASSERT().
2689 @param ListHead A pointer to the head node of a doubly linked list.
2691 @retval TRUE The linked list is empty.
2692 @retval FALSE The linked list is not empty.
2698 IN CONST LIST_ENTRY
*ListHead
2702 Determines if a node in a doubly linked list is the head node of a the same
2703 doubly linked list. This function is typically used to terminate a loop that
2704 traverses all the nodes in a doubly linked list starting with the head node.
2706 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
2707 nodes in the doubly linked list specified by List. List must have been
2708 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2710 If List is NULL, then ASSERT().
2711 If Node is NULL, then ASSERT().
2712 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
2714 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2715 in List, including the List node, is greater than or equal to
2716 PcdMaximumLinkedListLength, then ASSERT().
2717 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
2718 to List, then ASSERT().
2720 @param List A pointer to the head node of a doubly linked list.
2721 @param Node A pointer to a node in the doubly linked list.
2723 @retval TRUE Node is the head of the doubly-linked list pointed by List.
2724 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
2730 IN CONST LIST_ENTRY
*List
,
2731 IN CONST LIST_ENTRY
*Node
2735 Determines if a node the last node in a doubly linked list.
2737 Returns TRUE if Node is the last node in the doubly linked list specified by
2738 List. Otherwise, FALSE is returned. List must have been initialized with
2739 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2741 If List is NULL, then ASSERT().
2742 If Node is NULL, then ASSERT().
2743 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2744 InitializeListHead(), then ASSERT().
2745 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2746 in List, including the List node, is greater than or equal to
2747 PcdMaximumLinkedListLength, then ASSERT().
2748 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2750 @param List A pointer to the head node of a doubly linked list.
2751 @param Node A pointer to a node in the doubly linked list.
2753 @retval TRUE Node is the last node in the linked list.
2754 @retval FALSE Node is not the last node in the linked list.
2760 IN CONST LIST_ENTRY
*List
,
2761 IN CONST LIST_ENTRY
*Node
2765 Swaps the location of two nodes in a doubly linked list, and returns the
2766 first node after the swap.
2768 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
2769 Otherwise, the location of the FirstEntry node is swapped with the location
2770 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
2771 same double linked list as FirstEntry and that double linked list must have
2772 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2773 SecondEntry is returned after the nodes are swapped.
2775 If FirstEntry is NULL, then ASSERT().
2776 If SecondEntry is NULL, then ASSERT().
2777 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
2778 same linked list, then ASSERT().
2779 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2780 linked list containing the FirstEntry and SecondEntry nodes, including
2781 the FirstEntry and SecondEntry nodes, is greater than or equal to
2782 PcdMaximumLinkedListLength, then ASSERT().
2784 @param FirstEntry A pointer to a node in a linked list.
2785 @param SecondEntry A pointer to another node in the same linked list.
2787 @return SecondEntry.
2793 IN OUT LIST_ENTRY
*FirstEntry
,
2794 IN OUT LIST_ENTRY
*SecondEntry
2798 Removes a node from a doubly linked list, and returns the node that follows
2801 Removes the node Entry from a doubly linked list. It is up to the caller of
2802 this function to release the memory used by this node if that is required. On
2803 exit, the node following Entry in the doubly linked list is returned. If
2804 Entry is the only node in the linked list, then the head node of the linked
2807 If Entry is NULL, then ASSERT().
2808 If Entry is the head node of an empty list, then ASSERT().
2809 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2810 linked list containing Entry, including the Entry node, is greater than
2811 or equal to PcdMaximumLinkedListLength, then ASSERT().
2813 @param Entry A pointer to a node in a linked list.
2821 IN CONST LIST_ENTRY
*Entry
2829 Prototype for comparison function for any two element types.
2831 @param[in] Buffer1 The pointer to first buffer.
2832 @param[in] Buffer2 The pointer to second buffer.
2834 @retval 0 Buffer1 equal to Buffer2.
2835 @return <0 Buffer1 is less than Buffer2.
2836 @return >0 Buffer1 is greater than Buffer2.
2840 (EFIAPI
*BASE_SORT_COMPARE
)(
2841 IN CONST VOID
*Buffer1
,
2842 IN CONST VOID
*Buffer2
2846 This function is identical to perform QuickSort,
2847 except that is uses the pre-allocated buffer so the in place sorting does not need to
2848 allocate and free buffers constantly.
2850 Each element must be equal sized.
2852 if BufferToSort is NULL, then ASSERT.
2853 if CompareFunction is NULL, then ASSERT.
2854 if BufferOneElement is NULL, then ASSERT.
2855 if ElementSize is < 1, then ASSERT.
2857 if Count is < 2 then perform no action.
2859 @param[in, out] BufferToSort on call a Buffer of (possibly sorted) elements
2860 on return a buffer of sorted elements
2861 @param[in] Count the number of elements in the buffer to sort
2862 @param[in] ElementSize Size of an element in bytes
2863 @param[in] CompareFunction The function to call to perform the comparison
2865 @param[out] BufferOneElement Caller provided buffer whose size equals to ElementSize.
2866 It's used by QuickSort() for swapping in sorting.
2871 IN OUT VOID
*BufferToSort
,
2872 IN CONST UINTN Count
,
2873 IN CONST UINTN ElementSize
,
2874 IN BASE_SORT_COMPARE CompareFunction
,
2875 OUT VOID
*BufferOneElement
2879 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
2880 with zeros. The shifted value is returned.
2882 This function shifts the 64-bit value Operand to the left by Count bits. The
2883 low Count bits are set to zero. The shifted value is returned.
2885 If Count is greater than 63, then ASSERT().
2887 @param Operand The 64-bit operand to shift left.
2888 @param Count The number of bits to shift left.
2890 @return Operand << Count.
2901 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
2902 filled with zeros. The shifted value is returned.
2904 This function shifts the 64-bit value Operand to the right by Count bits. The
2905 high Count bits are set to zero. The shifted value is returned.
2907 If Count is greater than 63, then ASSERT().
2909 @param Operand The 64-bit operand to shift right.
2910 @param Count The number of bits to shift right.
2912 @return Operand >> Count
2923 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
2924 with original integer's bit 63. The shifted value is returned.
2926 This function shifts the 64-bit value Operand to the right by Count bits. The
2927 high Count bits are set to bit 63 of Operand. The shifted value is returned.
2929 If Count is greater than 63, then ASSERT().
2931 @param Operand The 64-bit operand to shift right.
2932 @param Count The number of bits to shift right.
2934 @return Operand >> Count
2945 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
2946 with the high bits that were rotated.
2948 This function rotates the 32-bit value Operand to the left by Count bits. The
2949 low Count bits are fill with the high Count bits of Operand. The rotated
2952 If Count is greater than 31, then ASSERT().
2954 @param Operand The 32-bit operand to rotate left.
2955 @param Count The number of bits to rotate left.
2957 @return Operand << Count
2968 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
2969 with the low bits that were rotated.
2971 This function rotates the 32-bit value Operand to the right by Count bits.
2972 The high Count bits are fill with the low Count bits of Operand. The rotated
2975 If Count is greater than 31, then ASSERT().
2977 @param Operand The 32-bit operand to rotate right.
2978 @param Count The number of bits to rotate right.
2980 @return Operand >> Count
2991 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
2992 with the high bits that were rotated.
2994 This function rotates the 64-bit value Operand to the left by Count bits. The
2995 low Count bits are fill with the high Count bits of Operand. The rotated
2998 If Count is greater than 63, then ASSERT().
3000 @param Operand The 64-bit operand to rotate left.
3001 @param Count The number of bits to rotate left.
3003 @return Operand << Count
3014 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3015 with the high low bits that were rotated.
3017 This function rotates the 64-bit value Operand to the right by Count bits.
3018 The high Count bits are fill with the low Count bits of Operand. The rotated
3021 If Count is greater than 63, then ASSERT().
3023 @param Operand The 64-bit operand to rotate right.
3024 @param Count The number of bits to rotate right.
3026 @return Operand >> Count
3037 Returns the bit position of the lowest bit set in a 32-bit value.
3039 This function computes the bit position of the lowest bit set in the 32-bit
3040 value specified by Operand. If Operand is zero, then -1 is returned.
3041 Otherwise, a value between 0 and 31 is returned.
3043 @param Operand The 32-bit operand to evaluate.
3045 @retval 0..31 The lowest bit set in Operand was found.
3046 @retval -1 Operand is zero.
3056 Returns the bit position of the lowest bit set in a 64-bit value.
3058 This function computes the bit position of the lowest bit set in the 64-bit
3059 value specified by Operand. If Operand is zero, then -1 is returned.
3060 Otherwise, a value between 0 and 63 is returned.
3062 @param Operand The 64-bit operand to evaluate.
3064 @retval 0..63 The lowest bit set in Operand was found.
3065 @retval -1 Operand is zero.
3076 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3079 This function computes the bit position of the highest bit set in the 32-bit
3080 value specified by Operand. If Operand is zero, then -1 is returned.
3081 Otherwise, a value between 0 and 31 is returned.
3083 @param Operand The 32-bit operand to evaluate.
3085 @retval 0..31 Position of the highest bit set in Operand if found.
3086 @retval -1 Operand is zero.
3096 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3099 This function computes the bit position of the highest bit set in the 64-bit
3100 value specified by Operand. If Operand is zero, then -1 is returned.
3101 Otherwise, a value between 0 and 63 is returned.
3103 @param Operand The 64-bit operand to evaluate.
3105 @retval 0..63 Position of the highest bit set in Operand if found.
3106 @retval -1 Operand is zero.
3116 Returns the value of the highest bit set in a 32-bit value. Equivalent to
3119 This function computes the value of the highest bit set in the 32-bit value
3120 specified by Operand. If Operand is zero, then zero is returned.
3122 @param Operand The 32-bit operand to evaluate.
3124 @return 1 << HighBitSet32(Operand)
3125 @retval 0 Operand is zero.
3135 Returns the value of the highest bit set in a 64-bit value. Equivalent to
3138 This function computes the value of the highest bit set in the 64-bit value
3139 specified by Operand. If Operand is zero, then zero is returned.
3141 @param Operand The 64-bit operand to evaluate.
3143 @return 1 << HighBitSet64(Operand)
3144 @retval 0 Operand is zero.
3154 Switches the endianness of a 16-bit integer.
3156 This function swaps the bytes in a 16-bit unsigned value to switch the value
3157 from little endian to big endian or vice versa. The byte swapped value is
3160 @param Value A 16-bit unsigned value.
3162 @return The byte swapped Value.
3172 Switches the endianness of a 32-bit integer.
3174 This function swaps the bytes in a 32-bit unsigned value to switch the value
3175 from little endian to big endian or vice versa. The byte swapped value is
3178 @param Value A 32-bit unsigned value.
3180 @return The byte swapped Value.
3190 Switches the endianness of a 64-bit integer.
3192 This function swaps the bytes in a 64-bit unsigned value to switch the value
3193 from little endian to big endian or vice versa. The byte swapped value is
3196 @param Value A 64-bit unsigned value.
3198 @return The byte swapped Value.
3208 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3209 generates a 64-bit unsigned result.
3211 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3212 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3213 bit unsigned result is returned.
3215 @param Multiplicand A 64-bit unsigned value.
3216 @param Multiplier A 32-bit unsigned value.
3218 @return Multiplicand * Multiplier
3224 IN UINT64 Multiplicand
,
3225 IN UINT32 Multiplier
3229 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3230 generates a 64-bit unsigned result.
3232 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3233 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3234 bit unsigned result is returned.
3236 @param Multiplicand A 64-bit unsigned value.
3237 @param Multiplier A 64-bit unsigned value.
3239 @return Multiplicand * Multiplier.
3245 IN UINT64 Multiplicand
,
3246 IN UINT64 Multiplier
3250 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3251 64-bit signed result.
3253 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3254 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3255 signed result is returned.
3257 @param Multiplicand A 64-bit signed value.
3258 @param Multiplier A 64-bit signed value.
3260 @return Multiplicand * Multiplier
3266 IN INT64 Multiplicand
,
3271 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3272 a 64-bit unsigned result.
3274 This function divides the 64-bit unsigned value Dividend by the 32-bit
3275 unsigned value Divisor and generates a 64-bit unsigned quotient. This
3276 function returns the 64-bit unsigned quotient.
3278 If Divisor is 0, then ASSERT().
3280 @param Dividend A 64-bit unsigned value.
3281 @param Divisor A 32-bit unsigned value.
3283 @return Dividend / Divisor.
3294 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3295 a 32-bit unsigned remainder.
3297 This function divides the 64-bit unsigned value Dividend by the 32-bit
3298 unsigned value Divisor and generates a 32-bit remainder. This function
3299 returns the 32-bit unsigned remainder.
3301 If Divisor is 0, then ASSERT().
3303 @param Dividend A 64-bit unsigned value.
3304 @param Divisor A 32-bit unsigned value.
3306 @return Dividend % Divisor.
3317 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3318 a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3320 This function divides the 64-bit unsigned value Dividend by the 32-bit
3321 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3322 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3323 This function returns the 64-bit unsigned quotient.
3325 If Divisor is 0, then ASSERT().
3327 @param Dividend A 64-bit unsigned value.
3328 @param Divisor A 32-bit unsigned value.
3329 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3330 optional and may be NULL.
3332 @return Dividend / Divisor.
3337 DivU64x32Remainder (
3340 OUT UINT32
*Remainder OPTIONAL
3344 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3345 a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3347 This function divides the 64-bit unsigned value Dividend by the 64-bit
3348 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3349 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3350 This 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 64-bit unsigned value.
3356 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3357 optional and may be NULL.
3359 @return Dividend / Divisor.
3364 DivU64x64Remainder (
3367 OUT UINT64
*Remainder OPTIONAL
3371 Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3372 64-bit signed result and a optional 64-bit signed remainder.
3374 This function divides the 64-bit signed value Dividend by the 64-bit signed
3375 value Divisor and generates a 64-bit signed quotient. If Remainder is not
3376 NULL, then the 64-bit signed remainder is returned in Remainder. This
3377 function returns the 64-bit signed quotient.
3379 It is the caller's responsibility to not call this function with a Divisor of 0.
3380 If Divisor is 0, then the quotient and remainder should be assumed to be
3381 the largest negative integer.
3383 If Divisor is 0, then ASSERT().
3385 @param Dividend A 64-bit signed value.
3386 @param Divisor A 64-bit signed value.
3387 @param Remainder A pointer to a 64-bit signed value. This parameter is
3388 optional and may be NULL.
3390 @return Dividend / Divisor.
3395 DivS64x64Remainder (
3398 OUT INT64
*Remainder OPTIONAL
3402 Reads a 16-bit value from memory that may be unaligned.
3404 This function returns the 16-bit value pointed to by Buffer. The function
3405 guarantees that the read operation does not produce an alignment fault.
3407 If the Buffer is NULL, then ASSERT().
3409 @param Buffer The pointer to a 16-bit value that may be unaligned.
3411 @return The 16-bit value read from Buffer.
3417 IN CONST UINT16
*Buffer
3421 Writes a 16-bit value to memory that may be unaligned.
3423 This function writes the 16-bit value specified by Value to Buffer. Value is
3424 returned. The function guarantees that the write operation does not produce
3427 If the Buffer is NULL, then ASSERT().
3429 @param Buffer The pointer to a 16-bit value that may be unaligned.
3430 @param Value 16-bit value to write to Buffer.
3432 @return The 16-bit value to write to Buffer.
3443 Reads a 24-bit value from memory that may be unaligned.
3445 This function returns the 24-bit value pointed to by Buffer. The function
3446 guarantees that the read operation does not produce an alignment fault.
3448 If the Buffer is NULL, then ASSERT().
3450 @param Buffer The pointer to a 24-bit value that may be unaligned.
3452 @return The 24-bit value read from Buffer.
3458 IN CONST UINT32
*Buffer
3462 Writes a 24-bit value to memory that may be unaligned.
3464 This function writes the 24-bit value specified by Value to Buffer. Value is
3465 returned. The function guarantees that the write operation does not produce
3468 If the Buffer is NULL, then ASSERT().
3470 @param Buffer The pointer to a 24-bit value that may be unaligned.
3471 @param Value 24-bit value to write to Buffer.
3473 @return The 24-bit value to write to Buffer.
3484 Reads a 32-bit value from memory that may be unaligned.
3486 This function returns the 32-bit value pointed to by Buffer. The function
3487 guarantees that the read operation does not produce an alignment fault.
3489 If the Buffer is NULL, then ASSERT().
3491 @param Buffer The pointer to a 32-bit value that may be unaligned.
3493 @return The 32-bit value read from Buffer.
3499 IN CONST UINT32
*Buffer
3503 Writes a 32-bit value to memory that may be unaligned.
3505 This function writes the 32-bit value specified by Value to Buffer. Value is
3506 returned. The function guarantees that the write operation does not produce
3509 If the Buffer is NULL, then ASSERT().
3511 @param Buffer The pointer to a 32-bit value that may be unaligned.
3512 @param Value 32-bit value to write to Buffer.
3514 @return The 32-bit value to write to Buffer.
3525 Reads a 64-bit value from memory that may be unaligned.
3527 This function returns the 64-bit value pointed to by Buffer. The function
3528 guarantees that the read operation does not produce an alignment fault.
3530 If the Buffer is NULL, then ASSERT().
3532 @param Buffer The pointer to a 64-bit value that may be unaligned.
3534 @return The 64-bit value read from Buffer.
3540 IN CONST UINT64
*Buffer
3544 Writes a 64-bit value to memory that may be unaligned.
3546 This function writes the 64-bit value specified by Value to Buffer. Value is
3547 returned. The function guarantees that the write operation does not produce
3550 If the Buffer is NULL, then ASSERT().
3552 @param Buffer The pointer to a 64-bit value that may be unaligned.
3553 @param Value 64-bit value to write to Buffer.
3555 @return The 64-bit value to write to Buffer.
3566 // Bit Field Functions
3570 Returns a bit field from an 8-bit value.
3572 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3574 If 8-bit operations are not supported, then ASSERT().
3575 If StartBit is greater than 7, then ASSERT().
3576 If EndBit is greater than 7, then ASSERT().
3577 If EndBit is less than StartBit, then ASSERT().
3579 @param Operand Operand on which to perform the bitfield operation.
3580 @param StartBit The ordinal of the least significant bit in the bit field.
3582 @param EndBit The ordinal of the most significant bit in the bit field.
3585 @return The bit field read.
3597 Writes a bit field to an 8-bit value, and returns the result.
3599 Writes Value to the bit field specified by the StartBit and the EndBit in
3600 Operand. All other bits in Operand are preserved. The new 8-bit value is
3603 If 8-bit operations are not supported, then ASSERT().
3604 If StartBit is greater than 7, then ASSERT().
3605 If EndBit is greater than 7, then ASSERT().
3606 If EndBit is less than StartBit, then ASSERT().
3607 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3609 @param Operand Operand on which to perform the bitfield operation.
3610 @param StartBit The ordinal of the least significant bit in the bit field.
3612 @param EndBit The ordinal of the most significant bit in the bit field.
3614 @param Value New value of the bit field.
3616 @return The new 8-bit value.
3629 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
3632 Performs a bitwise OR between the bit field specified by StartBit
3633 and EndBit in Operand and the value specified by OrData. All other bits in
3634 Operand are preserved. The new 8-bit value is returned.
3636 If 8-bit operations are not supported, then ASSERT().
3637 If StartBit is greater than 7, then ASSERT().
3638 If EndBit is greater than 7, then ASSERT().
3639 If EndBit is less than StartBit, then ASSERT().
3640 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3642 @param Operand Operand on which to perform the bitfield operation.
3643 @param StartBit The ordinal of the least significant bit in the bit field.
3645 @param EndBit The ordinal of the most significant bit in the bit field.
3647 @param OrData The value to OR with the read value from the value
3649 @return The new 8-bit value.
3662 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
3665 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3666 in Operand and the value specified by AndData. All other bits in Operand are
3667 preserved. The new 8-bit value is returned.
3669 If 8-bit operations are not supported, then ASSERT().
3670 If StartBit is greater than 7, then ASSERT().
3671 If EndBit is greater than 7, then ASSERT().
3672 If EndBit is less than StartBit, then ASSERT().
3673 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3675 @param Operand Operand on which to perform the bitfield operation.
3676 @param StartBit The ordinal of the least significant bit in the bit field.
3678 @param EndBit The ordinal of the most significant bit in the bit field.
3680 @param AndData The value to AND with the read value from the value.
3682 @return The new 8-bit value.
3695 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
3696 bitwise OR, and returns the result.
3698 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3699 in Operand and the value specified by AndData, followed by a bitwise
3700 OR with value specified by OrData. All other bits in Operand are
3701 preserved. The new 8-bit value is returned.
3703 If 8-bit operations are not supported, then ASSERT().
3704 If StartBit is greater than 7, then ASSERT().
3705 If EndBit is greater than 7, then ASSERT().
3706 If EndBit is less than StartBit, then ASSERT().
3707 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3708 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3710 @param Operand Operand on which to perform the bitfield operation.
3711 @param StartBit The ordinal of the least significant bit in the bit field.
3713 @param EndBit The ordinal of the most significant bit in the bit field.
3715 @param AndData The value to AND with the read value from the value.
3716 @param OrData The value to OR with the result of the AND operation.
3718 @return The new 8-bit value.
3723 BitFieldAndThenOr8 (
3732 Returns a bit field from a 16-bit value.
3734 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3736 If 16-bit operations are not supported, then ASSERT().
3737 If StartBit is greater than 15, then ASSERT().
3738 If EndBit is greater than 15, then ASSERT().
3739 If EndBit is less than StartBit, then ASSERT().
3741 @param Operand Operand on which to perform the bitfield operation.
3742 @param StartBit The ordinal of the least significant bit in the bit field.
3744 @param EndBit The ordinal of the most significant bit in the bit field.
3747 @return The bit field read.
3759 Writes a bit field to a 16-bit value, and returns the result.
3761 Writes Value to the bit field specified by the StartBit and the EndBit in
3762 Operand. All other bits in Operand are preserved. The new 16-bit value is
3765 If 16-bit operations are not supported, then ASSERT().
3766 If StartBit is greater than 15, then ASSERT().
3767 If EndBit is greater than 15, then ASSERT().
3768 If EndBit is less than StartBit, then ASSERT().
3769 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3771 @param Operand Operand on which to perform the bitfield operation.
3772 @param StartBit The ordinal of the least significant bit in the bit field.
3774 @param EndBit The ordinal of the most significant bit in the bit field.
3776 @param Value New value of the bit field.
3778 @return The new 16-bit value.
3791 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
3794 Performs a bitwise OR between the bit field specified by StartBit
3795 and EndBit in Operand and the value specified by OrData. All other bits in
3796 Operand are preserved. The new 16-bit value is returned.
3798 If 16-bit operations are not supported, then ASSERT().
3799 If StartBit is greater than 15, then ASSERT().
3800 If EndBit is greater than 15, then ASSERT().
3801 If EndBit is less than StartBit, then ASSERT().
3802 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3804 @param Operand Operand on which to perform the bitfield operation.
3805 @param StartBit The ordinal of the least significant bit in the bit field.
3807 @param EndBit The ordinal of the most significant bit in the bit field.
3809 @param OrData The value to OR with the read value from the value
3811 @return The new 16-bit value.
3824 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
3827 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3828 in Operand and the value specified by AndData. All other bits in Operand are
3829 preserved. The new 16-bit value is returned.
3831 If 16-bit operations are not supported, then ASSERT().
3832 If StartBit is greater than 15, then ASSERT().
3833 If EndBit is greater than 15, then ASSERT().
3834 If EndBit is less than StartBit, then ASSERT().
3835 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3837 @param Operand Operand on which to perform the bitfield operation.
3838 @param StartBit The ordinal of the least significant bit in the bit field.
3840 @param EndBit The ordinal of the most significant bit in the bit field.
3842 @param AndData The value to AND with the read value from the value
3844 @return The new 16-bit value.
3857 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
3858 bitwise OR, and returns the result.
3860 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3861 in Operand and the value specified by AndData, followed by a bitwise
3862 OR with value specified by OrData. All other bits in Operand are
3863 preserved. The new 16-bit value is returned.
3865 If 16-bit operations are not supported, then ASSERT().
3866 If StartBit is greater than 15, then ASSERT().
3867 If EndBit is greater than 15, then ASSERT().
3868 If EndBit is less than StartBit, then ASSERT().
3869 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3870 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3872 @param Operand Operand on which to perform the bitfield operation.
3873 @param StartBit The ordinal of the least significant bit in the bit field.
3875 @param EndBit The ordinal of the most significant bit in the bit field.
3877 @param AndData The value to AND with the read value from the value.
3878 @param OrData The value to OR with the result of the AND operation.
3880 @return The new 16-bit value.
3885 BitFieldAndThenOr16 (
3894 Returns a bit field from a 32-bit value.
3896 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3898 If 32-bit operations are not supported, then ASSERT().
3899 If StartBit is greater than 31, then ASSERT().
3900 If EndBit is greater than 31, then ASSERT().
3901 If EndBit is less than StartBit, then ASSERT().
3903 @param Operand Operand on which to perform the bitfield operation.
3904 @param StartBit The ordinal of the least significant bit in the bit field.
3906 @param EndBit The ordinal of the most significant bit in the bit field.
3909 @return The bit field read.
3921 Writes a bit field to a 32-bit value, and returns the result.
3923 Writes Value to the bit field specified by the StartBit and the EndBit in
3924 Operand. All other bits in Operand are preserved. The new 32-bit value is
3927 If 32-bit operations are not supported, then ASSERT().
3928 If StartBit is greater than 31, then ASSERT().
3929 If EndBit is greater than 31, then ASSERT().
3930 If EndBit is less than StartBit, then ASSERT().
3931 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3933 @param Operand Operand on which to perform the bitfield operation.
3934 @param StartBit The ordinal of the least significant bit in the bit field.
3936 @param EndBit The ordinal of the most significant bit in the bit field.
3938 @param Value New value of the bit field.
3940 @return The new 32-bit value.
3953 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
3956 Performs a bitwise OR between the bit field specified by StartBit
3957 and EndBit in Operand and the value specified by OrData. All other bits in
3958 Operand are preserved. The new 32-bit value is returned.
3960 If 32-bit operations are not supported, then ASSERT().
3961 If StartBit is greater than 31, then ASSERT().
3962 If EndBit is greater than 31, then ASSERT().
3963 If EndBit is less than StartBit, then ASSERT().
3964 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3966 @param Operand Operand on which to perform the bitfield operation.
3967 @param StartBit The ordinal of the least significant bit in the bit field.
3969 @param EndBit The ordinal of the most significant bit in the bit field.
3971 @param OrData The value to OR with the read value from the value.
3973 @return The new 32-bit value.
3986 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
3989 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3990 in Operand and the value specified by AndData. All other bits in Operand are
3991 preserved. The new 32-bit value is returned.
3993 If 32-bit operations are not supported, then ASSERT().
3994 If StartBit is greater than 31, then ASSERT().
3995 If EndBit is greater than 31, then ASSERT().
3996 If EndBit is less than StartBit, then ASSERT().
3997 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3999 @param Operand Operand on which to perform the bitfield operation.
4000 @param StartBit The ordinal of the least significant bit in the bit field.
4002 @param EndBit The ordinal of the most significant bit in the bit field.
4004 @param AndData The value to AND with the read value from the value
4006 @return The new 32-bit value.
4019 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4020 bitwise OR, and returns the result.
4022 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4023 in Operand and the value specified by AndData, followed by a bitwise
4024 OR with value specified by OrData. All other bits in Operand are
4025 preserved. The new 32-bit value is returned.
4027 If 32-bit operations are not supported, then ASSERT().
4028 If StartBit is greater than 31, then ASSERT().
4029 If EndBit is greater than 31, then ASSERT().
4030 If EndBit is less than StartBit, then ASSERT().
4031 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4032 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4034 @param Operand Operand on which to perform the bitfield operation.
4035 @param StartBit The ordinal of the least significant bit in the bit field.
4037 @param EndBit The ordinal of the most significant bit in the bit field.
4039 @param AndData The value to AND with the read value from the value.
4040 @param OrData The value to OR with the result of the AND operation.
4042 @return The new 32-bit value.
4047 BitFieldAndThenOr32 (
4056 Returns a bit field from a 64-bit value.
4058 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4060 If 64-bit operations are not supported, then ASSERT().
4061 If StartBit is greater than 63, then ASSERT().
4062 If EndBit is greater than 63, then ASSERT().
4063 If EndBit is less than StartBit, then ASSERT().
4065 @param Operand Operand on which to perform the bitfield operation.
4066 @param StartBit The ordinal of the least significant bit in the bit field.
4068 @param EndBit The ordinal of the most significant bit in the bit field.
4071 @return The bit field read.
4083 Writes a bit field to a 64-bit value, and returns the result.
4085 Writes Value to the bit field specified by the StartBit and the EndBit in
4086 Operand. All other bits in Operand are preserved. The new 64-bit value is
4089 If 64-bit operations are not supported, then ASSERT().
4090 If StartBit is greater than 63, then ASSERT().
4091 If EndBit is greater than 63, then ASSERT().
4092 If EndBit is less than StartBit, then ASSERT().
4093 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4095 @param Operand Operand on which to perform the bitfield operation.
4096 @param StartBit The ordinal of the least significant bit in the bit field.
4098 @param EndBit The ordinal of the most significant bit in the bit field.
4100 @param Value New value of the bit field.
4102 @return The new 64-bit value.
4115 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4118 Performs a bitwise OR between the bit field specified by StartBit
4119 and EndBit in Operand and the value specified by OrData. All other bits in
4120 Operand are preserved. The new 64-bit value is returned.
4122 If 64-bit operations are not supported, then ASSERT().
4123 If StartBit is greater than 63, then ASSERT().
4124 If EndBit is greater than 63, then ASSERT().
4125 If EndBit is less than StartBit, then ASSERT().
4126 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4128 @param Operand Operand on which to perform the bitfield operation.
4129 @param StartBit The ordinal of the least significant bit in the bit field.
4131 @param EndBit The ordinal of the most significant bit in the bit field.
4133 @param OrData The value to OR with the read value from the value
4135 @return The new 64-bit value.
4148 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4151 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4152 in Operand and the value specified by AndData. All other bits in Operand are
4153 preserved. The new 64-bit value is returned.
4155 If 64-bit operations are not supported, then ASSERT().
4156 If StartBit is greater than 63, then ASSERT().
4157 If EndBit is greater than 63, then ASSERT().
4158 If EndBit is less than StartBit, then ASSERT().
4159 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4161 @param Operand Operand on which to perform the bitfield operation.
4162 @param StartBit The ordinal of the least significant bit in the bit field.
4164 @param EndBit The ordinal of the most significant bit in the bit field.
4166 @param AndData The value to AND with the read value from the value
4168 @return The new 64-bit value.
4181 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4182 bitwise OR, and returns the result.
4184 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4185 in Operand and the value specified by AndData, followed by a bitwise
4186 OR with value specified by OrData. All other bits in Operand are
4187 preserved. The new 64-bit value is returned.
4189 If 64-bit operations are not supported, then ASSERT().
4190 If StartBit is greater than 63, then ASSERT().
4191 If EndBit is greater than 63, then ASSERT().
4192 If EndBit is less than StartBit, then ASSERT().
4193 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4194 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4196 @param Operand Operand on which to perform the bitfield operation.
4197 @param StartBit The ordinal of the least significant bit in the bit field.
4199 @param EndBit The ordinal of the most significant bit in the bit field.
4201 @param AndData The value to AND with the read value from the value.
4202 @param OrData The value to OR with the result of the AND operation.
4204 @return The new 64-bit value.
4209 BitFieldAndThenOr64 (
4218 Reads a bit field from a 32-bit value, counts and returns
4219 the number of set bits.
4221 Counts the number of set bits in the bit field specified by
4222 StartBit and EndBit in Operand. The count is returned.
4224 If StartBit is greater than 31, then ASSERT().
4225 If EndBit is greater than 31, then ASSERT().
4226 If EndBit is less than StartBit, then ASSERT().
4228 @param Operand Operand on which to perform the bitfield operation.
4229 @param StartBit The ordinal of the least significant bit in the bit field.
4231 @param EndBit The ordinal of the most significant bit in the bit field.
4234 @return The number of bits set between StartBit and EndBit.
4239 BitFieldCountOnes32 (
4246 Reads a bit field from a 64-bit value, counts and returns
4247 the number of set bits.
4249 Counts the number of set bits in the bit field specified by
4250 StartBit and EndBit in Operand. The count is returned.
4252 If StartBit is greater than 63, then ASSERT().
4253 If EndBit is greater than 63, then ASSERT().
4254 If EndBit is less than StartBit, then ASSERT().
4256 @param Operand Operand on which to perform the bitfield operation.
4257 @param StartBit The ordinal of the least significant bit in the bit field.
4259 @param EndBit The ordinal of the most significant bit in the bit field.
4262 @return The number of bits set between StartBit and EndBit.
4267 BitFieldCountOnes64 (
4274 // Base Library Checksum Functions
4278 Returns the sum of all elements in a buffer in unit of UINT8.
4279 During calculation, the carry bits are dropped.
4281 This function calculates the sum of all elements in a buffer
4282 in unit of UINT8. The carry bits in result of addition are dropped.
4283 The result is returned as UINT8. If Length is Zero, then Zero is
4286 If Buffer is NULL, then ASSERT().
4287 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4289 @param Buffer The pointer to the buffer to carry out the sum operation.
4290 @param Length The size, in bytes, of Buffer.
4292 @return Sum The sum of Buffer with carry bits dropped during additions.
4298 IN CONST UINT8
*Buffer
,
4303 Returns the two's complement checksum of all elements in a buffer
4306 This function first calculates the sum of the 8-bit values in the
4307 buffer specified by Buffer and Length. The carry bits in the result
4308 of addition are dropped. Then, the two's complement of the sum is
4309 returned. If Length is 0, then 0 is returned.
4311 If Buffer is NULL, then ASSERT().
4312 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4314 @param Buffer The pointer to the buffer to carry out the checksum operation.
4315 @param Length The size, in bytes, of Buffer.
4317 @return Checksum The two's complement checksum of Buffer.
4322 CalculateCheckSum8 (
4323 IN CONST UINT8
*Buffer
,
4328 Returns the sum of all elements in a buffer of 16-bit values. During
4329 calculation, the carry bits are dropped.
4331 This function calculates the sum of the 16-bit values in the buffer
4332 specified by Buffer and Length. The carry bits in result of addition are dropped.
4333 The 16-bit result is returned. If Length is 0, then 0 is returned.
4335 If Buffer is NULL, then ASSERT().
4336 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4337 If Length is not aligned on a 16-bit boundary, then ASSERT().
4338 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4340 @param Buffer The pointer to the buffer to carry out the sum operation.
4341 @param Length The size, in bytes, of Buffer.
4343 @return Sum The sum of Buffer with carry bits dropped during additions.
4349 IN CONST UINT16
*Buffer
,
4354 Returns the two's complement checksum of all elements in a buffer of
4357 This function first calculates the sum of the 16-bit values in the buffer
4358 specified by Buffer and Length. The carry bits in the result of addition
4359 are dropped. Then, the two's complement of the sum is returned. If Length
4360 is 0, then 0 is returned.
4362 If Buffer is NULL, then ASSERT().
4363 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4364 If Length is not aligned on a 16-bit boundary, then ASSERT().
4365 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4367 @param Buffer The pointer to the buffer to carry out the checksum operation.
4368 @param Length The size, in bytes, of Buffer.
4370 @return Checksum The two's complement checksum of Buffer.
4375 CalculateCheckSum16 (
4376 IN CONST UINT16
*Buffer
,
4381 Returns the sum of all elements in a buffer of 32-bit values. During
4382 calculation, the carry bits are dropped.
4384 This function calculates the sum of the 32-bit values in the buffer
4385 specified by Buffer and Length. The carry bits in result of addition are dropped.
4386 The 32-bit result is returned. If Length is 0, then 0 is returned.
4388 If Buffer is NULL, then ASSERT().
4389 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4390 If Length is not aligned on a 32-bit boundary, then ASSERT().
4391 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4393 @param Buffer The pointer to the buffer to carry out the sum operation.
4394 @param Length The size, in bytes, of Buffer.
4396 @return Sum The sum of Buffer with carry bits dropped during additions.
4402 IN CONST UINT32
*Buffer
,
4407 Returns the two's complement checksum of all elements in a buffer of
4410 This function first calculates the sum of the 32-bit values in the buffer
4411 specified by Buffer and Length. The carry bits in the result of addition
4412 are dropped. Then, the two's complement of the sum is returned. If Length
4413 is 0, then 0 is returned.
4415 If Buffer is NULL, then ASSERT().
4416 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4417 If Length is not aligned on a 32-bit boundary, then ASSERT().
4418 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4420 @param Buffer The pointer to the buffer to carry out the checksum operation.
4421 @param Length The size, in bytes, of Buffer.
4423 @return Checksum The two's complement checksum of Buffer.
4428 CalculateCheckSum32 (
4429 IN CONST UINT32
*Buffer
,
4434 Returns the sum of all elements in a buffer of 64-bit values. During
4435 calculation, the carry bits are dropped.
4437 This function calculates the sum of the 64-bit values in the buffer
4438 specified by Buffer and Length. The carry bits in result of addition are dropped.
4439 The 64-bit result is returned. If Length is 0, then 0 is returned.
4441 If Buffer is NULL, then ASSERT().
4442 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4443 If Length is not aligned on a 64-bit boundary, then ASSERT().
4444 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4446 @param Buffer The pointer to the buffer to carry out the sum operation.
4447 @param Length The size, in bytes, of Buffer.
4449 @return Sum The sum of Buffer with carry bits dropped during additions.
4455 IN CONST UINT64
*Buffer
,
4460 Returns the two's complement checksum of all elements in a buffer of
4463 This function first calculates the sum of the 64-bit values in the buffer
4464 specified by Buffer and Length. The carry bits in the result of addition
4465 are dropped. Then, the two's complement of the sum is returned. If Length
4466 is 0, then 0 is returned.
4468 If Buffer is NULL, then ASSERT().
4469 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4470 If Length is not aligned on a 64-bit boundary, then ASSERT().
4471 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4473 @param Buffer The pointer to the buffer to carry out the checksum operation.
4474 @param Length The size, in bytes, of Buffer.
4476 @return Checksum The two's complement checksum of Buffer.
4481 CalculateCheckSum64 (
4482 IN CONST UINT64
*Buffer
,
4487 Computes and returns a 32-bit CRC for a data buffer.
4488 CRC32 value bases on ITU-T V.42.
4490 If Buffer is NULL, then ASSERT().
4491 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4493 @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed.
4494 @param[in] Length The number of bytes in the buffer Data.
4496 @retval Crc32 The 32-bit CRC was computed for the data buffer.
4507 Calculates the CRC16-ANSI checksum of the given buffer.
4509 @param[in] Buffer Pointer to the buffer.
4510 @param[in] Length Length of the buffer, in bytes.
4511 @param[in] InitialValue Initial value of the CRC.
4513 @return The CRC16-ANSI checksum.
4517 CalculateCrc16Ansi (
4518 IN CONST VOID
*Buffer
,
4520 IN UINT16 InitialValue
4524 Calculates the CRC32c checksum of the given buffer.
4526 @param[in] Buffer Pointer to the buffer.
4527 @param[in] Length Length of the buffer, in bytes.
4528 @param[in] InitialValue Initial value of the CRC.
4530 @return The CRC32c checksum.
4535 IN CONST VOID
*Buffer
,
4537 IN UINT32 InitialValue
4541 // Base Library CPU Functions
4545 Function entry point used when a stack switch is requested with SwitchStack()
4547 @param Context1 Context1 parameter passed into SwitchStack().
4548 @param Context2 Context2 parameter passed into SwitchStack().
4552 (EFIAPI
*SWITCH_STACK_ENTRY_POINT
)(
4553 IN VOID
*Context1 OPTIONAL
,
4554 IN VOID
*Context2 OPTIONAL
4558 Used to serialize load and store operations.
4560 All loads and stores that proceed calls to this function are guaranteed to be
4561 globally visible when this function returns.
4571 Saves the current CPU context that can be restored with a call to LongJump()
4574 Saves the current CPU context in the buffer specified by JumpBuffer and
4575 returns 0. The initial call to SetJump() must always return 0. Subsequent
4576 calls to LongJump() cause a non-zero value to be returned by SetJump().
4578 If JumpBuffer is NULL, then ASSERT().
4579 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4581 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
4582 The same structure must never be used for more than one CPU architecture context.
4583 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
4584 SetJump()/LongJump() is not currently supported for the EBC processor type.
4586 @param JumpBuffer A pointer to CPU context buffer.
4588 @retval 0 Indicates a return from SetJump().
4595 OUT BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
4599 Restores the CPU context that was saved with SetJump().
4601 Restores the CPU context from the buffer specified by JumpBuffer. This
4602 function never returns to the caller. Instead is resumes execution based on
4603 the state of JumpBuffer.
4605 If JumpBuffer is NULL, then ASSERT().
4606 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4607 If Value is 0, then ASSERT().
4609 @param JumpBuffer A pointer to CPU context buffer.
4610 @param Value The value to return when the SetJump() context is
4611 restored and must be non-zero.
4617 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
4622 Enables CPU interrupts.
4632 Disables CPU interrupts.
4642 Disables CPU interrupts and returns the interrupt state prior to the disable
4645 @retval TRUE CPU interrupts were enabled on entry to this call.
4646 @retval FALSE CPU interrupts were disabled on entry to this call.
4651 SaveAndDisableInterrupts (
4656 Enables CPU interrupts for the smallest window required to capture any
4662 EnableDisableInterrupts (
4667 Retrieves the current CPU interrupt state.
4669 Returns TRUE if interrupts are currently enabled. Otherwise
4672 @retval TRUE CPU interrupts are enabled.
4673 @retval FALSE CPU interrupts are disabled.
4683 Set the current CPU interrupt state.
4685 Sets the current CPU interrupt state to the state specified by
4686 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
4687 InterruptState is FALSE, then interrupts are disabled. InterruptState is
4690 @param InterruptState TRUE if interrupts should enabled. FALSE if
4691 interrupts should be disabled.
4693 @return InterruptState
4699 IN BOOLEAN InterruptState
4703 Requests CPU to pause for a short period of time.
4705 Requests CPU to pause for a short period of time. Typically used in MP
4706 systems to prevent memory starvation while waiting for a spin lock.
4716 Transfers control to a function starting with a new stack.
4718 Transfers control to the function specified by EntryPoint using the
4719 new stack specified by NewStack and passing in the parameters specified
4720 by Context1 and Context2. Context1 and Context2 are optional and may
4721 be NULL. The function EntryPoint must never return. This function
4722 supports a variable number of arguments following the NewStack parameter.
4723 These additional arguments are ignored on IA-32, x64, and EBC architectures.
4724 Itanium processors expect one additional parameter of type VOID * that specifies
4725 the new backing store pointer.
4727 If EntryPoint is NULL, then ASSERT().
4728 If NewStack is NULL, then ASSERT().
4730 @param EntryPoint A pointer to function to call with the new stack.
4731 @param Context1 A pointer to the context to pass into the EntryPoint
4733 @param Context2 A pointer to the context to pass into the EntryPoint
4735 @param NewStack A pointer to the new stack to use for the EntryPoint
4737 @param ... This variable argument list is ignored for IA-32, x64, and
4738 EBC architectures. For Itanium processors, this variable
4739 argument list is expected to contain a single parameter of
4740 type VOID * that specifies the new backing store pointer.
4747 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
4748 IN VOID
*Context1 OPTIONAL
,
4749 IN VOID
*Context2 OPTIONAL
,
4755 Generates a breakpoint on the CPU.
4757 Generates a breakpoint on the CPU. The breakpoint must be implemented such
4758 that code can resume normal execution after the breakpoint.
4768 Executes an infinite loop.
4770 Forces the CPU to execute an infinite loop. A debugger may be used to skip
4771 past the loop and the code that follows the loop must execute properly. This
4772 implies that the infinite loop must not cause the code that follow it to be
4783 Uses as a barrier to stop speculative execution.
4785 Ensures that no later instruction will execute speculatively, until all prior
4786 instructions have completed.
4791 SpeculationBarrier (
4795 #if defined (MDE_CPU_X64) || defined (MDE_CPU_IA32)
4798 The TDCALL instruction causes a VM exit to the Intel TDX module. It is
4799 used to call guest-side Intel TDX functions, either local or a TD exit
4800 to the host VMM, as selected by Leaf.
4802 @param[in] Leaf Leaf number of TDCALL instruction
4803 @param[in] Arg1 Arg1
4804 @param[in] Arg2 Arg2
4805 @param[in] Arg3 Arg3
4806 @param[in,out] Results Returned result of the Leaf function
4808 @return 0 A successful call
4809 @return Other See individual leaf functions
4818 IN OUT VOID
*Results
4822 TDVMALL is a leaf function 0 for TDCALL. It helps invoke services from the
4823 host VMM to pass/receive information.
4825 @param[in] Leaf Number of sub-functions
4826 @param[in] Arg1 Arg1
4827 @param[in] Arg2 Arg2
4828 @param[in] Arg3 Arg3
4829 @param[in] Arg4 Arg4
4830 @param[in,out] Results Returned result of the sub-function
4832 @return 0 A successful call
4833 @return Other See individual sub-functions
4844 IN OUT VOID
*Results
4848 Probe if TD is enabled.
4850 @return TRUE TD is enabled.
4851 @return FALSE TD is not enabled.
4861 #if defined (MDE_CPU_X64)
4863 // The page size for the PVALIDATE instruction
4866 PvalidatePageSize4K
= 0,
4867 PvalidatePageSize2MB
,
4868 } PVALIDATE_PAGE_SIZE
;
4871 // PVALIDATE Return Code.
4873 #define PVALIDATE_RET_SUCCESS 0
4874 #define PVALIDATE_RET_FAIL_INPUT 1
4875 #define PVALIDATE_RET_SIZE_MISMATCH 6
4878 // The PVALIDATE instruction did not make any changes to the RMP entry.
4880 #define PVALIDATE_RET_NO_RMPUPDATE 255
4883 Execute a PVALIDATE instruction to validate or to rescinds validation of a guest
4886 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
4888 The function is available on X64.
4890 @param[in] PageSize The page size to use.
4891 @param[in] Validate If TRUE, validate the guest virtual address
4892 otherwise invalidate the guest virtual address.
4893 @param[in] Address The guest virtual address.
4895 @retval PVALIDATE_RET_SUCCESS The PVALIDATE instruction succeeded, and
4896 updated the RMP entry.
4897 @retval PVALIDATE_RET_NO_RMPUPDATE The PVALIDATE instruction succeeded, but
4898 did not update the RMP entry.
4899 @return Failure code from the PVALIDATE
4905 IN PVALIDATE_PAGE_SIZE PageSize
,
4906 IN BOOLEAN Validate
,
4907 IN PHYSICAL_ADDRESS Address
4911 // RDX settings for RMPADJUST
4913 #define RMPADJUST_VMPL_MAX 3
4914 #define RMPADJUST_VMPL_MASK 0xFF
4915 #define RMPADJUST_VMPL_SHIFT 0
4916 #define RMPADJUST_PERMISSION_MASK_MASK 0xFF
4917 #define RMPADJUST_PERMISSION_MASK_SHIFT 8
4918 #define RMPADJUST_VMSA_PAGE_BIT BIT16
4921 Adjusts the permissions of an SEV-SNP guest page.
4923 Executes a RMPADJUST instruction with the register state specified by Rax,
4924 Rcx, and Rdx. Returns Eax. This function is only available on X64.
4926 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
4928 @param[in] Rax The value to load into RAX before executing the RMPADJUST
4930 @param[in] Rcx The value to load into RCX before executing the RMPADJUST
4932 @param[in] Rdx The value to load into RDX before executing the RMPADJUST
4947 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
4949 /// IA32 and x64 Specific Functions.
4950 /// Byte packed structure for 16-bit Real Mode EFLAGS.
4954 UINT32 CF
: 1; ///< Carry Flag.
4955 UINT32 Reserved_0
: 1; ///< Reserved.
4956 UINT32 PF
: 1; ///< Parity Flag.
4957 UINT32 Reserved_1
: 1; ///< Reserved.
4958 UINT32 AF
: 1; ///< Auxiliary Carry Flag.
4959 UINT32 Reserved_2
: 1; ///< Reserved.
4960 UINT32 ZF
: 1; ///< Zero Flag.
4961 UINT32 SF
: 1; ///< Sign Flag.
4962 UINT32 TF
: 1; ///< Trap Flag.
4963 UINT32 IF
: 1; ///< Interrupt Enable Flag.
4964 UINT32 DF
: 1; ///< Direction Flag.
4965 UINT32 OF
: 1; ///< Overflow Flag.
4966 UINT32 IOPL
: 2; ///< I/O Privilege Level.
4967 UINT32 NT
: 1; ///< Nested Task.
4968 UINT32 Reserved_3
: 1; ///< Reserved.
4974 /// Byte packed structure for EFLAGS/RFLAGS.
4975 /// 32-bits on IA-32.
4976 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
4980 UINT32 CF
: 1; ///< Carry Flag.
4981 UINT32 Reserved_0
: 1; ///< Reserved.
4982 UINT32 PF
: 1; ///< Parity Flag.
4983 UINT32 Reserved_1
: 1; ///< Reserved.
4984 UINT32 AF
: 1; ///< Auxiliary Carry Flag.
4985 UINT32 Reserved_2
: 1; ///< Reserved.
4986 UINT32 ZF
: 1; ///< Zero Flag.
4987 UINT32 SF
: 1; ///< Sign Flag.
4988 UINT32 TF
: 1; ///< Trap Flag.
4989 UINT32 IF
: 1; ///< Interrupt Enable Flag.
4990 UINT32 DF
: 1; ///< Direction Flag.
4991 UINT32 OF
: 1; ///< Overflow Flag.
4992 UINT32 IOPL
: 2; ///< I/O Privilege Level.
4993 UINT32 NT
: 1; ///< Nested Task.
4994 UINT32 Reserved_3
: 1; ///< Reserved.
4995 UINT32 RF
: 1; ///< Resume Flag.
4996 UINT32 VM
: 1; ///< Virtual 8086 Mode.
4997 UINT32 AC
: 1; ///< Alignment Check.
4998 UINT32 VIF
: 1; ///< Virtual Interrupt Flag.
4999 UINT32 VIP
: 1; ///< Virtual Interrupt Pending.
5000 UINT32 ID
: 1; ///< ID Flag.
5001 UINT32 Reserved_4
: 10; ///< Reserved.
5007 /// Byte packed structure for Control Register 0 (CR0).
5008 /// 32-bits on IA-32.
5009 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5013 UINT32 PE
: 1; ///< Protection Enable.
5014 UINT32 MP
: 1; ///< Monitor Coprocessor.
5015 UINT32 EM
: 1; ///< Emulation.
5016 UINT32 TS
: 1; ///< Task Switched.
5017 UINT32 ET
: 1; ///< Extension Type.
5018 UINT32 NE
: 1; ///< Numeric Error.
5019 UINT32 Reserved_0
: 10; ///< Reserved.
5020 UINT32 WP
: 1; ///< Write Protect.
5021 UINT32 Reserved_1
: 1; ///< Reserved.
5022 UINT32 AM
: 1; ///< Alignment Mask.
5023 UINT32 Reserved_2
: 10; ///< Reserved.
5024 UINT32 NW
: 1; ///< Mot Write-through.
5025 UINT32 CD
: 1; ///< Cache Disable.
5026 UINT32 PG
: 1; ///< Paging.
5032 /// Byte packed structure for Control Register 4 (CR4).
5033 /// 32-bits on IA-32.
5034 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5038 UINT32 VME
: 1; ///< Virtual-8086 Mode Extensions.
5039 UINT32 PVI
: 1; ///< Protected-Mode Virtual Interrupts.
5040 UINT32 TSD
: 1; ///< Time Stamp Disable.
5041 UINT32 DE
: 1; ///< Debugging Extensions.
5042 UINT32 PSE
: 1; ///< Page Size Extensions.
5043 UINT32 PAE
: 1; ///< Physical Address Extension.
5044 UINT32 MCE
: 1; ///< Machine Check Enable.
5045 UINT32 PGE
: 1; ///< Page Global Enable.
5046 UINT32 PCE
: 1; ///< Performance Monitoring Counter
5048 UINT32 OSFXSR
: 1; ///< Operating System Support for
5049 ///< FXSAVE and FXRSTOR instructions
5050 UINT32 OSXMMEXCPT
: 1; ///< Operating System Support for
5051 ///< Unmasked SIMD Floating Point
5053 UINT32 UMIP
: 1; ///< User-Mode Instruction Prevention.
5054 UINT32 LA57
: 1; ///< Linear Address 57bit.
5055 UINT32 VMXE
: 1; ///< VMX Enable.
5056 UINT32 SMXE
: 1; ///< SMX Enable.
5057 UINT32 Reserved_3
: 1; ///< Reserved.
5058 UINT32 FSGSBASE
: 1; ///< FSGSBASE Enable.
5059 UINT32 PCIDE
: 1; ///< PCID Enable.
5060 UINT32 OSXSAVE
: 1; ///< XSAVE and Processor Extended States Enable.
5061 UINT32 Reserved_4
: 1; ///< Reserved.
5062 UINT32 SMEP
: 1; ///< SMEP Enable.
5063 UINT32 SMAP
: 1; ///< SMAP Enable.
5064 UINT32 PKE
: 1; ///< Protection-Key Enable.
5065 UINT32 Reserved_5
: 9; ///< Reserved.
5071 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5075 UINT32 LimitLow
: 16;
5076 UINT32 BaseLow
: 16;
5082 UINT32 LimitHigh
: 4;
5087 UINT32 BaseHigh
: 8;
5090 } IA32_SEGMENT_DESCRIPTOR
;
5093 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5102 #define IA32_IDT_GATE_TYPE_TASK 0x85
5103 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5104 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5105 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5106 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5108 #define IA32_GDT_TYPE_TSS 0x9
5109 #define IA32_GDT_ALIGNMENT 8
5111 #if defined (MDE_CPU_IA32)
5113 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5117 UINT32 OffsetLow
: 16; ///< Offset bits 15..0.
5118 UINT32 Selector
: 16; ///< Selector.
5119 UINT32 Reserved_0
: 8; ///< Reserved.
5120 UINT32 GateType
: 8; ///< Gate Type. See #defines above.
5121 UINT32 OffsetHigh
: 16; ///< Offset bits 31..16.
5124 } IA32_IDT_GATE_DESCRIPTOR
;
5128 // IA32 Task-State Segment Definition
5131 UINT16 PreviousTaskLink
;
5165 UINT16 LDTSegmentSelector
;
5168 UINT16 IOMapBaseAddress
;
5169 } IA32_TASK_STATE_SEGMENT
;
5173 UINT32 LimitLow
: 16; ///< Segment Limit 15..00
5174 UINT32 BaseLow
: 16; ///< Base Address 15..00
5175 UINT32 BaseMid
: 8; ///< Base Address 23..16
5176 UINT32 Type
: 4; ///< Type (1 0 B 1)
5177 UINT32 Reserved_43
: 1; ///< 0
5178 UINT32 DPL
: 2; ///< Descriptor Privilege Level
5179 UINT32 P
: 1; ///< Segment Present
5180 UINT32 LimitHigh
: 4; ///< Segment Limit 19..16
5181 UINT32 AVL
: 1; ///< Available for use by system software
5182 UINT32 Reserved_52
: 2; ///< 0 0
5183 UINT32 G
: 1; ///< Granularity
5184 UINT32 BaseHigh
: 8; ///< Base Address 31..24
5187 } IA32_TSS_DESCRIPTOR
;
5190 #endif // defined (MDE_CPU_IA32)
5192 #if defined (MDE_CPU_X64)
5194 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5198 UINT32 OffsetLow
: 16; ///< Offset bits 15..0.
5199 UINT32 Selector
: 16; ///< Selector.
5200 UINT32 Reserved_0
: 8; ///< Reserved.
5201 UINT32 GateType
: 8; ///< Gate Type. See #defines above.
5202 UINT32 OffsetHigh
: 16; ///< Offset bits 31..16.
5203 UINT32 OffsetUpper
: 32; ///< Offset bits 63..32.
5204 UINT32 Reserved_1
: 32; ///< Reserved.
5210 } IA32_IDT_GATE_DESCRIPTOR
;
5214 // IA32 Task-State Segment Definition
5224 UINT16 Reserved_100
;
5225 UINT16 IOMapBaseAddress
;
5226 } IA32_TASK_STATE_SEGMENT
;
5230 UINT32 LimitLow
: 16; ///< Segment Limit 15..00
5231 UINT32 BaseLow
: 16; ///< Base Address 15..00
5232 UINT32 BaseMidl
: 8; ///< Base Address 23..16
5233 UINT32 Type
: 4; ///< Type (1 0 B 1)
5234 UINT32 Reserved_43
: 1; ///< 0
5235 UINT32 DPL
: 2; ///< Descriptor Privilege Level
5236 UINT32 P
: 1; ///< Segment Present
5237 UINT32 LimitHigh
: 4; ///< Segment Limit 19..16
5238 UINT32 AVL
: 1; ///< Available for use by system software
5239 UINT32 Reserved_52
: 2; ///< 0 0
5240 UINT32 G
: 1; ///< Granularity
5241 UINT32 BaseMidh
: 8; ///< Base Address 31..24
5242 UINT32 BaseHigh
: 32; ///< Base Address 63..32
5243 UINT32 Reserved_96
: 32; ///< Reserved
5249 } IA32_TSS_DESCRIPTOR
;
5252 #endif // defined (MDE_CPU_X64)
5255 /// Byte packed structure for an FP/SSE/SSE2 context.
5262 /// Structures for the 16-bit real mode thunks.
5315 IA32_EFLAGS32 EFLAGS
;
5325 } IA32_REGISTER_SET
;
5328 /// Byte packed structure for an 16-bit real mode thunks.
5331 IA32_REGISTER_SET
*RealModeState
;
5332 VOID
*RealModeBuffer
;
5333 UINT32 RealModeBufferSize
;
5334 UINT32 ThunkAttributes
;
5337 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5338 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5339 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5342 /// Type definition for representing labels in NASM source code that allow for
5343 /// the patching of immediate operands of IA32 and X64 instructions.
5345 /// While the type is technically defined as a function type (note: not a
5346 /// pointer-to-function type), such labels in NASM source code never stand for
5347 /// actual functions, and identifiers declared with this function type should
5348 /// never be called. This is also why the EFIAPI calling convention specifier
5349 /// is missing from the typedef, and why the typedef does not follow the usual
5350 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5351 /// return type and the VOID argument list are merely artifacts.
5353 typedef VOID (X86_ASSEMBLY_PATCH_LABEL
) (
5358 Retrieves CPUID information.
5360 Executes the CPUID instruction with EAX set to the value specified by Index.
5361 This function always returns Index.
5362 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5363 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5364 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5365 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5366 This function is only available on IA-32 and x64.
5368 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5370 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5371 instruction. This is an optional parameter that may be NULL.
5372 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5373 instruction. This is an optional parameter that may be NULL.
5374 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5375 instruction. This is an optional parameter that may be NULL.
5376 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5377 instruction. This is an optional parameter that may be NULL.
5386 OUT UINT32
*Eax OPTIONAL
,
5387 OUT UINT32
*Ebx OPTIONAL
,
5388 OUT UINT32
*Ecx OPTIONAL
,
5389 OUT UINT32
*Edx OPTIONAL
5393 Retrieves CPUID information using an extended leaf identifier.
5395 Executes the CPUID instruction with EAX set to the value specified by Index
5396 and ECX set to the value specified by SubIndex. This function always returns
5397 Index. This function is only available on IA-32 and x64.
5399 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5400 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5401 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5402 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5404 @param Index The 32-bit value to load into EAX prior to invoking the
5406 @param SubIndex The 32-bit value to load into ECX prior to invoking the
5408 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5409 instruction. This is an optional parameter that may be
5411 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5412 instruction. This is an optional parameter that may be
5414 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5415 instruction. This is an optional parameter that may be
5417 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5418 instruction. This is an optional parameter that may be
5429 OUT UINT32
*Eax OPTIONAL
,
5430 OUT UINT32
*Ebx OPTIONAL
,
5431 OUT UINT32
*Ecx OPTIONAL
,
5432 OUT UINT32
*Edx OPTIONAL
5436 Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5438 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5439 and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5449 Perform a WBINVD and clear both the CD and NW bits of CR0.
5451 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5452 bits of CR0 to 0. This function is only available on IA-32 and x64.
5462 Returns the lower 32-bits of a Machine Specific Register(MSR).
5464 Reads and returns the lower 32-bits of the MSR specified by Index.
5465 No parameter checking is performed on Index, and some Index values may cause
5466 CPU exceptions. The caller must either guarantee that Index is valid, or the
5467 caller must set up exception handlers to catch the exceptions. This function
5468 is only available on IA-32 and x64.
5470 @param Index The 32-bit MSR index to read.
5472 @return The lower 32 bits of the MSR identified by Index.
5482 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5483 The upper 32-bits of the MSR are set to zero.
5485 Writes the 32-bit value specified by Value to the MSR specified by Index. The
5486 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5487 the MSR is returned. No parameter checking is performed on Index or Value,
5488 and some of these may cause CPU exceptions. The caller must either guarantee
5489 that Index and Value are valid, or the caller must establish proper exception
5490 handlers. This function is only available on IA-32 and x64.
5492 @param Index The 32-bit MSR index to write.
5493 @param Value The 32-bit value to write to the MSR.
5506 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5507 writes the result back to the 64-bit MSR.
5509 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5510 between the lower 32-bits of the read result and the value specified by
5511 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5512 32-bits of the value written to the MSR is returned. No parameter checking is
5513 performed on Index or OrData, and some of these may cause CPU exceptions. The
5514 caller must either guarantee that Index and OrData are valid, or the caller
5515 must establish proper exception handlers. This function is only available on
5518 @param Index The 32-bit MSR index to write.
5519 @param OrData The value to OR with the read value from the MSR.
5521 @return The lower 32-bit value written to the MSR.
5532 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5533 the result back to the 64-bit MSR.
5535 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5536 lower 32-bits of the read result and the value specified by AndData, and
5537 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5538 the value written to the MSR is returned. No parameter checking is performed
5539 on Index or AndData, and some of these may cause CPU exceptions. The caller
5540 must either guarantee that Index and AndData are valid, or the caller must
5541 establish proper exception handlers. This function is only available on IA-32
5544 @param Index The 32-bit MSR index to write.
5545 @param AndData The value to AND with the read value from the MSR.
5547 @return The lower 32-bit value written to the MSR.
5558 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5559 on the lower 32-bits, and writes the result back to the 64-bit MSR.
5561 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5562 lower 32-bits of the read result and the value specified by AndData
5563 preserving the upper 32-bits, performs a bitwise OR between the
5564 result of the AND operation and the value specified by OrData, and writes the
5565 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5566 written to the MSR is returned. No parameter checking is performed on Index,
5567 AndData, or OrData, and some of these may cause CPU exceptions. The caller
5568 must either guarantee that Index, AndData, and OrData are valid, or the
5569 caller must establish proper exception handlers. This function is only
5570 available on IA-32 and x64.
5572 @param Index The 32-bit MSR index to write.
5573 @param AndData The value to AND with the read value from the MSR.
5574 @param OrData The value to OR with the result of the AND operation.
5576 @return The lower 32-bit value written to the MSR.
5588 Reads a bit field of an MSR.
5590 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5591 specified by the StartBit and the EndBit. The value of the bit field is
5592 returned. The caller must either guarantee that Index is valid, or the caller
5593 must set up exception handlers to catch the exceptions. This function is only
5594 available on IA-32 and x64.
5596 If StartBit is greater than 31, then ASSERT().
5597 If EndBit is greater than 31, then ASSERT().
5598 If EndBit is less than StartBit, then ASSERT().
5600 @param Index The 32-bit MSR index to read.
5601 @param StartBit The ordinal of the least significant bit in the bit field.
5603 @param EndBit The ordinal of the most significant bit in the bit field.
5606 @return The bit field read from the MSR.
5611 AsmMsrBitFieldRead32 (
5618 Writes a bit field to an MSR.
5620 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5621 field is specified by the StartBit and the EndBit. All other bits in the
5622 destination MSR are preserved. The lower 32-bits of the MSR written is
5623 returned. The caller must either guarantee that Index and the data written
5624 is valid, or the caller must set up exception handlers to catch the exceptions.
5625 This function is only available on IA-32 and x64.
5627 If StartBit is greater than 31, then ASSERT().
5628 If EndBit is greater than 31, then ASSERT().
5629 If EndBit is less than StartBit, then ASSERT().
5630 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5632 @param Index The 32-bit MSR index to write.
5633 @param StartBit The ordinal of the least significant bit in the bit field.
5635 @param EndBit The ordinal of the most significant bit in the bit field.
5637 @param Value New value of the bit field.
5639 @return The lower 32-bit of the value written to the MSR.
5644 AsmMsrBitFieldWrite32 (
5652 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5653 result back to the bit field in the 64-bit MSR.
5655 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5656 between the read result and the value specified by OrData, and writes the
5657 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
5658 written to the MSR are returned. Extra left bits in OrData are stripped. The
5659 caller must either guarantee that Index and the data written is valid, or
5660 the caller must set up exception handlers to catch the exceptions. This
5661 function is only available on IA-32 and x64.
5663 If StartBit is greater than 31, then ASSERT().
5664 If EndBit is greater than 31, then ASSERT().
5665 If EndBit is less than StartBit, then ASSERT().
5666 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5668 @param Index The 32-bit MSR index to write.
5669 @param StartBit The ordinal of the least significant bit in the bit field.
5671 @param EndBit The ordinal of the most significant bit in the bit field.
5673 @param OrData The value to OR with the read value from the MSR.
5675 @return The lower 32-bit of the value written to the MSR.
5680 AsmMsrBitFieldOr32 (
5688 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5689 result back to the bit field in the 64-bit MSR.
5691 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5692 read result and the value specified by AndData, and writes the result to the
5693 64-bit MSR specified by Index. The lower 32-bits of the value written to the
5694 MSR are returned. Extra left bits in AndData are stripped. The caller must
5695 either guarantee that Index and the data written is valid, or the caller must
5696 set up exception handlers to catch the exceptions. This function is only
5697 available on IA-32 and x64.
5699 If StartBit is greater than 31, then ASSERT().
5700 If EndBit is greater than 31, then ASSERT().
5701 If EndBit is less than StartBit, then ASSERT().
5702 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5704 @param Index The 32-bit MSR index to write.
5705 @param StartBit The ordinal of the least significant bit in the bit field.
5707 @param EndBit The ordinal of the most significant bit in the bit field.
5709 @param AndData The value to AND with the read value from the MSR.
5711 @return The lower 32-bit of the value written to the MSR.
5716 AsmMsrBitFieldAnd32 (
5724 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
5725 bitwise OR, and writes the result back to the bit field in the
5728 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
5729 bitwise OR between the read result and the value specified by
5730 AndData, and writes the result to the 64-bit MSR specified by Index. The
5731 lower 32-bits of the value written to the MSR are returned. Extra left bits
5732 in both AndData and OrData are stripped. The caller must either guarantee
5733 that Index and the data written is valid, or the caller must set up exception
5734 handlers to catch the exceptions. This function is only available on IA-32
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 AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5741 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5743 @param Index The 32-bit MSR index to write.
5744 @param StartBit The ordinal of the least significant bit in the bit field.
5746 @param EndBit The ordinal of the most significant bit in the bit field.
5748 @param AndData The value to AND with the read value from the MSR.
5749 @param OrData The value to OR with the result of the AND operation.
5751 @return The lower 32-bit of the value written to the MSR.
5756 AsmMsrBitFieldAndThenOr32 (
5765 Returns a 64-bit Machine Specific Register(MSR).
5767 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
5768 performed on Index, and some Index values may cause CPU exceptions. The
5769 caller must either guarantee that Index is valid, or the caller must set up
5770 exception handlers to catch the exceptions. This function is only available
5773 @param Index The 32-bit MSR index to read.
5775 @return The value of the MSR identified by Index.
5785 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
5788 Writes the 64-bit value specified by Value to the MSR specified by Index. The
5789 64-bit value written to the MSR is returned. No parameter checking is
5790 performed on Index or Value, and some of these may cause CPU exceptions. The
5791 caller must either guarantee that Index and Value are valid, or the caller
5792 must establish proper exception handlers. This function is only available on
5795 @param Index The 32-bit MSR index to write.
5796 @param Value The 64-bit value to write to the MSR.
5809 Reads a 64-bit MSR, performs a bitwise OR, and writes the result
5810 back to the 64-bit MSR.
5812 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5813 between the read result and the value specified by OrData, and writes the
5814 result to the 64-bit MSR specified by Index. The value written to the MSR is
5815 returned. No parameter checking is performed on Index or OrData, and some of
5816 these may cause CPU exceptions. The caller must either guarantee that Index
5817 and OrData are valid, or the caller must establish proper exception handlers.
5818 This function is only available on IA-32 and x64.
5820 @param Index The 32-bit MSR index to write.
5821 @param OrData The value to OR with the read value from the MSR.
5823 @return The value written back to the MSR.
5834 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
5837 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5838 read result and the value specified by OrData, and writes the result to the
5839 64-bit MSR specified by Index. The value written to the MSR is returned. No
5840 parameter checking is performed on Index or OrData, and some of these may
5841 cause CPU exceptions. The caller must either guarantee that Index and OrData
5842 are valid, or the caller must establish proper exception handlers. This
5843 function is only available on IA-32 and x64.
5845 @param Index The 32-bit MSR index to write.
5846 @param AndData The value to AND with the read value from the MSR.
5848 @return The value written back to the MSR.
5859 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
5860 OR, and writes the result back to the 64-bit MSR.
5862 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
5863 result and the value specified by AndData, performs a bitwise OR
5864 between the result of the AND operation and the value specified by OrData,
5865 and writes the result to the 64-bit MSR specified by Index. The value written
5866 to the MSR is returned. No parameter checking is performed on Index, AndData,
5867 or OrData, and some of these may cause CPU exceptions. The caller must either
5868 guarantee that Index, AndData, and OrData are valid, or the caller must
5869 establish proper exception handlers. This function is only available on IA-32
5872 @param Index The 32-bit MSR index to write.
5873 @param AndData The value to AND with the read value from the MSR.
5874 @param OrData The value to OR with the result of the AND operation.
5876 @return The value written back to the MSR.
5888 Reads a bit field of an MSR.
5890 Reads the bit field in the 64-bit MSR. The bit field is specified by the
5891 StartBit and the EndBit. The value of the bit field is returned. The caller
5892 must either guarantee that Index is valid, or the caller must set up
5893 exception handlers to catch the exceptions. This function is only available
5896 If StartBit is greater than 63, then ASSERT().
5897 If EndBit is greater than 63, then ASSERT().
5898 If EndBit is less than StartBit, then ASSERT().
5900 @param Index The 32-bit MSR index to read.
5901 @param StartBit The ordinal of the least significant bit in the bit field.
5903 @param EndBit The ordinal of the most significant bit in the bit field.
5906 @return The value read from the MSR.
5911 AsmMsrBitFieldRead64 (
5918 Writes a bit field to an MSR.
5920 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
5921 the StartBit and the EndBit. All other bits in the destination MSR are
5922 preserved. The MSR written is returned. The caller must either guarantee
5923 that Index and the data written is valid, or the caller must set up exception
5924 handlers to catch the exceptions. This function is only available on IA-32 and x64.
5926 If StartBit is greater than 63, then ASSERT().
5927 If EndBit is greater than 63, then ASSERT().
5928 If EndBit is less than StartBit, then ASSERT().
5929 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5931 @param Index The 32-bit MSR index to write.
5932 @param StartBit The ordinal of the least significant bit in the bit field.
5934 @param EndBit The ordinal of the most significant bit in the bit field.
5936 @param Value New value of the bit field.
5938 @return The value written back to the MSR.
5943 AsmMsrBitFieldWrite64 (
5951 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
5952 writes the result back to the bit field in the 64-bit MSR.
5954 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5955 between the read result and the value specified by OrData, and writes the
5956 result to the 64-bit MSR specified by Index. The value written to the MSR is
5957 returned. Extra left bits in OrData are stripped. The caller must either
5958 guarantee that Index and the data written is valid, or the caller must set up
5959 exception handlers to catch the exceptions. This function is only available
5962 If StartBit is greater than 63, then ASSERT().
5963 If EndBit is greater than 63, then ASSERT().
5964 If EndBit is less than StartBit, then ASSERT().
5965 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5967 @param Index The 32-bit MSR index to write.
5968 @param StartBit The ordinal of the least significant bit in the bit field.
5970 @param EndBit The ordinal of the most significant bit in the bit field.
5972 @param OrData The value to OR with the read value from the bit field.
5974 @return The value written back to the MSR.
5979 AsmMsrBitFieldOr64 (
5987 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5988 result back to the bit field in the 64-bit MSR.
5990 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5991 read result and the value specified by AndData, and writes the result to the
5992 64-bit MSR specified by Index. The value written to the MSR is returned.
5993 Extra left bits in AndData are stripped. The caller must either guarantee
5994 that Index and the data written is valid, or the caller must set up exception
5995 handlers to catch the exceptions. This function is only available on IA-32
5998 If StartBit is greater than 63, then ASSERT().
5999 If EndBit is greater than 63, then ASSERT().
6000 If EndBit is less than StartBit, then ASSERT().
6001 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6003 @param Index The 32-bit MSR index to write.
6004 @param StartBit The ordinal of the least significant bit in the bit field.
6006 @param EndBit The ordinal of the most significant bit in the bit field.
6008 @param AndData The value to AND with the read value from the bit field.
6010 @return The value written back to the MSR.
6015 AsmMsrBitFieldAnd64 (
6023 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6024 bitwise OR, and writes the result back to the bit field in the
6027 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6028 a bitwise OR between the read result and the value specified by
6029 AndData, and writes the result to the 64-bit MSR specified by Index. The
6030 value written to the MSR is returned. Extra left bits in both AndData and
6031 OrData are stripped. The caller must either guarantee that Index and the data
6032 written is valid, or the caller must set up exception handlers to catch the
6033 exceptions. This function is only available on IA-32 and x64.
6035 If StartBit is greater than 63, then ASSERT().
6036 If EndBit is greater than 63, then ASSERT().
6037 If EndBit is less than StartBit, then ASSERT().
6038 If AndData is larger than the bitmask value range specified by StartBit and EndBit, 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 AndData The value to AND with the read value from the bit field.
6047 @param OrData The value to OR with the result of the AND operation.
6049 @return The value written back to the MSR.
6054 AsmMsrBitFieldAndThenOr64 (
6063 Reads the current value of the EFLAGS register.
6065 Reads and returns the current value of the EFLAGS register. This function is
6066 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6067 64-bit value on x64.
6069 @return EFLAGS on IA-32 or RFLAGS on x64.
6079 Reads the current value of the Control Register 0 (CR0).
6081 Reads and returns the current value of CR0. This function is only available
6082 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6085 @return The value of the Control Register 0 (CR0).
6095 Reads the current value of the Control Register 2 (CR2).
6097 Reads and returns the current value of CR2. This function is only available
6098 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6101 @return The value of the Control Register 2 (CR2).
6111 Reads the current value of the Control Register 3 (CR3).
6113 Reads and returns the current value of CR3. This function is only available
6114 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6117 @return The value of the Control Register 3 (CR3).
6127 Reads the current value of the Control Register 4 (CR4).
6129 Reads and returns the current value of CR4. This function is only available
6130 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6133 @return The value of the Control Register 4 (CR4).
6143 Writes a value to Control Register 0 (CR0).
6145 Writes and returns a new value to CR0. This function is only available on
6146 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6148 @param Cr0 The value to write to CR0.
6150 @return The value written to CR0.
6160 Writes a value to Control Register 2 (CR2).
6162 Writes and returns a new value to CR2. This function is only available on
6163 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6165 @param Cr2 The value to write to CR2.
6167 @return The value written to CR2.
6177 Writes a value to Control Register 3 (CR3).
6179 Writes and returns a new value to CR3. This function is only available on
6180 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6182 @param Cr3 The value to write to CR3.
6184 @return The value written to CR3.
6194 Writes a value to Control Register 4 (CR4).
6196 Writes and returns a new value to CR4. This function is only available on
6197 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6199 @param Cr4 The value to write to CR4.
6201 @return The value written to CR4.
6211 Reads the current value of Debug Register 0 (DR0).
6213 Reads and returns the current value of DR0. This function is only available
6214 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6217 @return The value of Debug Register 0 (DR0).
6227 Reads the current value of Debug Register 1 (DR1).
6229 Reads and returns the current value of DR1. This function is only available
6230 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6233 @return The value of Debug Register 1 (DR1).
6243 Reads the current value of Debug Register 2 (DR2).
6245 Reads and returns the current value of DR2. This function is only available
6246 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6249 @return The value of Debug Register 2 (DR2).
6259 Reads the current value of Debug Register 3 (DR3).
6261 Reads and returns the current value of DR3. This function is only available
6262 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6265 @return The value of Debug Register 3 (DR3).
6275 Reads the current value of Debug Register 4 (DR4).
6277 Reads and returns the current value of DR4. This function is only available
6278 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6281 @return The value of Debug Register 4 (DR4).
6291 Reads the current value of Debug Register 5 (DR5).
6293 Reads and returns the current value of DR5. This function is only available
6294 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6297 @return The value of Debug Register 5 (DR5).
6307 Reads the current value of Debug Register 6 (DR6).
6309 Reads and returns the current value of DR6. This function is only available
6310 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6313 @return The value of Debug Register 6 (DR6).
6323 Reads the current value of Debug Register 7 (DR7).
6325 Reads and returns the current value of DR7. This function is only available
6326 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6329 @return The value of Debug Register 7 (DR7).
6339 Writes a value to Debug Register 0 (DR0).
6341 Writes and returns a new value to DR0. This function is only available on
6342 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6344 @param Dr0 The value to write to Dr0.
6346 @return The value written to Debug Register 0 (DR0).
6356 Writes a value to Debug Register 1 (DR1).
6358 Writes and returns a new value to DR1. This function is only available on
6359 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6361 @param Dr1 The value to write to Dr1.
6363 @return The value written to Debug Register 1 (DR1).
6373 Writes a value to Debug Register 2 (DR2).
6375 Writes and returns a new value to DR2. This function is only available on
6376 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6378 @param Dr2 The value to write to Dr2.
6380 @return The value written to Debug Register 2 (DR2).
6390 Writes a value to Debug Register 3 (DR3).
6392 Writes and returns a new value to DR3. This function is only available on
6393 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6395 @param Dr3 The value to write to Dr3.
6397 @return The value written to Debug Register 3 (DR3).
6407 Writes a value to Debug Register 4 (DR4).
6409 Writes and returns a new value to DR4. This function is only available on
6410 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6412 @param Dr4 The value to write to Dr4.
6414 @return The value written to Debug Register 4 (DR4).
6424 Writes a value to Debug Register 5 (DR5).
6426 Writes and returns a new value to DR5. This function is only available on
6427 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6429 @param Dr5 The value to write to Dr5.
6431 @return The value written to Debug Register 5 (DR5).
6441 Writes a value to Debug Register 6 (DR6).
6443 Writes and returns a new value to DR6. This function is only available on
6444 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6446 @param Dr6 The value to write to Dr6.
6448 @return The value written to Debug Register 6 (DR6).
6458 Writes a value to Debug Register 7 (DR7).
6460 Writes and returns a new value to DR7. This function is only available on
6461 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6463 @param Dr7 The value to write to Dr7.
6465 @return The value written to Debug Register 7 (DR7).
6475 Reads the current value of Code Segment Register (CS).
6477 Reads and returns the current value of CS. This function is only available on
6480 @return The current value of CS.
6490 Reads the current value of Data Segment Register (DS).
6492 Reads and returns the current value of DS. This function is only available on
6495 @return The current value of DS.
6505 Reads the current value of Extra Segment Register (ES).
6507 Reads and returns the current value of ES. This function is only available on
6510 @return The current value of ES.
6520 Reads the current value of FS Data Segment Register (FS).
6522 Reads and returns the current value of FS. This function is only available on
6525 @return The current value of FS.
6535 Reads the current value of GS Data Segment Register (GS).
6537 Reads and returns the current value of GS. This function is only available on
6540 @return The current value of GS.
6550 Reads the current value of Stack Segment Register (SS).
6552 Reads and returns the current value of SS. This function is only available on
6555 @return The current value of SS.
6565 Reads the current value of Task Register (TR).
6567 Reads and returns the current value of TR. This function is only available on
6570 @return The current value of TR.
6580 Reads the current Global Descriptor Table Register(GDTR) descriptor.
6582 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6583 function is only available on IA-32 and x64.
6585 If Gdtr is NULL, then ASSERT().
6587 @param Gdtr The pointer to a GDTR descriptor.
6593 OUT IA32_DESCRIPTOR
*Gdtr
6597 Writes the current Global Descriptor Table Register (GDTR) descriptor.
6599 Writes and the current GDTR descriptor specified by Gdtr. This function is
6600 only available on IA-32 and x64.
6602 If Gdtr is NULL, then ASSERT().
6604 @param Gdtr The pointer to a GDTR descriptor.
6610 IN CONST IA32_DESCRIPTOR
*Gdtr
6614 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
6616 Reads and returns the current IDTR descriptor and returns it in Idtr. This
6617 function is only available on IA-32 and x64.
6619 If Idtr is NULL, then ASSERT().
6621 @param Idtr The pointer to a IDTR descriptor.
6627 OUT IA32_DESCRIPTOR
*Idtr
6631 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
6633 Writes the current IDTR descriptor and returns it in Idtr. This function is
6634 only available on IA-32 and x64.
6636 If Idtr is NULL, then ASSERT().
6638 @param Idtr The pointer to a IDTR descriptor.
6644 IN CONST IA32_DESCRIPTOR
*Idtr
6648 Reads the current Local Descriptor Table Register(LDTR) selector.
6650 Reads and returns the current 16-bit LDTR descriptor value. This function is
6651 only available on IA-32 and x64.
6653 @return The current selector of LDT.
6663 Writes the current Local Descriptor Table Register (LDTR) selector.
6665 Writes and the current LDTR descriptor specified by Ldtr. This function is
6666 only available on IA-32 and x64.
6668 @param Ldtr 16-bit LDTR selector value.
6678 Save the current floating point/SSE/SSE2 context to a buffer.
6680 Saves the current floating point/SSE/SSE2 state to the buffer specified by
6681 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
6682 available on IA-32 and x64.
6684 If Buffer is NULL, then ASSERT().
6685 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6687 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
6693 OUT IA32_FX_BUFFER
*Buffer
6697 Restores the current floating point/SSE/SSE2 context from a buffer.
6699 Restores the current floating point/SSE/SSE2 state from the buffer specified
6700 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
6701 only available on IA-32 and x64.
6703 If Buffer is NULL, then ASSERT().
6704 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6705 If Buffer was not saved with AsmFxSave(), then ASSERT().
6707 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
6713 IN CONST IA32_FX_BUFFER
*Buffer
6717 Reads the current value of 64-bit MMX Register #0 (MM0).
6719 Reads and returns the current value of MM0. This function is only available
6722 @return The current value of MM0.
6732 Reads the current value of 64-bit MMX Register #1 (MM1).
6734 Reads and returns the current value of MM1. This function is only available
6737 @return The current value of MM1.
6747 Reads the current value of 64-bit MMX Register #2 (MM2).
6749 Reads and returns the current value of MM2. This function is only available
6752 @return The current value of MM2.
6762 Reads the current value of 64-bit MMX Register #3 (MM3).
6764 Reads and returns the current value of MM3. This function is only available
6767 @return The current value of MM3.
6777 Reads the current value of 64-bit MMX Register #4 (MM4).
6779 Reads and returns the current value of MM4. This function is only available
6782 @return The current value of MM4.
6792 Reads the current value of 64-bit MMX Register #5 (MM5).
6794 Reads and returns the current value of MM5. This function is only available
6797 @return The current value of MM5.
6807 Reads the current value of 64-bit MMX Register #6 (MM6).
6809 Reads and returns the current value of MM6. This function is only available
6812 @return The current value of MM6.
6822 Reads the current value of 64-bit MMX Register #7 (MM7).
6824 Reads and returns the current value of MM7. This function is only available
6827 @return The current value of MM7.
6837 Writes the current value of 64-bit MMX Register #0 (MM0).
6839 Writes the current value of MM0. This function is only available on IA32 and
6842 @param Value The 64-bit value to write to MM0.
6852 Writes the current value of 64-bit MMX Register #1 (MM1).
6854 Writes the current value of MM1. This function is only available on IA32 and
6857 @param Value The 64-bit value to write to MM1.
6867 Writes the current value of 64-bit MMX Register #2 (MM2).
6869 Writes the current value of MM2. This function is only available on IA32 and
6872 @param Value The 64-bit value to write to MM2.
6882 Writes the current value of 64-bit MMX Register #3 (MM3).
6884 Writes the current value of MM3. This function is only available on IA32 and
6887 @param Value The 64-bit value to write to MM3.
6897 Writes the current value of 64-bit MMX Register #4 (MM4).
6899 Writes the current value of MM4. This function is only available on IA32 and
6902 @param Value The 64-bit value to write to MM4.
6912 Writes the current value of 64-bit MMX Register #5 (MM5).
6914 Writes the current value of MM5. This function is only available on IA32 and
6917 @param Value The 64-bit value to write to MM5.
6927 Writes the current value of 64-bit MMX Register #6 (MM6).
6929 Writes the current value of MM6. This function is only available on IA32 and
6932 @param Value The 64-bit value to write to MM6.
6942 Writes the current value of 64-bit MMX Register #7 (MM7).
6944 Writes the current value of MM7. This function is only available on IA32 and
6947 @param Value The 64-bit value to write to MM7.
6957 Reads the current value of Time Stamp Counter (TSC).
6959 Reads and returns the current value of TSC. This function is only available
6962 @return The current value of TSC
6972 Reads the current value of a Performance Counter (PMC).
6974 Reads and returns the current value of performance counter specified by
6975 Index. This function is only available on IA-32 and x64.
6977 @param Index The 32-bit Performance Counter index to read.
6979 @return The value of the PMC specified by Index.
6989 Sets up a monitor buffer that is used by AsmMwait().
6991 Executes a MONITOR instruction with the register state specified by Eax, Ecx
6992 and Edx. Returns Eax. This function is only available on IA-32 and x64.
6994 @param Eax The value to load into EAX or RAX before executing the MONITOR
6996 @param Ecx The value to load into ECX or RCX before executing the MONITOR
6998 @param Edx The value to load into EDX or RDX before executing the MONITOR
7013 Executes an MWAIT instruction.
7015 Executes an MWAIT instruction with the register state specified by Eax and
7016 Ecx. Returns Eax. This function is only available on IA-32 and x64.
7018 @param Eax The value to load into EAX or RAX before executing the MONITOR
7020 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7034 Executes a WBINVD instruction.
7036 Executes a WBINVD instruction. This function is only available on IA-32 and
7047 Executes a INVD instruction.
7049 Executes a INVD instruction. This function is only available on IA-32 and
7060 Flushes a cache line from all the instruction and data caches within the
7061 coherency domain of the CPU.
7063 Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7064 This function is only available on IA-32 and x64.
7066 @param LinearAddress The address of the cache line to flush. If the CPU is
7067 in a physical addressing mode, then LinearAddress is a
7068 physical address. If the CPU is in a virtual
7069 addressing mode, then LinearAddress is a virtual
7072 @return LinearAddress.
7077 IN VOID
*LinearAddress
7081 Enables the 32-bit paging mode on the CPU.
7083 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7084 must be properly initialized prior to calling this service. This function
7085 assumes the current execution mode is 32-bit protected mode. This function is
7086 only available on IA-32. After the 32-bit paging mode is enabled, control is
7087 transferred to the function specified by EntryPoint using the new stack
7088 specified by NewStack and passing in the parameters specified by Context1 and
7089 Context2. Context1 and Context2 are optional and may be NULL. The function
7090 EntryPoint must never return.
7092 If the current execution mode is not 32-bit protected mode, then ASSERT().
7093 If EntryPoint is NULL, then ASSERT().
7094 If NewStack is NULL, then ASSERT().
7096 There are a number of constraints that must be followed before calling this
7098 1) Interrupts must be disabled.
7099 2) The caller must be in 32-bit protected mode with flat descriptors. This
7100 means all descriptors must have a base of 0 and a limit of 4GB.
7101 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
7103 4) CR3 must point to valid page tables that will be used once the transition
7104 is complete, and those page tables must guarantee that the pages for this
7105 function and the stack are identity mapped.
7107 @param EntryPoint A pointer to function to call with the new stack after
7109 @param Context1 A pointer to the context to pass into the EntryPoint
7110 function as the first parameter after paging is enabled.
7111 @param Context2 A pointer to the context to pass into the EntryPoint
7112 function as the second parameter after paging is enabled.
7113 @param NewStack A pointer to the new stack to use for the EntryPoint
7114 function after paging is enabled.
7120 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7121 IN VOID
*Context1 OPTIONAL
,
7122 IN VOID
*Context2 OPTIONAL
,
7127 Disables the 32-bit paging mode on the CPU.
7129 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7130 mode. This function assumes the current execution mode is 32-paged protected
7131 mode. This function is only available on IA-32. After the 32-bit paging mode
7132 is disabled, control is transferred to the function specified by EntryPoint
7133 using the new stack specified by NewStack and passing in the parameters
7134 specified by Context1 and Context2. Context1 and Context2 are optional and
7135 may be NULL. The function EntryPoint must never return.
7137 If the current execution mode is not 32-bit paged mode, then ASSERT().
7138 If EntryPoint is NULL, then ASSERT().
7139 If NewStack is NULL, then ASSERT().
7141 There are a number of constraints that must be followed before calling this
7143 1) Interrupts must be disabled.
7144 2) The caller must be in 32-bit paged mode.
7145 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7146 4) CR3 must point to valid page tables that guarantee that the pages for
7147 this function and the stack are identity mapped.
7149 @param EntryPoint A pointer to function to call with the new stack after
7151 @param Context1 A pointer to the context to pass into the EntryPoint
7152 function as the first parameter after paging is disabled.
7153 @param Context2 A pointer to the context to pass into the EntryPoint
7154 function as the second parameter after paging is
7156 @param NewStack A pointer to the new stack to use for the EntryPoint
7157 function after paging is disabled.
7162 AsmDisablePaging32 (
7163 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7164 IN VOID
*Context1 OPTIONAL
,
7165 IN VOID
*Context2 OPTIONAL
,
7170 Enables the 64-bit paging mode on the CPU.
7172 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7173 must be properly initialized prior to calling this service. This function
7174 assumes the current execution mode is 32-bit protected mode with flat
7175 descriptors. This function is only available on IA-32. After the 64-bit
7176 paging mode is enabled, control is transferred to the function specified by
7177 EntryPoint using the new stack specified by NewStack and passing in the
7178 parameters specified by Context1 and Context2. Context1 and Context2 are
7179 optional and may be 0. The function EntryPoint must never return.
7181 If the current execution mode is not 32-bit protected mode with flat
7182 descriptors, then ASSERT().
7183 If EntryPoint is 0, then ASSERT().
7184 If NewStack is 0, then ASSERT().
7186 @param Cs The 16-bit selector to load in the CS before EntryPoint
7187 is called. The descriptor in the GDT that this selector
7188 references must be setup for long mode.
7189 @param EntryPoint The 64-bit virtual address of the function to call with
7190 the new stack after paging is enabled.
7191 @param Context1 The 64-bit virtual address of the context to pass into
7192 the EntryPoint function as the first parameter after
7194 @param Context2 The 64-bit virtual address of the context to pass into
7195 the EntryPoint function as the second parameter after
7197 @param NewStack The 64-bit virtual address of the new stack to use for
7198 the EntryPoint function after paging is enabled.
7205 IN UINT64 EntryPoint
,
7206 IN UINT64 Context1 OPTIONAL
,
7207 IN UINT64 Context2 OPTIONAL
,
7212 Disables the 64-bit paging mode on the CPU.
7214 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7215 mode. This function assumes the current execution mode is 64-paging mode.
7216 This function is only available on x64. After the 64-bit paging mode is
7217 disabled, control is transferred to the function specified by EntryPoint
7218 using the new stack specified by NewStack and passing in the parameters
7219 specified by Context1 and Context2. Context1 and Context2 are optional and
7220 may be 0. The function EntryPoint must never return.
7222 If the current execution mode is not 64-bit paged mode, then ASSERT().
7223 If EntryPoint is 0, then ASSERT().
7224 If NewStack is 0, then ASSERT().
7226 @param Cs The 16-bit selector to load in the CS before EntryPoint
7227 is called. The descriptor in the GDT that this selector
7228 references must be setup for 32-bit protected mode.
7229 @param EntryPoint The 64-bit virtual address of the function to call with
7230 the new stack after paging is disabled.
7231 @param Context1 The 64-bit virtual address of the context to pass into
7232 the EntryPoint function as the first parameter after
7234 @param Context2 The 64-bit virtual address of the context to pass into
7235 the EntryPoint function as the second parameter after
7237 @param NewStack The 64-bit virtual address of the new stack to use for
7238 the EntryPoint function after paging is disabled.
7243 AsmDisablePaging64 (
7245 IN UINT32 EntryPoint
,
7246 IN UINT32 Context1 OPTIONAL
,
7247 IN UINT32 Context2 OPTIONAL
,
7252 // 16-bit thunking services
7256 Retrieves the properties for 16-bit thunk functions.
7258 Computes the size of the buffer and stack below 1MB required to use the
7259 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7260 buffer size is returned in RealModeBufferSize, and the stack size is returned
7261 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7262 then the actual minimum stack size is ExtraStackSize plus the maximum number
7263 of bytes that need to be passed to the 16-bit real mode code.
7265 If RealModeBufferSize is NULL, then ASSERT().
7266 If ExtraStackSize is NULL, then ASSERT().
7268 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
7269 required to use the 16-bit thunk functions.
7270 @param ExtraStackSize A pointer to the extra size of stack below 1MB
7271 that the 16-bit thunk functions require for
7272 temporary storage in the transition to and from
7278 AsmGetThunk16Properties (
7279 OUT UINT32
*RealModeBufferSize
,
7280 OUT UINT32
*ExtraStackSize
7284 Prepares all structures a code required to use AsmThunk16().
7286 Prepares all structures and code required to use AsmThunk16().
7288 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7289 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7291 If ThunkContext is NULL, then ASSERT().
7293 @param ThunkContext A pointer to the context structure that describes the
7294 16-bit real mode code to call.
7300 IN OUT THUNK_CONTEXT
*ThunkContext
7304 Transfers control to a 16-bit real mode entry point and returns the results.
7306 Transfers control to a 16-bit real mode entry point and returns the results.
7307 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7308 This function must be called with interrupts disabled.
7310 The register state from the RealModeState field of ThunkContext is restored just prior
7311 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
7312 which is used to set the interrupt state when a 16-bit real mode entry point is called.
7313 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7314 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
7315 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7316 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7317 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7318 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7319 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7320 after the RETF instruction is executed.
7322 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7323 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7324 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7326 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7327 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7328 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7330 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7331 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7333 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7334 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7335 disable the A20 mask.
7337 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7338 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
7339 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7341 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7342 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7344 If ThunkContext is NULL, then ASSERT().
7345 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7346 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7347 ThunkAttributes, then ASSERT().
7349 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7350 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7352 @param ThunkContext A pointer to the context structure that describes the
7353 16-bit real mode code to call.
7359 IN OUT THUNK_CONTEXT
*ThunkContext
7363 Prepares all structures and code for a 16-bit real mode thunk, transfers
7364 control to a 16-bit real mode entry point, and returns the results.
7366 Prepares all structures and code for a 16-bit real mode thunk, transfers
7367 control to a 16-bit real mode entry point, and returns the results. If the
7368 caller only need to perform a single 16-bit real mode thunk, then this
7369 service should be used. If the caller intends to make more than one 16-bit
7370 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7371 once and AsmThunk16() can be called for each 16-bit real mode thunk.
7373 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7374 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7376 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7378 @param ThunkContext A pointer to the context structure that describes the
7379 16-bit real mode code to call.
7384 AsmPrepareAndThunk16 (
7385 IN OUT THUNK_CONTEXT
*ThunkContext
7389 Generates a 16-bit random number through RDRAND instruction.
7391 if Rand is NULL, then ASSERT().
7393 @param[out] Rand Buffer pointer to store the random result.
7395 @retval TRUE RDRAND call was successful.
7396 @retval FALSE Failed attempts to call RDRAND.
7406 Generates a 32-bit random number through RDRAND instruction.
7408 if Rand is NULL, then ASSERT().
7410 @param[out] Rand Buffer pointer to store the random result.
7412 @retval TRUE RDRAND call was successful.
7413 @retval FALSE Failed attempts to call RDRAND.
7423 Generates a 64-bit random number through RDRAND instruction.
7425 if Rand is NULL, then ASSERT().
7427 @param[out] Rand Buffer pointer to store the random result.
7429 @retval TRUE RDRAND call was successful.
7430 @retval FALSE Failed attempts to call RDRAND.
7440 Load given selector into TR register.
7442 @param[in] Selector Task segment selector
7451 Performs a serializing operation on all load-from-memory instructions that
7452 were issued prior the AsmLfence function.
7454 Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7464 Executes a XGETBV instruction
7466 Executes a XGETBV instruction. This function is only available on IA-32 and
7469 @param[in] Index Extended control register index
7471 @return The current value of the extended control register
7480 Executes a XSETBV instruction to write a 64-bit value to a Extended Control
7481 Register(XCR), and returns the value.
7483 Writes the 64-bit value specified by Value to the XCR specified by Index. The
7484 64-bit value written to the XCR is returned. No parameter checking is
7485 performed on Index or Value, and some of these may cause CPU exceptions. The
7486 caller must either guarantee that Index and Value are valid, or the caller
7487 must establish proper exception handlers. This function is only available on
7490 @param Index The 32-bit XCR index to write.
7491 @param Value The 64-bit value to write to the XCR.
7504 Executes a VMGEXIT instruction (VMMCALL with a REP prefix)
7506 Executes a VMGEXIT instruction. This function is only available on IA-32 and
7517 Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7518 word, dword or qword operand is encoded at the end of the instruction's
7519 binary representation.
7521 This function should be used to update object code that was compiled with
7522 NASM from assembly source code. Example:
7526 mov eax, strict dword 0 ; the imm32 zero operand will be patched
7532 X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7533 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7535 @param[out] InstructionEnd Pointer right past the instruction to patch. The
7536 immediate operand to patch is expected to
7537 comprise the trailing bytes of the instruction.
7538 If InstructionEnd is closer to address 0 than
7539 ValueSize permits, then ASSERT().
7541 @param[in] PatchValue The constant to write to the immediate operand.
7542 The caller is responsible for ensuring that
7543 PatchValue can be represented in the byte, word,
7544 dword or qword operand (as indicated through
7545 ValueSize); otherwise ASSERT().
7547 @param[in] ValueSize The size of the operand in bytes; must be 1, 2,
7548 4, or 8. ASSERT() otherwise.
7552 PatchInstructionX86 (
7553 OUT X86_ASSEMBLY_PATCH_LABEL
*InstructionEnd
,
7554 IN UINT64 PatchValue
,
7558 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7559 #endif // !defined (__BASE_LIB__)