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)
161 Returns the length of a Null-terminated Unicode string.
163 This function is similar as strlen_s defined in C11.
165 If String is not aligned on a 16-bit boundary, then ASSERT().
167 @param String A pointer to a Null-terminated Unicode string.
168 @param MaxSize The maximum number of Destination Unicode
169 char, including terminating null char.
171 @retval 0 If String is NULL.
172 @retval MaxSize If there is no null character in the first MaxSize characters of String.
173 @return The number of characters that percede the terminating null character.
179 IN CONST CHAR16
*String
,
184 Returns the size of a Null-terminated Unicode string in bytes, including the
187 This function returns the size of the Null-terminated Unicode string
188 specified by String in bytes, including the Null terminator.
190 If String is not aligned on a 16-bit boundary, then ASSERT().
192 @param String A pointer to a Null-terminated Unicode string.
193 @param MaxSize The maximum number of Destination Unicode
194 char, including the Null terminator.
196 @retval 0 If String is NULL.
197 @retval (sizeof (CHAR16) * (MaxSize + 1))
198 If there is no Null terminator in the first MaxSize characters of
200 @return The size of the Null-terminated Unicode string in bytes, including
207 IN CONST CHAR16
*String
,
212 Copies the string pointed to by Source (including the terminating null char)
213 to the array pointed to by Destination.
215 This function is similar as strcpy_s defined in C11.
217 If Destination is not aligned on a 16-bit boundary, then ASSERT().
218 If Source is not aligned on a 16-bit boundary, then ASSERT().
220 If an error is returned, then the Destination is unmodified.
222 @param Destination A pointer to a Null-terminated Unicode string.
223 @param DestMax The maximum number of Destination Unicode
224 char, including terminating null char.
225 @param Source A pointer to a Null-terminated Unicode string.
227 @retval RETURN_SUCCESS String is copied.
228 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
229 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
231 If PcdMaximumUnicodeStringLength is not zero,
232 and DestMax is greater than
233 PcdMaximumUnicodeStringLength.
235 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
240 OUT CHAR16
*Destination
,
242 IN CONST CHAR16
*Source
246 Copies not more than Length successive char from the string pointed to by
247 Source to the array pointed to by Destination. If no null char is copied from
248 Source, then Destination[Length] is always set to null.
250 This function is similar as strncpy_s defined in C11.
252 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
253 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
255 If an error is returned, then the Destination is unmodified.
257 @param Destination A pointer to a Null-terminated Unicode string.
258 @param DestMax The maximum number of Destination Unicode
259 char, including terminating null char.
260 @param Source A pointer to a Null-terminated Unicode string.
261 @param Length The maximum number of Unicode characters to copy.
263 @retval RETURN_SUCCESS String is copied.
264 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
265 MIN(StrLen(Source), Length).
266 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
268 If PcdMaximumUnicodeStringLength is not zero,
269 and DestMax is greater than
270 PcdMaximumUnicodeStringLength.
272 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
277 OUT CHAR16
*Destination
,
279 IN CONST CHAR16
*Source
,
284 Appends a copy of the string pointed to by Source (including the terminating
285 null char) to the end of the string pointed to by Destination.
287 This function is similar as strcat_s defined in C11.
289 If Destination is not aligned on a 16-bit boundary, then ASSERT().
290 If Source is not aligned on a 16-bit boundary, then ASSERT().
292 If an error is returned, then the Destination is unmodified.
294 @param Destination A pointer to a Null-terminated Unicode string.
295 @param DestMax The maximum number of Destination Unicode
296 char, including terminating null char.
297 @param Source A pointer to a Null-terminated Unicode string.
299 @retval RETURN_SUCCESS String is appended.
300 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
302 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
303 greater than StrLen(Source).
304 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
306 If PcdMaximumUnicodeStringLength is not zero,
307 and DestMax is greater than
308 PcdMaximumUnicodeStringLength.
310 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
315 IN OUT CHAR16
*Destination
,
317 IN CONST CHAR16
*Source
321 Appends not more than Length successive char from the string pointed to by
322 Source to the end of the string pointed to by Destination. If no null char is
323 copied from Source, then Destination[StrLen(Destination) + Length] is always
326 This function is similar as strncat_s defined in C11.
328 If Destination is not aligned on a 16-bit boundary, then ASSERT().
329 If Source is not aligned on a 16-bit boundary, then ASSERT().
331 If an error is returned, then the Destination is unmodified.
333 @param Destination A pointer to a Null-terminated Unicode string.
334 @param DestMax The maximum number of Destination Unicode
335 char, including terminating null char.
336 @param Source A pointer to a Null-terminated Unicode string.
337 @param Length The maximum number of Unicode characters to copy.
339 @retval RETURN_SUCCESS String is appended.
340 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
342 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
343 greater than MIN(StrLen(Source), Length).
344 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
346 If PcdMaximumUnicodeStringLength is not zero,
347 and DestMax is greater than
348 PcdMaximumUnicodeStringLength.
350 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
355 IN OUT CHAR16
*Destination
,
357 IN CONST CHAR16
*Source
,
362 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
364 This function outputs a value of type UINTN by interpreting the contents of
365 the Unicode string specified by String as a decimal number. The format of the
366 input Unicode string String is:
368 [spaces] [decimal digits].
370 The valid decimal digit character is in the range [0-9]. The function will
371 ignore the pad space, which includes spaces or tab characters, before
372 [decimal digits]. The running zero in the beginning of [decimal digits] will
373 be ignored. Then, the function stops at the first character that is a not a
374 valid decimal character or a Null-terminator, whichever one comes first.
376 If String is not aligned in a 16-bit boundary, then ASSERT().
378 If String has no valid decimal digits in the above format, then 0 is stored
379 at the location pointed to by Data.
380 If the number represented by String exceeds the range defined by UINTN, then
381 MAX_UINTN is stored at the location pointed to by Data.
383 If EndPointer is not NULL, a pointer to the character that stopped the scan
384 is stored at the location pointed to by EndPointer. If String has no valid
385 decimal digits right after the optional pad spaces, the value of String is
386 stored at the location pointed to by EndPointer.
388 @param String Pointer to a Null-terminated Unicode string.
389 @param EndPointer Pointer to character that stops scan.
390 @param Data Pointer to the converted value.
392 @retval RETURN_SUCCESS Value is translated from String.
393 @retval RETURN_INVALID_PARAMETER If String is NULL.
395 If PcdMaximumUnicodeStringLength is not
396 zero, and String contains more than
397 PcdMaximumUnicodeStringLength Unicode
398 characters, not including the
400 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
401 the range defined by UINTN.
407 IN CONST CHAR16
*String
,
408 OUT CHAR16
**EndPointer OPTIONAL
,
413 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
415 This function outputs a value of type UINT64 by interpreting the contents of
416 the Unicode string specified by String as a decimal number. The format of the
417 input Unicode string String is:
419 [spaces] [decimal digits].
421 The valid decimal digit character is in the range [0-9]. The function will
422 ignore the pad space, which includes spaces or tab characters, before
423 [decimal digits]. The running zero in the beginning of [decimal digits] will
424 be ignored. Then, the function stops at the first character that is a not a
425 valid decimal character or a Null-terminator, whichever one comes first.
427 If String is not aligned in a 16-bit boundary, then ASSERT().
429 If String has no valid decimal digits in the above format, then 0 is stored
430 at the location pointed to by Data.
431 If the number represented by String exceeds the range defined by UINT64, then
432 MAX_UINT64 is stored at the location pointed to by Data.
434 If EndPointer is not NULL, a pointer to the character that stopped the scan
435 is stored at the location pointed to by EndPointer. If String has no valid
436 decimal digits right after the optional pad spaces, the value of String is
437 stored at the location pointed to by EndPointer.
439 @param String Pointer to a Null-terminated Unicode string.
440 @param EndPointer Pointer to character that stops scan.
441 @param Data Pointer to the converted value.
443 @retval RETURN_SUCCESS Value is translated from String.
444 @retval RETURN_INVALID_PARAMETER If String is NULL.
446 If PcdMaximumUnicodeStringLength is not
447 zero, and String contains more than
448 PcdMaximumUnicodeStringLength Unicode
449 characters, not including the
451 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
452 the range defined by UINT64.
457 StrDecimalToUint64S (
458 IN CONST CHAR16
*String
,
459 OUT CHAR16
**EndPointer OPTIONAL
,
464 Convert a Null-terminated Unicode hexadecimal string to a value of type
467 This function outputs a value of type UINTN by interpreting the contents of
468 the Unicode string specified by String as a hexadecimal number. The format of
469 the input Unicode string String is:
471 [spaces][zeros][x][hexadecimal digits].
473 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
474 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
475 If "x" appears in the input string, it must be prefixed with at least one 0.
476 The function will ignore the pad space, which includes spaces or tab
477 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
478 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
479 after [x] or the first valid hexadecimal digit. Then, the function stops at
480 the first character that is a not a valid hexadecimal character or NULL,
481 whichever one comes first.
483 If String is not aligned in a 16-bit boundary, then ASSERT().
485 If String has no valid hexadecimal digits in the above format, then 0 is
486 stored at the location pointed to by Data.
487 If the number represented by String exceeds the range defined by UINTN, then
488 MAX_UINTN is stored at the location pointed to by Data.
490 If EndPointer is not NULL, a pointer to the character that stopped the scan
491 is stored at the location pointed to by EndPointer. If String has no valid
492 hexadecimal digits right after the optional pad spaces, the value of String
493 is stored at the location pointed to by EndPointer.
495 @param String Pointer to a Null-terminated Unicode string.
496 @param EndPointer Pointer to character that stops scan.
497 @param Data Pointer to the converted value.
499 @retval RETURN_SUCCESS Value is translated from String.
500 @retval RETURN_INVALID_PARAMETER If String is NULL.
502 If PcdMaximumUnicodeStringLength is not
503 zero, and String contains more than
504 PcdMaximumUnicodeStringLength Unicode
505 characters, not including the
507 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
508 the range defined by UINTN.
514 IN CONST CHAR16
*String
,
515 OUT CHAR16
**EndPointer OPTIONAL
,
520 Convert a Null-terminated Unicode hexadecimal string to a value of type
523 This function outputs a value of type UINT64 by interpreting the contents of
524 the Unicode string specified by String as a hexadecimal number. The format of
525 the input Unicode string String is:
527 [spaces][zeros][x][hexadecimal digits].
529 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
530 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
531 If "x" appears in the input string, it must be prefixed with at least one 0.
532 The function will ignore the pad space, which includes spaces or tab
533 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
534 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
535 after [x] or the first valid hexadecimal digit. Then, the function stops at
536 the first character that is a not a valid hexadecimal character or NULL,
537 whichever one comes first.
539 If String is not aligned in a 16-bit boundary, then ASSERT().
541 If String has no valid hexadecimal digits in the above format, then 0 is
542 stored at the location pointed to by Data.
543 If the number represented by String exceeds the range defined by UINT64, then
544 MAX_UINT64 is stored at the location pointed to by Data.
546 If EndPointer is not NULL, a pointer to the character that stopped the scan
547 is stored at the location pointed to by EndPointer. If String has no valid
548 hexadecimal digits right after the optional pad spaces, the value of String
549 is stored at the location pointed to by EndPointer.
551 @param String Pointer to a Null-terminated Unicode string.
552 @param EndPointer Pointer to character that stops scan.
553 @param Data Pointer to the converted value.
555 @retval RETURN_SUCCESS Value is translated from String.
556 @retval RETURN_INVALID_PARAMETER If String is NULL.
558 If PcdMaximumUnicodeStringLength is not
559 zero, and String contains more than
560 PcdMaximumUnicodeStringLength Unicode
561 characters, not including the
563 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
564 the range defined by UINT64.
570 IN CONST CHAR16
*String
,
571 OUT CHAR16
**EndPointer OPTIONAL
,
576 Returns the length of a Null-terminated Ascii string.
578 This function is similar as strlen_s defined in C11.
580 @param String A pointer to a Null-terminated Ascii string.
581 @param MaxSize The maximum number of Destination Ascii
582 char, including terminating null char.
584 @retval 0 If String is NULL.
585 @retval MaxSize If there is no null character in the first MaxSize characters of String.
586 @return The number of characters that percede the terminating null character.
592 IN CONST CHAR8
*String
,
597 Returns the size of a Null-terminated Ascii string in bytes, including the
600 This function returns the size of the Null-terminated Ascii string specified
601 by String in bytes, including the Null terminator.
603 @param String A pointer to a Null-terminated Ascii string.
604 @param MaxSize The maximum number of Destination Ascii
605 char, including the Null terminator.
607 @retval 0 If String is NULL.
608 @retval (sizeof (CHAR8) * (MaxSize + 1))
609 If there is no Null terminator in the first MaxSize characters of
611 @return The size of the Null-terminated Ascii string in bytes, including the
618 IN CONST CHAR8
*String
,
623 Copies the string pointed to by Source (including the terminating null char)
624 to the array pointed to by Destination.
626 This function is similar as strcpy_s defined in C11.
628 If an error is returned, then the Destination is unmodified.
630 @param Destination A pointer to a Null-terminated Ascii string.
631 @param DestMax The maximum number of Destination Ascii
632 char, including terminating null char.
633 @param Source A pointer to a Null-terminated Ascii string.
635 @retval RETURN_SUCCESS String is copied.
636 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
637 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
639 If PcdMaximumAsciiStringLength is not zero,
640 and DestMax is greater than
641 PcdMaximumAsciiStringLength.
643 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
648 OUT CHAR8
*Destination
,
650 IN CONST CHAR8
*Source
654 Copies not more than Length successive char from the string pointed to by
655 Source to the array pointed to by Destination. If no null char is copied from
656 Source, then Destination[Length] is always set to null.
658 This function is similar as strncpy_s defined in C11.
660 If an error is returned, then the Destination is unmodified.
662 @param Destination A pointer to a Null-terminated Ascii string.
663 @param DestMax The maximum number of Destination Ascii
664 char, including terminating null char.
665 @param Source A pointer to a Null-terminated Ascii string.
666 @param Length The maximum number of Ascii characters to copy.
668 @retval RETURN_SUCCESS String is copied.
669 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
670 MIN(StrLen(Source), Length).
671 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
673 If PcdMaximumAsciiStringLength is not zero,
674 and DestMax is greater than
675 PcdMaximumAsciiStringLength.
677 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
682 OUT CHAR8
*Destination
,
684 IN CONST CHAR8
*Source
,
689 Appends a copy of the string pointed to by Source (including the terminating
690 null char) to the end of the string pointed to by Destination.
692 This function is similar as strcat_s defined in C11.
694 If an error is returned, then the Destination is unmodified.
696 @param Destination A pointer to a Null-terminated Ascii string.
697 @param DestMax The maximum number of Destination Ascii
698 char, including terminating null char.
699 @param Source A pointer to a Null-terminated Ascii string.
701 @retval RETURN_SUCCESS String is appended.
702 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
704 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
705 greater than StrLen(Source).
706 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
708 If PcdMaximumAsciiStringLength is not zero,
709 and DestMax is greater than
710 PcdMaximumAsciiStringLength.
712 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
717 IN OUT CHAR8
*Destination
,
719 IN CONST CHAR8
*Source
723 Appends not more than Length successive char from the string pointed to by
724 Source to the end of the string pointed to by Destination. If no null char is
725 copied from Source, then Destination[StrLen(Destination) + Length] is always
728 This function is similar as strncat_s defined in C11.
730 If an error is returned, then the Destination is unmodified.
732 @param Destination A pointer to a Null-terminated Ascii string.
733 @param DestMax The maximum number of Destination Ascii
734 char, including terminating null char.
735 @param Source A pointer to a Null-terminated Ascii string.
736 @param Length The maximum number of Ascii characters to copy.
738 @retval RETURN_SUCCESS String is appended.
739 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
741 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
742 greater than MIN(StrLen(Source), Length).
743 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
745 If PcdMaximumAsciiStringLength is not zero,
746 and DestMax is greater than
747 PcdMaximumAsciiStringLength.
749 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
754 IN OUT CHAR8
*Destination
,
756 IN CONST CHAR8
*Source
,
761 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
763 This function outputs a value of type UINTN by interpreting the contents of
764 the Ascii string specified by String as a decimal number. The format of the
765 input Ascii string String is:
767 [spaces] [decimal digits].
769 The valid decimal digit character is in the range [0-9]. The function will
770 ignore the pad space, which includes spaces or tab characters, before
771 [decimal digits]. The running zero in the beginning of [decimal digits] will
772 be ignored. Then, the function stops at the first character that is a not a
773 valid decimal character or a Null-terminator, whichever one comes first.
775 If String has no valid decimal digits in the above format, then 0 is stored
776 at the location pointed to by Data.
777 If the number represented by String exceeds the range defined by UINTN, then
778 MAX_UINTN is stored at the location pointed to by Data.
780 If EndPointer is not NULL, a pointer to the character that stopped the scan
781 is stored at the location pointed to by EndPointer. If String has no valid
782 decimal digits right after the optional pad spaces, the value of String is
783 stored at the location pointed to by EndPointer.
785 @param String Pointer to a Null-terminated Ascii string.
786 @param EndPointer Pointer to character that stops scan.
787 @param Data Pointer to the converted value.
789 @retval RETURN_SUCCESS Value is translated from String.
790 @retval RETURN_INVALID_PARAMETER If String is NULL.
792 If PcdMaximumAsciiStringLength is not zero,
793 and String contains more than
794 PcdMaximumAsciiStringLength Ascii
795 characters, not including the
797 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
798 the range defined by UINTN.
803 AsciiStrDecimalToUintnS (
804 IN CONST CHAR8
*String
,
805 OUT CHAR8
**EndPointer OPTIONAL
,
810 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
812 This function outputs a value of type UINT64 by interpreting the contents of
813 the Ascii string specified by String as a decimal number. The format of the
814 input Ascii string String is:
816 [spaces] [decimal digits].
818 The valid decimal digit character is in the range [0-9]. The function will
819 ignore the pad space, which includes spaces or tab characters, before
820 [decimal digits]. The running zero in the beginning of [decimal digits] will
821 be ignored. Then, the function stops at the first character that is a not a
822 valid decimal character or a Null-terminator, whichever one comes first.
824 If String has no valid decimal digits in the above format, then 0 is stored
825 at the location pointed to by Data.
826 If the number represented by String exceeds the range defined by UINT64, then
827 MAX_UINT64 is stored at the location pointed to by Data.
829 If EndPointer is not NULL, a pointer to the character that stopped the scan
830 is stored at the location pointed to by EndPointer. If String has no valid
831 decimal digits right after the optional pad spaces, the value of String is
832 stored at the location pointed to by EndPointer.
834 @param String Pointer to a Null-terminated Ascii string.
835 @param EndPointer Pointer to character that stops scan.
836 @param Data Pointer to the converted value.
838 @retval RETURN_SUCCESS Value is translated from String.
839 @retval RETURN_INVALID_PARAMETER If String is NULL.
841 If PcdMaximumAsciiStringLength is not zero,
842 and String contains more than
843 PcdMaximumAsciiStringLength Ascii
844 characters, not including the
846 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
847 the range defined by UINT64.
852 AsciiStrDecimalToUint64S (
853 IN CONST CHAR8
*String
,
854 OUT CHAR8
**EndPointer OPTIONAL
,
859 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
861 This function outputs a value of type UINTN by interpreting the contents of
862 the Ascii string specified by String as a hexadecimal number. The format of
863 the input Ascii string String is:
865 [spaces][zeros][x][hexadecimal digits].
867 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
868 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
869 "x" appears in the input string, it must be prefixed with at least one 0. The
870 function will ignore the pad space, which includes spaces or tab characters,
871 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
872 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
873 the first valid hexadecimal digit. Then, the function stops at the first
874 character that is a not a valid hexadecimal character or Null-terminator,
875 whichever on comes first.
877 If String has no valid hexadecimal digits in the above format, then 0 is
878 stored at the location pointed to by Data.
879 If the number represented by String exceeds the range defined by UINTN, then
880 MAX_UINTN is stored at the location pointed to by Data.
882 If EndPointer is not NULL, a pointer to the character that stopped the scan
883 is stored at the location pointed to by EndPointer. If String has no valid
884 hexadecimal digits right after the optional pad spaces, the value of String
885 is stored at the location pointed to by EndPointer.
887 @param String Pointer to a Null-terminated Ascii string.
888 @param EndPointer Pointer to character that stops scan.
889 @param Data Pointer to the converted value.
891 @retval RETURN_SUCCESS Value is translated from String.
892 @retval RETURN_INVALID_PARAMETER If String is NULL.
894 If PcdMaximumAsciiStringLength is not zero,
895 and String contains more than
896 PcdMaximumAsciiStringLength Ascii
897 characters, not including the
899 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
900 the range defined by UINTN.
905 AsciiStrHexToUintnS (
906 IN CONST CHAR8
*String
,
907 OUT CHAR8
**EndPointer OPTIONAL
,
912 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
914 This function outputs a value of type UINT64 by interpreting the contents of
915 the Ascii string specified by String as a hexadecimal number. The format of
916 the input Ascii string String is:
918 [spaces][zeros][x][hexadecimal digits].
920 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
921 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
922 "x" appears in the input string, it must be prefixed with at least one 0. The
923 function will ignore the pad space, which includes spaces or tab characters,
924 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
925 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
926 the first valid hexadecimal digit. Then, the function stops at the first
927 character that is a not a valid hexadecimal character or Null-terminator,
928 whichever on comes first.
930 If String has no valid hexadecimal digits in the above format, then 0 is
931 stored at the location pointed to by Data.
932 If the number represented by String exceeds the range defined by UINT64, then
933 MAX_UINT64 is stored at the location pointed to by Data.
935 If EndPointer is not NULL, a pointer to the character that stopped the scan
936 is stored at the location pointed to by EndPointer. If String has no valid
937 hexadecimal digits right after the optional pad spaces, the value of String
938 is stored at the location pointed to by EndPointer.
940 @param String Pointer to a Null-terminated Ascii string.
941 @param EndPointer Pointer to character that stops scan.
942 @param Data Pointer to the converted value.
944 @retval RETURN_SUCCESS Value is translated from String.
945 @retval RETURN_INVALID_PARAMETER If String is NULL.
947 If PcdMaximumAsciiStringLength is not zero,
948 and String contains more than
949 PcdMaximumAsciiStringLength Ascii
950 characters, not including the
952 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
953 the range defined by UINT64.
958 AsciiStrHexToUint64S (
959 IN CONST CHAR8
*String
,
960 OUT CHAR8
**EndPointer OPTIONAL
,
966 Returns the length of a Null-terminated Unicode string.
968 This function returns the number of Unicode characters in the Null-terminated
969 Unicode string specified by String.
971 If String is NULL, then ASSERT().
972 If String is not aligned on a 16-bit boundary, then ASSERT().
973 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
974 PcdMaximumUnicodeStringLength Unicode characters not including the
975 Null-terminator, then ASSERT().
977 @param String Pointer to a Null-terminated Unicode string.
979 @return The length of String.
985 IN CONST CHAR16
*String
990 Returns the size of a Null-terminated Unicode string in bytes, including the
993 This function returns the size, in bytes, of the Null-terminated Unicode string
996 If String is NULL, then ASSERT().
997 If String is not aligned on a 16-bit boundary, then ASSERT().
998 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
999 PcdMaximumUnicodeStringLength Unicode characters not including the
1000 Null-terminator, then ASSERT().
1002 @param String The pointer to a Null-terminated Unicode string.
1004 @return The size of String.
1010 IN CONST CHAR16
*String
1015 Compares two Null-terminated Unicode strings, and returns the difference
1016 between the first mismatched Unicode characters.
1018 This function compares the Null-terminated Unicode string FirstString to the
1019 Null-terminated Unicode string SecondString. If FirstString is identical to
1020 SecondString, then 0 is returned. Otherwise, the value returned is the first
1021 mismatched Unicode character in SecondString subtracted from the first
1022 mismatched Unicode character in FirstString.
1024 If FirstString is NULL, then ASSERT().
1025 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1026 If SecondString is NULL, then ASSERT().
1027 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1028 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1029 than PcdMaximumUnicodeStringLength Unicode characters not including the
1030 Null-terminator, then ASSERT().
1031 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1032 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1033 Null-terminator, then ASSERT().
1035 @param FirstString The pointer to a Null-terminated Unicode string.
1036 @param SecondString The pointer to a Null-terminated Unicode string.
1038 @retval 0 FirstString is identical to SecondString.
1039 @return others FirstString is not identical to SecondString.
1045 IN CONST CHAR16
*FirstString
,
1046 IN CONST CHAR16
*SecondString
1051 Compares up to a specified length the contents of two Null-terminated Unicode strings,
1052 and returns the difference between the first mismatched Unicode characters.
1054 This function compares the Null-terminated Unicode string FirstString to the
1055 Null-terminated Unicode string SecondString. At most, Length Unicode
1056 characters will be compared. If Length is 0, then 0 is returned. If
1057 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1058 value returned is the first mismatched Unicode character in SecondString
1059 subtracted from the first mismatched Unicode character in FirstString.
1061 If Length > 0 and FirstString is NULL, then ASSERT().
1062 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1063 If Length > 0 and SecondString is NULL, then ASSERT().
1064 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1065 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1066 PcdMaximumUnicodeStringLength, then ASSERT().
1067 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1068 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1070 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1071 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1074 @param FirstString The pointer to a Null-terminated Unicode string.
1075 @param SecondString The pointer to a Null-terminated Unicode string.
1076 @param Length The maximum number of Unicode characters to compare.
1078 @retval 0 FirstString is identical to SecondString.
1079 @return others FirstString is not identical to SecondString.
1085 IN CONST CHAR16
*FirstString
,
1086 IN CONST CHAR16
*SecondString
,
1092 Returns the first occurrence of a Null-terminated Unicode sub-string
1093 in a Null-terminated Unicode string.
1095 This function scans the contents of the Null-terminated Unicode string
1096 specified by String and returns the first occurrence of SearchString.
1097 If SearchString is not found in String, then NULL is returned. If
1098 the length of SearchString is zero, then String is returned.
1100 If String is NULL, then ASSERT().
1101 If String is not aligned on a 16-bit boundary, then ASSERT().
1102 If SearchString is NULL, then ASSERT().
1103 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1105 If PcdMaximumUnicodeStringLength is not zero, and SearchString
1106 or String contains more than PcdMaximumUnicodeStringLength Unicode
1107 characters, not including the Null-terminator, then ASSERT().
1109 @param String The pointer to a Null-terminated Unicode string.
1110 @param SearchString The pointer to a Null-terminated Unicode string to search for.
1112 @retval NULL If the SearchString does not appear in String.
1113 @return others If there is a match.
1119 IN CONST CHAR16
*String
,
1120 IN CONST CHAR16
*SearchString
1124 Convert a Null-terminated Unicode decimal string to a value of
1127 This function returns a value of type UINTN by interpreting the contents
1128 of the Unicode string specified by String as a decimal number. The format
1129 of the input Unicode string String is:
1131 [spaces] [decimal digits].
1133 The valid decimal digit character is in the range [0-9]. The
1134 function will ignore the pad space, which includes spaces or
1135 tab characters, before [decimal digits]. The running zero in the
1136 beginning of [decimal digits] will be ignored. Then, the function
1137 stops at the first character that is a not a valid decimal character
1138 or a Null-terminator, whichever one comes first.
1140 If String is NULL, then ASSERT().
1141 If String is not aligned in a 16-bit boundary, then ASSERT().
1142 If String has only pad spaces, then 0 is returned.
1143 If String has no pad spaces or valid decimal digits,
1145 If the number represented by String overflows according
1146 to the range defined by UINTN, then MAX_UINTN is returned.
1148 If PcdMaximumUnicodeStringLength is not zero, and String contains
1149 more than PcdMaximumUnicodeStringLength Unicode characters not including
1150 the Null-terminator, then ASSERT().
1152 @param String The pointer to a Null-terminated Unicode string.
1154 @retval Value translated from String.
1160 IN CONST CHAR16
*String
1164 Convert a Null-terminated Unicode decimal string to a value of
1167 This function returns a value of type UINT64 by interpreting the contents
1168 of the Unicode string specified by String as a decimal number. The format
1169 of the input Unicode string String is:
1171 [spaces] [decimal digits].
1173 The valid decimal digit character is in the range [0-9]. The
1174 function will ignore the pad space, which includes spaces or
1175 tab characters, before [decimal digits]. The running zero in the
1176 beginning of [decimal digits] will be ignored. Then, the function
1177 stops at the first character that is a not a valid decimal character
1178 or a Null-terminator, whichever one comes first.
1180 If String is NULL, then ASSERT().
1181 If String is not aligned in a 16-bit boundary, then ASSERT().
1182 If String has only pad spaces, then 0 is returned.
1183 If String has no pad spaces or valid decimal digits,
1185 If the number represented by String overflows according
1186 to the range defined by UINT64, then MAX_UINT64 is returned.
1188 If PcdMaximumUnicodeStringLength is not zero, and String contains
1189 more than PcdMaximumUnicodeStringLength Unicode characters not including
1190 the Null-terminator, then ASSERT().
1192 @param String The pointer to a Null-terminated Unicode string.
1194 @retval Value translated from String.
1199 StrDecimalToUint64 (
1200 IN CONST CHAR16
*String
1205 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1207 This function returns a value of type UINTN by interpreting the contents
1208 of the Unicode string specified by String as a hexadecimal number.
1209 The format of the input Unicode string String is:
1211 [spaces][zeros][x][hexadecimal digits].
1213 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1214 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1215 If "x" appears in the input string, it must be prefixed with at least one 0.
1216 The function will ignore the pad space, which includes spaces or tab characters,
1217 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1218 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1219 first valid hexadecimal digit. Then, the function stops at the first character
1220 that is a not a valid hexadecimal character or NULL, whichever one comes first.
1222 If String is NULL, then ASSERT().
1223 If String is not aligned in a 16-bit boundary, then ASSERT().
1224 If String has only pad spaces, then zero is returned.
1225 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1226 then zero is returned.
1227 If the number represented by String overflows according to the range defined by
1228 UINTN, then MAX_UINTN is returned.
1230 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1231 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1234 @param String The pointer to a Null-terminated Unicode string.
1236 @retval Value translated from String.
1242 IN CONST CHAR16
*String
1247 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1249 This function returns a value of type UINT64 by interpreting the contents
1250 of the Unicode string specified by String as a hexadecimal number.
1251 The format of the input Unicode string String is
1253 [spaces][zeros][x][hexadecimal digits].
1255 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1256 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1257 If "x" appears in the input string, it must be prefixed with at least one 0.
1258 The function will ignore the pad space, which includes spaces or tab characters,
1259 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1260 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1261 first valid hexadecimal digit. Then, the function stops at the first character that is
1262 a not a valid hexadecimal character or NULL, whichever one comes first.
1264 If String is NULL, then ASSERT().
1265 If String is not aligned in a 16-bit boundary, then ASSERT().
1266 If String has only pad spaces, then zero is returned.
1267 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1268 then zero is returned.
1269 If the number represented by String overflows according to the range defined by
1270 UINT64, then MAX_UINT64 is returned.
1272 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1273 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1276 @param String The pointer to a Null-terminated Unicode string.
1278 @retval Value translated from String.
1284 IN CONST CHAR16
*String
1288 Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1290 This function outputs a value of type IPv6_ADDRESS and may output a value
1291 of type UINT8 by interpreting the contents of the Unicode string specified
1292 by String. The format of the input Unicode string String is as follows:
1296 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1297 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1298 memory address and high byte is stored in high memory address. P contains decimal
1299 digit characters in the range [0-9]. The running zero in the beginning of P will
1300 be ignored. /P is optional.
1302 When /P is not in the String, the function stops at the first character that is
1303 not a valid hexadecimal digit character after eight X's are converted.
1305 When /P is in the String, the function stops at the first character that is not
1306 a valid decimal digit character after P is converted.
1308 "::" can be used to compress one or more groups of X when X contains only 0.
1309 The "::" can only appear once in the String.
1311 If String is not aligned in a 16-bit boundary, then ASSERT().
1313 If EndPointer is not NULL and Address is translated from String, a pointer
1314 to the character that stopped the scan is stored at the location pointed to
1317 @param String Pointer to a Null-terminated Unicode string.
1318 @param EndPointer Pointer to character that stops scan.
1319 @param Address Pointer to the converted IPv6 address.
1320 @param PrefixLength Pointer to the converted IPv6 address prefix
1321 length. MAX_UINT8 is returned when /P is
1324 @retval RETURN_SUCCESS Address is translated from String.
1325 @retval RETURN_INVALID_PARAMETER If String is NULL.
1327 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1329 If String contains "::" and number of X
1331 If P starts with character that is not a
1332 valid decimal digit character.
1333 If the decimal number converted from P
1340 IN CONST CHAR16
*String
,
1341 OUT CHAR16
**EndPointer OPTIONAL
,
1342 OUT IPv6_ADDRESS
*Address
,
1343 OUT UINT8
*PrefixLength OPTIONAL
1347 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1349 This function outputs a value of type IPv4_ADDRESS and may output a value
1350 of type UINT8 by interpreting the contents of the Unicode string specified
1351 by String. The format of the input Unicode string String is as follows:
1355 D and P are decimal digit characters in the range [0-9]. The running zero in
1356 the beginning of D and P will be ignored. /P is optional.
1358 When /P is not in the String, the function stops at the first character that is
1359 not a valid decimal digit character after four D's are converted.
1361 When /P is in the String, the function stops at the first character that is not
1362 a valid decimal digit character after P is converted.
1364 If String is not aligned in a 16-bit boundary, then ASSERT().
1366 If EndPointer is not NULL and Address is translated from String, a pointer
1367 to the character that stopped the scan is stored at the location pointed to
1370 @param String Pointer to a Null-terminated Unicode string.
1371 @param EndPointer Pointer to character that stops scan.
1372 @param Address Pointer to the converted IPv4 address.
1373 @param PrefixLength Pointer to the converted IPv4 address prefix
1374 length. MAX_UINT8 is returned when /P is
1377 @retval RETURN_SUCCESS Address is translated from String.
1378 @retval RETURN_INVALID_PARAMETER If String is NULL.
1380 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1381 If any decimal number converted from D
1383 If the decimal number converted from P
1390 IN CONST CHAR16
*String
,
1391 OUT CHAR16
**EndPointer OPTIONAL
,
1392 OUT IPv4_ADDRESS
*Address
,
1393 OUT UINT8
*PrefixLength OPTIONAL
1396 #define GUID_STRING_LENGTH 36
1399 Convert a Null-terminated Unicode GUID string to a value of type
1402 This function outputs a GUID value by interpreting the contents of
1403 the Unicode string specified by String. The format of the input
1404 Unicode string String consists of 36 characters, as follows:
1406 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1408 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1409 [A-F], with each pair representing a single byte hexadecimal value.
1411 The mapping between String and the EFI_GUID structure is as follows:
1429 If String is not aligned in a 16-bit boundary, then ASSERT().
1431 @param String Pointer to a Null-terminated Unicode string.
1432 @param Guid Pointer to the converted GUID.
1434 @retval RETURN_SUCCESS Guid is translated from String.
1435 @retval RETURN_INVALID_PARAMETER If String is NULL.
1437 @retval RETURN_UNSUPPORTED If String is not as the above format.
1443 IN CONST CHAR16
*String
,
1448 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1450 This function outputs a byte array by interpreting the contents of
1451 the Unicode string specified by String in hexadecimal format. The format of
1452 the input Unicode string String is:
1456 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1457 The function decodes every two hexadecimal digit characters as one byte. The
1458 decoding stops after Length of characters and outputs Buffer containing
1461 If String is not aligned in a 16-bit boundary, then ASSERT().
1463 @param String Pointer to a Null-terminated Unicode string.
1464 @param Length The number of Unicode characters to decode.
1465 @param Buffer Pointer to the converted bytes array.
1466 @param MaxBufferSize The maximum size of Buffer.
1468 @retval RETURN_SUCCESS Buffer is translated from String.
1469 @retval RETURN_INVALID_PARAMETER If String is NULL.
1471 If Length is not multiple of 2.
1472 If PcdMaximumUnicodeStringLength is not zero,
1473 and Length is greater than
1474 PcdMaximumUnicodeStringLength.
1475 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1476 a character that is not valid hexadecimal
1477 digit characters, or a Null-terminator.
1478 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1483 IN CONST CHAR16
*String
,
1486 IN UINTN MaxBufferSize
1491 Convert a Null-terminated Unicode string to a Null-terminated
1494 This function is similar to AsciiStrCpyS.
1496 This function converts the content of the Unicode string Source
1497 to the ASCII string Destination by copying the lower 8 bits of
1498 each Unicode character. The function terminates the ASCII string
1499 Destination by appending a Null-terminator character at the end.
1501 The caller is responsible to make sure Destination points to a buffer with size
1502 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1504 If any Unicode characters in Source contain non-zero value in
1505 the upper 8 bits, then ASSERT().
1507 If Source is not aligned on a 16-bit boundary, then ASSERT().
1509 If an error is returned, then the Destination is unmodified.
1511 @param Source The pointer to a Null-terminated Unicode string.
1512 @param Destination The pointer to a Null-terminated ASCII string.
1513 @param DestMax The maximum number of Destination Ascii
1514 char, including terminating null char.
1516 @retval RETURN_SUCCESS String is converted.
1517 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1518 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1520 If PcdMaximumAsciiStringLength is not zero,
1521 and DestMax is greater than
1522 PcdMaximumAsciiStringLength.
1523 If PcdMaximumUnicodeStringLength is not zero,
1524 and DestMax is greater than
1525 PcdMaximumUnicodeStringLength.
1527 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1532 UnicodeStrToAsciiStrS (
1533 IN CONST CHAR16
*Source
,
1534 OUT CHAR8
*Destination
,
1539 Convert not more than Length successive characters from a Null-terminated
1540 Unicode string to a Null-terminated Ascii string. If no null char is copied
1541 from Source, then Destination[Length] is always set to null.
1543 This function converts not more than Length successive characters from the
1544 Unicode string Source to the Ascii string Destination by copying the lower 8
1545 bits of each Unicode character. The function terminates the Ascii string
1546 Destination by appending a Null-terminator character at the end.
1548 The caller is responsible to make sure Destination points to a buffer with size
1549 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1551 If any Unicode characters in Source contain non-zero value in the upper 8
1552 bits, then ASSERT().
1553 If Source is not aligned on a 16-bit boundary, then ASSERT().
1555 If an error is returned, then the Destination is unmodified.
1557 @param Source The pointer to a Null-terminated Unicode string.
1558 @param Length The maximum number of Unicode characters to
1560 @param Destination The pointer to a Null-terminated Ascii string.
1561 @param DestMax The maximum number of Destination Ascii
1562 char, including terminating null char.
1563 @param DestinationLength The number of Unicode characters converted.
1565 @retval RETURN_SUCCESS String is converted.
1566 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1568 If DestinationLength is NULL.
1569 If PcdMaximumAsciiStringLength is not zero,
1570 and Length or DestMax is greater than
1571 PcdMaximumAsciiStringLength.
1572 If PcdMaximumUnicodeStringLength is not
1573 zero, and Length or DestMax is greater than
1574 PcdMaximumUnicodeStringLength.
1576 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1577 MIN(StrLen(Source), Length).
1578 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1583 UnicodeStrnToAsciiStrS (
1584 IN CONST CHAR16
*Source
,
1586 OUT CHAR8
*Destination
,
1588 OUT UINTN
*DestinationLength
1593 Returns the length of a Null-terminated ASCII string.
1595 This function returns the number of ASCII characters in the Null-terminated
1596 ASCII string specified by String.
1598 If Length > 0 and Destination is NULL, then ASSERT().
1599 If Length > 0 and Source is NULL, then ASSERT().
1600 If PcdMaximumAsciiStringLength is not zero and String contains more than
1601 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1604 @param String The pointer to a Null-terminated ASCII string.
1606 @return The length of String.
1612 IN CONST CHAR8
*String
1617 Returns the size of a Null-terminated ASCII string in bytes, including the
1620 This function returns the size, in bytes, of the Null-terminated ASCII string
1621 specified by String.
1623 If String is NULL, then ASSERT().
1624 If PcdMaximumAsciiStringLength is not zero and String contains more than
1625 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1628 @param String The pointer to a Null-terminated ASCII string.
1630 @return The size of String.
1636 IN CONST CHAR8
*String
1641 Compares two Null-terminated ASCII strings, and returns the difference
1642 between the first mismatched ASCII characters.
1644 This function compares the Null-terminated ASCII string FirstString to the
1645 Null-terminated ASCII string SecondString. If FirstString is identical to
1646 SecondString, then 0 is returned. Otherwise, the value returned is the first
1647 mismatched ASCII character in SecondString subtracted from the first
1648 mismatched ASCII character in FirstString.
1650 If FirstString is NULL, then ASSERT().
1651 If SecondString is NULL, then ASSERT().
1652 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1653 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1655 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1656 than PcdMaximumAsciiStringLength ASCII characters not including the
1657 Null-terminator, then ASSERT().
1659 @param FirstString The pointer to a Null-terminated ASCII string.
1660 @param SecondString The pointer to a Null-terminated ASCII string.
1662 @retval ==0 FirstString is identical to SecondString.
1663 @retval !=0 FirstString is not identical to SecondString.
1669 IN CONST CHAR8
*FirstString
,
1670 IN CONST CHAR8
*SecondString
1675 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1676 and returns the difference between the first mismatched ASCII characters.
1678 This function performs a case insensitive comparison of the Null-terminated
1679 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1680 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1681 value returned is the first mismatched lower case ASCII character in
1682 SecondString subtracted from the first mismatched lower case ASCII character
1685 If FirstString is NULL, then ASSERT().
1686 If SecondString is NULL, then ASSERT().
1687 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1688 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1690 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1691 than PcdMaximumAsciiStringLength ASCII characters not including the
1692 Null-terminator, then ASSERT().
1694 @param FirstString The pointer to a Null-terminated ASCII string.
1695 @param SecondString The pointer to a Null-terminated ASCII string.
1697 @retval ==0 FirstString is identical to SecondString using case insensitive
1699 @retval !=0 FirstString is not identical to SecondString using case
1700 insensitive comparisons.
1706 IN CONST CHAR8
*FirstString
,
1707 IN CONST CHAR8
*SecondString
1712 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1713 the difference between the first mismatched ASCII characters.
1715 This function compares the Null-terminated ASCII string FirstString to the
1716 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1717 will be compared. If Length is 0, then 0 is returned. If FirstString is
1718 identical to SecondString, then 0 is returned. Otherwise, the value returned
1719 is the first mismatched ASCII character in SecondString subtracted from the
1720 first mismatched ASCII character in FirstString.
1722 If Length > 0 and FirstString is NULL, then ASSERT().
1723 If Length > 0 and SecondString is NULL, then ASSERT().
1724 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1725 PcdMaximumAsciiStringLength, then ASSERT().
1726 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
1727 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1729 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
1730 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1733 @param FirstString The pointer to a Null-terminated ASCII string.
1734 @param SecondString The pointer to a Null-terminated ASCII string.
1735 @param Length The maximum number of ASCII characters for compare.
1737 @retval ==0 FirstString is identical to SecondString.
1738 @retval !=0 FirstString is not identical to SecondString.
1744 IN CONST CHAR8
*FirstString
,
1745 IN CONST CHAR8
*SecondString
,
1751 Returns the first occurrence of a Null-terminated ASCII sub-string
1752 in a Null-terminated ASCII string.
1754 This function scans the contents of the ASCII string specified by String
1755 and returns the first occurrence of SearchString. If SearchString is not
1756 found in String, then NULL is returned. If the length of SearchString is zero,
1757 then String is returned.
1759 If String is NULL, then ASSERT().
1760 If SearchString is NULL, then ASSERT().
1762 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1763 String contains more than PcdMaximumAsciiStringLength Unicode characters
1764 not including the Null-terminator, then ASSERT().
1766 @param String The pointer to a Null-terminated ASCII string.
1767 @param SearchString The pointer to a Null-terminated ASCII string to search for.
1769 @retval NULL If the SearchString does not appear in String.
1770 @retval others If there is a match return the first occurrence of SearchingString.
1771 If the length of SearchString is zero,return String.
1777 IN CONST CHAR8
*String
,
1778 IN CONST CHAR8
*SearchString
1783 Convert a Null-terminated ASCII decimal string to a value of type
1786 This function returns a value of type UINTN by interpreting the contents
1787 of the ASCII string String as a decimal number. The format of the input
1788 ASCII string String is:
1790 [spaces] [decimal digits].
1792 The valid decimal digit character is in the range [0-9]. The function will
1793 ignore the pad space, which includes spaces or tab characters, before the digits.
1794 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1795 function stops at the first character that is a not a valid decimal character or
1796 Null-terminator, whichever on comes first.
1798 If String has only pad spaces, then 0 is returned.
1799 If String has no pad spaces or valid decimal digits, then 0 is returned.
1800 If the number represented by String overflows according to the range defined by
1801 UINTN, then MAX_UINTN is returned.
1802 If String is NULL, then ASSERT().
1803 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1804 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1807 @param String The pointer to a Null-terminated ASCII string.
1809 @retval The value translated from String.
1814 AsciiStrDecimalToUintn (
1815 IN CONST CHAR8
*String
1820 Convert a Null-terminated ASCII decimal string to a value of type
1823 This function returns a value of type UINT64 by interpreting the contents
1824 of the ASCII string String as a decimal number. The format of the input
1825 ASCII string String is:
1827 [spaces] [decimal digits].
1829 The valid decimal digit character is in the range [0-9]. The function will
1830 ignore the pad space, which includes spaces or tab characters, before the digits.
1831 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1832 function stops at the first character that is a not a valid decimal character or
1833 Null-terminator, whichever on comes first.
1835 If String has only pad spaces, then 0 is returned.
1836 If String has no pad spaces or valid decimal digits, then 0 is returned.
1837 If the number represented by String overflows according to the range defined by
1838 UINT64, then MAX_UINT64 is returned.
1839 If String is NULL, then ASSERT().
1840 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1841 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1844 @param String The pointer to a Null-terminated ASCII string.
1846 @retval Value translated from String.
1851 AsciiStrDecimalToUint64 (
1852 IN CONST CHAR8
*String
1857 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
1859 This function returns a value of type UINTN by interpreting the contents of
1860 the ASCII string String as a hexadecimal number. The format of the input ASCII
1863 [spaces][zeros][x][hexadecimal digits].
1865 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1866 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1867 appears in the input string, it must be prefixed with at least one 0. The function
1868 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1869 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1870 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1871 digit. Then, the function stops at the first character that is a not a valid
1872 hexadecimal character or Null-terminator, whichever on comes first.
1874 If String has only pad spaces, then 0 is returned.
1875 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1878 If the number represented by String overflows according to the range defined by UINTN,
1879 then MAX_UINTN is returned.
1880 If String is NULL, then ASSERT().
1881 If PcdMaximumAsciiStringLength is not zero,
1882 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1883 the Null-terminator, then ASSERT().
1885 @param String The pointer to a Null-terminated ASCII string.
1887 @retval Value translated from String.
1892 AsciiStrHexToUintn (
1893 IN CONST CHAR8
*String
1898 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
1900 This function returns a value of type UINT64 by interpreting the contents of
1901 the ASCII string String as a hexadecimal number. The format of the input ASCII
1904 [spaces][zeros][x][hexadecimal digits].
1906 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1907 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
1908 appears in the input string, it must be prefixed with at least one 0. The function
1909 will ignore the pad space, which includes spaces or tab characters, before [zeros],
1910 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
1911 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
1912 digit. Then, the function stops at the first character that is a not a valid
1913 hexadecimal character or Null-terminator, whichever on comes first.
1915 If String has only pad spaces, then 0 is returned.
1916 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
1919 If the number represented by String overflows according to the range defined by UINT64,
1920 then MAX_UINT64 is returned.
1921 If String is NULL, then ASSERT().
1922 If PcdMaximumAsciiStringLength is not zero,
1923 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
1924 the Null-terminator, then ASSERT().
1926 @param String The pointer to a Null-terminated ASCII string.
1928 @retval Value translated from String.
1933 AsciiStrHexToUint64 (
1934 IN CONST CHAR8
*String
1938 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
1940 This function outputs a value of type IPv6_ADDRESS and may output a value
1941 of type UINT8 by interpreting the contents of the ASCII string specified
1942 by String. The format of the input ASCII string String is as follows:
1946 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1947 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1948 memory address and high byte is stored in high memory address. P contains decimal
1949 digit characters in the range [0-9]. The running zero in the beginning of P will
1950 be ignored. /P is optional.
1952 When /P is not in the String, the function stops at the first character that is
1953 not a valid hexadecimal digit character after eight X's are converted.
1955 When /P is in the String, the function stops at the first character that is not
1956 a valid decimal digit character after P is converted.
1958 "::" can be used to compress one or more groups of X when X contains only 0.
1959 The "::" can only appear once in the String.
1961 If EndPointer is not NULL and Address is translated from String, a pointer
1962 to the character that stopped the scan is stored at the location pointed to
1965 @param String Pointer to a Null-terminated ASCII string.
1966 @param EndPointer Pointer to character that stops scan.
1967 @param Address Pointer to the converted IPv6 address.
1968 @param PrefixLength Pointer to the converted IPv6 address prefix
1969 length. MAX_UINT8 is returned when /P is
1972 @retval RETURN_SUCCESS Address is translated from String.
1973 @retval RETURN_INVALID_PARAMETER If String is NULL.
1975 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1977 If String contains "::" and number of X
1979 If P starts with character that is not a
1980 valid decimal digit character.
1981 If the decimal number converted from P
1987 AsciiStrToIpv6Address (
1988 IN CONST CHAR8
*String
,
1989 OUT CHAR8
**EndPointer OPTIONAL
,
1990 OUT IPv6_ADDRESS
*Address
,
1991 OUT UINT8
*PrefixLength OPTIONAL
1995 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
1997 This function outputs a value of type IPv4_ADDRESS and may output a value
1998 of type UINT8 by interpreting the contents of the ASCII string specified
1999 by String. The format of the input ASCII string String is as follows:
2003 D and P are decimal digit characters in the range [0-9]. The running zero in
2004 the beginning of D and P will be ignored. /P is optional.
2006 When /P is not in the String, the function stops at the first character that is
2007 not a valid decimal digit character after four D's are converted.
2009 When /P is in the String, the function stops at the first character that is not
2010 a valid decimal digit character after P is converted.
2012 If EndPointer is not NULL and Address is translated from String, a pointer
2013 to the character that stopped the scan is stored at the location pointed to
2016 @param String Pointer to a Null-terminated ASCII string.
2017 @param EndPointer Pointer to character that stops scan.
2018 @param Address Pointer to the converted IPv4 address.
2019 @param PrefixLength Pointer to the converted IPv4 address prefix
2020 length. MAX_UINT8 is returned when /P is
2023 @retval RETURN_SUCCESS Address is translated from String.
2024 @retval RETURN_INVALID_PARAMETER If String is NULL.
2026 @retval RETURN_UNSUPPORTED If String is not in the correct format.
2027 If any decimal number converted from D
2029 If the decimal number converted from P
2035 AsciiStrToIpv4Address (
2036 IN CONST CHAR8
*String
,
2037 OUT CHAR8
**EndPointer OPTIONAL
,
2038 OUT IPv4_ADDRESS
*Address
,
2039 OUT UINT8
*PrefixLength OPTIONAL
2043 Convert a Null-terminated ASCII GUID string to a value of type
2046 This function outputs a GUID value by interpreting the contents of
2047 the ASCII string specified by String. The format of the input
2048 ASCII string String consists of 36 characters, as follows:
2050 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
2052 The pairs aa - pp are two characters in the range [0-9], [a-f] and
2053 [A-F], with each pair representing a single byte hexadecimal value.
2055 The mapping between String and the EFI_GUID structure is as follows:
2073 @param String Pointer to a Null-terminated ASCII string.
2074 @param Guid Pointer to the converted GUID.
2076 @retval RETURN_SUCCESS Guid is translated from String.
2077 @retval RETURN_INVALID_PARAMETER If String is NULL.
2079 @retval RETURN_UNSUPPORTED If String is not as the above format.
2085 IN CONST CHAR8
*String
,
2090 Convert a Null-terminated ASCII hexadecimal string to a byte array.
2092 This function outputs a byte array by interpreting the contents of
2093 the ASCII string specified by String in hexadecimal format. The format of
2094 the input ASCII string String is:
2098 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
2099 The function decodes every two hexadecimal digit characters as one byte. The
2100 decoding stops after Length of characters and outputs Buffer containing
2103 @param String Pointer to a Null-terminated ASCII string.
2104 @param Length The number of ASCII characters to decode.
2105 @param Buffer Pointer to the converted bytes array.
2106 @param MaxBufferSize The maximum size of Buffer.
2108 @retval RETURN_SUCCESS Buffer is translated from String.
2109 @retval RETURN_INVALID_PARAMETER If String is NULL.
2111 If Length is not multiple of 2.
2112 If PcdMaximumAsciiStringLength is not zero,
2113 and Length is greater than
2114 PcdMaximumAsciiStringLength.
2115 @retval RETURN_UNSUPPORTED If Length of characters from String contain
2116 a character that is not valid hexadecimal
2117 digit characters, or a Null-terminator.
2118 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
2122 AsciiStrHexToBytes (
2123 IN CONST CHAR8
*String
,
2126 IN UINTN MaxBufferSize
2131 Convert one Null-terminated ASCII string to a Null-terminated
2134 This function is similar to StrCpyS.
2136 This function converts the contents of the ASCII string Source to the Unicode
2137 string Destination. The function terminates the Unicode string Destination by
2138 appending a Null-terminator character at the end.
2140 The caller is responsible to make sure Destination points to a buffer with size
2141 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2143 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2145 If an error is returned, then the Destination is unmodified.
2147 @param Source The pointer to a Null-terminated ASCII string.
2148 @param Destination The pointer to a Null-terminated Unicode string.
2149 @param DestMax The maximum number of Destination Unicode
2150 char, including terminating null char.
2152 @retval RETURN_SUCCESS String is converted.
2153 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2154 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2156 If PcdMaximumUnicodeStringLength is not zero,
2157 and DestMax is greater than
2158 PcdMaximumUnicodeStringLength.
2159 If PcdMaximumAsciiStringLength is not zero,
2160 and DestMax is greater than
2161 PcdMaximumAsciiStringLength.
2163 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2168 AsciiStrToUnicodeStrS (
2169 IN CONST CHAR8
*Source
,
2170 OUT CHAR16
*Destination
,
2175 Convert not more than Length successive characters from a Null-terminated
2176 Ascii string to a Null-terminated Unicode string. If no null char is copied
2177 from Source, then Destination[Length] is always set to null.
2179 This function converts not more than Length successive characters from the
2180 Ascii string Source to the Unicode string Destination. The function
2181 terminates the Unicode string Destination by appending a Null-terminator
2182 character at the end.
2184 The caller is responsible to make sure Destination points to a buffer with
2185 size not smaller than
2186 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2188 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2190 If an error is returned, then Destination and DestinationLength are
2193 @param Source The pointer to a Null-terminated Ascii string.
2194 @param Length The maximum number of Ascii characters to convert.
2195 @param Destination The pointer to a Null-terminated Unicode string.
2196 @param DestMax The maximum number of Destination Unicode char,
2197 including terminating null char.
2198 @param DestinationLength The number of Ascii characters converted.
2200 @retval RETURN_SUCCESS String is converted.
2201 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2203 If DestinationLength is NULL.
2204 If PcdMaximumUnicodeStringLength is not
2205 zero, and Length or DestMax is greater than
2206 PcdMaximumUnicodeStringLength.
2207 If PcdMaximumAsciiStringLength is not zero,
2208 and Length or DestMax is greater than
2209 PcdMaximumAsciiStringLength.
2211 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2212 MIN(AsciiStrLen(Source), Length).
2213 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2218 AsciiStrnToUnicodeStrS (
2219 IN CONST CHAR8
*Source
,
2221 OUT CHAR16
*Destination
,
2223 OUT UINTN
*DestinationLength
2227 Convert a Unicode character to upper case only if
2228 it maps to a valid small-case ASCII character.
2230 This internal function only deal with Unicode character
2231 which maps to a valid small-case ASCII character, i.e.
2232 L'a' to L'z'. For other Unicode character, the input character
2233 is returned directly.
2235 @param Char The character to convert.
2237 @retval LowerCharacter If the Char is with range L'a' to L'z'.
2238 @retval Unchanged Otherwise.
2248 Converts a lowercase Ascii character to upper one.
2250 If Chr is lowercase Ascii character, then converts it to upper one.
2252 If Value >= 0xA0, then ASSERT().
2253 If (Value & 0x0F) >= 0x0A, then ASSERT().
2255 @param Chr one Ascii character
2257 @return The uppercase value of Ascii character
2267 Convert binary data to a Base64 encoded ascii string based on RFC4648.
2269 Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
2270 The Ascii string is produced by converting the data string specified by Source and SourceLength.
2272 @param Source Input UINT8 data
2273 @param SourceLength Number of UINT8 bytes of data
2274 @param Destination Pointer to output string buffer
2275 @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed.
2276 Caller is responsible for passing in buffer of DestinationSize
2278 @retval RETURN_SUCCESS When ascii buffer is filled in.
2279 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
2280 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
2281 @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1.
2282 @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize.
2288 IN CONST UINT8
*Source
,
2289 IN UINTN SourceLength
,
2290 OUT CHAR8
*Destination OPTIONAL
,
2291 IN OUT UINTN
*DestinationSize
2295 Decode Base64 ASCII encoded data to 8-bit binary representation, based on
2298 Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648.
2300 Whitespace is ignored at all positions:
2301 - 0x09 ('\t') horizontal tab
2302 - 0x0A ('\n') new line
2303 - 0x0B ('\v') vertical tab
2304 - 0x0C ('\f') form feed
2305 - 0x0D ('\r') carriage return
2308 The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated
2309 and enforced at the end of the Base64 ASCII encoded data, and only there.
2311 Other characters outside of the encoding alphabet cause the function to
2312 reject the Base64 ASCII encoded data.
2314 @param[in] Source Array of CHAR8 elements containing the Base64
2315 ASCII encoding. May be NULL if SourceSize is
2318 @param[in] SourceSize Number of CHAR8 elements in Source.
2320 @param[out] Destination Array of UINT8 elements receiving the decoded
2321 8-bit binary representation. Allocated by the
2322 caller. May be NULL if DestinationSize is
2323 zero on input. If NULL, decoding is
2324 performed, but the 8-bit binary
2325 representation is not stored. If non-NULL and
2326 the function returns an error, the contents
2327 of Destination are indeterminate.
2329 @param[in,out] DestinationSize On input, the number of UINT8 elements that
2330 the caller allocated for Destination. On
2331 output, if the function returns
2332 RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL,
2333 the number of UINT8 elements that are
2334 required for decoding the Base64 ASCII
2335 representation. If the function returns a
2336 value different from both RETURN_SUCCESS and
2337 RETURN_BUFFER_TOO_SMALL, then DestinationSize
2338 is indeterminate on output.
2340 @retval RETURN_SUCCESS SourceSize CHAR8 elements at Source have
2341 been decoded to on-output DestinationSize
2342 UINT8 elements at Destination. Note that
2343 RETURN_SUCCESS covers the case when
2344 DestinationSize is zero on input, and
2345 Source decodes to zero bytes (due to
2346 containing at most ignored whitespace).
2348 @retval RETURN_BUFFER_TOO_SMALL The input value of DestinationSize is not
2349 large enough for decoding SourceSize CHAR8
2350 elements at Source. The required number of
2351 UINT8 elements has been stored to
2354 @retval RETURN_INVALID_PARAMETER DestinationSize is NULL.
2356 @retval RETURN_INVALID_PARAMETER Source is NULL, but SourceSize is not zero.
2358 @retval RETURN_INVALID_PARAMETER Destination is NULL, but DestinationSize is
2361 @retval RETURN_INVALID_PARAMETER Source is non-NULL, and (Source +
2362 SourceSize) would wrap around MAX_ADDRESS.
2364 @retval RETURN_INVALID_PARAMETER Destination is non-NULL, and (Destination +
2365 DestinationSize) would wrap around
2366 MAX_ADDRESS, as specified on input.
2368 @retval RETURN_INVALID_PARAMETER None of Source and Destination are NULL,
2369 and CHAR8[SourceSize] at Source overlaps
2370 UINT8[DestinationSize] at Destination, as
2373 @retval RETURN_INVALID_PARAMETER Invalid CHAR8 element encountered in
2379 IN CONST CHAR8
*Source OPTIONAL
,
2380 IN UINTN SourceSize
,
2381 OUT UINT8
*Destination OPTIONAL
,
2382 IN OUT UINTN
*DestinationSize
2386 Converts an 8-bit value to an 8-bit BCD value.
2388 Converts the 8-bit value specified by Value to BCD. The BCD value is
2391 If Value >= 100, then ASSERT().
2393 @param Value The 8-bit value to convert to BCD. Range 0..99.
2395 @return The BCD value.
2406 Converts an 8-bit BCD value to an 8-bit value.
2408 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2411 If Value >= 0xA0, then ASSERT().
2412 If (Value & 0x0F) >= 0x0A, then ASSERT().
2414 @param Value The 8-bit BCD value to convert to an 8-bit value.
2416 @return The 8-bit value is returned.
2426 // File Path Manipulation Functions
2430 Removes the last directory or file entry in a path.
2432 @param[in, out] Path The pointer to the path to modify.
2434 @retval FALSE Nothing was found to remove.
2435 @retval TRUE A directory or file was removed.
2444 Function to clean up paths.
2445 - Single periods in the path are removed.
2446 - Double periods in the path are removed along with a single parent directory.
2447 - Forward slashes L'/' are converted to backward slashes L'\'.
2449 This will be done inline and the existing buffer may be larger than required
2452 @param[in] Path The pointer to the string containing the path.
2454 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2458 PathCleanUpDirectories(
2463 // Linked List Functions and Macros
2467 Initializes the head node of a doubly linked list that is declared as a
2468 global variable in a module.
2470 Initializes the forward and backward links of a new linked list. After
2471 initializing a linked list with this macro, the other linked list functions
2472 may be used to add and remove nodes from the linked list. This macro results
2473 in smaller executables by initializing the linked list in the data section,
2474 instead if calling the InitializeListHead() function to perform the
2475 equivalent operation.
2477 @param ListHead The head note of a list to initialize.
2480 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2483 Iterates over each node in a doubly linked list using each node's forward link.
2485 @param Entry A pointer to a list node used as a loop cursor during iteration
2486 @param ListHead The head node of the doubly linked list
2489 #define BASE_LIST_FOR_EACH(Entry, ListHead) \
2490 for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)
2493 Iterates over each node in a doubly linked list using each node's forward link
2494 with safety against node removal.
2496 This macro uses NextEntry to temporarily store the next list node so the node
2497 pointed to by Entry may be deleted in the current loop iteration step and
2498 iteration can continue from the node pointed to by NextEntry.
2500 @param Entry A pointer to a list node used as a loop cursor during iteration
2501 @param NextEntry A pointer to a list node used to temporarily store the next node
2502 @param ListHead The head node of the doubly linked list
2505 #define BASE_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \
2506 for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
2507 Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
2510 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2513 If FirstEntry is NULL, then ASSERT().
2514 If FirstEntry->ForwardLink is NULL, then ASSERT().
2515 If FirstEntry->BackLink is NULL, then ASSERT().
2516 If SecondEntry is NULL, then ASSERT();
2517 If PcdMaximumLinkedListLength is not zero, and List contains more than
2518 PcdMaximumLinkedListLength nodes, then ASSERT().
2520 @param FirstEntry A pointer to a node in a linked list.
2521 @param SecondEntry A pointer to the node to locate.
2523 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.
2524 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,
2525 or FirstEntry is invalid.
2531 IN CONST LIST_ENTRY
*FirstEntry
,
2532 IN CONST LIST_ENTRY
*SecondEntry
2537 Initializes the head node of a doubly linked list, and returns the pointer to
2538 the head node of the doubly linked list.
2540 Initializes the forward and backward links of a new linked list. After
2541 initializing a linked list with this function, the other linked list
2542 functions may be used to add and remove nodes from the linked list. It is up
2543 to the caller of this function to allocate the memory for ListHead.
2545 If ListHead is NULL, then ASSERT().
2547 @param ListHead A pointer to the head node of a new doubly linked list.
2554 InitializeListHead (
2555 IN OUT LIST_ENTRY
*ListHead
2560 Adds a node to the beginning of a doubly linked list, and returns the pointer
2561 to the head node of the doubly linked list.
2563 Adds the node Entry at the beginning of the doubly linked list denoted by
2564 ListHead, and returns ListHead.
2566 If ListHead is NULL, then ASSERT().
2567 If Entry is NULL, then ASSERT().
2568 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2569 InitializeListHead(), then ASSERT().
2570 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2571 of nodes in ListHead, including the ListHead node, is greater than or
2572 equal to PcdMaximumLinkedListLength, then ASSERT().
2574 @param ListHead A pointer to the head node of a doubly linked list.
2575 @param Entry A pointer to a node that is to be inserted at the beginning
2576 of a doubly linked list.
2584 IN OUT LIST_ENTRY
*ListHead
,
2585 IN OUT LIST_ENTRY
*Entry
2590 Adds a node to the end of a doubly linked list, and returns the pointer to
2591 the head node of the doubly linked list.
2593 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2594 and returns ListHead.
2596 If ListHead is NULL, then ASSERT().
2597 If Entry is NULL, then ASSERT().
2598 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2599 InitializeListHead(), then ASSERT().
2600 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2601 of nodes in ListHead, including the ListHead node, is greater than or
2602 equal to PcdMaximumLinkedListLength, then ASSERT().
2604 @param ListHead A pointer to the head node of a doubly linked list.
2605 @param Entry A pointer to a node that is to be added at the end of the
2614 IN OUT LIST_ENTRY
*ListHead
,
2615 IN OUT LIST_ENTRY
*Entry
2620 Retrieves the first node of a doubly linked list.
2622 Returns the first node of a doubly linked list. List must have been
2623 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2624 If List is empty, then List is returned.
2626 If List is NULL, then ASSERT().
2627 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2628 InitializeListHead(), then ASSERT().
2629 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2630 in List, including the List node, is greater than or equal to
2631 PcdMaximumLinkedListLength, then ASSERT().
2633 @param List A pointer to the head node of a doubly linked list.
2635 @return The first node of a doubly linked list.
2636 @retval List The list is empty.
2642 IN CONST LIST_ENTRY
*List
2647 Retrieves the next node of a doubly linked list.
2649 Returns the node of a doubly linked list that follows Node.
2650 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2651 or InitializeListHead(). If List is empty, then List is returned.
2653 If List is NULL, then ASSERT().
2654 If Node is NULL, then ASSERT().
2655 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2656 InitializeListHead(), then ASSERT().
2657 If PcdMaximumLinkedListLength is not zero, and List contains more than
2658 PcdMaximumLinkedListLength nodes, then ASSERT().
2659 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2661 @param List A pointer to the head node of a doubly linked list.
2662 @param Node A pointer to a node in the doubly linked list.
2664 @return The pointer to the next node if one exists. Otherwise List is returned.
2670 IN CONST LIST_ENTRY
*List
,
2671 IN CONST LIST_ENTRY
*Node
2676 Retrieves the previous node of a doubly linked list.
2678 Returns the node of a doubly linked list that precedes Node.
2679 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2680 or InitializeListHead(). If List is empty, then List is returned.
2682 If List is NULL, then ASSERT().
2683 If Node is NULL, then ASSERT().
2684 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2685 InitializeListHead(), then ASSERT().
2686 If PcdMaximumLinkedListLength is not zero, and List contains more than
2687 PcdMaximumLinkedListLength nodes, then ASSERT().
2688 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2690 @param List A pointer to the head node of a doubly linked list.
2691 @param Node A pointer to a node in the doubly linked list.
2693 @return The pointer to the previous node if one exists. Otherwise List is returned.
2699 IN CONST LIST_ENTRY
*List
,
2700 IN CONST LIST_ENTRY
*Node
2705 Checks to see if a doubly linked list is empty or not.
2707 Checks to see if the doubly linked list is empty. If the linked list contains
2708 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
2710 If ListHead is NULL, then ASSERT().
2711 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2712 InitializeListHead(), then ASSERT().
2713 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2714 in List, including the List node, is greater than or equal to
2715 PcdMaximumLinkedListLength, then ASSERT().
2717 @param ListHead A pointer to the head node of a doubly linked list.
2719 @retval TRUE The linked list is empty.
2720 @retval FALSE The linked list is not empty.
2726 IN CONST LIST_ENTRY
*ListHead
2731 Determines if a node in a doubly linked list is the head node of a the same
2732 doubly linked list. This function is typically used to terminate a loop that
2733 traverses all the nodes in a doubly linked list starting with the head node.
2735 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
2736 nodes in the doubly linked list specified by List. List must have been
2737 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2739 If List is NULL, then ASSERT().
2740 If Node is NULL, then ASSERT().
2741 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
2743 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2744 in List, including the List node, is greater than or equal to
2745 PcdMaximumLinkedListLength, then ASSERT().
2746 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
2747 to List, then ASSERT().
2749 @param List A pointer to the head node of a doubly linked list.
2750 @param Node A pointer to a node in the doubly linked list.
2752 @retval TRUE Node is the head of the doubly-linked list pointed by List.
2753 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
2759 IN CONST LIST_ENTRY
*List
,
2760 IN CONST LIST_ENTRY
*Node
2765 Determines if a node the last node in a doubly linked list.
2767 Returns TRUE if Node is the last node in the doubly linked list specified by
2768 List. Otherwise, FALSE is returned. List must have been initialized with
2769 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2771 If List is NULL, then ASSERT().
2772 If Node is NULL, then ASSERT().
2773 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2774 InitializeListHead(), then ASSERT().
2775 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2776 in List, including the List node, is greater than or equal to
2777 PcdMaximumLinkedListLength, then ASSERT().
2778 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2780 @param List A pointer to the head node of a doubly linked list.
2781 @param Node A pointer to a node in the doubly linked list.
2783 @retval TRUE Node is the last node in the linked list.
2784 @retval FALSE Node is not the last node in the linked list.
2790 IN CONST LIST_ENTRY
*List
,
2791 IN CONST LIST_ENTRY
*Node
2796 Swaps the location of two nodes in a doubly linked list, and returns the
2797 first node after the swap.
2799 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
2800 Otherwise, the location of the FirstEntry node is swapped with the location
2801 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
2802 same double linked list as FirstEntry and that double linked list must have
2803 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2804 SecondEntry is returned after the nodes are swapped.
2806 If FirstEntry is NULL, then ASSERT().
2807 If SecondEntry is NULL, then ASSERT().
2808 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
2809 same linked list, then ASSERT().
2810 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2811 linked list containing the FirstEntry and SecondEntry nodes, including
2812 the FirstEntry and SecondEntry nodes, is greater than or equal to
2813 PcdMaximumLinkedListLength, then ASSERT().
2815 @param FirstEntry A pointer to a node in a linked list.
2816 @param SecondEntry A pointer to another node in the same linked list.
2818 @return SecondEntry.
2824 IN OUT LIST_ENTRY
*FirstEntry
,
2825 IN OUT LIST_ENTRY
*SecondEntry
2830 Removes a node from a doubly linked list, and returns the node that follows
2833 Removes the node Entry from a doubly linked list. It is up to the caller of
2834 this function to release the memory used by this node if that is required. On
2835 exit, the node following Entry in the doubly linked list is returned. If
2836 Entry is the only node in the linked list, then the head node of the linked
2839 If Entry is NULL, then ASSERT().
2840 If Entry is the head node of an empty list, then ASSERT().
2841 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2842 linked list containing Entry, including the Entry node, is greater than
2843 or equal to PcdMaximumLinkedListLength, then ASSERT().
2845 @param Entry A pointer to a node in a linked list.
2853 IN CONST LIST_ENTRY
*Entry
2860 Prototype for comparison function for any two element types.
2862 @param[in] Buffer1 The pointer to first buffer.
2863 @param[in] Buffer2 The pointer to second buffer.
2865 @retval 0 Buffer1 equal to Buffer2.
2866 @return <0 Buffer1 is less than Buffer2.
2867 @return >0 Buffer1 is greater than Buffer2.
2871 (EFIAPI
*BASE_SORT_COMPARE
)(
2872 IN CONST VOID
*Buffer1
,
2873 IN CONST VOID
*Buffer2
2877 This function is identical to perform QuickSort,
2878 except that is uses the pre-allocated buffer so the in place sorting does not need to
2879 allocate and free buffers constantly.
2881 Each element must be equal sized.
2883 if BufferToSort is NULL, then ASSERT.
2884 if CompareFunction is NULL, then ASSERT.
2885 if BufferOneElement is NULL, then ASSERT.
2886 if ElementSize is < 1, then ASSERT.
2888 if Count is < 2 then perform no action.
2890 @param[in, out] BufferToSort on call a Buffer of (possibly sorted) elements
2891 on return a buffer of sorted elements
2892 @param[in] Count the number of elements in the buffer to sort
2893 @param[in] ElementSize Size of an element in bytes
2894 @param[in] CompareFunction The function to call to perform the comparison
2896 @param[out] BufferOneElement Caller provided buffer whose size equals to ElementSize.
2897 It's used by QuickSort() for swapping in sorting.
2902 IN OUT VOID
*BufferToSort
,
2903 IN CONST UINTN Count
,
2904 IN CONST UINTN ElementSize
,
2905 IN BASE_SORT_COMPARE CompareFunction
,
2906 OUT VOID
*BufferOneElement
2910 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
2911 with zeros. The shifted value is returned.
2913 This function shifts the 64-bit value Operand to the left by Count bits. The
2914 low Count bits are set to zero. The shifted value is returned.
2916 If Count is greater than 63, then ASSERT().
2918 @param Operand The 64-bit operand to shift left.
2919 @param Count The number of bits to shift left.
2921 @return Operand << Count.
2933 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
2934 filled with zeros. The shifted value is returned.
2936 This function shifts the 64-bit value Operand to the right by Count bits. The
2937 high Count bits are set to zero. The shifted value is returned.
2939 If Count is greater than 63, then ASSERT().
2941 @param Operand The 64-bit operand to shift right.
2942 @param Count The number of bits to shift right.
2944 @return Operand >> Count
2956 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
2957 with original integer's bit 63. The shifted value is returned.
2959 This function shifts the 64-bit value Operand to the right by Count bits. The
2960 high Count bits are set to bit 63 of Operand. The shifted value is returned.
2962 If Count is greater than 63, then ASSERT().
2964 @param Operand The 64-bit operand to shift right.
2965 @param Count The number of bits to shift right.
2967 @return Operand >> Count
2979 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
2980 with the high bits that were rotated.
2982 This function rotates the 32-bit value Operand to the left by Count bits. The
2983 low Count bits are fill with the high Count bits of Operand. The rotated
2986 If Count is greater than 31, then ASSERT().
2988 @param Operand The 32-bit operand to rotate left.
2989 @param Count The number of bits to rotate left.
2991 @return Operand << Count
3003 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
3004 with the low bits that were rotated.
3006 This function rotates the 32-bit value Operand to the right by Count bits.
3007 The high Count bits are fill with the low Count bits of Operand. The rotated
3010 If Count is greater than 31, then ASSERT().
3012 @param Operand The 32-bit operand to rotate right.
3013 @param Count The number of bits to rotate right.
3015 @return Operand >> Count
3027 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3028 with the high bits that were rotated.
3030 This function rotates the 64-bit value Operand to the left by Count bits. The
3031 low Count bits are fill with the high Count bits of Operand. The rotated
3034 If Count is greater than 63, then ASSERT().
3036 @param Operand The 64-bit operand to rotate left.
3037 @param Count The number of bits to rotate left.
3039 @return Operand << Count
3051 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3052 with the high low bits that were rotated.
3054 This function rotates the 64-bit value Operand to the right by Count bits.
3055 The high Count bits are fill with the low Count bits of Operand. The rotated
3058 If Count is greater than 63, then ASSERT().
3060 @param Operand The 64-bit operand to rotate right.
3061 @param Count The number of bits to rotate right.
3063 @return Operand >> Count
3075 Returns the bit position of the lowest bit set in a 32-bit value.
3077 This function computes the bit position of the lowest bit set in the 32-bit
3078 value specified by Operand. If Operand is zero, then -1 is returned.
3079 Otherwise, a value between 0 and 31 is returned.
3081 @param Operand The 32-bit operand to evaluate.
3083 @retval 0..31 The lowest bit set in Operand was found.
3084 @retval -1 Operand is zero.
3095 Returns the bit position of the lowest bit set in a 64-bit value.
3097 This function computes the bit position of the lowest bit set in the 64-bit
3098 value specified by Operand. If Operand is zero, then -1 is returned.
3099 Otherwise, a value between 0 and 63 is returned.
3101 @param Operand The 64-bit operand to evaluate.
3103 @retval 0..63 The lowest bit set in Operand was found.
3104 @retval -1 Operand is zero.
3116 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3119 This function computes the bit position of the highest bit set in the 32-bit
3120 value specified by Operand. If Operand is zero, then -1 is returned.
3121 Otherwise, a value between 0 and 31 is returned.
3123 @param Operand The 32-bit operand to evaluate.
3125 @retval 0..31 Position of the highest bit set in Operand if found.
3126 @retval -1 Operand is zero.
3137 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3140 This function computes the bit position of the highest bit set in the 64-bit
3141 value specified by Operand. If Operand is zero, then -1 is returned.
3142 Otherwise, a value between 0 and 63 is returned.
3144 @param Operand The 64-bit operand to evaluate.
3146 @retval 0..63 Position of the highest bit set in Operand if found.
3147 @retval -1 Operand is zero.
3158 Returns the value of the highest bit set in a 32-bit value. Equivalent to
3161 This function computes the value of the highest bit set in the 32-bit value
3162 specified by Operand. If Operand is zero, then zero is returned.
3164 @param Operand The 32-bit operand to evaluate.
3166 @return 1 << HighBitSet32(Operand)
3167 @retval 0 Operand is zero.
3178 Returns the value of the highest bit set in a 64-bit value. Equivalent to
3181 This function computes the value of the highest bit set in the 64-bit value
3182 specified by Operand. If Operand is zero, then zero is returned.
3184 @param Operand The 64-bit operand to evaluate.
3186 @return 1 << HighBitSet64(Operand)
3187 @retval 0 Operand is zero.
3198 Switches the endianness of a 16-bit integer.
3200 This function swaps the bytes in a 16-bit unsigned value to switch the value
3201 from little endian to big endian or vice versa. The byte swapped value is
3204 @param Value A 16-bit unsigned value.
3206 @return The byte swapped Value.
3217 Switches the endianness of a 32-bit integer.
3219 This function swaps the bytes in a 32-bit unsigned value to switch the value
3220 from little endian to big endian or vice versa. The byte swapped value is
3223 @param Value A 32-bit unsigned value.
3225 @return The byte swapped Value.
3236 Switches the endianness of a 64-bit integer.
3238 This function swaps the bytes in a 64-bit unsigned value to switch the value
3239 from little endian to big endian or vice versa. The byte swapped value is
3242 @param Value A 64-bit unsigned value.
3244 @return The byte swapped Value.
3255 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3256 generates a 64-bit unsigned result.
3258 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3259 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3260 bit unsigned result is returned.
3262 @param Multiplicand A 64-bit unsigned value.
3263 @param Multiplier A 32-bit unsigned value.
3265 @return Multiplicand * Multiplier
3271 IN UINT64 Multiplicand
,
3272 IN UINT32 Multiplier
3277 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3278 generates a 64-bit unsigned result.
3280 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3281 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3282 bit unsigned result is returned.
3284 @param Multiplicand A 64-bit unsigned value.
3285 @param Multiplier A 64-bit unsigned value.
3287 @return Multiplicand * Multiplier.
3293 IN UINT64 Multiplicand
,
3294 IN UINT64 Multiplier
3299 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3300 64-bit signed result.
3302 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3303 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3304 signed result is returned.
3306 @param Multiplicand A 64-bit signed value.
3307 @param Multiplier A 64-bit signed value.
3309 @return Multiplicand * Multiplier
3315 IN INT64 Multiplicand
,
3321 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3322 a 64-bit unsigned result.
3324 This function divides the 64-bit unsigned value Dividend by the 32-bit
3325 unsigned value Divisor and generates a 64-bit unsigned quotient. This
3326 function returns the 64-bit unsigned quotient.
3328 If Divisor is 0, then ASSERT().
3330 @param Dividend A 64-bit unsigned value.
3331 @param Divisor A 32-bit unsigned value.
3333 @return Dividend / Divisor.
3345 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3346 a 32-bit unsigned remainder.
3348 This function divides the 64-bit unsigned value Dividend by the 32-bit
3349 unsigned value Divisor and generates a 32-bit remainder. This function
3350 returns the 32-bit unsigned remainder.
3352 If Divisor is 0, then ASSERT().
3354 @param Dividend A 64-bit unsigned value.
3355 @param Divisor A 32-bit unsigned value.
3357 @return Dividend % Divisor.
3369 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3370 a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3372 This function divides the 64-bit unsigned value Dividend by the 32-bit
3373 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3374 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3375 This function returns the 64-bit unsigned quotient.
3377 If Divisor is 0, then ASSERT().
3379 @param Dividend A 64-bit unsigned value.
3380 @param Divisor A 32-bit unsigned value.
3381 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3382 optional and may be NULL.
3384 @return Dividend / Divisor.
3389 DivU64x32Remainder (
3392 OUT UINT32
*Remainder OPTIONAL
3397 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3398 a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3400 This function divides the 64-bit unsigned value Dividend by the 64-bit
3401 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3402 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3403 This function returns the 64-bit unsigned quotient.
3405 If Divisor is 0, then ASSERT().
3407 @param Dividend A 64-bit unsigned value.
3408 @param Divisor A 64-bit unsigned value.
3409 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3410 optional and may be NULL.
3412 @return Dividend / Divisor.
3417 DivU64x64Remainder (
3420 OUT UINT64
*Remainder OPTIONAL
3425 Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3426 64-bit signed result and a optional 64-bit signed remainder.
3428 This function divides the 64-bit signed value Dividend by the 64-bit signed
3429 value Divisor and generates a 64-bit signed quotient. If Remainder is not
3430 NULL, then the 64-bit signed remainder is returned in Remainder. This
3431 function returns the 64-bit signed quotient.
3433 It is the caller's responsibility to not call this function with a Divisor of 0.
3434 If Divisor is 0, then the quotient and remainder should be assumed to be
3435 the largest negative integer.
3437 If Divisor is 0, then ASSERT().
3439 @param Dividend A 64-bit signed value.
3440 @param Divisor A 64-bit signed value.
3441 @param Remainder A pointer to a 64-bit signed value. This parameter is
3442 optional and may be NULL.
3444 @return Dividend / Divisor.
3449 DivS64x64Remainder (
3452 OUT INT64
*Remainder OPTIONAL
3457 Reads a 16-bit value from memory that may be unaligned.
3459 This function returns the 16-bit value pointed to by Buffer. The function
3460 guarantees that the read operation does not produce an alignment fault.
3462 If the Buffer is NULL, then ASSERT().
3464 @param Buffer The pointer to a 16-bit value that may be unaligned.
3466 @return The 16-bit value read from Buffer.
3472 IN CONST UINT16
*Buffer
3477 Writes a 16-bit value to memory that may be unaligned.
3479 This function writes the 16-bit value specified by Value to Buffer. Value is
3480 returned. The function guarantees that the write operation does not produce
3483 If the Buffer is NULL, then ASSERT().
3485 @param Buffer The pointer to a 16-bit value that may be unaligned.
3486 @param Value 16-bit value to write to Buffer.
3488 @return The 16-bit value to write to Buffer.
3500 Reads a 24-bit value from memory that may be unaligned.
3502 This function returns the 24-bit value pointed to by Buffer. The function
3503 guarantees that the read operation does not produce an alignment fault.
3505 If the Buffer is NULL, then ASSERT().
3507 @param Buffer The pointer to a 24-bit value that may be unaligned.
3509 @return The 24-bit value read from Buffer.
3515 IN CONST UINT32
*Buffer
3520 Writes a 24-bit value to memory that may be unaligned.
3522 This function writes the 24-bit value specified by Value to Buffer. Value is
3523 returned. The function guarantees that the write operation does not produce
3526 If the Buffer is NULL, then ASSERT().
3528 @param Buffer The pointer to a 24-bit value that may be unaligned.
3529 @param Value 24-bit value to write to Buffer.
3531 @return The 24-bit value to write to Buffer.
3543 Reads a 32-bit value from memory that may be unaligned.
3545 This function returns the 32-bit value pointed to by Buffer. The function
3546 guarantees that the read operation does not produce an alignment fault.
3548 If the Buffer is NULL, then ASSERT().
3550 @param Buffer The pointer to a 32-bit value that may be unaligned.
3552 @return The 32-bit value read from Buffer.
3558 IN CONST UINT32
*Buffer
3563 Writes a 32-bit value to memory that may be unaligned.
3565 This function writes the 32-bit value specified by Value to Buffer. Value is
3566 returned. The function guarantees that the write operation does not produce
3569 If the Buffer is NULL, then ASSERT().
3571 @param Buffer The pointer to a 32-bit value that may be unaligned.
3572 @param Value 32-bit value to write to Buffer.
3574 @return The 32-bit value to write to Buffer.
3586 Reads a 64-bit value from memory that may be unaligned.
3588 This function returns the 64-bit value pointed to by Buffer. The function
3589 guarantees that the read operation does not produce an alignment fault.
3591 If the Buffer is NULL, then ASSERT().
3593 @param Buffer The pointer to a 64-bit value that may be unaligned.
3595 @return The 64-bit value read from Buffer.
3601 IN CONST UINT64
*Buffer
3606 Writes a 64-bit value to memory that may be unaligned.
3608 This function writes the 64-bit value specified by Value to Buffer. Value is
3609 returned. The function guarantees that the write operation does not produce
3612 If the Buffer is NULL, then ASSERT().
3614 @param Buffer The pointer to a 64-bit value that may be unaligned.
3615 @param Value 64-bit value to write to Buffer.
3617 @return The 64-bit value to write to Buffer.
3629 // Bit Field Functions
3633 Returns a bit field from an 8-bit value.
3635 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3637 If 8-bit operations are not supported, then ASSERT().
3638 If StartBit is greater than 7, then ASSERT().
3639 If EndBit is greater than 7, then ASSERT().
3640 If EndBit is less than StartBit, 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.
3648 @return The bit field read.
3661 Writes a bit field to an 8-bit value, and returns the result.
3663 Writes Value to the bit field specified by the StartBit and the EndBit in
3664 Operand. All other bits in Operand are preserved. The new 8-bit value is
3667 If 8-bit operations are not supported, then ASSERT().
3668 If StartBit is greater than 7, then ASSERT().
3669 If EndBit is greater than 7, then ASSERT().
3670 If EndBit is less than StartBit, then ASSERT().
3671 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3673 @param Operand Operand on which to perform the bitfield operation.
3674 @param StartBit The ordinal of the least significant bit in the bit field.
3676 @param EndBit The ordinal of the most significant bit in the bit field.
3678 @param Value New value of the bit field.
3680 @return The new 8-bit value.
3694 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
3697 Performs a bitwise OR between the bit field specified by StartBit
3698 and EndBit in Operand and the value specified by OrData. All other bits in
3699 Operand are preserved. The new 8-bit value is returned.
3701 If 8-bit operations are not supported, then ASSERT().
3702 If StartBit is greater than 7, then ASSERT().
3703 If EndBit is greater than 7, then ASSERT().
3704 If EndBit is less than StartBit, then ASSERT().
3705 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3707 @param Operand Operand on which to perform the bitfield operation.
3708 @param StartBit The ordinal of the least significant bit in the bit field.
3710 @param EndBit The ordinal of the most significant bit in the bit field.
3712 @param OrData The value to OR with the read value from the value
3714 @return The new 8-bit value.
3728 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
3731 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3732 in Operand and the value specified by AndData. All other bits in Operand are
3733 preserved. The new 8-bit value is returned.
3735 If 8-bit operations are not supported, then ASSERT().
3736 If StartBit is greater than 7, then ASSERT().
3737 If EndBit is greater than 7, then ASSERT().
3738 If EndBit is less than StartBit, then ASSERT().
3739 If AndData is larger than the bitmask value range specified by StartBit and EndBit, 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.
3746 @param AndData The value to AND with the read value from the value.
3748 @return The new 8-bit value.
3762 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
3763 bitwise OR, and returns the result.
3765 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3766 in Operand and the value specified by AndData, followed by a bitwise
3767 OR with value specified by OrData. All other bits in Operand are
3768 preserved. The new 8-bit value is returned.
3770 If 8-bit operations are not supported, then ASSERT().
3771 If StartBit is greater than 7, then ASSERT().
3772 If EndBit is greater than 7, then ASSERT().
3773 If EndBit is less than StartBit, then ASSERT().
3774 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3775 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3777 @param Operand Operand on which to perform the bitfield operation.
3778 @param StartBit The ordinal of the least significant bit in the bit field.
3780 @param EndBit The ordinal of the most significant bit in the bit field.
3782 @param AndData The value to AND with the read value from the value.
3783 @param OrData The value to OR with the result of the AND operation.
3785 @return The new 8-bit value.
3790 BitFieldAndThenOr8 (
3800 Returns a bit field from a 16-bit value.
3802 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3804 If 16-bit operations are not supported, then ASSERT().
3805 If StartBit is greater than 15, then ASSERT().
3806 If EndBit is greater than 15, then ASSERT().
3807 If EndBit is less than StartBit, then ASSERT().
3809 @param Operand Operand on which to perform the bitfield operation.
3810 @param StartBit The ordinal of the least significant bit in the bit field.
3812 @param EndBit The ordinal of the most significant bit in the bit field.
3815 @return The bit field read.
3828 Writes a bit field to a 16-bit value, and returns the result.
3830 Writes Value to the bit field specified by the StartBit and the EndBit in
3831 Operand. All other bits in Operand are preserved. The new 16-bit value is
3834 If 16-bit operations are not supported, then ASSERT().
3835 If StartBit is greater than 15, then ASSERT().
3836 If EndBit is greater than 15, then ASSERT().
3837 If EndBit is less than StartBit, then ASSERT().
3838 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3840 @param Operand Operand on which to perform the bitfield operation.
3841 @param StartBit The ordinal of the least significant bit in the bit field.
3843 @param EndBit The ordinal of the most significant bit in the bit field.
3845 @param Value New value of the bit field.
3847 @return The new 16-bit value.
3861 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
3864 Performs a bitwise OR between the bit field specified by StartBit
3865 and EndBit in Operand and the value specified by OrData. All other bits in
3866 Operand are preserved. The new 16-bit value is returned.
3868 If 16-bit operations are not supported, then ASSERT().
3869 If StartBit is greater than 15, then ASSERT().
3870 If EndBit is greater than 15, then ASSERT().
3871 If EndBit is less than StartBit, then ASSERT().
3872 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3874 @param Operand Operand on which to perform the bitfield operation.
3875 @param StartBit The ordinal of the least significant bit in the bit field.
3877 @param EndBit The ordinal of the most significant bit in the bit field.
3879 @param OrData The value to OR with the read value from the value
3881 @return The new 16-bit value.
3895 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
3898 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3899 in Operand and the value specified by AndData. All other bits in Operand are
3900 preserved. The new 16-bit value is returned.
3902 If 16-bit operations are not supported, then ASSERT().
3903 If StartBit is greater than 15, then ASSERT().
3904 If EndBit is greater than 15, then ASSERT().
3905 If EndBit is less than StartBit, then ASSERT().
3906 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3908 @param Operand Operand on which to perform the bitfield operation.
3909 @param StartBit The ordinal of the least significant bit in the bit field.
3911 @param EndBit The ordinal of the most significant bit in the bit field.
3913 @param AndData The value to AND with the read value from the value
3915 @return The new 16-bit value.
3929 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
3930 bitwise OR, and returns the result.
3932 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3933 in Operand and the value specified by AndData, followed by a bitwise
3934 OR with value specified by OrData. All other bits in Operand are
3935 preserved. The new 16-bit value is returned.
3937 If 16-bit operations are not supported, then ASSERT().
3938 If StartBit is greater than 15, then ASSERT().
3939 If EndBit is greater than 15, then ASSERT().
3940 If EndBit is less than StartBit, then ASSERT().
3941 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3942 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3944 @param Operand Operand on which to perform the bitfield operation.
3945 @param StartBit The ordinal of the least significant bit in the bit field.
3947 @param EndBit The ordinal of the most significant bit in the bit field.
3949 @param AndData The value to AND with the read value from the value.
3950 @param OrData The value to OR with the result of the AND operation.
3952 @return The new 16-bit value.
3957 BitFieldAndThenOr16 (
3967 Returns a bit field from a 32-bit value.
3969 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3971 If 32-bit operations are not supported, then ASSERT().
3972 If StartBit is greater than 31, then ASSERT().
3973 If EndBit is greater than 31, then ASSERT().
3974 If EndBit is less than StartBit, then ASSERT().
3976 @param Operand Operand on which to perform the bitfield operation.
3977 @param StartBit The ordinal of the least significant bit in the bit field.
3979 @param EndBit The ordinal of the most significant bit in the bit field.
3982 @return The bit field read.
3995 Writes a bit field to a 32-bit value, and returns the result.
3997 Writes Value to the bit field specified by the StartBit and the EndBit in
3998 Operand. All other bits in Operand are preserved. The new 32-bit value is
4001 If 32-bit operations are not supported, then ASSERT().
4002 If StartBit is greater than 31, then ASSERT().
4003 If EndBit is greater than 31, then ASSERT().
4004 If EndBit is less than StartBit, then ASSERT().
4005 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4007 @param Operand Operand on which to perform the bitfield operation.
4008 @param StartBit The ordinal of the least significant bit in the bit field.
4010 @param EndBit The ordinal of the most significant bit in the bit field.
4012 @param Value New value of the bit field.
4014 @return The new 32-bit value.
4028 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
4031 Performs a bitwise OR between the bit field specified by StartBit
4032 and EndBit in Operand and the value specified by OrData. All other bits in
4033 Operand are preserved. The new 32-bit value is returned.
4035 If 32-bit operations are not supported, then ASSERT().
4036 If StartBit is greater than 31, then ASSERT().
4037 If EndBit is greater than 31, then ASSERT().
4038 If EndBit is less than StartBit, then ASSERT().
4039 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4041 @param Operand Operand on which to perform the bitfield operation.
4042 @param StartBit The ordinal of the least significant bit in the bit field.
4044 @param EndBit The ordinal of the most significant bit in the bit field.
4046 @param OrData The value to OR with the read value from the value.
4048 @return The new 32-bit value.
4062 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
4065 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4066 in Operand and the value specified by AndData. All other bits in Operand are
4067 preserved. The new 32-bit value is returned.
4069 If 32-bit operations are not supported, then ASSERT().
4070 If StartBit is greater than 31, then ASSERT().
4071 If EndBit is greater than 31, then ASSERT().
4072 If EndBit is less than StartBit, then ASSERT().
4073 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4075 @param Operand Operand on which to perform the bitfield operation.
4076 @param StartBit The ordinal of the least significant bit in the bit field.
4078 @param EndBit The ordinal of the most significant bit in the bit field.
4080 @param AndData The value to AND with the read value from the value
4082 @return The new 32-bit value.
4096 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4097 bitwise OR, and returns the result.
4099 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4100 in Operand and the value specified by AndData, followed by a bitwise
4101 OR with value specified by OrData. All other bits in Operand are
4102 preserved. The new 32-bit value is returned.
4104 If 32-bit operations are not supported, then ASSERT().
4105 If StartBit is greater than 31, then ASSERT().
4106 If EndBit is greater than 31, then ASSERT().
4107 If EndBit is less than StartBit, then ASSERT().
4108 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4109 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4111 @param Operand Operand on which to perform the bitfield operation.
4112 @param StartBit The ordinal of the least significant bit in the bit field.
4114 @param EndBit The ordinal of the most significant bit in the bit field.
4116 @param AndData The value to AND with the read value from the value.
4117 @param OrData The value to OR with the result of the AND operation.
4119 @return The new 32-bit value.
4124 BitFieldAndThenOr32 (
4134 Returns a bit field from a 64-bit value.
4136 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4138 If 64-bit operations are not supported, then ASSERT().
4139 If StartBit is greater than 63, then ASSERT().
4140 If EndBit is greater than 63, then ASSERT().
4141 If EndBit is less than StartBit, then ASSERT().
4143 @param Operand Operand on which to perform the bitfield operation.
4144 @param StartBit The ordinal of the least significant bit in the bit field.
4146 @param EndBit The ordinal of the most significant bit in the bit field.
4149 @return The bit field read.
4162 Writes a bit field to a 64-bit value, and returns the result.
4164 Writes Value to the bit field specified by the StartBit and the EndBit in
4165 Operand. All other bits in Operand are preserved. The new 64-bit value is
4168 If 64-bit operations are not supported, then ASSERT().
4169 If StartBit is greater than 63, then ASSERT().
4170 If EndBit is greater than 63, then ASSERT().
4171 If EndBit is less than StartBit, then ASSERT().
4172 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4174 @param Operand Operand on which to perform the bitfield operation.
4175 @param StartBit The ordinal of the least significant bit in the bit field.
4177 @param EndBit The ordinal of the most significant bit in the bit field.
4179 @param Value New value of the bit field.
4181 @return The new 64-bit value.
4195 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4198 Performs a bitwise OR between the bit field specified by StartBit
4199 and EndBit in Operand and the value specified by OrData. All other bits in
4200 Operand are preserved. The new 64-bit value is returned.
4202 If 64-bit operations are not supported, then ASSERT().
4203 If StartBit is greater than 63, then ASSERT().
4204 If EndBit is greater than 63, then ASSERT().
4205 If EndBit is less than StartBit, then ASSERT().
4206 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4208 @param Operand Operand on which to perform the bitfield operation.
4209 @param StartBit The ordinal of the least significant bit in the bit field.
4211 @param EndBit The ordinal of the most significant bit in the bit field.
4213 @param OrData The value to OR with the read value from the value
4215 @return The new 64-bit value.
4229 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4232 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4233 in Operand and the value specified by AndData. All other bits in Operand are
4234 preserved. The new 64-bit value is returned.
4236 If 64-bit operations are not supported, then ASSERT().
4237 If StartBit is greater than 63, then ASSERT().
4238 If EndBit is greater than 63, then ASSERT().
4239 If EndBit is less than StartBit, then ASSERT().
4240 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4242 @param Operand Operand on which to perform the bitfield operation.
4243 @param StartBit The ordinal of the least significant bit in the bit field.
4245 @param EndBit The ordinal of the most significant bit in the bit field.
4247 @param AndData The value to AND with the read value from the value
4249 @return The new 64-bit value.
4263 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4264 bitwise OR, and returns the result.
4266 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4267 in Operand and the value specified by AndData, followed by a bitwise
4268 OR with value specified by OrData. All other bits in Operand are
4269 preserved. The new 64-bit value is returned.
4271 If 64-bit operations are not supported, then ASSERT().
4272 If StartBit is greater than 63, then ASSERT().
4273 If EndBit is greater than 63, then ASSERT().
4274 If EndBit is less than StartBit, then ASSERT().
4275 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4276 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4278 @param Operand Operand on which to perform the bitfield operation.
4279 @param StartBit The ordinal of the least significant bit in the bit field.
4281 @param EndBit The ordinal of the most significant bit in the bit field.
4283 @param AndData The value to AND with the read value from the value.
4284 @param OrData The value to OR with the result of the AND operation.
4286 @return The new 64-bit value.
4291 BitFieldAndThenOr64 (
4300 Reads a bit field from a 32-bit value, counts and returns
4301 the number of set bits.
4303 Counts the number of set bits in the bit field specified by
4304 StartBit and EndBit in Operand. The count is returned.
4306 If StartBit is greater than 31, then ASSERT().
4307 If EndBit is greater than 31, then ASSERT().
4308 If EndBit is less than StartBit, then ASSERT().
4310 @param Operand Operand on which to perform the bitfield operation.
4311 @param StartBit The ordinal of the least significant bit in the bit field.
4313 @param EndBit The ordinal of the most significant bit in the bit field.
4316 @return The number of bits set between StartBit and EndBit.
4321 BitFieldCountOnes32 (
4328 Reads a bit field from a 64-bit value, counts and returns
4329 the number of set bits.
4331 Counts the number of set bits in the bit field specified by
4332 StartBit and EndBit in Operand. The count is returned.
4334 If StartBit is greater than 63, then ASSERT().
4335 If EndBit is greater than 63, then ASSERT().
4336 If EndBit is less than StartBit, then ASSERT().
4338 @param Operand Operand on which to perform the bitfield operation.
4339 @param StartBit The ordinal of the least significant bit in the bit field.
4341 @param EndBit The ordinal of the most significant bit in the bit field.
4344 @return The number of bits set between StartBit and EndBit.
4349 BitFieldCountOnes64 (
4356 // Base Library Checksum Functions
4360 Returns the sum of all elements in a buffer in unit of UINT8.
4361 During calculation, the carry bits are dropped.
4363 This function calculates the sum of all elements in a buffer
4364 in unit of UINT8. The carry bits in result of addition are dropped.
4365 The result is returned as UINT8. If Length is Zero, then Zero is
4368 If Buffer is NULL, then ASSERT().
4369 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4371 @param Buffer The pointer to the buffer to carry out the sum operation.
4372 @param Length The size, in bytes, of Buffer.
4374 @return Sum The sum of Buffer with carry bits dropped during additions.
4380 IN CONST UINT8
*Buffer
,
4386 Returns the two's complement checksum of all elements in a buffer
4389 This function first calculates the sum of the 8-bit values in the
4390 buffer specified by Buffer and Length. The carry bits in the result
4391 of addition are dropped. Then, the two's complement of the sum is
4392 returned. If Length is 0, then 0 is returned.
4394 If Buffer is NULL, then ASSERT().
4395 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4397 @param Buffer The pointer to the buffer to carry out the checksum operation.
4398 @param Length The size, in bytes, of Buffer.
4400 @return Checksum The two's complement checksum of Buffer.
4405 CalculateCheckSum8 (
4406 IN CONST UINT8
*Buffer
,
4412 Returns the sum of all elements in a buffer of 16-bit values. During
4413 calculation, the carry bits are dropped.
4415 This function calculates the sum of the 16-bit values in the buffer
4416 specified by Buffer and Length. The carry bits in result of addition are dropped.
4417 The 16-bit result is returned. If Length is 0, then 0 is returned.
4419 If Buffer is NULL, then ASSERT().
4420 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4421 If Length is not aligned on a 16-bit boundary, then ASSERT().
4422 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4424 @param Buffer The pointer to the buffer to carry out the sum operation.
4425 @param Length The size, in bytes, of Buffer.
4427 @return Sum The sum of Buffer with carry bits dropped during additions.
4433 IN CONST UINT16
*Buffer
,
4439 Returns the two's complement checksum of all elements in a buffer of
4442 This function first calculates the sum of the 16-bit values in the buffer
4443 specified by Buffer and Length. The carry bits in the result of addition
4444 are dropped. Then, the two's complement of the sum is returned. If Length
4445 is 0, then 0 is returned.
4447 If Buffer is NULL, then ASSERT().
4448 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4449 If Length is not aligned on a 16-bit boundary, then ASSERT().
4450 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4452 @param Buffer The pointer to the buffer to carry out the checksum operation.
4453 @param Length The size, in bytes, of Buffer.
4455 @return Checksum The two's complement checksum of Buffer.
4460 CalculateCheckSum16 (
4461 IN CONST UINT16
*Buffer
,
4467 Returns the sum of all elements in a buffer of 32-bit values. During
4468 calculation, the carry bits are dropped.
4470 This function calculates the sum of the 32-bit values in the buffer
4471 specified by Buffer and Length. The carry bits in result of addition are dropped.
4472 The 32-bit result is returned. If Length is 0, then 0 is returned.
4474 If Buffer is NULL, then ASSERT().
4475 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4476 If Length is not aligned on a 32-bit boundary, then ASSERT().
4477 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4479 @param Buffer The pointer to the buffer to carry out the sum operation.
4480 @param Length The size, in bytes, of Buffer.
4482 @return Sum The sum of Buffer with carry bits dropped during additions.
4488 IN CONST UINT32
*Buffer
,
4494 Returns the two's complement checksum of all elements in a buffer of
4497 This function first calculates the sum of the 32-bit values in the buffer
4498 specified by Buffer and Length. The carry bits in the result of addition
4499 are dropped. Then, the two's complement of the sum is returned. If Length
4500 is 0, then 0 is returned.
4502 If Buffer is NULL, then ASSERT().
4503 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4504 If Length is not aligned on a 32-bit boundary, then ASSERT().
4505 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4507 @param Buffer The pointer to the buffer to carry out the checksum operation.
4508 @param Length The size, in bytes, of Buffer.
4510 @return Checksum The two's complement checksum of Buffer.
4515 CalculateCheckSum32 (
4516 IN CONST UINT32
*Buffer
,
4522 Returns the sum of all elements in a buffer of 64-bit values. During
4523 calculation, the carry bits are dropped.
4525 This function calculates the sum of the 64-bit values in the buffer
4526 specified by Buffer and Length. The carry bits in result of addition are dropped.
4527 The 64-bit result is returned. If Length is 0, then 0 is returned.
4529 If Buffer is NULL, then ASSERT().
4530 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4531 If Length is not aligned on a 64-bit boundary, then ASSERT().
4532 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4534 @param Buffer The pointer to the buffer to carry out the sum operation.
4535 @param Length The size, in bytes, of Buffer.
4537 @return Sum The sum of Buffer with carry bits dropped during additions.
4543 IN CONST UINT64
*Buffer
,
4549 Returns the two's complement checksum of all elements in a buffer of
4552 This function first calculates the sum of the 64-bit values in the buffer
4553 specified by Buffer and Length. The carry bits in the result of addition
4554 are dropped. Then, the two's complement of the sum is returned. If Length
4555 is 0, then 0 is returned.
4557 If Buffer is NULL, then ASSERT().
4558 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4559 If Length is not aligned on a 64-bit boundary, then ASSERT().
4560 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4562 @param Buffer The pointer to the buffer to carry out the checksum operation.
4563 @param Length The size, in bytes, of Buffer.
4565 @return Checksum The two's complement checksum of Buffer.
4570 CalculateCheckSum64 (
4571 IN CONST UINT64
*Buffer
,
4576 Computes and returns a 32-bit CRC for a data buffer.
4577 CRC32 value bases on ITU-T V.42.
4579 If Buffer is NULL, then ASSERT().
4580 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4582 @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed.
4583 @param[in] Length The number of bytes in the buffer Data.
4585 @retval Crc32 The 32-bit CRC was computed for the data buffer.
4596 // Base Library CPU Functions
4600 Function entry point used when a stack switch is requested with SwitchStack()
4602 @param Context1 Context1 parameter passed into SwitchStack().
4603 @param Context2 Context2 parameter passed into SwitchStack().
4608 (EFIAPI
*SWITCH_STACK_ENTRY_POINT
)(
4609 IN VOID
*Context1 OPTIONAL
,
4610 IN VOID
*Context2 OPTIONAL
4615 Used to serialize load and store operations.
4617 All loads and stores that proceed calls to this function are guaranteed to be
4618 globally visible when this function returns.
4629 Saves the current CPU context that can be restored with a call to LongJump()
4632 Saves the current CPU context in the buffer specified by JumpBuffer and
4633 returns 0. The initial call to SetJump() must always return 0. Subsequent
4634 calls to LongJump() cause a non-zero value to be returned by SetJump().
4636 If JumpBuffer is NULL, then ASSERT().
4637 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4639 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
4640 The same structure must never be used for more than one CPU architecture context.
4641 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
4642 SetJump()/LongJump() is not currently supported for the EBC processor type.
4644 @param JumpBuffer A pointer to CPU context buffer.
4646 @retval 0 Indicates a return from SetJump().
4653 OUT BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
4658 Restores the CPU context that was saved with SetJump().
4660 Restores the CPU context from the buffer specified by JumpBuffer. This
4661 function never returns to the caller. Instead is resumes execution based on
4662 the state of JumpBuffer.
4664 If JumpBuffer is NULL, then ASSERT().
4665 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4666 If Value is 0, then ASSERT().
4668 @param JumpBuffer A pointer to CPU context buffer.
4669 @param Value The value to return when the SetJump() context is
4670 restored and must be non-zero.
4676 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
4682 Enables CPU interrupts.
4693 Disables CPU interrupts.
4704 Disables CPU interrupts and returns the interrupt state prior to the disable
4707 @retval TRUE CPU interrupts were enabled on entry to this call.
4708 @retval FALSE CPU interrupts were disabled on entry to this call.
4713 SaveAndDisableInterrupts (
4719 Enables CPU interrupts for the smallest window required to capture any
4725 EnableDisableInterrupts (
4731 Retrieves the current CPU interrupt state.
4733 Returns TRUE if interrupts are currently enabled. Otherwise
4736 @retval TRUE CPU interrupts are enabled.
4737 @retval FALSE CPU interrupts are disabled.
4748 Set the current CPU interrupt state.
4750 Sets the current CPU interrupt state to the state specified by
4751 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
4752 InterruptState is FALSE, then interrupts are disabled. InterruptState is
4755 @param InterruptState TRUE if interrupts should enabled. FALSE if
4756 interrupts should be disabled.
4758 @return InterruptState
4764 IN BOOLEAN InterruptState
4769 Requests CPU to pause for a short period of time.
4771 Requests CPU to pause for a short period of time. Typically used in MP
4772 systems to prevent memory starvation while waiting for a spin lock.
4783 Transfers control to a function starting with a new stack.
4785 Transfers control to the function specified by EntryPoint using the
4786 new stack specified by NewStack and passing in the parameters specified
4787 by Context1 and Context2. Context1 and Context2 are optional and may
4788 be NULL. The function EntryPoint must never return. This function
4789 supports a variable number of arguments following the NewStack parameter.
4790 These additional arguments are ignored on IA-32, x64, and EBC architectures.
4791 Itanium processors expect one additional parameter of type VOID * that specifies
4792 the new backing store pointer.
4794 If EntryPoint is NULL, then ASSERT().
4795 If NewStack is NULL, then ASSERT().
4797 @param EntryPoint A pointer to function to call with the new stack.
4798 @param Context1 A pointer to the context to pass into the EntryPoint
4800 @param Context2 A pointer to the context to pass into the EntryPoint
4802 @param NewStack A pointer to the new stack to use for the EntryPoint
4804 @param ... This variable argument list is ignored for IA-32, x64, and
4805 EBC architectures. For Itanium processors, this variable
4806 argument list is expected to contain a single parameter of
4807 type VOID * that specifies the new backing store pointer.
4814 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
4815 IN VOID
*Context1 OPTIONAL
,
4816 IN VOID
*Context2 OPTIONAL
,
4823 Generates a breakpoint on the CPU.
4825 Generates a breakpoint on the CPU. The breakpoint must be implemented such
4826 that code can resume normal execution after the breakpoint.
4837 Executes an infinite loop.
4839 Forces the CPU to execute an infinite loop. A debugger may be used to skip
4840 past the loop and the code that follows the loop must execute properly. This
4841 implies that the infinite loop must not cause the code that follow it to be
4853 Uses as a barrier to stop speculative execution.
4855 Ensures that no later instruction will execute speculatively, until all prior
4856 instructions have completed.
4861 SpeculationBarrier (
4865 #if defined (MDE_CPU_X64)
4867 // The page size for the PVALIDATE instruction
4870 PvalidatePageSize4K
= 0,
4871 PvalidatePageSize2MB
,
4872 } PVALIDATE_PAGE_SIZE
;
4875 // PVALIDATE Return Code.
4877 #define PVALIDATE_RET_SUCCESS 0
4878 #define PVALIDATE_RET_FAIL_INPUT 1
4879 #define PVALIDATE_RET_SIZE_MISMATCH 6
4882 // The PVALIDATE instruction did not make any changes to the RMP entry.
4884 #define PVALIDATE_RET_NO_RMPUPDATE 255
4887 Execute a PVALIDATE instruction to validate or to rescinds validation of a guest
4890 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
4892 The function is available on X64.
4894 @param[in] PageSize The page size to use.
4895 @param[in] Validate If TRUE, validate the guest virtual address
4896 otherwise invalidate the guest virtual address.
4897 @param[in] Address The guest virtual address.
4899 @retval PVALIDATE_RET_SUCCESS The PVALIDATE instruction succeeded, and
4900 updated the RMP entry.
4901 @retval PVALIDATE_RET_NO_RMPUPDATE The PVALIDATE instruction succeeded, but
4902 did not update the RMP entry.
4903 @return Failure code from the PVALIDATE
4909 IN PVALIDATE_PAGE_SIZE PageSize
,
4910 IN BOOLEAN Validate
,
4911 IN PHYSICAL_ADDRESS Address
4915 // RDX settings for RMPADJUST
4917 #define RMPADJUST_VMPL_MAX 3
4918 #define RMPADJUST_VMPL_MASK 0xFF
4919 #define RMPADJUST_VMPL_SHIFT 0
4920 #define RMPADJUST_PERMISSION_MASK_MASK 0xFF
4921 #define RMPADJUST_PERMISSION_MASK_SHIFT 8
4922 #define RMPADJUST_VMSA_PAGE_BIT BIT16
4925 Adjusts the permissions of an SEV-SNP guest page.
4927 Executes a RMPADJUST instruction with the register state specified by Rax,
4928 Rcx, and Rdx. Returns Eax. This function is only available on X64.
4930 The instruction is available only when CPUID Fn8000_001F_EAX[SNP]=1.
4932 @param[in] Rax The value to load into RAX before executing the RMPADJUST
4934 @param[in] Rcx The value to load into RCX before executing the RMPADJUST
4936 @param[in] Rdx The value to load into RDX before executing the RMPADJUST
4951 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
4953 /// IA32 and x64 Specific Functions.
4954 /// Byte packed structure for 16-bit Real Mode EFLAGS.
4958 UINT32 CF
:1; ///< Carry Flag.
4959 UINT32 Reserved_0
:1; ///< Reserved.
4960 UINT32 PF
:1; ///< Parity Flag.
4961 UINT32 Reserved_1
:1; ///< Reserved.
4962 UINT32 AF
:1; ///< Auxiliary Carry Flag.
4963 UINT32 Reserved_2
:1; ///< Reserved.
4964 UINT32 ZF
:1; ///< Zero Flag.
4965 UINT32 SF
:1; ///< Sign Flag.
4966 UINT32 TF
:1; ///< Trap Flag.
4967 UINT32 IF
:1; ///< Interrupt Enable Flag.
4968 UINT32 DF
:1; ///< Direction Flag.
4969 UINT32 OF
:1; ///< Overflow Flag.
4970 UINT32 IOPL
:2; ///< I/O Privilege Level.
4971 UINT32 NT
:1; ///< Nested Task.
4972 UINT32 Reserved_3
:1; ///< Reserved.
4978 /// Byte packed structure for EFLAGS/RFLAGS.
4979 /// 32-bits on IA-32.
4980 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
4984 UINT32 CF
:1; ///< Carry Flag.
4985 UINT32 Reserved_0
:1; ///< Reserved.
4986 UINT32 PF
:1; ///< Parity Flag.
4987 UINT32 Reserved_1
:1; ///< Reserved.
4988 UINT32 AF
:1; ///< Auxiliary Carry Flag.
4989 UINT32 Reserved_2
:1; ///< Reserved.
4990 UINT32 ZF
:1; ///< Zero Flag.
4991 UINT32 SF
:1; ///< Sign Flag.
4992 UINT32 TF
:1; ///< Trap Flag.
4993 UINT32 IF
:1; ///< Interrupt Enable Flag.
4994 UINT32 DF
:1; ///< Direction Flag.
4995 UINT32 OF
:1; ///< Overflow Flag.
4996 UINT32 IOPL
:2; ///< I/O Privilege Level.
4997 UINT32 NT
:1; ///< Nested Task.
4998 UINT32 Reserved_3
:1; ///< Reserved.
4999 UINT32 RF
:1; ///< Resume Flag.
5000 UINT32 VM
:1; ///< Virtual 8086 Mode.
5001 UINT32 AC
:1; ///< Alignment Check.
5002 UINT32 VIF
:1; ///< Virtual Interrupt Flag.
5003 UINT32 VIP
:1; ///< Virtual Interrupt Pending.
5004 UINT32 ID
:1; ///< ID Flag.
5005 UINT32 Reserved_4
:10; ///< Reserved.
5011 /// Byte packed structure for Control Register 0 (CR0).
5012 /// 32-bits on IA-32.
5013 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5017 UINT32 PE
:1; ///< Protection Enable.
5018 UINT32 MP
:1; ///< Monitor Coprocessor.
5019 UINT32 EM
:1; ///< Emulation.
5020 UINT32 TS
:1; ///< Task Switched.
5021 UINT32 ET
:1; ///< Extension Type.
5022 UINT32 NE
:1; ///< Numeric Error.
5023 UINT32 Reserved_0
:10; ///< Reserved.
5024 UINT32 WP
:1; ///< Write Protect.
5025 UINT32 Reserved_1
:1; ///< Reserved.
5026 UINT32 AM
:1; ///< Alignment Mask.
5027 UINT32 Reserved_2
:10; ///< Reserved.
5028 UINT32 NW
:1; ///< Mot Write-through.
5029 UINT32 CD
:1; ///< Cache Disable.
5030 UINT32 PG
:1; ///< Paging.
5036 /// Byte packed structure for Control Register 4 (CR4).
5037 /// 32-bits on IA-32.
5038 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5042 UINT32 VME
:1; ///< Virtual-8086 Mode Extensions.
5043 UINT32 PVI
:1; ///< Protected-Mode Virtual Interrupts.
5044 UINT32 TSD
:1; ///< Time Stamp Disable.
5045 UINT32 DE
:1; ///< Debugging Extensions.
5046 UINT32 PSE
:1; ///< Page Size Extensions.
5047 UINT32 PAE
:1; ///< Physical Address Extension.
5048 UINT32 MCE
:1; ///< Machine Check Enable.
5049 UINT32 PGE
:1; ///< Page Global Enable.
5050 UINT32 PCE
:1; ///< Performance Monitoring Counter
5052 UINT32 OSFXSR
:1; ///< Operating System Support for
5053 ///< FXSAVE and FXRSTOR instructions
5054 UINT32 OSXMMEXCPT
:1; ///< Operating System Support for
5055 ///< Unmasked SIMD Floating Point
5057 UINT32 UMIP
:1; ///< User-Mode Instruction Prevention.
5058 UINT32 LA57
:1; ///< Linear Address 57bit.
5059 UINT32 VMXE
:1; ///< VMX Enable.
5060 UINT32 SMXE
:1; ///< SMX Enable.
5061 UINT32 Reserved_3
:1; ///< Reserved.
5062 UINT32 FSGSBASE
:1; ///< FSGSBASE Enable.
5063 UINT32 PCIDE
:1; ///< PCID Enable.
5064 UINT32 OSXSAVE
:1; ///< XSAVE and Processor Extended States Enable.
5065 UINT32 Reserved_4
:1; ///< Reserved.
5066 UINT32 SMEP
:1; ///< SMEP Enable.
5067 UINT32 SMAP
:1; ///< SMAP Enable.
5068 UINT32 PKE
:1; ///< Protection-Key Enable.
5069 UINT32 Reserved_5
:9; ///< Reserved.
5075 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5094 } IA32_SEGMENT_DESCRIPTOR
;
5097 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5106 #define IA32_IDT_GATE_TYPE_TASK 0x85
5107 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5108 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5109 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5110 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5112 #define IA32_GDT_TYPE_TSS 0x9
5113 #define IA32_GDT_ALIGNMENT 8
5115 #if defined (MDE_CPU_IA32)
5117 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5121 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5122 UINT32 Selector
:16; ///< Selector.
5123 UINT32 Reserved_0
:8; ///< Reserved.
5124 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5125 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5128 } IA32_IDT_GATE_DESCRIPTOR
;
5132 // IA32 Task-State Segment Definition
5135 UINT16 PreviousTaskLink
;
5169 UINT16 LDTSegmentSelector
;
5172 UINT16 IOMapBaseAddress
;
5173 } IA32_TASK_STATE_SEGMENT
;
5177 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5178 UINT32 BaseLow
:16; ///< Base Address 15..00
5179 UINT32 BaseMid
:8; ///< Base Address 23..16
5180 UINT32 Type
:4; ///< Type (1 0 B 1)
5181 UINT32 Reserved_43
:1; ///< 0
5182 UINT32 DPL
:2; ///< Descriptor Privilege Level
5183 UINT32 P
:1; ///< Segment Present
5184 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5185 UINT32 AVL
:1; ///< Available for use by system software
5186 UINT32 Reserved_52
:2; ///< 0 0
5187 UINT32 G
:1; ///< Granularity
5188 UINT32 BaseHigh
:8; ///< Base Address 31..24
5191 } IA32_TSS_DESCRIPTOR
;
5194 #endif // defined (MDE_CPU_IA32)
5196 #if defined (MDE_CPU_X64)
5198 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5202 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5203 UINT32 Selector
:16; ///< Selector.
5204 UINT32 Reserved_0
:8; ///< Reserved.
5205 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5206 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5207 UINT32 OffsetUpper
:32; ///< Offset bits 63..32.
5208 UINT32 Reserved_1
:32; ///< Reserved.
5214 } IA32_IDT_GATE_DESCRIPTOR
;
5218 // IA32 Task-State Segment Definition
5228 UINT16 Reserved_100
;
5229 UINT16 IOMapBaseAddress
;
5230 } IA32_TASK_STATE_SEGMENT
;
5234 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5235 UINT32 BaseLow
:16; ///< Base Address 15..00
5236 UINT32 BaseMidl
:8; ///< Base Address 23..16
5237 UINT32 Type
:4; ///< Type (1 0 B 1)
5238 UINT32 Reserved_43
:1; ///< 0
5239 UINT32 DPL
:2; ///< Descriptor Privilege Level
5240 UINT32 P
:1; ///< Segment Present
5241 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5242 UINT32 AVL
:1; ///< Available for use by system software
5243 UINT32 Reserved_52
:2; ///< 0 0
5244 UINT32 G
:1; ///< Granularity
5245 UINT32 BaseMidh
:8; ///< Base Address 31..24
5246 UINT32 BaseHigh
:32; ///< Base Address 63..32
5247 UINT32 Reserved_96
:32; ///< Reserved
5253 } IA32_TSS_DESCRIPTOR
;
5256 #endif // defined (MDE_CPU_X64)
5259 /// Byte packed structure for an FP/SSE/SSE2 context.
5266 /// Structures for the 16-bit real mode thunks.
5319 IA32_EFLAGS32 EFLAGS
;
5329 } IA32_REGISTER_SET
;
5332 /// Byte packed structure for an 16-bit real mode thunks.
5335 IA32_REGISTER_SET
*RealModeState
;
5336 VOID
*RealModeBuffer
;
5337 UINT32 RealModeBufferSize
;
5338 UINT32 ThunkAttributes
;
5341 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5342 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5343 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5346 /// Type definition for representing labels in NASM source code that allow for
5347 /// the patching of immediate operands of IA32 and X64 instructions.
5349 /// While the type is technically defined as a function type (note: not a
5350 /// pointer-to-function type), such labels in NASM source code never stand for
5351 /// actual functions, and identifiers declared with this function type should
5352 /// never be called. This is also why the EFIAPI calling convention specifier
5353 /// is missing from the typedef, and why the typedef does not follow the usual
5354 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5355 /// return type and the VOID argument list are merely artifacts.
5357 typedef VOID (X86_ASSEMBLY_PATCH_LABEL
) (VOID
);
5360 Retrieves CPUID information.
5362 Executes the CPUID instruction with EAX set to the value specified by Index.
5363 This function always returns Index.
5364 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5365 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5366 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5367 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5368 This function is only available on IA-32 and x64.
5370 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5372 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5373 instruction. This is an optional parameter that may be NULL.
5374 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5375 instruction. This is an optional parameter that may be NULL.
5376 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5377 instruction. This is an optional parameter that may be NULL.
5378 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5379 instruction. This is an optional parameter that may be NULL.
5388 OUT UINT32
*Eax OPTIONAL
,
5389 OUT UINT32
*Ebx OPTIONAL
,
5390 OUT UINT32
*Ecx OPTIONAL
,
5391 OUT UINT32
*Edx OPTIONAL
5396 Retrieves CPUID information using an extended leaf identifier.
5398 Executes the CPUID instruction with EAX set to the value specified by Index
5399 and ECX set to the value specified by SubIndex. This function always returns
5400 Index. This function is only available on IA-32 and x64.
5402 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5403 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5404 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5405 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5407 @param Index The 32-bit value to load into EAX prior to invoking the
5409 @param SubIndex The 32-bit value to load into ECX prior to invoking the
5411 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5412 instruction. This is an optional parameter that may be
5414 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5415 instruction. This is an optional parameter that may be
5417 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5418 instruction. This is an optional parameter that may be
5420 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5421 instruction. This is an optional parameter that may be
5432 OUT UINT32
*Eax OPTIONAL
,
5433 OUT UINT32
*Ebx OPTIONAL
,
5434 OUT UINT32
*Ecx OPTIONAL
,
5435 OUT UINT32
*Edx OPTIONAL
5440 Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5442 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5443 and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5454 Perform a WBINVD and clear both the CD and NW bits of CR0.
5456 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5457 bits of CR0 to 0. This function is only available on IA-32 and x64.
5468 Returns the lower 32-bits of a Machine Specific Register(MSR).
5470 Reads and returns the lower 32-bits of the MSR specified by Index.
5471 No parameter checking is performed on Index, and some Index values may cause
5472 CPU exceptions. The caller must either guarantee that Index is valid, or the
5473 caller must set up exception handlers to catch the exceptions. This function
5474 is only available on IA-32 and x64.
5476 @param Index The 32-bit MSR index to read.
5478 @return The lower 32 bits of the MSR identified by Index.
5489 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5490 The upper 32-bits of the MSR are set to zero.
5492 Writes the 32-bit value specified by Value to the MSR specified by Index. The
5493 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5494 the MSR is returned. No parameter checking is performed on Index or Value,
5495 and some of these may cause CPU exceptions. The caller must either guarantee
5496 that Index and Value are valid, or the caller must establish proper exception
5497 handlers. This function is only available on IA-32 and x64.
5499 @param Index The 32-bit MSR index to write.
5500 @param Value The 32-bit value to write to the MSR.
5514 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5515 writes the result back to the 64-bit MSR.
5517 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5518 between the lower 32-bits of the read result and the value specified by
5519 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5520 32-bits of the value written to the MSR is returned. No parameter checking is
5521 performed on Index or OrData, and some of these may cause CPU exceptions. The
5522 caller must either guarantee that Index and OrData are valid, or the caller
5523 must establish proper exception handlers. This function is only available on
5526 @param Index The 32-bit MSR index to write.
5527 @param OrData The value to OR with the read value from the MSR.
5529 @return The lower 32-bit value written to the MSR.
5541 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5542 the result back to the 64-bit MSR.
5544 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5545 lower 32-bits of the read result and the value specified by AndData, and
5546 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5547 the value written to the MSR is returned. No parameter checking is performed
5548 on Index or AndData, and some of these may cause CPU exceptions. The caller
5549 must either guarantee that Index and AndData are valid, or the caller must
5550 establish proper exception handlers. This function is only available on IA-32
5553 @param Index The 32-bit MSR index to write.
5554 @param AndData The value to AND with the read value from the MSR.
5556 @return The lower 32-bit value written to the MSR.
5568 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5569 on the lower 32-bits, and writes the result back to the 64-bit MSR.
5571 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5572 lower 32-bits of the read result and the value specified by AndData
5573 preserving the upper 32-bits, performs a bitwise OR between the
5574 result of the AND operation and the value specified by OrData, and writes the
5575 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5576 written to the MSR is returned. No parameter checking is performed on Index,
5577 AndData, or OrData, and some of these may cause CPU exceptions. The caller
5578 must either guarantee that Index, AndData, and OrData are valid, or the
5579 caller must establish proper exception handlers. This function is only
5580 available on IA-32 and x64.
5582 @param Index The 32-bit MSR index to write.
5583 @param AndData The value to AND with the read value from the MSR.
5584 @param OrData The value to OR with the result of the AND operation.
5586 @return The lower 32-bit value written to the MSR.
5599 Reads a bit field of an MSR.
5601 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5602 specified by the StartBit and the EndBit. The value of the bit field is
5603 returned. The caller must either guarantee that Index is valid, or the caller
5604 must set up exception handlers to catch the exceptions. This function is only
5605 available on IA-32 and x64.
5607 If StartBit is greater than 31, then ASSERT().
5608 If EndBit is greater than 31, then ASSERT().
5609 If EndBit is less than StartBit, then ASSERT().
5611 @param Index The 32-bit MSR index to read.
5612 @param StartBit The ordinal of the least significant bit in the bit field.
5614 @param EndBit The ordinal of the most significant bit in the bit field.
5617 @return The bit field read from the MSR.
5622 AsmMsrBitFieldRead32 (
5630 Writes a bit field to an MSR.
5632 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5633 field is specified by the StartBit and the EndBit. All other bits in the
5634 destination MSR are preserved. The lower 32-bits of the MSR written is
5635 returned. The caller must either guarantee that Index and the data written
5636 is valid, or the caller must set up exception handlers to catch the exceptions.
5637 This function is only available on IA-32 and x64.
5639 If StartBit is greater than 31, then ASSERT().
5640 If EndBit is greater than 31, then ASSERT().
5641 If EndBit is less than StartBit, then ASSERT().
5642 If Value 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 Value New value of the bit field.
5651 @return The lower 32-bit of the value written to the MSR.
5656 AsmMsrBitFieldWrite32 (
5665 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5666 result back to the bit field in the 64-bit MSR.
5668 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5669 between the read result and the value specified by OrData, and writes the
5670 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
5671 written to the MSR are returned. Extra left bits in OrData are stripped. The
5672 caller must either guarantee that Index and the data written is valid, or
5673 the caller must set up exception handlers to catch the exceptions. This
5674 function is only available on IA-32 and x64.
5676 If StartBit is greater than 31, then ASSERT().
5677 If EndBit is greater than 31, then ASSERT().
5678 If EndBit is less than StartBit, then ASSERT().
5679 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5681 @param Index The 32-bit MSR index to write.
5682 @param StartBit The ordinal of the least significant bit in the bit field.
5684 @param EndBit The ordinal of the most significant bit in the bit field.
5686 @param OrData The value to OR with the read value from the MSR.
5688 @return The lower 32-bit of the value written to the MSR.
5693 AsmMsrBitFieldOr32 (
5702 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5703 result back to the bit field in the 64-bit MSR.
5705 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5706 read result and the value specified by AndData, and writes the result to the
5707 64-bit MSR specified by Index. The lower 32-bits of the value written to the
5708 MSR are returned. Extra left bits in AndData are stripped. The caller must
5709 either guarantee that Index and the data written is valid, or the caller must
5710 set up exception handlers to catch the exceptions. This function is only
5711 available on IA-32 and x64.
5713 If StartBit is greater than 31, then ASSERT().
5714 If EndBit is greater than 31, then ASSERT().
5715 If EndBit is less than StartBit, then ASSERT().
5716 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5718 @param Index The 32-bit MSR index to write.
5719 @param StartBit The ordinal of the least significant bit in the bit field.
5721 @param EndBit The ordinal of the most significant bit in the bit field.
5723 @param AndData The value to AND with the read value from the MSR.
5725 @return The lower 32-bit of the value written to the MSR.
5730 AsmMsrBitFieldAnd32 (
5739 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
5740 bitwise OR, and writes the result back to the bit field in the
5743 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
5744 bitwise OR between the read result and the value specified by
5745 AndData, and writes the result to the 64-bit MSR specified by Index. The
5746 lower 32-bits of the value written to the MSR are returned. Extra left bits
5747 in both AndData and OrData are stripped. The caller must either guarantee
5748 that Index and the data written is valid, or the caller must set up exception
5749 handlers to catch the exceptions. This function is only available on IA-32
5752 If StartBit is greater than 31, then ASSERT().
5753 If EndBit is greater than 31, then ASSERT().
5754 If EndBit is less than StartBit, then ASSERT().
5755 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5756 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5758 @param Index The 32-bit MSR index to write.
5759 @param StartBit The ordinal of the least significant bit in the bit field.
5761 @param EndBit The ordinal of the most significant bit in the bit field.
5763 @param AndData The value to AND with the read value from the MSR.
5764 @param OrData The value to OR with the result of the AND operation.
5766 @return The lower 32-bit of the value written to the MSR.
5771 AsmMsrBitFieldAndThenOr32 (
5781 Returns a 64-bit Machine Specific Register(MSR).
5783 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
5784 performed on Index, and some Index values may cause CPU exceptions. The
5785 caller must either guarantee that Index is valid, or the caller must set up
5786 exception handlers to catch the exceptions. This function is only available
5789 @param Index The 32-bit MSR index to read.
5791 @return The value of the MSR identified by Index.
5802 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
5805 Writes the 64-bit value specified by Value to the MSR specified by Index. The
5806 64-bit value written to the MSR is returned. No parameter checking is
5807 performed on Index or Value, and some of these may cause CPU exceptions. The
5808 caller must either guarantee that Index and Value are valid, or the caller
5809 must establish proper exception handlers. This function is only available on
5812 @param Index The 32-bit MSR index to write.
5813 @param Value The 64-bit value to write to the MSR.
5827 Reads a 64-bit MSR, performs a bitwise OR, and writes the result
5828 back to the 64-bit MSR.
5830 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5831 between the read result and the value specified by OrData, and writes the
5832 result to the 64-bit MSR specified by Index. The value written to the MSR is
5833 returned. No parameter checking is performed on Index or OrData, and some of
5834 these may cause CPU exceptions. The caller must either guarantee that Index
5835 and OrData are valid, or the caller must establish proper exception handlers.
5836 This function is only available on IA-32 and x64.
5838 @param Index The 32-bit MSR index to write.
5839 @param OrData The value to OR with the read value from the MSR.
5841 @return The value written back to the MSR.
5853 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
5856 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5857 read result and the value specified by OrData, and writes the result to the
5858 64-bit MSR specified by Index. The value written to the MSR is returned. No
5859 parameter checking is performed on Index or OrData, and some of these may
5860 cause CPU exceptions. The caller must either guarantee that Index and OrData
5861 are valid, or the caller must establish proper exception handlers. This
5862 function is only available on IA-32 and x64.
5864 @param Index The 32-bit MSR index to write.
5865 @param AndData The value to AND with the read value from the MSR.
5867 @return The value written back to the MSR.
5879 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
5880 OR, and writes the result back to the 64-bit MSR.
5882 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
5883 result and the value specified by AndData, performs a bitwise OR
5884 between the result of the AND operation and the value specified by OrData,
5885 and writes the result to the 64-bit MSR specified by Index. The value written
5886 to the MSR is returned. No parameter checking is performed on Index, AndData,
5887 or OrData, and some of these may cause CPU exceptions. The caller must either
5888 guarantee that Index, AndData, and OrData are valid, or the caller must
5889 establish proper exception handlers. This function is only available on IA-32
5892 @param Index The 32-bit MSR index to write.
5893 @param AndData The value to AND with the read value from the MSR.
5894 @param OrData The value to OR with the result of the AND operation.
5896 @return The value written back to the MSR.
5909 Reads a bit field of an MSR.
5911 Reads the bit field in the 64-bit MSR. The bit field is specified by the
5912 StartBit and the EndBit. The value of the bit field is returned. The caller
5913 must either guarantee that Index is valid, or the caller must set up
5914 exception handlers to catch the exceptions. This function is only available
5917 If StartBit is greater than 63, then ASSERT().
5918 If EndBit is greater than 63, then ASSERT().
5919 If EndBit is less than StartBit, then ASSERT().
5921 @param Index The 32-bit MSR index to read.
5922 @param StartBit The ordinal of the least significant bit in the bit field.
5924 @param EndBit The ordinal of the most significant bit in the bit field.
5927 @return The value read from the MSR.
5932 AsmMsrBitFieldRead64 (
5940 Writes a bit field to an MSR.
5942 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
5943 the StartBit and the EndBit. All other bits in the destination MSR are
5944 preserved. The MSR written is returned. The caller must either guarantee
5945 that Index and the data written is valid, or the caller must set up exception
5946 handlers to catch the exceptions. This function is only available on IA-32 and x64.
5948 If StartBit is greater than 63, then ASSERT().
5949 If EndBit is greater than 63, then ASSERT().
5950 If EndBit is less than StartBit, then ASSERT().
5951 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5953 @param Index The 32-bit MSR index to write.
5954 @param StartBit The ordinal of the least significant bit in the bit field.
5956 @param EndBit The ordinal of the most significant bit in the bit field.
5958 @param Value New value of the bit field.
5960 @return The value written back to the MSR.
5965 AsmMsrBitFieldWrite64 (
5974 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
5975 writes the result back to the bit field in the 64-bit MSR.
5977 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5978 between the read result and the value specified by OrData, and writes the
5979 result to the 64-bit MSR specified by Index. The value written to the MSR is
5980 returned. Extra left bits in OrData are stripped. The caller must either
5981 guarantee that Index and the data written is valid, or the caller must set up
5982 exception handlers to catch the exceptions. This function is only available
5985 If StartBit is greater than 63, then ASSERT().
5986 If EndBit is greater than 63, then ASSERT().
5987 If EndBit is less than StartBit, then ASSERT().
5988 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5990 @param Index The 32-bit MSR index to write.
5991 @param StartBit The ordinal of the least significant bit in the bit field.
5993 @param EndBit The ordinal of the most significant bit in the bit field.
5995 @param OrData The value to OR with the read value from the bit field.
5997 @return The value written back to the MSR.
6002 AsmMsrBitFieldOr64 (
6011 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6012 result back to the bit field in the 64-bit MSR.
6014 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6015 read result and the value specified by AndData, and writes the result to the
6016 64-bit MSR specified by Index. The value written to the MSR is returned.
6017 Extra left bits in AndData are stripped. The caller must either guarantee
6018 that Index and the data written is valid, or the caller must set up exception
6019 handlers to catch the exceptions. This function is only available on IA-32
6022 If StartBit is greater than 63, then ASSERT().
6023 If EndBit is greater than 63, then ASSERT().
6024 If EndBit is less than StartBit, then ASSERT().
6025 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6027 @param Index The 32-bit MSR index to write.
6028 @param StartBit The ordinal of the least significant bit in the bit field.
6030 @param EndBit The ordinal of the most significant bit in the bit field.
6032 @param AndData The value to AND with the read value from the bit field.
6034 @return The value written back to the MSR.
6039 AsmMsrBitFieldAnd64 (
6048 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6049 bitwise OR, and writes the result back to the bit field in the
6052 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6053 a bitwise OR between the read result and the value specified by
6054 AndData, and writes the result to the 64-bit MSR specified by Index. The
6055 value written to the MSR is returned. Extra left bits in both AndData and
6056 OrData are stripped. The caller must either guarantee that Index and the data
6057 written is valid, or the caller must set up exception handlers to catch the
6058 exceptions. This function is only available on IA-32 and x64.
6060 If StartBit is greater than 63, then ASSERT().
6061 If EndBit is greater than 63, then ASSERT().
6062 If EndBit is less than StartBit, then ASSERT().
6063 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6064 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6066 @param Index The 32-bit MSR index to write.
6067 @param StartBit The ordinal of the least significant bit in the bit field.
6069 @param EndBit The ordinal of the most significant bit in the bit field.
6071 @param AndData The value to AND with the read value from the bit field.
6072 @param OrData The value to OR with the result of the AND operation.
6074 @return The value written back to the MSR.
6079 AsmMsrBitFieldAndThenOr64 (
6089 Reads the current value of the EFLAGS register.
6091 Reads and returns the current value of the EFLAGS register. This function is
6092 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6093 64-bit value on x64.
6095 @return EFLAGS on IA-32 or RFLAGS on x64.
6106 Reads the current value of the Control Register 0 (CR0).
6108 Reads and returns the current value of CR0. This function is only available
6109 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6112 @return The value of the Control Register 0 (CR0).
6123 Reads the current value of the Control Register 2 (CR2).
6125 Reads and returns the current value of CR2. This function is only available
6126 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6129 @return The value of the Control Register 2 (CR2).
6140 Reads the current value of the Control Register 3 (CR3).
6142 Reads and returns the current value of CR3. This function is only available
6143 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6146 @return The value of the Control Register 3 (CR3).
6157 Reads the current value of the Control Register 4 (CR4).
6159 Reads and returns the current value of CR4. This function is only available
6160 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6163 @return The value of the Control Register 4 (CR4).
6174 Writes a value to Control Register 0 (CR0).
6176 Writes and returns a new value to CR0. This function is only available on
6177 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6179 @param Cr0 The value to write to CR0.
6181 @return The value written to CR0.
6192 Writes a value to Control Register 2 (CR2).
6194 Writes and returns a new value to CR2. This function is only available on
6195 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6197 @param Cr2 The value to write to CR2.
6199 @return The value written to CR2.
6210 Writes a value to Control Register 3 (CR3).
6212 Writes and returns a new value to CR3. This function is only available on
6213 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6215 @param Cr3 The value to write to CR3.
6217 @return The value written to CR3.
6228 Writes a value to Control Register 4 (CR4).
6230 Writes and returns a new value to CR4. This function is only available on
6231 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6233 @param Cr4 The value to write to CR4.
6235 @return The value written to CR4.
6246 Reads the current value of Debug Register 0 (DR0).
6248 Reads and returns the current value of DR0. This function is only available
6249 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6252 @return The value of Debug Register 0 (DR0).
6263 Reads the current value of Debug Register 1 (DR1).
6265 Reads and returns the current value of DR1. This function is only available
6266 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6269 @return The value of Debug Register 1 (DR1).
6280 Reads the current value of Debug Register 2 (DR2).
6282 Reads and returns the current value of DR2. This function is only available
6283 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6286 @return The value of Debug Register 2 (DR2).
6297 Reads the current value of Debug Register 3 (DR3).
6299 Reads and returns the current value of DR3. This function is only available
6300 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6303 @return The value of Debug Register 3 (DR3).
6314 Reads the current value of Debug Register 4 (DR4).
6316 Reads and returns the current value of DR4. This function is only available
6317 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6320 @return The value of Debug Register 4 (DR4).
6331 Reads the current value of Debug Register 5 (DR5).
6333 Reads and returns the current value of DR5. This function is only available
6334 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6337 @return The value of Debug Register 5 (DR5).
6348 Reads the current value of Debug Register 6 (DR6).
6350 Reads and returns the current value of DR6. This function is only available
6351 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6354 @return The value of Debug Register 6 (DR6).
6365 Reads the current value of Debug Register 7 (DR7).
6367 Reads and returns the current value of DR7. This function is only available
6368 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6371 @return The value of Debug Register 7 (DR7).
6382 Writes a value to Debug Register 0 (DR0).
6384 Writes and returns a new value to DR0. This function is only available on
6385 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6387 @param Dr0 The value to write to Dr0.
6389 @return The value written to Debug Register 0 (DR0).
6400 Writes a value to Debug Register 1 (DR1).
6402 Writes and returns a new value to DR1. This function is only available on
6403 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6405 @param Dr1 The value to write to Dr1.
6407 @return The value written to Debug Register 1 (DR1).
6418 Writes a value to Debug Register 2 (DR2).
6420 Writes and returns a new value to DR2. This function is only available on
6421 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6423 @param Dr2 The value to write to Dr2.
6425 @return The value written to Debug Register 2 (DR2).
6436 Writes a value to Debug Register 3 (DR3).
6438 Writes and returns a new value to DR3. This function is only available on
6439 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6441 @param Dr3 The value to write to Dr3.
6443 @return The value written to Debug Register 3 (DR3).
6454 Writes a value to Debug Register 4 (DR4).
6456 Writes and returns a new value to DR4. This function is only available on
6457 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6459 @param Dr4 The value to write to Dr4.
6461 @return The value written to Debug Register 4 (DR4).
6472 Writes a value to Debug Register 5 (DR5).
6474 Writes and returns a new value to DR5. This function is only available on
6475 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6477 @param Dr5 The value to write to Dr5.
6479 @return The value written to Debug Register 5 (DR5).
6490 Writes a value to Debug Register 6 (DR6).
6492 Writes and returns a new value to DR6. This function is only available on
6493 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6495 @param Dr6 The value to write to Dr6.
6497 @return The value written to Debug Register 6 (DR6).
6508 Writes a value to Debug Register 7 (DR7).
6510 Writes and returns a new value to DR7. This function is only available on
6511 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6513 @param Dr7 The value to write to Dr7.
6515 @return The value written to Debug Register 7 (DR7).
6526 Reads the current value of Code Segment Register (CS).
6528 Reads and returns the current value of CS. This function is only available on
6531 @return The current value of CS.
6542 Reads the current value of Data Segment Register (DS).
6544 Reads and returns the current value of DS. This function is only available on
6547 @return The current value of DS.
6558 Reads the current value of Extra Segment Register (ES).
6560 Reads and returns the current value of ES. This function is only available on
6563 @return The current value of ES.
6574 Reads the current value of FS Data Segment Register (FS).
6576 Reads and returns the current value of FS. This function is only available on
6579 @return The current value of FS.
6590 Reads the current value of GS Data Segment Register (GS).
6592 Reads and returns the current value of GS. This function is only available on
6595 @return The current value of GS.
6606 Reads the current value of Stack Segment Register (SS).
6608 Reads and returns the current value of SS. This function is only available on
6611 @return The current value of SS.
6622 Reads the current value of Task Register (TR).
6624 Reads and returns the current value of TR. This function is only available on
6627 @return The current value of TR.
6638 Reads the current Global Descriptor Table Register(GDTR) descriptor.
6640 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6641 function is only available on IA-32 and x64.
6643 If Gdtr is NULL, then ASSERT().
6645 @param Gdtr The pointer to a GDTR descriptor.
6651 OUT IA32_DESCRIPTOR
*Gdtr
6656 Writes the current Global Descriptor Table Register (GDTR) descriptor.
6658 Writes and the current GDTR descriptor specified by Gdtr. This function is
6659 only available on IA-32 and x64.
6661 If Gdtr is NULL, then ASSERT().
6663 @param Gdtr The pointer to a GDTR descriptor.
6669 IN CONST IA32_DESCRIPTOR
*Gdtr
6674 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
6676 Reads and returns the current IDTR descriptor and returns it in Idtr. This
6677 function is only available on IA-32 and x64.
6679 If Idtr is NULL, then ASSERT().
6681 @param Idtr The pointer to a IDTR descriptor.
6687 OUT IA32_DESCRIPTOR
*Idtr
6692 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
6694 Writes the current IDTR descriptor and returns it in Idtr. This function is
6695 only available on IA-32 and x64.
6697 If Idtr is NULL, then ASSERT().
6699 @param Idtr The pointer to a IDTR descriptor.
6705 IN CONST IA32_DESCRIPTOR
*Idtr
6710 Reads the current Local Descriptor Table Register(LDTR) selector.
6712 Reads and returns the current 16-bit LDTR descriptor value. This function is
6713 only available on IA-32 and x64.
6715 @return The current selector of LDT.
6726 Writes the current Local Descriptor Table Register (LDTR) selector.
6728 Writes and the current LDTR descriptor specified by Ldtr. This function is
6729 only available on IA-32 and x64.
6731 @param Ldtr 16-bit LDTR selector value.
6742 Save the current floating point/SSE/SSE2 context to a buffer.
6744 Saves the current floating point/SSE/SSE2 state to the buffer specified by
6745 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
6746 available on IA-32 and x64.
6748 If Buffer is NULL, then ASSERT().
6749 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6751 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
6757 OUT IA32_FX_BUFFER
*Buffer
6762 Restores the current floating point/SSE/SSE2 context from a buffer.
6764 Restores the current floating point/SSE/SSE2 state from the buffer specified
6765 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
6766 only available on IA-32 and x64.
6768 If Buffer is NULL, then ASSERT().
6769 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
6770 If Buffer was not saved with AsmFxSave(), then ASSERT().
6772 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
6778 IN CONST IA32_FX_BUFFER
*Buffer
6783 Reads the current value of 64-bit MMX Register #0 (MM0).
6785 Reads and returns the current value of MM0. This function is only available
6788 @return The current value of MM0.
6799 Reads the current value of 64-bit MMX Register #1 (MM1).
6801 Reads and returns the current value of MM1. This function is only available
6804 @return The current value of MM1.
6815 Reads the current value of 64-bit MMX Register #2 (MM2).
6817 Reads and returns the current value of MM2. This function is only available
6820 @return The current value of MM2.
6831 Reads the current value of 64-bit MMX Register #3 (MM3).
6833 Reads and returns the current value of MM3. This function is only available
6836 @return The current value of MM3.
6847 Reads the current value of 64-bit MMX Register #4 (MM4).
6849 Reads and returns the current value of MM4. This function is only available
6852 @return The current value of MM4.
6863 Reads the current value of 64-bit MMX Register #5 (MM5).
6865 Reads and returns the current value of MM5. This function is only available
6868 @return The current value of MM5.
6879 Reads the current value of 64-bit MMX Register #6 (MM6).
6881 Reads and returns the current value of MM6. This function is only available
6884 @return The current value of MM6.
6895 Reads the current value of 64-bit MMX Register #7 (MM7).
6897 Reads and returns the current value of MM7. This function is only available
6900 @return The current value of MM7.
6911 Writes the current value of 64-bit MMX Register #0 (MM0).
6913 Writes the current value of MM0. This function is only available on IA32 and
6916 @param Value The 64-bit value to write to MM0.
6927 Writes the current value of 64-bit MMX Register #1 (MM1).
6929 Writes the current value of MM1. This function is only available on IA32 and
6932 @param Value The 64-bit value to write to MM1.
6943 Writes the current value of 64-bit MMX Register #2 (MM2).
6945 Writes the current value of MM2. This function is only available on IA32 and
6948 @param Value The 64-bit value to write to MM2.
6959 Writes the current value of 64-bit MMX Register #3 (MM3).
6961 Writes the current value of MM3. This function is only available on IA32 and
6964 @param Value The 64-bit value to write to MM3.
6975 Writes the current value of 64-bit MMX Register #4 (MM4).
6977 Writes the current value of MM4. This function is only available on IA32 and
6980 @param Value The 64-bit value to write to MM4.
6991 Writes the current value of 64-bit MMX Register #5 (MM5).
6993 Writes the current value of MM5. This function is only available on IA32 and
6996 @param Value The 64-bit value to write to MM5.
7007 Writes the current value of 64-bit MMX Register #6 (MM6).
7009 Writes the current value of MM6. This function is only available on IA32 and
7012 @param Value The 64-bit value to write to MM6.
7023 Writes the current value of 64-bit MMX Register #7 (MM7).
7025 Writes the current value of MM7. This function is only available on IA32 and
7028 @param Value The 64-bit value to write to MM7.
7039 Reads the current value of Time Stamp Counter (TSC).
7041 Reads and returns the current value of TSC. This function is only available
7044 @return The current value of TSC
7055 Reads the current value of a Performance Counter (PMC).
7057 Reads and returns the current value of performance counter specified by
7058 Index. This function is only available on IA-32 and x64.
7060 @param Index The 32-bit Performance Counter index to read.
7062 @return The value of the PMC specified by Index.
7073 Sets up a monitor buffer that is used by AsmMwait().
7075 Executes a MONITOR instruction with the register state specified by Eax, Ecx
7076 and Edx. Returns Eax. This function is only available on IA-32 and x64.
7078 @param Eax The value to load into EAX or RAX before executing the MONITOR
7080 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7082 @param Edx The value to load into EDX or RDX before executing the MONITOR
7098 Executes an MWAIT instruction.
7100 Executes an MWAIT instruction with the register state specified by Eax and
7101 Ecx. Returns Eax. This function is only available on IA-32 and x64.
7103 @param Eax The value to load into EAX or RAX before executing the MONITOR
7105 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7120 Executes a WBINVD instruction.
7122 Executes a WBINVD instruction. This function is only available on IA-32 and
7134 Executes a INVD instruction.
7136 Executes a INVD instruction. This function is only available on IA-32 and
7148 Flushes a cache line from all the instruction and data caches within the
7149 coherency domain of the CPU.
7151 Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7152 This function is only available on IA-32 and x64.
7154 @param LinearAddress The address of the cache line to flush. If the CPU is
7155 in a physical addressing mode, then LinearAddress is a
7156 physical address. If the CPU is in a virtual
7157 addressing mode, then LinearAddress is a virtual
7160 @return LinearAddress.
7165 IN VOID
*LinearAddress
7170 Enables the 32-bit paging mode on the CPU.
7172 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7173 must be properly initialized prior to calling this service. This function
7174 assumes the current execution mode is 32-bit protected mode. This function is
7175 only available on IA-32. After the 32-bit paging mode is enabled, control is
7176 transferred to the function specified by EntryPoint using the new stack
7177 specified by NewStack and passing in the parameters specified by Context1 and
7178 Context2. Context1 and Context2 are optional and may be NULL. The function
7179 EntryPoint must never return.
7181 If the current execution mode is not 32-bit protected mode, then ASSERT().
7182 If EntryPoint is NULL, then ASSERT().
7183 If NewStack is NULL, then ASSERT().
7185 There are a number of constraints that must be followed before calling this
7187 1) Interrupts must be disabled.
7188 2) The caller must be in 32-bit protected mode with flat descriptors. This
7189 means all descriptors must have a base of 0 and a limit of 4GB.
7190 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
7192 4) CR3 must point to valid page tables that will be used once the transition
7193 is complete, and those page tables must guarantee that the pages for this
7194 function and the stack are identity mapped.
7196 @param EntryPoint A pointer to function to call with the new stack after
7198 @param Context1 A pointer to the context to pass into the EntryPoint
7199 function as the first parameter after paging is enabled.
7200 @param Context2 A pointer to the context to pass into the EntryPoint
7201 function as the second parameter after paging is enabled.
7202 @param NewStack A pointer to the new stack to use for the EntryPoint
7203 function after paging is enabled.
7209 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7210 IN VOID
*Context1 OPTIONAL
,
7211 IN VOID
*Context2 OPTIONAL
,
7217 Disables the 32-bit paging mode on the CPU.
7219 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7220 mode. This function assumes the current execution mode is 32-paged protected
7221 mode. This function is only available on IA-32. After the 32-bit paging mode
7222 is disabled, control is transferred to the function specified by EntryPoint
7223 using the new stack specified by NewStack and passing in the parameters
7224 specified by Context1 and Context2. Context1 and Context2 are optional and
7225 may be NULL. The function EntryPoint must never return.
7227 If the current execution mode is not 32-bit paged mode, then ASSERT().
7228 If EntryPoint is NULL, then ASSERT().
7229 If NewStack is NULL, then ASSERT().
7231 There are a number of constraints that must be followed before calling this
7233 1) Interrupts must be disabled.
7234 2) The caller must be in 32-bit paged mode.
7235 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7236 4) CR3 must point to valid page tables that guarantee that the pages for
7237 this function and the stack are identity mapped.
7239 @param EntryPoint A pointer to function to call with the new stack after
7241 @param Context1 A pointer to the context to pass into the EntryPoint
7242 function as the first parameter after paging is disabled.
7243 @param Context2 A pointer to the context to pass into the EntryPoint
7244 function as the second parameter after paging is
7246 @param NewStack A pointer to the new stack to use for the EntryPoint
7247 function after paging is disabled.
7252 AsmDisablePaging32 (
7253 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7254 IN VOID
*Context1 OPTIONAL
,
7255 IN VOID
*Context2 OPTIONAL
,
7261 Enables the 64-bit paging mode on the CPU.
7263 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7264 must be properly initialized prior to calling this service. This function
7265 assumes the current execution mode is 32-bit protected mode with flat
7266 descriptors. This function is only available on IA-32. After the 64-bit
7267 paging mode is enabled, control is transferred to the function specified by
7268 EntryPoint using the new stack specified by NewStack and passing in the
7269 parameters specified by Context1 and Context2. Context1 and Context2 are
7270 optional and may be 0. The function EntryPoint must never return.
7272 If the current execution mode is not 32-bit protected mode with flat
7273 descriptors, then ASSERT().
7274 If EntryPoint is 0, then ASSERT().
7275 If NewStack is 0, then ASSERT().
7277 @param Cs The 16-bit selector to load in the CS before EntryPoint
7278 is called. The descriptor in the GDT that this selector
7279 references must be setup for long mode.
7280 @param EntryPoint The 64-bit virtual address of the function to call with
7281 the new stack after paging is enabled.
7282 @param Context1 The 64-bit virtual address of the context to pass into
7283 the EntryPoint function as the first parameter after
7285 @param Context2 The 64-bit virtual address of the context to pass into
7286 the EntryPoint function as the second parameter after
7288 @param NewStack The 64-bit virtual address of the new stack to use for
7289 the EntryPoint function after paging is enabled.
7296 IN UINT64 EntryPoint
,
7297 IN UINT64 Context1 OPTIONAL
,
7298 IN UINT64 Context2 OPTIONAL
,
7304 Disables the 64-bit paging mode on the CPU.
7306 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7307 mode. This function assumes the current execution mode is 64-paging mode.
7308 This function is only available on x64. After the 64-bit paging mode is
7309 disabled, control is transferred to the function specified by EntryPoint
7310 using the new stack specified by NewStack and passing in the parameters
7311 specified by Context1 and Context2. Context1 and Context2 are optional and
7312 may be 0. The function EntryPoint must never return.
7314 If the current execution mode is not 64-bit paged mode, then ASSERT().
7315 If EntryPoint is 0, then ASSERT().
7316 If NewStack is 0, then ASSERT().
7318 @param Cs The 16-bit selector to load in the CS before EntryPoint
7319 is called. The descriptor in the GDT that this selector
7320 references must be setup for 32-bit protected mode.
7321 @param EntryPoint The 64-bit virtual address of the function to call with
7322 the new stack after paging is disabled.
7323 @param Context1 The 64-bit virtual address of the context to pass into
7324 the EntryPoint function as the first parameter after
7326 @param Context2 The 64-bit virtual address of the context to pass into
7327 the EntryPoint function as the second parameter after
7329 @param NewStack The 64-bit virtual address of the new stack to use for
7330 the EntryPoint function after paging is disabled.
7335 AsmDisablePaging64 (
7337 IN UINT32 EntryPoint
,
7338 IN UINT32 Context1 OPTIONAL
,
7339 IN UINT32 Context2 OPTIONAL
,
7345 // 16-bit thunking services
7349 Retrieves the properties for 16-bit thunk functions.
7351 Computes the size of the buffer and stack below 1MB required to use the
7352 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7353 buffer size is returned in RealModeBufferSize, and the stack size is returned
7354 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7355 then the actual minimum stack size is ExtraStackSize plus the maximum number
7356 of bytes that need to be passed to the 16-bit real mode code.
7358 If RealModeBufferSize is NULL, then ASSERT().
7359 If ExtraStackSize is NULL, then ASSERT().
7361 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
7362 required to use the 16-bit thunk functions.
7363 @param ExtraStackSize A pointer to the extra size of stack below 1MB
7364 that the 16-bit thunk functions require for
7365 temporary storage in the transition to and from
7371 AsmGetThunk16Properties (
7372 OUT UINT32
*RealModeBufferSize
,
7373 OUT UINT32
*ExtraStackSize
7378 Prepares all structures a code required to use AsmThunk16().
7380 Prepares all structures and code required to use AsmThunk16().
7382 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7383 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7385 If ThunkContext is NULL, then ASSERT().
7387 @param ThunkContext A pointer to the context structure that describes the
7388 16-bit real mode code to call.
7394 IN OUT THUNK_CONTEXT
*ThunkContext
7399 Transfers control to a 16-bit real mode entry point and returns the results.
7401 Transfers control to a 16-bit real mode entry point and returns the results.
7402 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7403 This function must be called with interrupts disabled.
7405 The register state from the RealModeState field of ThunkContext is restored just prior
7406 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
7407 which is used to set the interrupt state when a 16-bit real mode entry point is called.
7408 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7409 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
7410 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7411 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7412 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7413 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7414 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7415 after the RETF instruction is executed.
7417 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7418 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7419 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7421 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7422 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7423 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7425 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7426 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7428 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7429 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7430 disable the A20 mask.
7432 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7433 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
7434 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7436 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7437 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7439 If ThunkContext is NULL, then ASSERT().
7440 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7441 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7442 ThunkAttributes, then ASSERT().
7444 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7445 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7447 @param ThunkContext A pointer to the context structure that describes the
7448 16-bit real mode code to call.
7454 IN OUT THUNK_CONTEXT
*ThunkContext
7459 Prepares all structures and code for a 16-bit real mode thunk, transfers
7460 control to a 16-bit real mode entry point, and returns the results.
7462 Prepares all structures and code for a 16-bit real mode thunk, transfers
7463 control to a 16-bit real mode entry point, and returns the results. If the
7464 caller only need to perform a single 16-bit real mode thunk, then this
7465 service should be used. If the caller intends to make more than one 16-bit
7466 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7467 once and AsmThunk16() can be called for each 16-bit real mode thunk.
7469 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7470 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7472 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7474 @param ThunkContext A pointer to the context structure that describes the
7475 16-bit real mode code to call.
7480 AsmPrepareAndThunk16 (
7481 IN OUT THUNK_CONTEXT
*ThunkContext
7485 Generates a 16-bit random number through RDRAND instruction.
7487 if Rand is NULL, then ASSERT().
7489 @param[out] Rand Buffer pointer to store the random result.
7491 @retval TRUE RDRAND call was successful.
7492 @retval FALSE Failed attempts to call RDRAND.
7502 Generates a 32-bit random number through RDRAND instruction.
7504 if Rand is NULL, then ASSERT().
7506 @param[out] Rand Buffer pointer to store the random result.
7508 @retval TRUE RDRAND call was successful.
7509 @retval FALSE Failed attempts to call RDRAND.
7519 Generates a 64-bit random number through RDRAND instruction.
7521 if Rand is NULL, then ASSERT().
7523 @param[out] Rand Buffer pointer to store the random result.
7525 @retval TRUE RDRAND call was successful.
7526 @retval FALSE Failed attempts to call RDRAND.
7536 Load given selector into TR register.
7538 @param[in] Selector Task segment selector
7547 Performs a serializing operation on all load-from-memory instructions that
7548 were issued prior the AsmLfence function.
7550 Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7560 Executes a XGETBV instruction
7562 Executes a XGETBV instruction. This function is only available on IA-32 and
7565 @param[in] Index Extended control register index
7567 @return The current value of the extended control register
7576 Executes a XSETBV instruction to write a 64-bit value to a Extended Control
7577 Register(XCR), and returns the value.
7579 Writes the 64-bit value specified by Value to the XCR specified by Index. The
7580 64-bit value written to the XCR is returned. No parameter checking is
7581 performed on Index or Value, and some of these may cause CPU exceptions. The
7582 caller must either guarantee that Index and Value are valid, or the caller
7583 must establish proper exception handlers. This function is only available on
7586 @param Index The 32-bit XCR index to write.
7587 @param Value The 64-bit value to write to the XCR.
7600 Executes a VMGEXIT instruction (VMMCALL with a REP prefix)
7602 Executes a VMGEXIT instruction. This function is only available on IA-32 and
7614 Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7615 word, dword or qword operand is encoded at the end of the instruction's
7616 binary representation.
7618 This function should be used to update object code that was compiled with
7619 NASM from assembly source code. Example:
7623 mov eax, strict dword 0 ; the imm32 zero operand will be patched
7629 X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7630 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7632 @param[out] InstructionEnd Pointer right past the instruction to patch. The
7633 immediate operand to patch is expected to
7634 comprise the trailing bytes of the instruction.
7635 If InstructionEnd is closer to address 0 than
7636 ValueSize permits, then ASSERT().
7638 @param[in] PatchValue The constant to write to the immediate operand.
7639 The caller is responsible for ensuring that
7640 PatchValue can be represented in the byte, word,
7641 dword or qword operand (as indicated through
7642 ValueSize); otherwise ASSERT().
7644 @param[in] ValueSize The size of the operand in bytes; must be 1, 2,
7645 4, or 8. ASSERT() otherwise.
7649 PatchInstructionX86 (
7650 OUT X86_ASSEMBLY_PATCH_LABEL
*InstructionEnd
,
7651 IN UINT64 PatchValue
,
7655 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7656 #endif // !defined (__BASE_LIB__)