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 // Base Library CPU Functions
4511 Function entry point used when a stack switch is requested with SwitchStack()
4513 @param Context1 Context1 parameter passed into SwitchStack().
4514 @param Context2 Context2 parameter passed into SwitchStack().
4519 (EFIAPI
*SWITCH_STACK_ENTRY_POINT
)(
4520 IN VOID
*Context1 OPTIONAL
,
4521 IN VOID
*Context2 OPTIONAL
4525 Used to serialize load and store operations.
4527 All loads and stores that proceed calls to this function are guaranteed to be
4528 globally visible when this function returns.
4538 Saves the current CPU context that can be restored with a call to LongJump()
4541 Saves the current CPU context in the buffer specified by JumpBuffer and
4542 returns 0. The initial call to SetJump() must always return 0. Subsequent
4543 calls to LongJump() cause a non-zero value to be returned by SetJump().
4545 If JumpBuffer is NULL, then ASSERT().
4546 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4548 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
4549 The same structure must never be used for more than one CPU architecture context.
4550 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
4551 SetJump()/LongJump() is not currently supported for the EBC processor type.
4553 @param JumpBuffer A pointer to CPU context buffer.
4555 @retval 0 Indicates a return from SetJump().
4562 OUT BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
4566 Restores the CPU context that was saved with SetJump().
4568 Restores the CPU context from the buffer specified by JumpBuffer. This
4569 function never returns to the caller. Instead is resumes execution based on
4570 the state of JumpBuffer.
4572 If JumpBuffer is NULL, then ASSERT().
4573 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4574 If Value is 0, then ASSERT().
4576 @param JumpBuffer A pointer to CPU context buffer.
4577 @param Value The value to return when the SetJump() context is
4578 restored and must be non-zero.
4584 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
4589 Enables CPU interrupts.
4599 Disables CPU interrupts.
4609 Disables CPU interrupts and returns the interrupt state prior to the disable
4612 @retval TRUE CPU interrupts were enabled on entry to this call.
4613 @retval FALSE CPU interrupts were disabled on entry to this call.
4618 SaveAndDisableInterrupts (
4623 Enables CPU interrupts for the smallest window required to capture any
4629 EnableDisableInterrupts (
4634 Retrieves the current CPU interrupt state.
4636 Returns TRUE if interrupts are currently enabled. Otherwise
4639 @retval TRUE CPU interrupts are enabled.
4640 @retval FALSE CPU interrupts are disabled.
4650 Set the current CPU interrupt state.
4652 Sets the current CPU interrupt state to the state specified by
4653 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
4654 InterruptState is FALSE, then interrupts are disabled. InterruptState is
4657 @param InterruptState TRUE if interrupts should enabled. FALSE if
4658 interrupts should be disabled.
4660 @return InterruptState
4666 IN BOOLEAN InterruptState
4670 Requests CPU to pause for a short period of time.
4672 Requests CPU to pause for a short period of time. Typically used in MP
4673 systems to prevent memory starvation while waiting for a spin lock.
4683 Transfers control to a function starting with a new stack.
4685 Transfers control to the function specified by EntryPoint using the
4686 new stack specified by NewStack and passing in the parameters specified
4687 by Context1 and Context2. Context1 and Context2 are optional and may
4688 be NULL. The function EntryPoint must never return. This function
4689 supports a variable number of arguments following the NewStack parameter.
4690 These additional arguments are ignored on IA-32, x64, and EBC architectures.
4691 Itanium processors expect one additional parameter of type VOID * that specifies
4692 the new backing store pointer.
4694 If EntryPoint is NULL, then ASSERT().
4695 If NewStack is NULL, then ASSERT().
4697 @param EntryPoint A pointer to function to call with the new stack.
4698 @param Context1 A pointer to the context to pass into the EntryPoint
4700 @param Context2 A pointer to the context to pass into the EntryPoint
4702 @param NewStack A pointer to the new stack to use for the EntryPoint
4704 @param ... This variable argument list is ignored for IA-32, x64, and
4705 EBC architectures. For Itanium processors, this variable
4706 argument list is expected to contain a single parameter of
4707 type VOID * that specifies the new backing store pointer.
4714 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
4715 IN VOID
*Context1 OPTIONAL
,
4716 IN VOID
*Context2 OPTIONAL
,
4722 Generates a breakpoint on the CPU.
4724 Generates a breakpoint on the CPU. The breakpoint must be implemented such
4725 that code can resume normal execution after the breakpoint.
4735 Executes an infinite loop.
4737 Forces the CPU to execute an infinite loop. A debugger may be used to skip
4738 past the loop and the code that follows the loop must execute properly. This
4739 implies that the infinite loop must not cause the code that follow it to be
4750 Uses as a barrier to stop speculative execution.
4752 Ensures that no later instruction will execute speculatively, until all prior
4753 instructions have completed.
4758 SpeculationBarrier (
4762 #if defined (MDE_CPU_X64)
4764 // The page size for the PVALIDATE instruction
4767 PvalidatePageSize4K
= 0,
4768 PvalidatePageSize2MB
,
4769 } PVALIDATE_PAGE_SIZE
;
4772 // PVALIDATE Return Code.
4774 #define PVALIDATE_RET_SUCCESS 0
4775 #define PVALIDATE_RET_FAIL_INPUT 1
4776 #define PVALIDATE_RET_SIZE_MISMATCH 6
4779 // The PVALIDATE instruction did not make any changes to the RMP entry.
4781 #define PVALIDATE_RET_NO_RMPUPDATE 255
4784 Execute a PVALIDATE instruction to validate or to rescinds validation of a guest
4787 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
4789 The function is available on X64.
4791 @param[in] PageSize The page size to use.
4792 @param[in] Validate If TRUE, validate the guest virtual address
4793 otherwise invalidate the guest virtual address.
4794 @param[in] Address The guest virtual address.
4796 @retval PVALIDATE_RET_SUCCESS The PVALIDATE instruction succeeded, and
4797 updated the RMP entry.
4798 @retval PVALIDATE_RET_NO_RMPUPDATE The PVALIDATE instruction succeeded, but
4799 did not update the RMP entry.
4800 @return Failure code from the PVALIDATE
4806 IN PVALIDATE_PAGE_SIZE PageSize
,
4807 IN BOOLEAN Validate
,
4808 IN PHYSICAL_ADDRESS Address
4812 // RDX settings for RMPADJUST
4814 #define RMPADJUST_VMPL_MAX 3
4815 #define RMPADJUST_VMPL_MASK 0xFF
4816 #define RMPADJUST_VMPL_SHIFT 0
4817 #define RMPADJUST_PERMISSION_MASK_MASK 0xFF
4818 #define RMPADJUST_PERMISSION_MASK_SHIFT 8
4819 #define RMPADJUST_VMSA_PAGE_BIT BIT16
4822 Adjusts the permissions of an SEV-SNP guest page.
4824 Executes a RMPADJUST instruction with the register state specified by Rax,
4825 Rcx, and Rdx. Returns Eax. This function is only available on X64.
4827 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
4829 @param[in] Rax The value to load into RAX before executing the RMPADJUST
4831 @param[in] Rcx The value to load into RCX before executing the RMPADJUST
4833 @param[in] Rdx The value to load into RDX before executing the RMPADJUST
4848 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
4850 /// IA32 and x64 Specific Functions.
4851 /// Byte packed structure for 16-bit Real Mode EFLAGS.
4855 UINT32 CF
: 1; ///< Carry Flag.
4856 UINT32 Reserved_0
: 1; ///< Reserved.
4857 UINT32 PF
: 1; ///< Parity Flag.
4858 UINT32 Reserved_1
: 1; ///< Reserved.
4859 UINT32 AF
: 1; ///< Auxiliary Carry Flag.
4860 UINT32 Reserved_2
: 1; ///< Reserved.
4861 UINT32 ZF
: 1; ///< Zero Flag.
4862 UINT32 SF
: 1; ///< Sign Flag.
4863 UINT32 TF
: 1; ///< Trap Flag.
4864 UINT32 IF
: 1; ///< Interrupt Enable Flag.
4865 UINT32 DF
: 1; ///< Direction Flag.
4866 UINT32 OF
: 1; ///< Overflow Flag.
4867 UINT32 IOPL
: 2; ///< I/O Privilege Level.
4868 UINT32 NT
: 1; ///< Nested Task.
4869 UINT32 Reserved_3
: 1; ///< Reserved.
4875 /// Byte packed structure for EFLAGS/RFLAGS.
4876 /// 32-bits on IA-32.
4877 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
4881 UINT32 CF
: 1; ///< Carry Flag.
4882 UINT32 Reserved_0
: 1; ///< Reserved.
4883 UINT32 PF
: 1; ///< Parity Flag.
4884 UINT32 Reserved_1
: 1; ///< Reserved.
4885 UINT32 AF
: 1; ///< Auxiliary Carry Flag.
4886 UINT32 Reserved_2
: 1; ///< Reserved.
4887 UINT32 ZF
: 1; ///< Zero Flag.
4888 UINT32 SF
: 1; ///< Sign Flag.
4889 UINT32 TF
: 1; ///< Trap Flag.
4890 UINT32 IF
: 1; ///< Interrupt Enable Flag.
4891 UINT32 DF
: 1; ///< Direction Flag.
4892 UINT32 OF
: 1; ///< Overflow Flag.
4893 UINT32 IOPL
: 2; ///< I/O Privilege Level.
4894 UINT32 NT
: 1; ///< Nested Task.
4895 UINT32 Reserved_3
: 1; ///< Reserved.
4896 UINT32 RF
: 1; ///< Resume Flag.
4897 UINT32 VM
: 1; ///< Virtual 8086 Mode.
4898 UINT32 AC
: 1; ///< Alignment Check.
4899 UINT32 VIF
: 1; ///< Virtual Interrupt Flag.
4900 UINT32 VIP
: 1; ///< Virtual Interrupt Pending.
4901 UINT32 ID
: 1; ///< ID Flag.
4902 UINT32 Reserved_4
: 10; ///< Reserved.
4908 /// Byte packed structure for Control Register 0 (CR0).
4909 /// 32-bits on IA-32.
4910 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
4914 UINT32 PE
: 1; ///< Protection Enable.
4915 UINT32 MP
: 1; ///< Monitor Coprocessor.
4916 UINT32 EM
: 1; ///< Emulation.
4917 UINT32 TS
: 1; ///< Task Switched.
4918 UINT32 ET
: 1; ///< Extension Type.
4919 UINT32 NE
: 1; ///< Numeric Error.
4920 UINT32 Reserved_0
: 10; ///< Reserved.
4921 UINT32 WP
: 1; ///< Write Protect.
4922 UINT32 Reserved_1
: 1; ///< Reserved.
4923 UINT32 AM
: 1; ///< Alignment Mask.
4924 UINT32 Reserved_2
: 10; ///< Reserved.
4925 UINT32 NW
: 1; ///< Mot Write-through.
4926 UINT32 CD
: 1; ///< Cache Disable.
4927 UINT32 PG
: 1; ///< Paging.
4933 /// Byte packed structure for Control Register 4 (CR4).
4934 /// 32-bits on IA-32.
4935 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
4939 UINT32 VME
: 1; ///< Virtual-8086 Mode Extensions.
4940 UINT32 PVI
: 1; ///< Protected-Mode Virtual Interrupts.
4941 UINT32 TSD
: 1; ///< Time Stamp Disable.
4942 UINT32 DE
: 1; ///< Debugging Extensions.
4943 UINT32 PSE
: 1; ///< Page Size Extensions.
4944 UINT32 PAE
: 1; ///< Physical Address Extension.
4945 UINT32 MCE
: 1; ///< Machine Check Enable.
4946 UINT32 PGE
: 1; ///< Page Global Enable.
4947 UINT32 PCE
: 1; ///< Performance Monitoring Counter
4949 UINT32 OSFXSR
: 1; ///< Operating System Support for
4950 ///< FXSAVE and FXRSTOR instructions
4951 UINT32 OSXMMEXCPT
: 1; ///< Operating System Support for
4952 ///< Unmasked SIMD Floating Point
4954 UINT32 UMIP
: 1; ///< User-Mode Instruction Prevention.
4955 UINT32 LA57
: 1; ///< Linear Address 57bit.
4956 UINT32 VMXE
: 1; ///< VMX Enable.
4957 UINT32 SMXE
: 1; ///< SMX Enable.
4958 UINT32 Reserved_3
: 1; ///< Reserved.
4959 UINT32 FSGSBASE
: 1; ///< FSGSBASE Enable.
4960 UINT32 PCIDE
: 1; ///< PCID Enable.
4961 UINT32 OSXSAVE
: 1; ///< XSAVE and Processor Extended States Enable.
4962 UINT32 Reserved_4
: 1; ///< Reserved.
4963 UINT32 SMEP
: 1; ///< SMEP Enable.
4964 UINT32 SMAP
: 1; ///< SMAP Enable.
4965 UINT32 PKE
: 1; ///< Protection-Key Enable.
4966 UINT32 Reserved_5
: 9; ///< Reserved.
4972 /// Byte packed structure for a segment descriptor in a GDT/LDT.
4976 UINT32 LimitLow
: 16;
4977 UINT32 BaseLow
: 16;
4983 UINT32 LimitHigh
: 4;
4988 UINT32 BaseHigh
: 8;
4991 } IA32_SEGMENT_DESCRIPTOR
;
4994 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5003 #define IA32_IDT_GATE_TYPE_TASK 0x85
5004 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5005 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5006 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5007 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5009 #define IA32_GDT_TYPE_TSS 0x9
5010 #define IA32_GDT_ALIGNMENT 8
5012 #if defined (MDE_CPU_IA32)
5014 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5018 UINT32 OffsetLow
: 16; ///< Offset bits 15..0.
5019 UINT32 Selector
: 16; ///< Selector.
5020 UINT32 Reserved_0
: 8; ///< Reserved.
5021 UINT32 GateType
: 8; ///< Gate Type. See #defines above.
5022 UINT32 OffsetHigh
: 16; ///< Offset bits 31..16.
5025 } IA32_IDT_GATE_DESCRIPTOR
;
5029 // IA32 Task-State Segment Definition
5032 UINT16 PreviousTaskLink
;
5066 UINT16 LDTSegmentSelector
;
5069 UINT16 IOMapBaseAddress
;
5070 } IA32_TASK_STATE_SEGMENT
;
5074 UINT32 LimitLow
: 16; ///< Segment Limit 15..00
5075 UINT32 BaseLow
: 16; ///< Base Address 15..00
5076 UINT32 BaseMid
: 8; ///< Base Address 23..16
5077 UINT32 Type
: 4; ///< Type (1 0 B 1)
5078 UINT32 Reserved_43
: 1; ///< 0
5079 UINT32 DPL
: 2; ///< Descriptor Privilege Level
5080 UINT32 P
: 1; ///< Segment Present
5081 UINT32 LimitHigh
: 4; ///< Segment Limit 19..16
5082 UINT32 AVL
: 1; ///< Available for use by system software
5083 UINT32 Reserved_52
: 2; ///< 0 0
5084 UINT32 G
: 1; ///< Granularity
5085 UINT32 BaseHigh
: 8; ///< Base Address 31..24
5088 } IA32_TSS_DESCRIPTOR
;
5091 #endif // defined (MDE_CPU_IA32)
5093 #if defined (MDE_CPU_X64)
5095 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5099 UINT32 OffsetLow
: 16; ///< Offset bits 15..0.
5100 UINT32 Selector
: 16; ///< Selector.
5101 UINT32 Reserved_0
: 8; ///< Reserved.
5102 UINT32 GateType
: 8; ///< Gate Type. See #defines above.
5103 UINT32 OffsetHigh
: 16; ///< Offset bits 31..16.
5104 UINT32 OffsetUpper
: 32; ///< Offset bits 63..32.
5105 UINT32 Reserved_1
: 32; ///< Reserved.
5111 } IA32_IDT_GATE_DESCRIPTOR
;
5115 // IA32 Task-State Segment Definition
5125 UINT16 Reserved_100
;
5126 UINT16 IOMapBaseAddress
;
5127 } IA32_TASK_STATE_SEGMENT
;
5131 UINT32 LimitLow
: 16; ///< Segment Limit 15..00
5132 UINT32 BaseLow
: 16; ///< Base Address 15..00
5133 UINT32 BaseMidl
: 8; ///< Base Address 23..16
5134 UINT32 Type
: 4; ///< Type (1 0 B 1)
5135 UINT32 Reserved_43
: 1; ///< 0
5136 UINT32 DPL
: 2; ///< Descriptor Privilege Level
5137 UINT32 P
: 1; ///< Segment Present
5138 UINT32 LimitHigh
: 4; ///< Segment Limit 19..16
5139 UINT32 AVL
: 1; ///< Available for use by system software
5140 UINT32 Reserved_52
: 2; ///< 0 0
5141 UINT32 G
: 1; ///< Granularity
5142 UINT32 BaseMidh
: 8; ///< Base Address 31..24
5143 UINT32 BaseHigh
: 32; ///< Base Address 63..32
5144 UINT32 Reserved_96
: 32; ///< Reserved
5150 } IA32_TSS_DESCRIPTOR
;
5153 #endif // defined (MDE_CPU_X64)
5156 /// Byte packed structure for an FP/SSE/SSE2 context.
5163 /// Structures for the 16-bit real mode thunks.
5216 IA32_EFLAGS32 EFLAGS
;
5226 } IA32_REGISTER_SET
;
5229 /// Byte packed structure for an 16-bit real mode thunks.
5232 IA32_REGISTER_SET
*RealModeState
;
5233 VOID
*RealModeBuffer
;
5234 UINT32 RealModeBufferSize
;
5235 UINT32 ThunkAttributes
;
5238 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5239 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5240 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5243 /// Type definition for representing labels in NASM source code that allow for
5244 /// the patching of immediate operands of IA32 and X64 instructions.
5246 /// While the type is technically defined as a function type (note: not a
5247 /// pointer-to-function type), such labels in NASM source code never stand for
5248 /// actual functions, and identifiers declared with this function type should
5249 /// never be called. This is also why the EFIAPI calling convention specifier
5250 /// is missing from the typedef, and why the typedef does not follow the usual
5251 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5252 /// return type and the VOID argument list are merely artifacts.
5254 typedef VOID (X86_ASSEMBLY_PATCH_LABEL
) (
5259 Retrieves CPUID information.
5261 Executes the CPUID instruction with EAX set to the value specified by Index.
5262 This function always returns Index.
5263 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5264 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5265 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5266 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5267 This function is only available on IA-32 and x64.
5269 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5271 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5272 instruction. This is an optional parameter that may be NULL.
5273 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5274 instruction. This is an optional parameter that may be NULL.
5275 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5276 instruction. This is an optional parameter that may be NULL.
5277 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5278 instruction. This is an optional parameter that may be NULL.
5287 OUT UINT32
*Eax OPTIONAL
,
5288 OUT UINT32
*Ebx OPTIONAL
,
5289 OUT UINT32
*Ecx OPTIONAL
,
5290 OUT UINT32
*Edx OPTIONAL
5294 Retrieves CPUID information using an extended leaf identifier.
5296 Executes the CPUID instruction with EAX set to the value specified by Index
5297 and ECX set to the value specified by SubIndex. This function always returns
5298 Index. This function is only available on IA-32 and x64.
5300 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5301 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5302 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5303 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5305 @param Index The 32-bit value to load into EAX prior to invoking the
5307 @param SubIndex The 32-bit value to load into ECX prior to invoking the
5309 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5310 instruction. This is an optional parameter that may be
5312 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5313 instruction. This is an optional parameter that may be
5315 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5316 instruction. This is an optional parameter that may be
5318 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5319 instruction. This is an optional parameter that may be
5330 OUT UINT32
*Eax OPTIONAL
,
5331 OUT UINT32
*Ebx OPTIONAL
,
5332 OUT UINT32
*Ecx OPTIONAL
,
5333 OUT UINT32
*Edx OPTIONAL
5337 Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5339 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5340 and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5350 Perform a WBINVD and clear both the CD and NW bits of CR0.
5352 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5353 bits of CR0 to 0. This function is only available on IA-32 and x64.
5363 Returns the lower 32-bits of a Machine Specific Register(MSR).
5365 Reads and returns the lower 32-bits of the MSR specified by Index.
5366 No parameter checking is performed on Index, and some Index values may cause
5367 CPU exceptions. The caller must either guarantee that Index is valid, or the
5368 caller must set up exception handlers to catch the exceptions. This function
5369 is only available on IA-32 and x64.
5371 @param Index The 32-bit MSR index to read.
5373 @return The lower 32 bits of the MSR identified by Index.
5383 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5384 The upper 32-bits of the MSR are set to zero.
5386 Writes the 32-bit value specified by Value to the MSR specified by Index. The
5387 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5388 the MSR is returned. No parameter checking is performed on Index or Value,
5389 and some of these may cause CPU exceptions. The caller must either guarantee
5390 that Index and Value are valid, or the caller must establish proper exception
5391 handlers. This function is only available on IA-32 and x64.
5393 @param Index The 32-bit MSR index to write.
5394 @param Value The 32-bit value to write to the MSR.
5407 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5408 writes the result back to the 64-bit MSR.
5410 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5411 between the lower 32-bits of the read result and the value specified by
5412 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5413 32-bits of the value written to the MSR is returned. No parameter checking is
5414 performed on Index or OrData, and some of these may cause CPU exceptions. The
5415 caller must either guarantee that Index and OrData are valid, or the caller
5416 must establish proper exception handlers. This function is only available on
5419 @param Index The 32-bit MSR index to write.
5420 @param OrData The value to OR with the read value from the MSR.
5422 @return The lower 32-bit value written to the MSR.
5433 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5434 the result back to the 64-bit MSR.
5436 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5437 lower 32-bits of the read result and the value specified by AndData, and
5438 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5439 the value written to the MSR is returned. No parameter checking is performed
5440 on Index or AndData, and some of these may cause CPU exceptions. The caller
5441 must either guarantee that Index and AndData are valid, or the caller must
5442 establish proper exception handlers. This function is only available on IA-32
5445 @param Index The 32-bit MSR index to write.
5446 @param AndData The value to AND with the read value from the MSR.
5448 @return The lower 32-bit value written to the MSR.
5459 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5460 on the lower 32-bits, and writes the result back to the 64-bit MSR.
5462 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5463 lower 32-bits of the read result and the value specified by AndData
5464 preserving the upper 32-bits, performs a bitwise OR between the
5465 result of the AND operation and the value specified by OrData, and writes the
5466 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5467 written to the MSR is returned. No parameter checking is performed on Index,
5468 AndData, or OrData, and some of these may cause CPU exceptions. The caller
5469 must either guarantee that Index, AndData, and OrData are valid, or the
5470 caller must establish proper exception handlers. This function is only
5471 available on IA-32 and x64.
5473 @param Index The 32-bit MSR index to write.
5474 @param AndData The value to AND with the read value from the MSR.
5475 @param OrData The value to OR with the result of the AND operation.
5477 @return The lower 32-bit value written to the MSR.
5489 Reads a bit field of an MSR.
5491 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5492 specified by the StartBit and the EndBit. The value of the bit field is
5493 returned. The caller must either guarantee that Index is valid, or the caller
5494 must set up exception handlers to catch the exceptions. This function is only
5495 available on IA-32 and x64.
5497 If StartBit is greater than 31, then ASSERT().
5498 If EndBit is greater than 31, then ASSERT().
5499 If EndBit is less than StartBit, then ASSERT().
5501 @param Index The 32-bit MSR index to read.
5502 @param StartBit The ordinal of the least significant bit in the bit field.
5504 @param EndBit The ordinal of the most significant bit in the bit field.
5507 @return The bit field read from the MSR.
5512 AsmMsrBitFieldRead32 (
5519 Writes a bit field to an MSR.
5521 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5522 field is specified by the StartBit and the EndBit. All other bits in the
5523 destination MSR are preserved. The lower 32-bits of the MSR written is
5524 returned. The caller must either guarantee that Index and the data written
5525 is valid, or the caller must set up exception handlers to catch the exceptions.
5526 This function is only available on IA-32 and x64.
5528 If StartBit is greater than 31, then ASSERT().
5529 If EndBit is greater than 31, then ASSERT().
5530 If EndBit is less than StartBit, then ASSERT().
5531 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5533 @param Index The 32-bit MSR index to write.
5534 @param StartBit The ordinal of the least significant bit in the bit field.
5536 @param EndBit The ordinal of the most significant bit in the bit field.
5538 @param Value New value of the bit field.
5540 @return The lower 32-bit of the value written to the MSR.
5545 AsmMsrBitFieldWrite32 (
5553 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5554 result back to the bit field in the 64-bit MSR.
5556 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5557 between the read result and the value specified by OrData, and writes the
5558 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
5559 written to the MSR are returned. Extra left bits in OrData are stripped. The
5560 caller must either guarantee that Index and the data written is valid, or
5561 the caller must set up exception handlers to catch the exceptions. This
5562 function is only available on IA-32 and x64.
5564 If StartBit is greater than 31, then ASSERT().
5565 If EndBit is greater than 31, then ASSERT().
5566 If EndBit is less than StartBit, then ASSERT().
5567 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5569 @param Index The 32-bit MSR index to write.
5570 @param StartBit The ordinal of the least significant bit in the bit field.
5572 @param EndBit The ordinal of the most significant bit in the bit field.
5574 @param OrData The value to OR with the read value from the MSR.
5576 @return The lower 32-bit of the value written to the MSR.
5581 AsmMsrBitFieldOr32 (
5589 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5590 result back to the bit field in the 64-bit MSR.
5592 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5593 read result and the value specified by AndData, and writes the result to the
5594 64-bit MSR specified by Index. The lower 32-bits of the value written to the
5595 MSR are returned. Extra left bits in AndData are stripped. The caller must
5596 either guarantee that Index and the data written is valid, or the caller must
5597 set up exception handlers to catch the exceptions. This function is only
5598 available on IA-32 and x64.
5600 If StartBit is greater than 31, then ASSERT().
5601 If EndBit is greater than 31, then ASSERT().
5602 If EndBit is less than StartBit, then ASSERT().
5603 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5605 @param Index The 32-bit MSR index to write.
5606 @param StartBit The ordinal of the least significant bit in the bit field.
5608 @param EndBit The ordinal of the most significant bit in the bit field.
5610 @param AndData The value to AND with the read value from the MSR.
5612 @return The lower 32-bit of the value written to the MSR.
5617 AsmMsrBitFieldAnd32 (
5625 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
5626 bitwise OR, and writes the result back to the bit field in the
5629 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
5630 bitwise OR between the read result and the value specified by
5631 AndData, and writes the result to the 64-bit MSR specified by Index. The
5632 lower 32-bits of the value written to the MSR are returned. Extra left bits
5633 in both AndData and OrData are stripped. The caller must either guarantee
5634 that Index and the data written is valid, or the caller must set up exception
5635 handlers to catch the exceptions. This function is only available on IA-32
5638 If StartBit is greater than 31, then ASSERT().
5639 If EndBit is greater than 31, then ASSERT().
5640 If EndBit is less than StartBit, then ASSERT().
5641 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5642 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5644 @param Index The 32-bit MSR index to write.
5645 @param StartBit The ordinal of the least significant bit in the bit field.
5647 @param EndBit The ordinal of the most significant bit in the bit field.
5649 @param AndData The value to AND with the read value from the MSR.
5650 @param OrData The value to OR with the result of the AND operation.
5652 @return The lower 32-bit of the value written to the MSR.
5657 AsmMsrBitFieldAndThenOr32 (
5666 Returns a 64-bit Machine Specific Register(MSR).
5668 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
5669 performed on Index, and some Index values may cause CPU exceptions. The
5670 caller must either guarantee that Index is valid, or the caller must set up
5671 exception handlers to catch the exceptions. This function is only available
5674 @param Index The 32-bit MSR index to read.
5676 @return The value of the MSR identified by Index.
5686 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
5689 Writes the 64-bit value specified by Value to the MSR specified by Index. The
5690 64-bit value written to the MSR is returned. No parameter checking is
5691 performed on Index or Value, and some of these may cause CPU exceptions. The
5692 caller must either guarantee that Index and Value are valid, or the caller
5693 must establish proper exception handlers. This function is only available on
5696 @param Index The 32-bit MSR index to write.
5697 @param Value The 64-bit value to write to the MSR.
5710 Reads a 64-bit MSR, performs a bitwise OR, and writes the result
5711 back to the 64-bit MSR.
5713 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5714 between the read result and the value specified by OrData, and writes the
5715 result to the 64-bit MSR specified by Index. The value written to the MSR is
5716 returned. No parameter checking is performed on Index or OrData, and some of
5717 these may cause CPU exceptions. The caller must either guarantee that Index
5718 and OrData are valid, or the caller must establish proper exception handlers.
5719 This function is only available on IA-32 and x64.
5721 @param Index The 32-bit MSR index to write.
5722 @param OrData The value to OR with the read value from the MSR.
5724 @return The value written back to the MSR.
5735 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
5738 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5739 read result and the value specified by OrData, and writes the result to the
5740 64-bit MSR specified by Index. The value written to the MSR is returned. No
5741 parameter checking is performed on Index or OrData, and some of these may
5742 cause CPU exceptions. The caller must either guarantee that Index and OrData
5743 are valid, or the caller must establish proper exception handlers. This
5744 function is only available on IA-32 and x64.
5746 @param Index The 32-bit MSR index to write.
5747 @param AndData The value to AND with the read value from the MSR.
5749 @return The value written back to the MSR.
5760 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
5761 OR, and writes the result back to the 64-bit MSR.
5763 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
5764 result and the value specified by AndData, performs a bitwise OR
5765 between the result of the AND operation and the value specified by OrData,
5766 and writes the result to the 64-bit MSR specified by Index. The value written
5767 to the MSR is returned. No parameter checking is performed on Index, AndData,
5768 or OrData, and some of these may cause CPU exceptions. The caller must either
5769 guarantee that Index, AndData, and OrData are valid, or the caller must
5770 establish proper exception handlers. This function is only available on IA-32
5773 @param Index The 32-bit MSR index to write.
5774 @param AndData The value to AND with the read value from the MSR.
5775 @param OrData The value to OR with the result of the AND operation.
5777 @return The value written back to the MSR.
5789 Reads a bit field of an MSR.
5791 Reads the bit field in the 64-bit MSR. The bit field is specified by the
5792 StartBit and the EndBit. The value of the bit field is returned. The caller
5793 must either guarantee that Index is valid, or the caller must set up
5794 exception handlers to catch the exceptions. This function is only available
5797 If StartBit is greater than 63, then ASSERT().
5798 If EndBit is greater than 63, then ASSERT().
5799 If EndBit is less than StartBit, then ASSERT().
5801 @param Index The 32-bit MSR index to read.
5802 @param StartBit The ordinal of the least significant bit in the bit field.
5804 @param EndBit The ordinal of the most significant bit in the bit field.
5807 @return The value read from the MSR.
5812 AsmMsrBitFieldRead64 (
5819 Writes a bit field to an MSR.
5821 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
5822 the StartBit and the EndBit. All other bits in the destination MSR are
5823 preserved. The MSR written is returned. The caller must either guarantee
5824 that Index and the data written is valid, or the caller must set up exception
5825 handlers to catch the exceptions. This function is only available on IA-32 and x64.
5827 If StartBit is greater than 63, then ASSERT().
5828 If EndBit is greater than 63, then ASSERT().
5829 If EndBit is less than StartBit, then ASSERT().
5830 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5832 @param Index The 32-bit MSR index to write.
5833 @param StartBit The ordinal of the least significant bit in the bit field.
5835 @param EndBit The ordinal of the most significant bit in the bit field.
5837 @param Value New value of the bit field.
5839 @return The value written back to the MSR.
5844 AsmMsrBitFieldWrite64 (
5852 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
5853 writes the result back to the bit field in the 64-bit MSR.
5855 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5856 between the read result and the value specified by OrData, and writes the
5857 result to the 64-bit MSR specified by Index. The value written to the MSR is
5858 returned. Extra left bits in OrData are stripped. The caller must either
5859 guarantee that Index and the data written is valid, or the caller must set up
5860 exception handlers to catch the exceptions. This function is only available
5863 If StartBit is greater than 63, then ASSERT().
5864 If EndBit is greater than 63, then ASSERT().
5865 If EndBit is less than StartBit, then ASSERT().
5866 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5868 @param Index The 32-bit MSR index to write.
5869 @param StartBit The ordinal of the least significant bit in the bit field.
5871 @param EndBit The ordinal of the most significant bit in the bit field.
5873 @param OrData The value to OR with the read value from the bit field.
5875 @return The value written back to the MSR.
5880 AsmMsrBitFieldOr64 (
5888 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5889 result back to the bit field in the 64-bit MSR.
5891 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5892 read result and the value specified by AndData, and writes the result to the
5893 64-bit MSR specified by Index. The value written to the MSR is returned.
5894 Extra left bits in AndData are stripped. The caller must either guarantee
5895 that Index and the data written is valid, or the caller must set up exception
5896 handlers to catch the exceptions. This function is only available on IA-32
5899 If StartBit is greater than 63, then ASSERT().
5900 If EndBit is greater than 63, then ASSERT().
5901 If EndBit is less than StartBit, then ASSERT().
5902 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5904 @param Index The 32-bit MSR index to write.
5905 @param StartBit The ordinal of the least significant bit in the bit field.
5907 @param EndBit The ordinal of the most significant bit in the bit field.
5909 @param AndData The value to AND with the read value from the bit field.
5911 @return The value written back to the MSR.
5916 AsmMsrBitFieldAnd64 (
5924 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
5925 bitwise OR, and writes the result back to the bit field in the
5928 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
5929 a bitwise OR between the read result and the value specified by
5930 AndData, and writes the result to the 64-bit MSR specified by Index. The
5931 value written to the MSR is returned. Extra left bits in both AndData and
5932 OrData are stripped. The caller must either guarantee that Index and the data
5933 written is valid, or the caller must set up exception handlers to catch the
5934 exceptions. This function is only available on IA-32 and x64.
5936 If StartBit is greater than 63, then ASSERT().
5937 If EndBit is greater than 63, then ASSERT().
5938 If EndBit is less than StartBit, then ASSERT().
5939 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5940 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5942 @param Index The 32-bit MSR index to write.
5943 @param StartBit The ordinal of the least significant bit in the bit field.
5945 @param EndBit The ordinal of the most significant bit in the bit field.
5947 @param AndData The value to AND with the read value from the bit field.
5948 @param OrData The value to OR with the result of the AND operation.
5950 @return The value written back to the MSR.
5955 AsmMsrBitFieldAndThenOr64 (
5964 Reads the current value of the EFLAGS register.
5966 Reads and returns the current value of the EFLAGS register. This function is
5967 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
5968 64-bit value on x64.
5970 @return EFLAGS on IA-32 or RFLAGS on x64.
5980 Reads the current value of the Control Register 0 (CR0).
5982 Reads and returns the current value of CR0. This function is only available
5983 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
5986 @return The value of the Control Register 0 (CR0).
5996 Reads the current value of the Control Register 2 (CR2).
5998 Reads and returns the current value of CR2. This function is only available
5999 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6002 @return The value of the Control Register 2 (CR2).
6012 Reads the current value of the Control Register 3 (CR3).
6014 Reads and returns the current value of CR3. This function is only available
6015 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6018 @return The value of the Control Register 3 (CR3).
6028 Reads the current value of the Control Register 4 (CR4).
6030 Reads and returns the current value of CR4. This function is only available
6031 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6034 @return The value of the Control Register 4 (CR4).
6044 Writes a value to Control Register 0 (CR0).
6046 Writes and returns a new value to CR0. This function is only available on
6047 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6049 @param Cr0 The value to write to CR0.
6051 @return The value written to CR0.
6061 Writes a value to Control Register 2 (CR2).
6063 Writes and returns a new value to CR2. This function is only available on
6064 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6066 @param Cr2 The value to write to CR2.
6068 @return The value written to CR2.
6078 Writes a value to Control Register 3 (CR3).
6080 Writes and returns a new value to CR3. This function is only available on
6081 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6083 @param Cr3 The value to write to CR3.
6085 @return The value written to CR3.
6095 Writes a value to Control Register 4 (CR4).
6097 Writes and returns a new value to CR4. This function is only available on
6098 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6100 @param Cr4 The value to write to CR4.
6102 @return The value written to CR4.
6112 Reads the current value of Debug Register 0 (DR0).
6114 Reads and returns the current value of DR0. This function is only available
6115 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6118 @return The value of Debug Register 0 (DR0).
6128 Reads the current value of Debug Register 1 (DR1).
6130 Reads and returns the current value of DR1. This function is only available
6131 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6134 @return The value of Debug Register 1 (DR1).
6144 Reads the current value of Debug Register 2 (DR2).
6146 Reads and returns the current value of DR2. This function is only available
6147 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6150 @return The value of Debug Register 2 (DR2).
6160 Reads the current value of Debug Register 3 (DR3).
6162 Reads and returns the current value of DR3. This function is only available
6163 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6166 @return The value of Debug Register 3 (DR3).
6176 Reads the current value of Debug Register 4 (DR4).
6178 Reads and returns the current value of DR4. This function is only available
6179 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6182 @return The value of Debug Register 4 (DR4).
6192 Reads the current value of Debug Register 5 (DR5).
6194 Reads and returns the current value of DR5. This function is only available
6195 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6198 @return The value of Debug Register 5 (DR5).
6208 Reads the current value of Debug Register 6 (DR6).
6210 Reads and returns the current value of DR6. This function is only available
6211 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6214 @return The value of Debug Register 6 (DR6).
6224 Reads the current value of Debug Register 7 (DR7).
6226 Reads and returns the current value of DR7. This function is only available
6227 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6230 @return The value of Debug Register 7 (DR7).
6240 Writes a value to Debug Register 0 (DR0).
6242 Writes and returns a new value to DR0. This function is only available on
6243 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6245 @param Dr0 The value to write to Dr0.
6247 @return The value written to Debug Register 0 (DR0).
6257 Writes a value to Debug Register 1 (DR1).
6259 Writes and returns a new value to DR1. This function is only available on
6260 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6262 @param Dr1 The value to write to Dr1.
6264 @return The value written to Debug Register 1 (DR1).
6274 Writes a value to Debug Register 2 (DR2).
6276 Writes and returns a new value to DR2. This function is only available on
6277 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6279 @param Dr2 The value to write to Dr2.
6281 @return The value written to Debug Register 2 (DR2).
6291 Writes a value to Debug Register 3 (DR3).
6293 Writes and returns a new value to DR3. This function is only available on
6294 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6296 @param Dr3 The value to write to Dr3.
6298 @return The value written to Debug Register 3 (DR3).
6308 Writes a value to Debug Register 4 (DR4).
6310 Writes and returns a new value to DR4. This function is only available on
6311 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6313 @param Dr4 The value to write to Dr4.
6315 @return The value written to Debug Register 4 (DR4).
6325 Writes a value to Debug Register 5 (DR5).
6327 Writes and returns a new value to DR5. This function is only available on
6328 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6330 @param Dr5 The value to write to Dr5.
6332 @return The value written to Debug Register 5 (DR5).
6342 Writes a value to Debug Register 6 (DR6).
6344 Writes and returns a new value to DR6. This function is only available on
6345 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6347 @param Dr6 The value to write to Dr6.
6349 @return The value written to Debug Register 6 (DR6).
6359 Writes a value to Debug Register 7 (DR7).
6361 Writes and returns a new value to DR7. This function is only available on
6362 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6364 @param Dr7 The value to write to Dr7.
6366 @return The value written to Debug Register 7 (DR7).
6376 Reads the current value of Code Segment Register (CS).
6378 Reads and returns the current value of CS. This function is only available on
6381 @return The current value of CS.
6391 Reads the current value of Data Segment Register (DS).
6393 Reads and returns the current value of DS. This function is only available on
6396 @return The current value of DS.
6406 Reads the current value of Extra Segment Register (ES).
6408 Reads and returns the current value of ES. This function is only available on
6411 @return The current value of ES.
6421 Reads the current value of FS Data Segment Register (FS).
6423 Reads and returns the current value of FS. This function is only available on
6426 @return The current value of FS.
6436 Reads the current value of GS Data Segment Register (GS).
6438 Reads and returns the current value of GS. This function is only available on
6441 @return The current value of GS.
6451 Reads the current value of Stack Segment Register (SS).
6453 Reads and returns the current value of SS. This function is only available on
6456 @return The current value of SS.
6466 Reads the current value of Task Register (TR).
6468 Reads and returns the current value of TR. This function is only available on
6471 @return The current value of TR.
6481 Reads the current Global Descriptor Table Register(GDTR) descriptor.
6483 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6484 function is only available on IA-32 and x64.
6486 If Gdtr is NULL, then ASSERT().
6488 @param Gdtr The pointer to a GDTR descriptor.
6494 OUT IA32_DESCRIPTOR
*Gdtr
6498 Writes the current Global Descriptor Table Register (GDTR) descriptor.
6500 Writes and the current GDTR descriptor specified by Gdtr. This function is
6501 only available on IA-32 and x64.
6503 If Gdtr is NULL, then ASSERT().
6505 @param Gdtr The pointer to a GDTR descriptor.
6511 IN CONST IA32_DESCRIPTOR
*Gdtr
6515 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
6517 Reads and returns the current IDTR descriptor and returns it in Idtr. This
6518 function is only available on IA-32 and x64.
6520 If Idtr is NULL, then ASSERT().
6522 @param Idtr The pointer to a IDTR descriptor.
6528 OUT IA32_DESCRIPTOR
*Idtr
6532 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
6534 Writes the current IDTR descriptor and returns it in Idtr. This function is
6535 only available on IA-32 and x64.
6537 If Idtr is NULL, then ASSERT().
6539 @param Idtr The pointer to a IDTR descriptor.
6545 IN CONST IA32_DESCRIPTOR
*Idtr
6549 Reads the current Local Descriptor Table Register(LDTR) selector.
6551 Reads and returns the current 16-bit LDTR descriptor value. This function is
6552 only available on IA-32 and x64.
6554 @return The current selector of LDT.
6564 Writes the current Local Descriptor Table Register (LDTR) selector.
6566 Writes and the current LDTR descriptor specified by Ldtr. This function is
6567 only available on IA-32 and x64.
6569 @param Ldtr 16-bit LDTR selector value.
6579 Save the current floating point/SSE/SSE2 context to a buffer.
6581 Saves the current floating point/SSE/SSE2 state to the buffer specified by
6582 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
6583 available on IA-32 and x64.
6585 If Buffer is NULL, then ASSERT().
6586 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6588 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
6594 OUT IA32_FX_BUFFER
*Buffer
6598 Restores the current floating point/SSE/SSE2 context from a buffer.
6600 Restores the current floating point/SSE/SSE2 state from the buffer specified
6601 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
6602 only available on IA-32 and x64.
6604 If Buffer is NULL, then ASSERT().
6605 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6606 If Buffer was not saved with AsmFxSave(), then ASSERT().
6608 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
6614 IN CONST IA32_FX_BUFFER
*Buffer
6618 Reads the current value of 64-bit MMX Register #0 (MM0).
6620 Reads and returns the current value of MM0. This function is only available
6623 @return The current value of MM0.
6633 Reads the current value of 64-bit MMX Register #1 (MM1).
6635 Reads and returns the current value of MM1. This function is only available
6638 @return The current value of MM1.
6648 Reads the current value of 64-bit MMX Register #2 (MM2).
6650 Reads and returns the current value of MM2. This function is only available
6653 @return The current value of MM2.
6663 Reads the current value of 64-bit MMX Register #3 (MM3).
6665 Reads and returns the current value of MM3. This function is only available
6668 @return The current value of MM3.
6678 Reads the current value of 64-bit MMX Register #4 (MM4).
6680 Reads and returns the current value of MM4. This function is only available
6683 @return The current value of MM4.
6693 Reads the current value of 64-bit MMX Register #5 (MM5).
6695 Reads and returns the current value of MM5. This function is only available
6698 @return The current value of MM5.
6708 Reads the current value of 64-bit MMX Register #6 (MM6).
6710 Reads and returns the current value of MM6. This function is only available
6713 @return The current value of MM6.
6723 Reads the current value of 64-bit MMX Register #7 (MM7).
6725 Reads and returns the current value of MM7. This function is only available
6728 @return The current value of MM7.
6738 Writes the current value of 64-bit MMX Register #0 (MM0).
6740 Writes the current value of MM0. This function is only available on IA32 and
6743 @param Value The 64-bit value to write to MM0.
6753 Writes the current value of 64-bit MMX Register #1 (MM1).
6755 Writes the current value of MM1. This function is only available on IA32 and
6758 @param Value The 64-bit value to write to MM1.
6768 Writes the current value of 64-bit MMX Register #2 (MM2).
6770 Writes the current value of MM2. This function is only available on IA32 and
6773 @param Value The 64-bit value to write to MM2.
6783 Writes the current value of 64-bit MMX Register #3 (MM3).
6785 Writes the current value of MM3. This function is only available on IA32 and
6788 @param Value The 64-bit value to write to MM3.
6798 Writes the current value of 64-bit MMX Register #4 (MM4).
6800 Writes the current value of MM4. This function is only available on IA32 and
6803 @param Value The 64-bit value to write to MM4.
6813 Writes the current value of 64-bit MMX Register #5 (MM5).
6815 Writes the current value of MM5. This function is only available on IA32 and
6818 @param Value The 64-bit value to write to MM5.
6828 Writes the current value of 64-bit MMX Register #6 (MM6).
6830 Writes the current value of MM6. This function is only available on IA32 and
6833 @param Value The 64-bit value to write to MM6.
6843 Writes the current value of 64-bit MMX Register #7 (MM7).
6845 Writes the current value of MM7. This function is only available on IA32 and
6848 @param Value The 64-bit value to write to MM7.
6858 Reads the current value of Time Stamp Counter (TSC).
6860 Reads and returns the current value of TSC. This function is only available
6863 @return The current value of TSC
6873 Reads the current value of a Performance Counter (PMC).
6875 Reads and returns the current value of performance counter specified by
6876 Index. This function is only available on IA-32 and x64.
6878 @param Index The 32-bit Performance Counter index to read.
6880 @return The value of the PMC specified by Index.
6890 Sets up a monitor buffer that is used by AsmMwait().
6892 Executes a MONITOR instruction with the register state specified by Eax, Ecx
6893 and Edx. Returns Eax. This function is only available on IA-32 and x64.
6895 @param Eax The value to load into EAX or RAX before executing the MONITOR
6897 @param Ecx The value to load into ECX or RCX before executing the MONITOR
6899 @param Edx The value to load into EDX or RDX before executing the MONITOR
6914 Executes an MWAIT instruction.
6916 Executes an MWAIT instruction with the register state specified by Eax and
6917 Ecx. Returns Eax. This function is only available on IA-32 and x64.
6919 @param Eax The value to load into EAX or RAX before executing the MONITOR
6921 @param Ecx The value to load into ECX or RCX before executing the MONITOR
6935 Executes a WBINVD instruction.
6937 Executes a WBINVD instruction. This function is only available on IA-32 and
6948 Executes a INVD instruction.
6950 Executes a INVD instruction. This function is only available on IA-32 and
6961 Flushes a cache line from all the instruction and data caches within the
6962 coherency domain of the CPU.
6964 Flushed the cache line specified by LinearAddress, and returns LinearAddress.
6965 This function is only available on IA-32 and x64.
6967 @param LinearAddress The address of the cache line to flush. If the CPU is
6968 in a physical addressing mode, then LinearAddress is a
6969 physical address. If the CPU is in a virtual
6970 addressing mode, then LinearAddress is a virtual
6973 @return LinearAddress.
6978 IN VOID
*LinearAddress
6982 Enables the 32-bit paging mode on the CPU.
6984 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
6985 must be properly initialized prior to calling this service. This function
6986 assumes the current execution mode is 32-bit protected mode. This function is
6987 only available on IA-32. After the 32-bit paging mode is enabled, control is
6988 transferred to the function specified by EntryPoint using the new stack
6989 specified by NewStack and passing in the parameters specified by Context1 and
6990 Context2. Context1 and Context2 are optional and may be NULL. The function
6991 EntryPoint must never return.
6993 If the current execution mode is not 32-bit protected mode, then ASSERT().
6994 If EntryPoint is NULL, then ASSERT().
6995 If NewStack is NULL, then ASSERT().
6997 There are a number of constraints that must be followed before calling this
6999 1) Interrupts must be disabled.
7000 2) The caller must be in 32-bit protected mode with flat descriptors. This
7001 means all descriptors must have a base of 0 and a limit of 4GB.
7002 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
7004 4) CR3 must point to valid page tables that will be used once the transition
7005 is complete, and those page tables must guarantee that the pages for this
7006 function and the stack are identity mapped.
7008 @param EntryPoint A pointer to function to call with the new stack after
7010 @param Context1 A pointer to the context to pass into the EntryPoint
7011 function as the first parameter after paging is enabled.
7012 @param Context2 A pointer to the context to pass into the EntryPoint
7013 function as the second parameter after paging is enabled.
7014 @param NewStack A pointer to the new stack to use for the EntryPoint
7015 function after paging is enabled.
7021 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7022 IN VOID
*Context1 OPTIONAL
,
7023 IN VOID
*Context2 OPTIONAL
,
7028 Disables the 32-bit paging mode on the CPU.
7030 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7031 mode. This function assumes the current execution mode is 32-paged protected
7032 mode. This function is only available on IA-32. After the 32-bit paging mode
7033 is disabled, control is transferred to the function specified by EntryPoint
7034 using the new stack specified by NewStack and passing in the parameters
7035 specified by Context1 and Context2. Context1 and Context2 are optional and
7036 may be NULL. The function EntryPoint must never return.
7038 If the current execution mode is not 32-bit paged mode, then ASSERT().
7039 If EntryPoint is NULL, then ASSERT().
7040 If NewStack is NULL, then ASSERT().
7042 There are a number of constraints that must be followed before calling this
7044 1) Interrupts must be disabled.
7045 2) The caller must be in 32-bit paged mode.
7046 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7047 4) CR3 must point to valid page tables that guarantee that the pages for
7048 this function and the stack are identity mapped.
7050 @param EntryPoint A pointer to function to call with the new stack after
7052 @param Context1 A pointer to the context to pass into the EntryPoint
7053 function as the first parameter after paging is disabled.
7054 @param Context2 A pointer to the context to pass into the EntryPoint
7055 function as the second parameter after paging is
7057 @param NewStack A pointer to the new stack to use for the EntryPoint
7058 function after paging is disabled.
7063 AsmDisablePaging32 (
7064 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7065 IN VOID
*Context1 OPTIONAL
,
7066 IN VOID
*Context2 OPTIONAL
,
7071 Enables the 64-bit paging mode on the CPU.
7073 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7074 must be properly initialized prior to calling this service. This function
7075 assumes the current execution mode is 32-bit protected mode with flat
7076 descriptors. This function is only available on IA-32. After the 64-bit
7077 paging mode is enabled, control is transferred to the function specified by
7078 EntryPoint using the new stack specified by NewStack and passing in the
7079 parameters specified by Context1 and Context2. Context1 and Context2 are
7080 optional and may be 0. The function EntryPoint must never return.
7082 If the current execution mode is not 32-bit protected mode with flat
7083 descriptors, then ASSERT().
7084 If EntryPoint is 0, then ASSERT().
7085 If NewStack is 0, then ASSERT().
7087 @param Cs The 16-bit selector to load in the CS before EntryPoint
7088 is called. The descriptor in the GDT that this selector
7089 references must be setup for long mode.
7090 @param EntryPoint The 64-bit virtual address of the function to call with
7091 the new stack after paging is enabled.
7092 @param Context1 The 64-bit virtual address of the context to pass into
7093 the EntryPoint function as the first parameter after
7095 @param Context2 The 64-bit virtual address of the context to pass into
7096 the EntryPoint function as the second parameter after
7098 @param NewStack The 64-bit virtual address of the new stack to use for
7099 the EntryPoint function after paging is enabled.
7106 IN UINT64 EntryPoint
,
7107 IN UINT64 Context1 OPTIONAL
,
7108 IN UINT64 Context2 OPTIONAL
,
7113 Disables the 64-bit paging mode on the CPU.
7115 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7116 mode. This function assumes the current execution mode is 64-paging mode.
7117 This function is only available on x64. After the 64-bit paging mode is
7118 disabled, control is transferred to the function specified by EntryPoint
7119 using the new stack specified by NewStack and passing in the parameters
7120 specified by Context1 and Context2. Context1 and Context2 are optional and
7121 may be 0. The function EntryPoint must never return.
7123 If the current execution mode is not 64-bit paged mode, then ASSERT().
7124 If EntryPoint is 0, then ASSERT().
7125 If NewStack is 0, then ASSERT().
7127 @param Cs The 16-bit selector to load in the CS before EntryPoint
7128 is called. The descriptor in the GDT that this selector
7129 references must be setup for 32-bit protected mode.
7130 @param EntryPoint The 64-bit virtual address of the function to call with
7131 the new stack after paging is disabled.
7132 @param Context1 The 64-bit virtual address of the context to pass into
7133 the EntryPoint function as the first parameter after
7135 @param Context2 The 64-bit virtual address of the context to pass into
7136 the EntryPoint function as the second parameter after
7138 @param NewStack The 64-bit virtual address of the new stack to use for
7139 the EntryPoint function after paging is disabled.
7144 AsmDisablePaging64 (
7146 IN UINT32 EntryPoint
,
7147 IN UINT32 Context1 OPTIONAL
,
7148 IN UINT32 Context2 OPTIONAL
,
7153 // 16-bit thunking services
7157 Retrieves the properties for 16-bit thunk functions.
7159 Computes the size of the buffer and stack below 1MB required to use the
7160 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7161 buffer size is returned in RealModeBufferSize, and the stack size is returned
7162 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7163 then the actual minimum stack size is ExtraStackSize plus the maximum number
7164 of bytes that need to be passed to the 16-bit real mode code.
7166 If RealModeBufferSize is NULL, then ASSERT().
7167 If ExtraStackSize is NULL, then ASSERT().
7169 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
7170 required to use the 16-bit thunk functions.
7171 @param ExtraStackSize A pointer to the extra size of stack below 1MB
7172 that the 16-bit thunk functions require for
7173 temporary storage in the transition to and from
7179 AsmGetThunk16Properties (
7180 OUT UINT32
*RealModeBufferSize
,
7181 OUT UINT32
*ExtraStackSize
7185 Prepares all structures a code required to use AsmThunk16().
7187 Prepares all structures and code required to use AsmThunk16().
7189 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7190 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7192 If ThunkContext is NULL, then ASSERT().
7194 @param ThunkContext A pointer to the context structure that describes the
7195 16-bit real mode code to call.
7201 IN OUT THUNK_CONTEXT
*ThunkContext
7205 Transfers control to a 16-bit real mode entry point and returns the results.
7207 Transfers control to a 16-bit real mode entry point and returns the results.
7208 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7209 This function must be called with interrupts disabled.
7211 The register state from the RealModeState field of ThunkContext is restored just prior
7212 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
7213 which is used to set the interrupt state when a 16-bit real mode entry point is called.
7214 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7215 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
7216 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7217 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7218 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7219 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7220 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7221 after the RETF instruction is executed.
7223 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7224 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7225 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7227 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7228 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7229 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7231 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7232 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7234 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7235 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7236 disable the A20 mask.
7238 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7239 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
7240 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7242 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7243 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7245 If ThunkContext is NULL, then ASSERT().
7246 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7247 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7248 ThunkAttributes, then ASSERT().
7250 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7251 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7253 @param ThunkContext A pointer to the context structure that describes the
7254 16-bit real mode code to call.
7260 IN OUT THUNK_CONTEXT
*ThunkContext
7264 Prepares all structures and code for a 16-bit real mode thunk, transfers
7265 control to a 16-bit real mode entry point, and returns the results.
7267 Prepares all structures and code for a 16-bit real mode thunk, transfers
7268 control to a 16-bit real mode entry point, and returns the results. If the
7269 caller only need to perform a single 16-bit real mode thunk, then this
7270 service should be used. If the caller intends to make more than one 16-bit
7271 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7272 once and AsmThunk16() can be called for each 16-bit real mode thunk.
7274 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7275 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7277 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7279 @param ThunkContext A pointer to the context structure that describes the
7280 16-bit real mode code to call.
7285 AsmPrepareAndThunk16 (
7286 IN OUT THUNK_CONTEXT
*ThunkContext
7290 Generates a 16-bit random number through RDRAND instruction.
7292 if Rand is NULL, then ASSERT().
7294 @param[out] Rand Buffer pointer to store the random result.
7296 @retval TRUE RDRAND call was successful.
7297 @retval FALSE Failed attempts to call RDRAND.
7307 Generates a 32-bit random number through RDRAND instruction.
7309 if Rand is NULL, then ASSERT().
7311 @param[out] Rand Buffer pointer to store the random result.
7313 @retval TRUE RDRAND call was successful.
7314 @retval FALSE Failed attempts to call RDRAND.
7324 Generates a 64-bit random number through RDRAND instruction.
7326 if Rand is NULL, then ASSERT().
7328 @param[out] Rand Buffer pointer to store the random result.
7330 @retval TRUE RDRAND call was successful.
7331 @retval FALSE Failed attempts to call RDRAND.
7341 Load given selector into TR register.
7343 @param[in] Selector Task segment selector
7352 Performs a serializing operation on all load-from-memory instructions that
7353 were issued prior the AsmLfence function.
7355 Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7365 Executes a XGETBV instruction
7367 Executes a XGETBV instruction. This function is only available on IA-32 and
7370 @param[in] Index Extended control register index
7372 @return The current value of the extended control register
7381 Executes a XSETBV instruction to write a 64-bit value to a Extended Control
7382 Register(XCR), and returns the value.
7384 Writes the 64-bit value specified by Value to the XCR specified by Index. The
7385 64-bit value written to the XCR is returned. No parameter checking is
7386 performed on Index or Value, and some of these may cause CPU exceptions. The
7387 caller must either guarantee that Index and Value are valid, or the caller
7388 must establish proper exception handlers. This function is only available on
7391 @param Index The 32-bit XCR index to write.
7392 @param Value The 64-bit value to write to the XCR.
7405 Executes a VMGEXIT instruction (VMMCALL with a REP prefix)
7407 Executes a VMGEXIT instruction. This function is only available on IA-32 and
7418 Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7419 word, dword or qword operand is encoded at the end of the instruction's
7420 binary representation.
7422 This function should be used to update object code that was compiled with
7423 NASM from assembly source code. Example:
7427 mov eax, strict dword 0 ; the imm32 zero operand will be patched
7433 X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7434 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7436 @param[out] InstructionEnd Pointer right past the instruction to patch. The
7437 immediate operand to patch is expected to
7438 comprise the trailing bytes of the instruction.
7439 If InstructionEnd is closer to address 0 than
7440 ValueSize permits, then ASSERT().
7442 @param[in] PatchValue The constant to write to the immediate operand.
7443 The caller is responsible for ensuring that
7444 PatchValue can be represented in the byte, word,
7445 dword or qword operand (as indicated through
7446 ValueSize); otherwise ASSERT().
7448 @param[in] ValueSize The size of the operand in bytes; must be 1, 2,
7449 4, or 8. ASSERT() otherwise.
7453 PatchInstructionX86 (
7454 OUT X86_ASSEMBLY_PATCH_LABEL
*InstructionEnd
,
7455 IN UINT64 PatchValue
,
7459 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7460 #endif // !defined (__BASE_LIB__)