2 Provides string functions, linked list functions, math functions, synchronization
3 functions, file path functions, and CPU architecture-specific functions.
5 Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
15 // Definitions for architecture-specific types
17 #if defined (MDE_CPU_IA32)
19 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
29 } BASE_LIBRARY_JUMP_BUFFER
;
31 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
33 #endif // defined (MDE_CPU_IA32)
35 #if defined (MDE_CPU_X64)
37 /// The x64 architecture context buffer used by SetJump() and LongJump().
51 UINT8 XmmBuffer
[160]; ///< XMM6-XMM15.
53 } BASE_LIBRARY_JUMP_BUFFER
;
55 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
57 #endif // defined (MDE_CPU_X64)
59 #if defined (MDE_CPU_EBC)
61 /// The EBC context buffer used by SetJump() and LongJump().
69 } BASE_LIBRARY_JUMP_BUFFER
;
71 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
73 #endif // defined (MDE_CPU_EBC)
75 #if defined (MDE_CPU_ARM)
78 UINT32 R3
; ///< A copy of R13.
89 } BASE_LIBRARY_JUMP_BUFFER
;
91 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
93 #endif // defined (MDE_CPU_ARM)
95 #if defined (MDE_CPU_AARCH64)
121 } BASE_LIBRARY_JUMP_BUFFER
;
123 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
125 #endif // defined (MDE_CPU_AARCH64)
134 Returns the length of a Null-terminated Unicode string.
136 This function is similar as strlen_s defined in C11.
138 If String is not aligned on a 16-bit boundary, then ASSERT().
140 @param String A pointer to a Null-terminated Unicode string.
141 @param MaxSize The maximum number of Destination Unicode
142 char, including terminating null char.
144 @retval 0 If String is NULL.
145 @retval MaxSize If there is no null character in the first MaxSize characters of String.
146 @return The number of characters that percede the terminating null character.
152 IN CONST CHAR16
*String
,
157 Returns the size of a Null-terminated Unicode string in bytes, including the
160 This function returns the size of the Null-terminated Unicode string
161 specified by String in bytes, including the Null terminator.
163 If String is not aligned on a 16-bit boundary, then ASSERT().
165 @param String A pointer to a Null-terminated Unicode string.
166 @param MaxSize The maximum number of Destination Unicode
167 char, including the Null terminator.
169 @retval 0 If String is NULL.
170 @retval (sizeof (CHAR16) * (MaxSize + 1))
171 If there is no Null terminator in the first MaxSize characters of
173 @return The size of the Null-terminated Unicode string in bytes, including
180 IN CONST CHAR16
*String
,
185 Copies the string pointed to by Source (including the terminating null char)
186 to the array pointed to by Destination.
188 This function is similar as strcpy_s defined in C11.
190 If Destination is not aligned on a 16-bit boundary, then ASSERT().
191 If Source is not aligned on a 16-bit boundary, then ASSERT().
192 If an error would be returned, then the function will also ASSERT().
194 If an error is returned, then the Destination is unmodified.
196 @param Destination A pointer to a Null-terminated Unicode string.
197 @param DestMax The maximum number of Destination Unicode
198 char, including terminating null char.
199 @param Source A pointer to a Null-terminated Unicode string.
201 @retval RETURN_SUCCESS String is copied.
202 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
203 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
205 If PcdMaximumUnicodeStringLength is not zero,
206 and DestMax is greater than
207 PcdMaximumUnicodeStringLength.
209 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
214 OUT CHAR16
*Destination
,
216 IN CONST CHAR16
*Source
220 Copies not more than Length successive char from the string pointed to by
221 Source to the array pointed to by Destination. If no null char is copied from
222 Source, then Destination[Length] is always set to null.
224 This function is similar as strncpy_s defined in C11.
226 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
227 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
228 If an error would be returned, then the function will also ASSERT().
230 If an error is returned, then the Destination is unmodified.
232 @param Destination A pointer to a Null-terminated Unicode string.
233 @param DestMax The maximum number of Destination Unicode
234 char, including terminating null char.
235 @param Source A pointer to a Null-terminated Unicode string.
236 @param Length The maximum number of Unicode characters to copy.
238 @retval RETURN_SUCCESS String is copied.
239 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
240 MIN(StrLen(Source), Length).
241 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
243 If PcdMaximumUnicodeStringLength is not zero,
244 and DestMax is greater than
245 PcdMaximumUnicodeStringLength.
247 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
252 OUT CHAR16
*Destination
,
254 IN CONST CHAR16
*Source
,
259 Appends a copy of the string pointed to by Source (including the terminating
260 null char) to the end of the string pointed to by Destination.
262 This function is similar as strcat_s defined in C11.
264 If Destination is not aligned on a 16-bit boundary, then ASSERT().
265 If Source is not aligned on a 16-bit boundary, then ASSERT().
266 If an error would be returned, then the function will also ASSERT().
268 If an error is returned, then the Destination is unmodified.
270 @param Destination A pointer to a Null-terminated Unicode string.
271 @param DestMax The maximum number of Destination Unicode
272 char, including terminating null char.
273 @param Source A pointer to a Null-terminated Unicode string.
275 @retval RETURN_SUCCESS String is appended.
276 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
278 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
279 greater than StrLen(Source).
280 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
282 If PcdMaximumUnicodeStringLength is not zero,
283 and DestMax is greater than
284 PcdMaximumUnicodeStringLength.
286 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
291 IN OUT CHAR16
*Destination
,
293 IN CONST CHAR16
*Source
297 Appends not more than Length successive char from the string pointed to by
298 Source to the end of the string pointed to by Destination. If no null char is
299 copied from Source, then Destination[StrLen(Destination) + Length] is always
302 This function is similar as strncat_s defined in C11.
304 If Destination is not aligned on a 16-bit boundary, then ASSERT().
305 If Source is not aligned on a 16-bit boundary, then ASSERT().
306 If an error would be returned, then the function will also ASSERT().
308 If an error is returned, then the Destination is unmodified.
310 @param Destination A pointer to a Null-terminated Unicode string.
311 @param DestMax The maximum number of Destination Unicode
312 char, including terminating null char.
313 @param Source A pointer to a Null-terminated Unicode string.
314 @param Length The maximum number of Unicode characters to copy.
316 @retval RETURN_SUCCESS String is appended.
317 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
319 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
320 greater than MIN(StrLen(Source), Length).
321 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
323 If PcdMaximumUnicodeStringLength is not zero,
324 and DestMax is greater than
325 PcdMaximumUnicodeStringLength.
327 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
332 IN OUT CHAR16
*Destination
,
334 IN CONST CHAR16
*Source
,
339 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
341 This function outputs a value of type UINTN by interpreting the contents of
342 the Unicode string specified by String as a decimal number. The format of the
343 input Unicode string String is:
345 [spaces] [decimal digits].
347 The valid decimal digit character is in the range [0-9]. The function will
348 ignore the pad space, which includes spaces or tab characters, before
349 [decimal digits]. The running zero in the beginning of [decimal digits] will
350 be ignored. Then, the function stops at the first character that is a not a
351 valid decimal character or a Null-terminator, whichever one comes first.
353 If String is NULL, then ASSERT().
354 If Data is NULL, then ASSERT().
355 If String is not aligned in a 16-bit boundary, then ASSERT().
356 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
357 PcdMaximumUnicodeStringLength Unicode characters, not including the
358 Null-terminator, then ASSERT().
360 If String has no valid decimal digits in the above format, then 0 is stored
361 at the location pointed to by Data.
362 If the number represented by String exceeds the range defined by UINTN, then
363 MAX_UINTN is stored at the location pointed to by Data.
365 If EndPointer is not NULL, a pointer to the character that stopped the scan
366 is stored at the location pointed to by EndPointer. If String has no valid
367 decimal digits right after the optional pad spaces, the value of String is
368 stored at the location pointed to by EndPointer.
370 @param String Pointer to a Null-terminated Unicode string.
371 @param EndPointer Pointer to character that stops scan.
372 @param Data Pointer to the converted value.
374 @retval RETURN_SUCCESS Value is translated from String.
375 @retval RETURN_INVALID_PARAMETER If String is NULL.
377 If PcdMaximumUnicodeStringLength is not
378 zero, and String contains more than
379 PcdMaximumUnicodeStringLength Unicode
380 characters, not including the
382 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
383 the range defined by UINTN.
389 IN CONST CHAR16
*String
,
390 OUT CHAR16
**EndPointer
, OPTIONAL
395 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
397 This function outputs a value of type UINT64 by interpreting the contents of
398 the Unicode string specified by String as a decimal number. The format of the
399 input Unicode string String is:
401 [spaces] [decimal digits].
403 The valid decimal digit character is in the range [0-9]. The function will
404 ignore the pad space, which includes spaces or tab characters, before
405 [decimal digits]. The running zero in the beginning of [decimal digits] will
406 be ignored. Then, the function stops at the first character that is a not a
407 valid decimal character or a Null-terminator, whichever one comes first.
409 If String is NULL, then ASSERT().
410 If Data is NULL, then ASSERT().
411 If String is not aligned in a 16-bit boundary, then ASSERT().
412 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
413 PcdMaximumUnicodeStringLength Unicode characters, not including the
414 Null-terminator, then ASSERT().
416 If String has no valid decimal digits in the above format, then 0 is stored
417 at the location pointed to by Data.
418 If the number represented by String exceeds the range defined by UINT64, then
419 MAX_UINT64 is stored at the location pointed to by Data.
421 If EndPointer is not NULL, a pointer to the character that stopped the scan
422 is stored at the location pointed to by EndPointer. If String has no valid
423 decimal digits right after the optional pad spaces, the value of String is
424 stored at the location pointed to by EndPointer.
426 @param String Pointer to a Null-terminated Unicode string.
427 @param EndPointer Pointer to character that stops scan.
428 @param Data Pointer to the converted value.
430 @retval RETURN_SUCCESS Value is translated from String.
431 @retval RETURN_INVALID_PARAMETER If String is NULL.
433 If PcdMaximumUnicodeStringLength is not
434 zero, and String contains more than
435 PcdMaximumUnicodeStringLength Unicode
436 characters, not including the
438 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
439 the range defined by UINT64.
444 StrDecimalToUint64S (
445 IN CONST CHAR16
*String
,
446 OUT CHAR16
**EndPointer
, OPTIONAL
451 Convert a Null-terminated Unicode hexadecimal string to a value of type
454 This function outputs a value of type UINTN by interpreting the contents of
455 the Unicode string specified by String as a hexadecimal number. The format of
456 the input Unicode string String is:
458 [spaces][zeros][x][hexadecimal digits].
460 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
461 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
462 If "x" appears in the input string, it must be prefixed with at least one 0.
463 The function will ignore the pad space, which includes spaces or tab
464 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
465 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
466 after [x] or the first valid hexadecimal digit. Then, the function stops at
467 the first character that is a not a valid hexadecimal character or NULL,
468 whichever one comes first.
470 If String is NULL, then ASSERT().
471 If Data is NULL, then ASSERT().
472 If String is not aligned in a 16-bit boundary, then ASSERT().
473 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
474 PcdMaximumUnicodeStringLength Unicode characters, not including the
475 Null-terminator, then ASSERT().
477 If String has no valid hexadecimal digits in the above format, then 0 is
478 stored at the location pointed to by Data.
479 If the number represented by String exceeds the range defined by UINTN, then
480 MAX_UINTN is stored at the location pointed to by Data.
482 If EndPointer is not NULL, a pointer to the character that stopped the scan
483 is stored at the location pointed to by EndPointer. If String has no valid
484 hexadecimal digits right after the optional pad spaces, the value of String
485 is stored at the location pointed to by EndPointer.
487 @param String Pointer to a Null-terminated Unicode string.
488 @param EndPointer Pointer to character that stops scan.
489 @param Data Pointer to the converted value.
491 @retval RETURN_SUCCESS Value is translated from String.
492 @retval RETURN_INVALID_PARAMETER If String is NULL.
494 If PcdMaximumUnicodeStringLength is not
495 zero, and String contains more than
496 PcdMaximumUnicodeStringLength Unicode
497 characters, not including the
499 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
500 the range defined by UINTN.
506 IN CONST CHAR16
*String
,
507 OUT CHAR16
**EndPointer
, OPTIONAL
512 Convert a Null-terminated Unicode hexadecimal string to a value of type
515 This function outputs a value of type UINT64 by interpreting the contents of
516 the Unicode string specified by String as a hexadecimal number. The format of
517 the input Unicode string String is:
519 [spaces][zeros][x][hexadecimal digits].
521 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
522 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
523 If "x" appears in the input string, it must be prefixed with at least one 0.
524 The function will ignore the pad space, which includes spaces or tab
525 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
526 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
527 after [x] or the first valid hexadecimal digit. Then, the function stops at
528 the first character that is a not a valid hexadecimal character or NULL,
529 whichever one comes first.
531 If String is NULL, then ASSERT().
532 If Data is NULL, then ASSERT().
533 If String is not aligned in a 16-bit boundary, then ASSERT().
534 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
535 PcdMaximumUnicodeStringLength Unicode characters, not including the
536 Null-terminator, then ASSERT().
538 If String has no valid hexadecimal digits in the above format, then 0 is
539 stored at the location pointed to by Data.
540 If the number represented by String exceeds the range defined by UINT64, then
541 MAX_UINT64 is stored at the location pointed to by Data.
543 If EndPointer is not NULL, a pointer to the character that stopped the scan
544 is stored at the location pointed to by EndPointer. If String has no valid
545 hexadecimal digits right after the optional pad spaces, the value of String
546 is stored at the location pointed to by EndPointer.
548 @param String Pointer to a Null-terminated Unicode string.
549 @param EndPointer Pointer to character that stops scan.
550 @param Data Pointer to the converted value.
552 @retval RETURN_SUCCESS Value is translated from String.
553 @retval RETURN_INVALID_PARAMETER If String is NULL.
555 If PcdMaximumUnicodeStringLength is not
556 zero, and String contains more than
557 PcdMaximumUnicodeStringLength Unicode
558 characters, not including the
560 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
561 the range defined by UINT64.
567 IN CONST CHAR16
*String
,
568 OUT CHAR16
**EndPointer
, OPTIONAL
573 Returns the length of a Null-terminated Ascii string.
575 This function is similar as strlen_s defined in C11.
577 @param String A pointer to a Null-terminated Ascii string.
578 @param MaxSize The maximum number of Destination Ascii
579 char, including terminating null char.
581 @retval 0 If String is NULL.
582 @retval MaxSize If there is no null character in the first MaxSize characters of String.
583 @return The number of characters that percede the terminating null character.
589 IN CONST CHAR8
*String
,
594 Returns the size of a Null-terminated Ascii string in bytes, including the
597 This function returns the size of the Null-terminated Ascii string specified
598 by String in bytes, including the Null terminator.
600 @param String A pointer to a Null-terminated Ascii string.
601 @param MaxSize The maximum number of Destination Ascii
602 char, including the Null terminator.
604 @retval 0 If String is NULL.
605 @retval (sizeof (CHAR8) * (MaxSize + 1))
606 If there is no Null terminator in the first MaxSize characters of
608 @return The size of the Null-terminated Ascii string in bytes, including the
615 IN CONST CHAR8
*String
,
620 Copies the string pointed to by Source (including the terminating null char)
621 to the array pointed to by Destination.
623 This function is similar as strcpy_s defined in C11.
625 If an error would be returned, then the function will also ASSERT().
627 If an error is returned, then the Destination is unmodified.
629 @param Destination A pointer to a Null-terminated Ascii string.
630 @param DestMax The maximum number of Destination Ascii
631 char, including terminating null char.
632 @param Source A pointer to a Null-terminated Ascii string.
634 @retval RETURN_SUCCESS String is copied.
635 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
636 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
638 If PcdMaximumAsciiStringLength is not zero,
639 and DestMax is greater than
640 PcdMaximumAsciiStringLength.
642 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
647 OUT CHAR8
*Destination
,
649 IN CONST CHAR8
*Source
653 Copies not more than Length successive char from the string pointed to by
654 Source to the array pointed to by Destination. If no null char is copied from
655 Source, then Destination[Length] is always set to null.
657 This function is similar as strncpy_s defined in C11.
659 If an error would be returned, then the function will also ASSERT().
661 If an error is returned, then the Destination is unmodified.
663 @param Destination A pointer to a Null-terminated Ascii string.
664 @param DestMax The maximum number of Destination Ascii
665 char, including terminating null char.
666 @param Source A pointer to a Null-terminated Ascii string.
667 @param Length The maximum number of Ascii characters to copy.
669 @retval RETURN_SUCCESS String is copied.
670 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
671 MIN(StrLen(Source), Length).
672 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
674 If PcdMaximumAsciiStringLength is not zero,
675 and DestMax is greater than
676 PcdMaximumAsciiStringLength.
678 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
683 OUT CHAR8
*Destination
,
685 IN CONST CHAR8
*Source
,
690 Appends a copy of the string pointed to by Source (including the terminating
691 null char) to the end of the string pointed to by Destination.
693 This function is similar as strcat_s defined in C11.
695 If an error would be returned, then the function will also ASSERT().
697 If an error is returned, then the Destination is unmodified.
699 @param Destination A pointer to a Null-terminated Ascii string.
700 @param DestMax The maximum number of Destination Ascii
701 char, including terminating null char.
702 @param Source A pointer to a Null-terminated Ascii string.
704 @retval RETURN_SUCCESS String is appended.
705 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
707 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
708 greater than StrLen(Source).
709 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
711 If PcdMaximumAsciiStringLength is not zero,
712 and DestMax is greater than
713 PcdMaximumAsciiStringLength.
715 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
720 IN OUT CHAR8
*Destination
,
722 IN CONST CHAR8
*Source
726 Appends not more than Length successive char from the string pointed to by
727 Source to the end of the string pointed to by Destination. If no null char is
728 copied from Source, then Destination[StrLen(Destination) + Length] is always
731 This function is similar as strncat_s defined in C11.
733 If an error would be returned, then the function will also ASSERT().
735 If an error is returned, then the Destination is unmodified.
737 @param Destination A pointer to a Null-terminated Ascii string.
738 @param DestMax The maximum number of Destination Ascii
739 char, including terminating null char.
740 @param Source A pointer to a Null-terminated Ascii string.
741 @param Length The maximum number of Ascii characters to copy.
743 @retval RETURN_SUCCESS String is appended.
744 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
746 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
747 greater than MIN(StrLen(Source), Length).
748 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
750 If PcdMaximumAsciiStringLength is not zero,
751 and DestMax is greater than
752 PcdMaximumAsciiStringLength.
754 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
759 IN OUT CHAR8
*Destination
,
761 IN CONST CHAR8
*Source
,
766 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
768 This function outputs a value of type UINTN by interpreting the contents of
769 the Ascii string specified by String as a decimal number. The format of the
770 input Ascii string String is:
772 [spaces] [decimal digits].
774 The valid decimal digit character is in the range [0-9]. The function will
775 ignore the pad space, which includes spaces or tab characters, before
776 [decimal digits]. The running zero in the beginning of [decimal digits] will
777 be ignored. Then, the function stops at the first character that is a not a
778 valid decimal character or a Null-terminator, whichever one comes first.
780 If String is NULL, then ASSERT().
781 If Data is NULL, then ASSERT().
782 If PcdMaximumAsciiStringLength is not zero, and String contains more than
783 PcdMaximumAsciiStringLength Ascii characters, not including the
784 Null-terminator, then ASSERT().
786 If String has no valid decimal digits in the above format, then 0 is stored
787 at the location pointed to by Data.
788 If the number represented by String exceeds the range defined by UINTN, then
789 MAX_UINTN is stored at the location pointed to by Data.
791 If EndPointer is not NULL, a pointer to the character that stopped the scan
792 is stored at the location pointed to by EndPointer. If String has no valid
793 decimal digits right after the optional pad spaces, the value of String is
794 stored at the location pointed to by EndPointer.
796 @param String Pointer to a Null-terminated Ascii string.
797 @param EndPointer Pointer to character that stops scan.
798 @param Data Pointer to the converted value.
800 @retval RETURN_SUCCESS Value is translated from String.
801 @retval RETURN_INVALID_PARAMETER If String is NULL.
803 If PcdMaximumAsciiStringLength is not zero,
804 and String contains more than
805 PcdMaximumAsciiStringLength Ascii
806 characters, not including the
808 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
809 the range defined by UINTN.
814 AsciiStrDecimalToUintnS (
815 IN CONST CHAR8
*String
,
816 OUT CHAR8
**EndPointer
, OPTIONAL
821 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
823 This function outputs a value of type UINT64 by interpreting the contents of
824 the Ascii string specified by String as a decimal number. The format of the
825 input Ascii string String is:
827 [spaces] [decimal digits].
829 The valid decimal digit character is in the range [0-9]. The function will
830 ignore the pad space, which includes spaces or tab characters, before
831 [decimal digits]. The running zero in the beginning of [decimal digits] will
832 be ignored. Then, the function stops at the first character that is a not a
833 valid decimal character or a Null-terminator, whichever one comes first.
835 If String is NULL, then ASSERT().
836 If Data is NULL, then ASSERT().
837 If PcdMaximumAsciiStringLength is not zero, and String contains more than
838 PcdMaximumAsciiStringLength Ascii characters, not including the
839 Null-terminator, then ASSERT().
841 If String has no valid decimal digits in the above format, then 0 is stored
842 at the location pointed to by Data.
843 If the number represented by String exceeds the range defined by UINT64, then
844 MAX_UINT64 is stored at the location pointed to by Data.
846 If EndPointer is not NULL, a pointer to the character that stopped the scan
847 is stored at the location pointed to by EndPointer. If String has no valid
848 decimal digits right after the optional pad spaces, the value of String is
849 stored at the location pointed to by EndPointer.
851 @param String Pointer to a Null-terminated Ascii string.
852 @param EndPointer Pointer to character that stops scan.
853 @param Data Pointer to the converted value.
855 @retval RETURN_SUCCESS Value is translated from String.
856 @retval RETURN_INVALID_PARAMETER If String is NULL.
858 If PcdMaximumAsciiStringLength is not zero,
859 and String contains more than
860 PcdMaximumAsciiStringLength Ascii
861 characters, not including the
863 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
864 the range defined by UINT64.
869 AsciiStrDecimalToUint64S (
870 IN CONST CHAR8
*String
,
871 OUT CHAR8
**EndPointer
, OPTIONAL
876 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
878 This function outputs a value of type UINTN by interpreting the contents of
879 the Ascii string specified by String as a hexadecimal number. The format of
880 the input Ascii string String is:
882 [spaces][zeros][x][hexadecimal digits].
884 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
885 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
886 "x" appears in the input string, it must be prefixed with at least one 0. The
887 function will ignore the pad space, which includes spaces or tab characters,
888 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
889 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
890 the first valid hexadecimal digit. Then, the function stops at the first
891 character that is a not a valid hexadecimal character or Null-terminator,
892 whichever on comes first.
894 If String is NULL, then ASSERT().
895 If Data is NULL, then ASSERT().
896 If PcdMaximumAsciiStringLength is not zero, and String contains more than
897 PcdMaximumAsciiStringLength Ascii characters, not including the
898 Null-terminator, then ASSERT().
900 If String has no valid hexadecimal digits in the above format, then 0 is
901 stored at the location pointed to by Data.
902 If the number represented by String exceeds the range defined by UINTN, then
903 MAX_UINTN is stored at the location pointed to by Data.
905 If EndPointer is not NULL, a pointer to the character that stopped the scan
906 is stored at the location pointed to by EndPointer. If String has no valid
907 hexadecimal digits right after the optional pad spaces, the value of String
908 is stored at the location pointed to by EndPointer.
910 @param String Pointer to a Null-terminated Ascii string.
911 @param EndPointer Pointer to character that stops scan.
912 @param Data Pointer to the converted value.
914 @retval RETURN_SUCCESS Value is translated from String.
915 @retval RETURN_INVALID_PARAMETER If String is NULL.
917 If PcdMaximumAsciiStringLength is not zero,
918 and String contains more than
919 PcdMaximumAsciiStringLength Ascii
920 characters, not including the
922 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
923 the range defined by UINTN.
928 AsciiStrHexToUintnS (
929 IN CONST CHAR8
*String
,
930 OUT CHAR8
**EndPointer
, OPTIONAL
935 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
937 This function outputs a value of type UINT64 by interpreting the contents of
938 the Ascii string specified by String as a hexadecimal number. The format of
939 the input Ascii string String is:
941 [spaces][zeros][x][hexadecimal digits].
943 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
944 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
945 "x" appears in the input string, it must be prefixed with at least one 0. The
946 function will ignore the pad space, which includes spaces or tab characters,
947 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
948 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
949 the first valid hexadecimal digit. Then, the function stops at the first
950 character that is a not a valid hexadecimal character or Null-terminator,
951 whichever on comes first.
953 If String is NULL, then ASSERT().
954 If Data is NULL, then ASSERT().
955 If PcdMaximumAsciiStringLength is not zero, and String contains more than
956 PcdMaximumAsciiStringLength Ascii characters, not including the
957 Null-terminator, then ASSERT().
959 If String has no valid hexadecimal digits in the above format, then 0 is
960 stored at the location pointed to by Data.
961 If the number represented by String exceeds the range defined by UINT64, then
962 MAX_UINT64 is stored at the location pointed to by Data.
964 If EndPointer is not NULL, a pointer to the character that stopped the scan
965 is stored at the location pointed to by EndPointer. If String has no valid
966 hexadecimal digits right after the optional pad spaces, the value of String
967 is stored at the location pointed to by EndPointer.
969 @param String Pointer to a Null-terminated Ascii string.
970 @param EndPointer Pointer to character that stops scan.
971 @param Data Pointer to the converted value.
973 @retval RETURN_SUCCESS Value is translated from String.
974 @retval RETURN_INVALID_PARAMETER If String is NULL.
976 If PcdMaximumAsciiStringLength is not zero,
977 and String contains more than
978 PcdMaximumAsciiStringLength Ascii
979 characters, not including the
981 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
982 the range defined by UINT64.
987 AsciiStrHexToUint64S (
988 IN CONST CHAR8
*String
,
989 OUT CHAR8
**EndPointer
, OPTIONAL
994 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
997 [ATTENTION] This function is deprecated for security reason.
999 Copies one Null-terminated Unicode string to another Null-terminated Unicode
1000 string and returns the new Unicode string.
1002 This function copies the contents of the Unicode string Source to the Unicode
1003 string Destination, and returns Destination. If Source and Destination
1004 overlap, then the results are undefined.
1006 If Destination is NULL, then ASSERT().
1007 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1008 If Source is NULL, then ASSERT().
1009 If Source is not aligned on a 16-bit boundary, then ASSERT().
1010 If Source and Destination overlap, then ASSERT().
1011 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1012 PcdMaximumUnicodeStringLength Unicode characters not including the
1013 Null-terminator, then ASSERT().
1015 @param Destination The pointer to a Null-terminated Unicode string.
1016 @param Source The pointer to a Null-terminated Unicode string.
1018 @return Destination.
1024 OUT CHAR16
*Destination
,
1025 IN CONST CHAR16
*Source
1030 [ATTENTION] This function is deprecated for security reason.
1032 Copies up to a specified length from one Null-terminated Unicode string to
1033 another Null-terminated Unicode string and returns the new Unicode string.
1035 This function copies the contents of the Unicode string Source to the Unicode
1036 string Destination, and returns Destination. At most, Length Unicode
1037 characters are copied from Source to Destination. If Length is 0, then
1038 Destination is returned unmodified. If Length is greater that the number of
1039 Unicode characters in Source, then Destination is padded with Null Unicode
1040 characters. If Source and Destination overlap, then the results are
1043 If Length > 0 and Destination is NULL, then ASSERT().
1044 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1045 If Length > 0 and Source is NULL, then ASSERT().
1046 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1047 If Source and Destination overlap, then ASSERT().
1048 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1049 PcdMaximumUnicodeStringLength, then ASSERT().
1050 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1051 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1054 @param Destination The pointer to a Null-terminated Unicode string.
1055 @param Source The pointer to a Null-terminated Unicode string.
1056 @param Length The maximum number of Unicode characters to copy.
1058 @return Destination.
1064 OUT CHAR16
*Destination
,
1065 IN CONST CHAR16
*Source
,
1068 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1071 Returns the length of a Null-terminated Unicode string.
1073 This function returns the number of Unicode characters in the Null-terminated
1074 Unicode string specified by String.
1076 If String is NULL, then ASSERT().
1077 If String is not aligned on a 16-bit boundary, then ASSERT().
1078 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1079 PcdMaximumUnicodeStringLength Unicode characters not including the
1080 Null-terminator, then ASSERT().
1082 @param String Pointer to a Null-terminated Unicode string.
1084 @return The length of String.
1090 IN CONST CHAR16
*String
1095 Returns the size of a Null-terminated Unicode string in bytes, including the
1098 This function returns the size, in bytes, of the Null-terminated Unicode string
1099 specified by String.
1101 If String is NULL, then ASSERT().
1102 If String is not aligned on a 16-bit boundary, then ASSERT().
1103 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1104 PcdMaximumUnicodeStringLength Unicode characters not including the
1105 Null-terminator, then ASSERT().
1107 @param String The pointer to a Null-terminated Unicode string.
1109 @return The size of String.
1115 IN CONST CHAR16
*String
1120 Compares two Null-terminated Unicode strings, and returns the difference
1121 between the first mismatched Unicode characters.
1123 This function compares the Null-terminated Unicode string FirstString to the
1124 Null-terminated Unicode string SecondString. If FirstString is identical to
1125 SecondString, then 0 is returned. Otherwise, the value returned is the first
1126 mismatched Unicode character in SecondString subtracted from the first
1127 mismatched Unicode character in FirstString.
1129 If FirstString is NULL, then ASSERT().
1130 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1131 If SecondString is NULL, then ASSERT().
1132 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1133 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1134 than PcdMaximumUnicodeStringLength Unicode characters not including the
1135 Null-terminator, then ASSERT().
1136 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1137 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1138 Null-terminator, then ASSERT().
1140 @param FirstString The pointer to a Null-terminated Unicode string.
1141 @param SecondString The pointer to a Null-terminated Unicode string.
1143 @retval 0 FirstString is identical to SecondString.
1144 @return others FirstString is not identical to SecondString.
1150 IN CONST CHAR16
*FirstString
,
1151 IN CONST CHAR16
*SecondString
1156 Compares up to a specified length the contents of two Null-terminated Unicode strings,
1157 and returns the difference between the first mismatched Unicode characters.
1159 This function compares the Null-terminated Unicode string FirstString to the
1160 Null-terminated Unicode string SecondString. At most, Length Unicode
1161 characters will be compared. If Length is 0, then 0 is returned. If
1162 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1163 value returned is the first mismatched Unicode character in SecondString
1164 subtracted from the first mismatched Unicode character in FirstString.
1166 If Length > 0 and FirstString is NULL, then ASSERT().
1167 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1168 If Length > 0 and SecondString is NULL, then ASSERT().
1169 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1170 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1171 PcdMaximumUnicodeStringLength, then ASSERT().
1172 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1173 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1175 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1176 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1179 @param FirstString The pointer to a Null-terminated Unicode string.
1180 @param SecondString The pointer to a Null-terminated Unicode string.
1181 @param Length The maximum number of Unicode characters to compare.
1183 @retval 0 FirstString is identical to SecondString.
1184 @return others FirstString is not identical to SecondString.
1190 IN CONST CHAR16
*FirstString
,
1191 IN CONST CHAR16
*SecondString
,
1196 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1199 [ATTENTION] This function is deprecated for security reason.
1201 Concatenates one Null-terminated Unicode string to another Null-terminated
1202 Unicode string, and returns the concatenated Unicode string.
1204 This function concatenates two Null-terminated Unicode strings. The contents
1205 of Null-terminated Unicode string Source are concatenated to the end of
1206 Null-terminated Unicode string Destination. The Null-terminated concatenated
1207 Unicode String is returned. If Source and Destination overlap, then the
1208 results are undefined.
1210 If Destination is NULL, then ASSERT().
1211 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1212 If Source is NULL, then ASSERT().
1213 If Source is not aligned on a 16-bit boundary, then ASSERT().
1214 If Source and Destination overlap, then ASSERT().
1215 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1216 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1217 Null-terminator, then ASSERT().
1218 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1219 PcdMaximumUnicodeStringLength Unicode characters, not including the
1220 Null-terminator, then ASSERT().
1221 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1222 and Source results in a Unicode string with more than
1223 PcdMaximumUnicodeStringLength Unicode characters, not including the
1224 Null-terminator, then ASSERT().
1226 @param Destination The pointer to a Null-terminated Unicode string.
1227 @param Source The pointer to a Null-terminated Unicode string.
1229 @return Destination.
1235 IN OUT CHAR16
*Destination
,
1236 IN CONST CHAR16
*Source
1241 [ATTENTION] This function is deprecated for security reason.
1243 Concatenates up to a specified length one Null-terminated Unicode to the end
1244 of another Null-terminated Unicode string, and returns the concatenated
1247 This function concatenates two Null-terminated Unicode strings. The contents
1248 of Null-terminated Unicode string Source are concatenated to the end of
1249 Null-terminated Unicode string Destination, and Destination is returned. At
1250 most, Length Unicode characters are concatenated from Source to the end of
1251 Destination, and Destination is always Null-terminated. If Length is 0, then
1252 Destination is returned unmodified. If Source and Destination overlap, then
1253 the results are undefined.
1255 If Destination is NULL, then ASSERT().
1256 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1257 If Length > 0 and Source is NULL, then ASSERT().
1258 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1259 If Source and Destination overlap, then ASSERT().
1260 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1261 PcdMaximumUnicodeStringLength, then ASSERT().
1262 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1263 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1264 Null-terminator, then ASSERT().
1265 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1266 PcdMaximumUnicodeStringLength Unicode characters, not including the
1267 Null-terminator, then ASSERT().
1268 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1269 and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength
1270 Unicode characters, not including the Null-terminator, then ASSERT().
1272 @param Destination The pointer to a Null-terminated Unicode string.
1273 @param Source The pointer to a Null-terminated Unicode string.
1274 @param Length The maximum number of Unicode characters to concatenate from
1277 @return Destination.
1283 IN OUT CHAR16
*Destination
,
1284 IN CONST CHAR16
*Source
,
1287 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1290 Returns the first occurrence of a Null-terminated Unicode sub-string
1291 in a Null-terminated Unicode string.
1293 This function scans the contents of the Null-terminated Unicode string
1294 specified by String and returns the first occurrence of SearchString.
1295 If SearchString is not found in String, then NULL is returned. If
1296 the length of SearchString is zero, then String is returned.
1298 If String is NULL, then ASSERT().
1299 If String is not aligned on a 16-bit boundary, then ASSERT().
1300 If SearchString is NULL, then ASSERT().
1301 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1303 If PcdMaximumUnicodeStringLength is not zero, and SearchString
1304 or String contains more than PcdMaximumUnicodeStringLength Unicode
1305 characters, not including the Null-terminator, then ASSERT().
1307 @param String The pointer to a Null-terminated Unicode string.
1308 @param SearchString The pointer to a Null-terminated Unicode string to search for.
1310 @retval NULL If the SearchString does not appear in String.
1311 @return others If there is a match.
1317 IN CONST CHAR16
*String
,
1318 IN CONST CHAR16
*SearchString
1322 Convert a Null-terminated Unicode decimal string to a value of
1325 This function returns a value of type UINTN by interpreting the contents
1326 of the Unicode string specified by String as a decimal number. The format
1327 of the input Unicode string String is:
1329 [spaces] [decimal digits].
1331 The valid decimal digit character is in the range [0-9]. The
1332 function will ignore the pad space, which includes spaces or
1333 tab characters, before [decimal digits]. The running zero in the
1334 beginning of [decimal digits] will be ignored. Then, the function
1335 stops at the first character that is a not a valid decimal character
1336 or a Null-terminator, whichever one comes first.
1338 If String is NULL, then ASSERT().
1339 If String is not aligned in a 16-bit boundary, then ASSERT().
1340 If String has only pad spaces, then 0 is returned.
1341 If String has no pad spaces or valid decimal digits,
1343 If the number represented by String overflows according
1344 to the range defined by UINTN, then MAX_UINTN is returned.
1346 If PcdMaximumUnicodeStringLength is not zero, and String contains
1347 more than PcdMaximumUnicodeStringLength Unicode characters not including
1348 the Null-terminator, then ASSERT().
1350 @param String The pointer to a Null-terminated Unicode string.
1352 @retval Value translated from String.
1358 IN CONST CHAR16
*String
1362 Convert a Null-terminated Unicode decimal string to a value of
1365 This function returns a value of type UINT64 by interpreting the contents
1366 of the Unicode string specified by String as a decimal number. The format
1367 of the input Unicode string String is:
1369 [spaces] [decimal digits].
1371 The valid decimal digit character is in the range [0-9]. The
1372 function will ignore the pad space, which includes spaces or
1373 tab characters, before [decimal digits]. The running zero in the
1374 beginning of [decimal digits] will be ignored. Then, the function
1375 stops at the first character that is a not a valid decimal character
1376 or a Null-terminator, whichever one comes first.
1378 If String is NULL, then ASSERT().
1379 If String is not aligned in a 16-bit boundary, then ASSERT().
1380 If String has only pad spaces, then 0 is returned.
1381 If String has no pad spaces or valid decimal digits,
1383 If the number represented by String overflows according
1384 to the range defined by UINT64, then MAX_UINT64 is returned.
1386 If PcdMaximumUnicodeStringLength is not zero, and String contains
1387 more than PcdMaximumUnicodeStringLength Unicode characters not including
1388 the Null-terminator, then ASSERT().
1390 @param String The pointer to a Null-terminated Unicode string.
1392 @retval Value translated from String.
1397 StrDecimalToUint64 (
1398 IN CONST CHAR16
*String
1403 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1405 This function returns a value of type UINTN by interpreting the contents
1406 of the Unicode string specified by String as a hexadecimal number.
1407 The format of the input Unicode string String is:
1409 [spaces][zeros][x][hexadecimal digits].
1411 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1412 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1413 If "x" appears in the input string, it must be prefixed with at least one 0.
1414 The function will ignore the pad space, which includes spaces or tab characters,
1415 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1416 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1417 first valid hexadecimal digit. Then, the function stops at the first character
1418 that is a not a valid hexadecimal character or NULL, whichever one comes first.
1420 If String is NULL, then ASSERT().
1421 If String is not aligned in a 16-bit boundary, then ASSERT().
1422 If String has only pad spaces, then zero is returned.
1423 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1424 then zero is returned.
1425 If the number represented by String overflows according to the range defined by
1426 UINTN, then MAX_UINTN is returned.
1428 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1429 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1432 @param String The pointer to a Null-terminated Unicode string.
1434 @retval Value translated from String.
1440 IN CONST CHAR16
*String
1445 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1447 This function returns a value of type UINT64 by interpreting the contents
1448 of the Unicode string specified by String as a hexadecimal number.
1449 The format of the input Unicode string String is
1451 [spaces][zeros][x][hexadecimal digits].
1453 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1454 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1455 If "x" appears in the input string, it must be prefixed with at least one 0.
1456 The function will ignore the pad space, which includes spaces or tab characters,
1457 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1458 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1459 first valid hexadecimal digit. Then, the function stops at the first character that is
1460 a not a valid hexadecimal character or NULL, whichever one comes first.
1462 If String is NULL, then ASSERT().
1463 If String is not aligned in a 16-bit boundary, then ASSERT().
1464 If String has only pad spaces, then zero is returned.
1465 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1466 then zero is returned.
1467 If the number represented by String overflows according to the range defined by
1468 UINT64, then MAX_UINT64 is returned.
1470 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1471 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1474 @param String The pointer to a Null-terminated Unicode string.
1476 @retval Value translated from String.
1482 IN CONST CHAR16
*String
1486 Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1488 This function outputs a value of type IPv6_ADDRESS and may output a value
1489 of type UINT8 by interpreting the contents of the Unicode string specified
1490 by String. The format of the input Unicode string String is as follows:
1494 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1495 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1496 memory address and high byte is stored in high memory address. P contains decimal
1497 digit characters in the range [0-9]. The running zero in the beginning of P will
1498 be ignored. /P is optional.
1500 When /P is not in the String, the function stops at the first character that is
1501 not a valid hexadecimal digit character after eight X's are converted.
1503 When /P is in the String, the function stops at the first character that is not
1504 a valid decimal digit character after P is converted.
1506 "::" can be used to compress one or more groups of X when X contains only 0.
1507 The "::" can only appear once in the String.
1509 If String is NULL, then ASSERT().
1511 If Address is NULL, then ASSERT().
1513 If String is not aligned in a 16-bit boundary, then ASSERT().
1515 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1516 PcdMaximumUnicodeStringLength Unicode characters, not including the
1517 Null-terminator, then ASSERT().
1519 If EndPointer is not NULL and Address is translated from String, a pointer
1520 to the character that stopped the scan is stored at the location pointed to
1523 @param String Pointer to a Null-terminated Unicode string.
1524 @param EndPointer Pointer to character that stops scan.
1525 @param Address Pointer to the converted IPv6 address.
1526 @param PrefixLength Pointer to the converted IPv6 address prefix
1527 length. MAX_UINT8 is returned when /P is
1530 @retval RETURN_SUCCESS Address is translated from String.
1531 @retval RETURN_INVALID_PARAMETER If String is NULL.
1533 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1535 If String contains "::" and number of X
1537 If P starts with character that is not a
1538 valid decimal digit character.
1539 If the decimal number converted from P
1546 IN CONST CHAR16
*String
,
1547 OUT CHAR16
**EndPointer
, OPTIONAL
1548 OUT IPv6_ADDRESS
*Address
,
1549 OUT UINT8
*PrefixLength OPTIONAL
1553 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1555 This function outputs a value of type IPv4_ADDRESS and may output a value
1556 of type UINT8 by interpreting the contents of the Unicode string specified
1557 by String. The format of the input Unicode string String is as follows:
1561 D and P are decimal digit characters in the range [0-9]. The running zero in
1562 the beginning of D and P will be ignored. /P is optional.
1564 When /P is not in the String, the function stops at the first character that is
1565 not a valid decimal digit character after four D's are converted.
1567 When /P is in the String, the function stops at the first character that is not
1568 a valid decimal digit character after P is converted.
1570 If String is NULL, then ASSERT().
1572 If Address is NULL, then ASSERT().
1574 If String is not aligned in a 16-bit boundary, then ASSERT().
1576 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1577 PcdMaximumUnicodeStringLength Unicode characters, not including the
1578 Null-terminator, then ASSERT().
1580 If EndPointer is not NULL and Address is translated from String, a pointer
1581 to the character that stopped the scan is stored at the location pointed to
1584 @param String Pointer to a Null-terminated Unicode string.
1585 @param EndPointer Pointer to character that stops scan.
1586 @param Address Pointer to the converted IPv4 address.
1587 @param PrefixLength Pointer to the converted IPv4 address prefix
1588 length. MAX_UINT8 is returned when /P is
1591 @retval RETURN_SUCCESS Address is translated from String.
1592 @retval RETURN_INVALID_PARAMETER If String is NULL.
1594 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1595 If any decimal number converted from D
1597 If the decimal number converted from P
1604 IN CONST CHAR16
*String
,
1605 OUT CHAR16
**EndPointer
, OPTIONAL
1606 OUT IPv4_ADDRESS
*Address
,
1607 OUT UINT8
*PrefixLength OPTIONAL
1610 #define GUID_STRING_LENGTH 36
1613 Convert a Null-terminated Unicode GUID string to a value of type
1616 This function outputs a GUID value by interpreting the contents of
1617 the Unicode string specified by String. The format of the input
1618 Unicode string String consists of 36 characters, as follows:
1620 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1622 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1623 [A-F], with each pair representing a single byte hexadecimal value.
1625 The mapping between String and the EFI_GUID structure is as follows:
1643 If String is NULL, then ASSERT().
1644 If Guid is NULL, then ASSERT().
1645 If String is not aligned in a 16-bit boundary, then ASSERT().
1647 @param String Pointer to a Null-terminated Unicode string.
1648 @param Guid Pointer to the converted GUID.
1650 @retval RETURN_SUCCESS Guid is translated from String.
1651 @retval RETURN_INVALID_PARAMETER If String is NULL.
1653 @retval RETURN_UNSUPPORTED If String is not as the above format.
1659 IN CONST CHAR16
*String
,
1664 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1666 This function outputs a byte array by interpreting the contents of
1667 the Unicode string specified by String in hexadecimal format. The format of
1668 the input Unicode string String is:
1672 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1673 The function decodes every two hexadecimal digit characters as one byte. The
1674 decoding stops after Length of characters and outputs Buffer containing
1677 If String is not aligned in a 16-bit boundary, then ASSERT().
1679 If String is NULL, then ASSERT().
1681 If Buffer is NULL, then ASSERT().
1683 If Length is not multiple of 2, then ASSERT().
1685 If PcdMaximumUnicodeStringLength is not zero and Length is greater than
1686 PcdMaximumUnicodeStringLength, then ASSERT().
1688 If MaxBufferSize is less than (Length / 2), then ASSERT().
1690 @param String Pointer to a Null-terminated Unicode string.
1691 @param Length The number of Unicode characters to decode.
1692 @param Buffer Pointer to the converted bytes array.
1693 @param MaxBufferSize The maximum size of Buffer.
1695 @retval RETURN_SUCCESS Buffer is translated from String.
1696 @retval RETURN_INVALID_PARAMETER If String is NULL.
1698 If Length is not multiple of 2.
1699 If PcdMaximumUnicodeStringLength is not zero,
1700 and Length is greater than
1701 PcdMaximumUnicodeStringLength.
1702 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1703 a character that is not valid hexadecimal
1704 digit characters, or a Null-terminator.
1705 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1710 IN CONST CHAR16
*String
,
1713 IN UINTN MaxBufferSize
1716 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1719 [ATTENTION] This function is deprecated for security reason.
1721 Convert a Null-terminated Unicode string to a Null-terminated
1722 ASCII string and returns the ASCII string.
1724 This function converts the content of the Unicode string Source
1725 to the ASCII string Destination by copying the lower 8 bits of
1726 each Unicode character. It returns Destination.
1728 The caller is responsible to make sure Destination points to a buffer with size
1729 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1731 If any Unicode characters in Source contain non-zero value in
1732 the upper 8 bits, then ASSERT().
1734 If Destination is NULL, then ASSERT().
1735 If Source is NULL, then ASSERT().
1736 If Source is not aligned on a 16-bit boundary, then ASSERT().
1737 If Source and Destination overlap, then ASSERT().
1739 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1740 more than PcdMaximumUnicodeStringLength Unicode characters not including
1741 the Null-terminator, then ASSERT().
1743 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1744 than PcdMaximumAsciiStringLength Unicode characters not including the
1745 Null-terminator, then ASSERT().
1747 @param Source The pointer to a Null-terminated Unicode string.
1748 @param Destination The pointer to a Null-terminated ASCII string.
1750 @return Destination.
1755 UnicodeStrToAsciiStr (
1756 IN CONST CHAR16
*Source
,
1757 OUT CHAR8
*Destination
1760 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1763 Convert a Null-terminated Unicode string to a Null-terminated
1766 This function is similar to AsciiStrCpyS.
1768 This function converts the content of the Unicode string Source
1769 to the ASCII string Destination by copying the lower 8 bits of
1770 each Unicode character. The function terminates the ASCII string
1771 Destination by appending a Null-terminator character at the end.
1773 The caller is responsible to make sure Destination points to a buffer with size
1774 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1776 If any Unicode characters in Source contain non-zero value in
1777 the upper 8 bits, then ASSERT().
1779 If Source is not aligned on a 16-bit boundary, then ASSERT().
1780 If an error would be returned, then the function will also ASSERT().
1782 If an error is returned, then the Destination is unmodified.
1784 @param Source The pointer to a Null-terminated Unicode string.
1785 @param Destination The pointer to a Null-terminated ASCII string.
1786 @param DestMax The maximum number of Destination Ascii
1787 char, including terminating null char.
1789 @retval RETURN_SUCCESS String is converted.
1790 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1791 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1793 If PcdMaximumAsciiStringLength is not zero,
1794 and DestMax is greater than
1795 PcdMaximumAsciiStringLength.
1796 If PcdMaximumUnicodeStringLength is not zero,
1797 and DestMax is greater than
1798 PcdMaximumUnicodeStringLength.
1800 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1805 UnicodeStrToAsciiStrS (
1806 IN CONST CHAR16
*Source
,
1807 OUT CHAR8
*Destination
,
1812 Convert not more than Length successive characters from a Null-terminated
1813 Unicode string to a Null-terminated Ascii string. If no null char is copied
1814 from Source, then Destination[Length] is always set to null.
1816 This function converts not more than Length successive characters from the
1817 Unicode string Source to the Ascii string Destination by copying the lower 8
1818 bits of each Unicode character. The function terminates the Ascii string
1819 Destination by appending a Null-terminator character at the end.
1821 The caller is responsible to make sure Destination points to a buffer with size
1822 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1824 If any Unicode characters in Source contain non-zero value in the upper 8
1825 bits, then ASSERT().
1826 If Source is not aligned on a 16-bit boundary, then ASSERT().
1827 If an error would be returned, then the function will also ASSERT().
1829 If an error is returned, then the Destination is unmodified.
1831 @param Source The pointer to a Null-terminated Unicode string.
1832 @param Length The maximum number of Unicode characters to
1834 @param Destination The pointer to a Null-terminated Ascii string.
1835 @param DestMax The maximum number of Destination Ascii
1836 char, including terminating null char.
1837 @param DestinationLength The number of Unicode characters converted.
1839 @retval RETURN_SUCCESS String is converted.
1840 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1842 If DestinationLength is NULL.
1843 If PcdMaximumAsciiStringLength is not zero,
1844 and Length or DestMax is greater than
1845 PcdMaximumAsciiStringLength.
1846 If PcdMaximumUnicodeStringLength is not
1847 zero, and Length or DestMax is greater than
1848 PcdMaximumUnicodeStringLength.
1850 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1851 MIN(StrLen(Source), Length).
1852 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1857 UnicodeStrnToAsciiStrS (
1858 IN CONST CHAR16
*Source
,
1860 OUT CHAR8
*Destination
,
1862 OUT UINTN
*DestinationLength
1865 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1868 [ATTENTION] This function is deprecated for security reason.
1870 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1871 string and returns the new ASCII string.
1873 This function copies the contents of the ASCII string Source to the ASCII
1874 string Destination, and returns Destination. If Source and Destination
1875 overlap, then the results are undefined.
1877 If Destination is NULL, then ASSERT().
1878 If Source is NULL, then ASSERT().
1879 If Source and Destination overlap, then ASSERT().
1880 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1881 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1884 @param Destination The pointer to a Null-terminated ASCII string.
1885 @param Source The pointer to a Null-terminated ASCII string.
1893 OUT CHAR8
*Destination
,
1894 IN CONST CHAR8
*Source
1899 [ATTENTION] This function is deprecated for security reason.
1901 Copies up to a specified length one Null-terminated ASCII string to another
1902 Null-terminated ASCII string and returns the new ASCII string.
1904 This function copies the contents of the ASCII string Source to the ASCII
1905 string Destination, and returns Destination. At most, Length ASCII characters
1906 are copied from Source to Destination. If Length is 0, then Destination is
1907 returned unmodified. If Length is greater that the number of ASCII characters
1908 in Source, then Destination is padded with Null ASCII characters. If Source
1909 and Destination overlap, then the results are undefined.
1911 If Destination is NULL, then ASSERT().
1912 If Source is NULL, then ASSERT().
1913 If Source and Destination overlap, then ASSERT().
1914 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1915 PcdMaximumAsciiStringLength, then ASSERT().
1916 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1917 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1920 @param Destination The pointer to a Null-terminated ASCII string.
1921 @param Source The pointer to a Null-terminated ASCII string.
1922 @param Length The maximum number of ASCII characters to copy.
1930 OUT CHAR8
*Destination
,
1931 IN CONST CHAR8
*Source
,
1934 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1937 Returns the length of a Null-terminated ASCII string.
1939 This function returns the number of ASCII characters in the Null-terminated
1940 ASCII string specified by String.
1942 If Length > 0 and Destination is NULL, then ASSERT().
1943 If Length > 0 and Source is NULL, then ASSERT().
1944 If PcdMaximumAsciiStringLength is not zero and String contains more than
1945 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1948 @param String The pointer to a Null-terminated ASCII string.
1950 @return The length of String.
1956 IN CONST CHAR8
*String
1961 Returns the size of a Null-terminated ASCII string in bytes, including the
1964 This function returns the size, in bytes, of the Null-terminated ASCII string
1965 specified by String.
1967 If String is NULL, then ASSERT().
1968 If PcdMaximumAsciiStringLength is not zero and String contains more than
1969 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1972 @param String The pointer to a Null-terminated ASCII string.
1974 @return The size of String.
1980 IN CONST CHAR8
*String
1985 Compares two Null-terminated ASCII strings, and returns the difference
1986 between the first mismatched ASCII characters.
1988 This function compares the Null-terminated ASCII string FirstString to the
1989 Null-terminated ASCII string SecondString. If FirstString is identical to
1990 SecondString, then 0 is returned. Otherwise, the value returned is the first
1991 mismatched ASCII character in SecondString subtracted from the first
1992 mismatched ASCII character in FirstString.
1994 If FirstString is NULL, then ASSERT().
1995 If SecondString is NULL, then ASSERT().
1996 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1997 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1999 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2000 than PcdMaximumAsciiStringLength ASCII characters not including the
2001 Null-terminator, then ASSERT().
2003 @param FirstString The pointer to a Null-terminated ASCII string.
2004 @param SecondString The pointer to a Null-terminated ASCII string.
2006 @retval ==0 FirstString is identical to SecondString.
2007 @retval !=0 FirstString is not identical to SecondString.
2013 IN CONST CHAR8
*FirstString
,
2014 IN CONST CHAR8
*SecondString
2019 Performs a case insensitive comparison of two Null-terminated ASCII strings,
2020 and returns the difference between the first mismatched ASCII characters.
2022 This function performs a case insensitive comparison of the Null-terminated
2023 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
2024 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
2025 value returned is the first mismatched lower case ASCII character in
2026 SecondString subtracted from the first mismatched lower case ASCII character
2029 If FirstString is NULL, then ASSERT().
2030 If SecondString is NULL, then ASSERT().
2031 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
2032 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2034 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2035 than PcdMaximumAsciiStringLength ASCII characters not including the
2036 Null-terminator, then ASSERT().
2038 @param FirstString The pointer to a Null-terminated ASCII string.
2039 @param SecondString The pointer to a Null-terminated ASCII string.
2041 @retval ==0 FirstString is identical to SecondString using case insensitive
2043 @retval !=0 FirstString is not identical to SecondString using case
2044 insensitive comparisons.
2050 IN CONST CHAR8
*FirstString
,
2051 IN CONST CHAR8
*SecondString
2056 Compares two Null-terminated ASCII strings with maximum lengths, and returns
2057 the difference between the first mismatched ASCII characters.
2059 This function compares the Null-terminated ASCII string FirstString to the
2060 Null-terminated ASCII string SecondString. At most, Length ASCII characters
2061 will be compared. If Length is 0, then 0 is returned. If FirstString is
2062 identical to SecondString, then 0 is returned. Otherwise, the value returned
2063 is the first mismatched ASCII character in SecondString subtracted from the
2064 first mismatched ASCII character in FirstString.
2066 If Length > 0 and FirstString is NULL, then ASSERT().
2067 If Length > 0 and SecondString is NULL, then ASSERT().
2068 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
2069 PcdMaximumAsciiStringLength, then ASSERT().
2070 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
2071 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2073 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
2074 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2077 @param FirstString The pointer to a Null-terminated ASCII string.
2078 @param SecondString The pointer to a Null-terminated ASCII string.
2079 @param Length The maximum number of ASCII characters for compare.
2081 @retval ==0 FirstString is identical to SecondString.
2082 @retval !=0 FirstString is not identical to SecondString.
2088 IN CONST CHAR8
*FirstString
,
2089 IN CONST CHAR8
*SecondString
,
2094 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2097 [ATTENTION] This function is deprecated for security reason.
2099 Concatenates one Null-terminated ASCII string to another Null-terminated
2100 ASCII string, and returns the concatenated ASCII string.
2102 This function concatenates two Null-terminated ASCII strings. The contents of
2103 Null-terminated ASCII string Source are concatenated to the end of Null-
2104 terminated ASCII string Destination. The Null-terminated concatenated ASCII
2107 If Destination is NULL, then ASSERT().
2108 If Source is NULL, then ASSERT().
2109 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
2110 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2112 If PcdMaximumAsciiStringLength is not zero and Source contains more than
2113 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2115 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
2116 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
2117 ASCII characters, then ASSERT().
2119 @param Destination The pointer to a Null-terminated ASCII string.
2120 @param Source The pointer to a Null-terminated ASCII string.
2128 IN OUT CHAR8
*Destination
,
2129 IN CONST CHAR8
*Source
2134 [ATTENTION] This function is deprecated for security reason.
2136 Concatenates up to a specified length one Null-terminated ASCII string to
2137 the end of another Null-terminated ASCII string, and returns the
2138 concatenated ASCII string.
2140 This function concatenates two Null-terminated ASCII strings. The contents
2141 of Null-terminated ASCII string Source are concatenated to the end of Null-
2142 terminated ASCII string Destination, and Destination is returned. At most,
2143 Length ASCII characters are concatenated from Source to the end of
2144 Destination, and Destination is always Null-terminated. If Length is 0, then
2145 Destination is returned unmodified. If Source and Destination overlap, then
2146 the results are undefined.
2148 If Length > 0 and Destination is NULL, then ASSERT().
2149 If Length > 0 and Source is NULL, then ASSERT().
2150 If Source and Destination overlap, then ASSERT().
2151 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
2152 PcdMaximumAsciiStringLength, then ASSERT().
2153 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
2154 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2156 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2157 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2159 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
2160 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
2161 ASCII characters, not including the Null-terminator, then ASSERT().
2163 @param Destination The pointer to a Null-terminated ASCII string.
2164 @param Source The pointer to a Null-terminated ASCII string.
2165 @param Length The maximum number of ASCII characters to concatenate from
2174 IN OUT CHAR8
*Destination
,
2175 IN CONST CHAR8
*Source
,
2178 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
2181 Returns the first occurrence of a Null-terminated ASCII sub-string
2182 in a Null-terminated ASCII string.
2184 This function scans the contents of the ASCII string specified by String
2185 and returns the first occurrence of SearchString. If SearchString is not
2186 found in String, then NULL is returned. If the length of SearchString is zero,
2187 then String is returned.
2189 If String is NULL, then ASSERT().
2190 If SearchString is NULL, then ASSERT().
2192 If PcdMaximumAsciiStringLength is not zero, and SearchString or
2193 String contains more than PcdMaximumAsciiStringLength Unicode characters
2194 not including the Null-terminator, then ASSERT().
2196 @param String The pointer to a Null-terminated ASCII string.
2197 @param SearchString The pointer to a Null-terminated ASCII string to search for.
2199 @retval NULL If the SearchString does not appear in String.
2200 @retval others If there is a match return the first occurrence of SearchingString.
2201 If the length of SearchString is zero,return String.
2207 IN CONST CHAR8
*String
,
2208 IN CONST CHAR8
*SearchString
2213 Convert a Null-terminated ASCII decimal string to a value of type
2216 This function returns a value of type UINTN by interpreting the contents
2217 of the ASCII string String as a decimal number. The format of the input
2218 ASCII string String is:
2220 [spaces] [decimal digits].
2222 The valid decimal digit character is in the range [0-9]. The function will
2223 ignore the pad space, which includes spaces or tab characters, before the digits.
2224 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2225 function stops at the first character that is a not a valid decimal character or
2226 Null-terminator, whichever on comes first.
2228 If String has only pad spaces, then 0 is returned.
2229 If String has no pad spaces or valid decimal digits, then 0 is returned.
2230 If the number represented by String overflows according to the range defined by
2231 UINTN, then MAX_UINTN is returned.
2232 If String is NULL, then ASSERT().
2233 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2234 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2237 @param String The pointer to a Null-terminated ASCII string.
2239 @retval The value translated from String.
2244 AsciiStrDecimalToUintn (
2245 IN CONST CHAR8
*String
2250 Convert a Null-terminated ASCII decimal string to a value of type
2253 This function returns a value of type UINT64 by interpreting the contents
2254 of the ASCII string String as a decimal number. The format of the input
2255 ASCII string String is:
2257 [spaces] [decimal digits].
2259 The valid decimal digit character is in the range [0-9]. The function will
2260 ignore the pad space, which includes spaces or tab characters, before the digits.
2261 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2262 function stops at the first character that is a not a valid decimal character or
2263 Null-terminator, whichever on comes first.
2265 If String has only pad spaces, then 0 is returned.
2266 If String has no pad spaces or valid decimal digits, then 0 is returned.
2267 If the number represented by String overflows according to the range defined by
2268 UINT64, then MAX_UINT64 is returned.
2269 If String is NULL, then ASSERT().
2270 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2271 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2274 @param String The pointer to a Null-terminated ASCII string.
2276 @retval Value translated from String.
2281 AsciiStrDecimalToUint64 (
2282 IN CONST CHAR8
*String
2287 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
2289 This function returns a value of type UINTN by interpreting the contents of
2290 the ASCII string String as a hexadecimal number. The format of the input ASCII
2293 [spaces][zeros][x][hexadecimal digits].
2295 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2296 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2297 appears in the input string, it must be prefixed with at least one 0. The function
2298 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2299 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2300 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2301 digit. Then, the function stops at the first character that is a not a valid
2302 hexadecimal character or Null-terminator, whichever on comes first.
2304 If String has only pad spaces, then 0 is returned.
2305 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2308 If the number represented by String overflows according to the range defined by UINTN,
2309 then MAX_UINTN is returned.
2310 If String is NULL, then ASSERT().
2311 If PcdMaximumAsciiStringLength is not zero,
2312 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2313 the Null-terminator, then ASSERT().
2315 @param String The pointer to a Null-terminated ASCII string.
2317 @retval Value translated from String.
2322 AsciiStrHexToUintn (
2323 IN CONST CHAR8
*String
2328 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
2330 This function returns a value of type UINT64 by interpreting the contents of
2331 the ASCII string String as a hexadecimal number. The format of the input ASCII
2334 [spaces][zeros][x][hexadecimal digits].
2336 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2337 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2338 appears in the input string, it must be prefixed with at least one 0. The function
2339 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2340 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2341 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2342 digit. Then, the function stops at the first character that is a not a valid
2343 hexadecimal character or Null-terminator, whichever on comes first.
2345 If String has only pad spaces, then 0 is returned.
2346 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2349 If the number represented by String overflows according to the range defined by UINT64,
2350 then MAX_UINT64 is returned.
2351 If String is NULL, then ASSERT().
2352 If PcdMaximumAsciiStringLength is not zero,
2353 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2354 the Null-terminator, then ASSERT().
2356 @param String The pointer to a Null-terminated ASCII string.
2358 @retval Value translated from String.
2363 AsciiStrHexToUint64 (
2364 IN CONST CHAR8
*String
2368 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
2370 This function outputs a value of type IPv6_ADDRESS and may output a value
2371 of type UINT8 by interpreting the contents of the ASCII string specified
2372 by String. The format of the input ASCII string String is as follows:
2376 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
2377 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
2378 memory address and high byte is stored in high memory address. P contains decimal
2379 digit characters in the range [0-9]. The running zero in the beginning of P will
2380 be ignored. /P is optional.
2382 When /P is not in the String, the function stops at the first character that is
2383 not a valid hexadecimal digit character after eight X's are converted.
2385 When /P is in the String, the function stops at the first character that is not
2386 a valid decimal digit character after P is converted.
2388 "::" can be used to compress one or more groups of X when X contains only 0.
2389 The "::" can only appear once in the String.
2391 If String is NULL, then ASSERT().
2393 If Address is NULL, then ASSERT().
2395 If EndPointer is not NULL and Address is translated from String, a pointer
2396 to the character that stopped the scan is stored at the location pointed to
2399 @param String Pointer to a Null-terminated ASCII string.
2400 @param EndPointer Pointer to character that stops scan.
2401 @param Address Pointer to the converted IPv6 address.
2402 @param PrefixLength Pointer to the converted IPv6 address prefix
2403 length. MAX_UINT8 is returned when /P is
2406 @retval RETURN_SUCCESS Address is translated from String.
2407 @retval RETURN_INVALID_PARAMETER If String is NULL.
2409 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
2411 If String contains "::" and number of X
2413 If P starts with character that is not a
2414 valid decimal digit character.
2415 If the decimal number converted from P
2421 AsciiStrToIpv6Address (
2422 IN CONST CHAR8
*String
,
2423 OUT CHAR8
**EndPointer
, OPTIONAL
2424 OUT IPv6_ADDRESS
*Address
,
2425 OUT UINT8
*PrefixLength OPTIONAL
2429 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
2431 This function outputs a value of type IPv4_ADDRESS and may output a value
2432 of type UINT8 by interpreting the contents of the ASCII string specified
2433 by String. The format of the input ASCII string String is as follows:
2437 D and P are decimal digit characters in the range [0-9]. The running zero in
2438 the beginning of D and P will be ignored. /P is optional.
2440 When /P is not in the String, the function stops at the first character that is
2441 not a valid decimal digit character after four D's are converted.
2443 When /P is in the String, the function stops at the first character that is not
2444 a valid decimal digit character after P is converted.
2446 If String is NULL, then ASSERT().
2448 If Address is NULL, then ASSERT().
2450 If EndPointer is not NULL and Address is translated from String, a pointer
2451 to the character that stopped the scan is stored at the location pointed to
2454 @param String Pointer to a Null-terminated ASCII string.
2455 @param EndPointer Pointer to character that stops scan.
2456 @param Address Pointer to the converted IPv4 address.
2457 @param PrefixLength Pointer to the converted IPv4 address prefix
2458 length. MAX_UINT8 is returned when /P is
2461 @retval RETURN_SUCCESS Address is translated from String.
2462 @retval RETURN_INVALID_PARAMETER If String is NULL.
2464 @retval RETURN_UNSUPPORTED If String is not in the correct format.
2465 If any decimal number converted from D
2467 If the decimal number converted from P
2473 AsciiStrToIpv4Address (
2474 IN CONST CHAR8
*String
,
2475 OUT CHAR8
**EndPointer
, OPTIONAL
2476 OUT IPv4_ADDRESS
*Address
,
2477 OUT UINT8
*PrefixLength OPTIONAL
2481 Convert a Null-terminated ASCII GUID string to a value of type
2484 This function outputs a GUID value by interpreting the contents of
2485 the ASCII string specified by String. The format of the input
2486 ASCII string String consists of 36 characters, as follows:
2488 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
2490 The pairs aa - pp are two characters in the range [0-9], [a-f] and
2491 [A-F], with each pair representing a single byte hexadecimal value.
2493 The mapping between String and the EFI_GUID structure is as follows:
2511 If String is NULL, then ASSERT().
2512 If Guid is NULL, then ASSERT().
2514 @param String Pointer to a Null-terminated ASCII string.
2515 @param Guid Pointer to the converted GUID.
2517 @retval RETURN_SUCCESS Guid is translated from String.
2518 @retval RETURN_INVALID_PARAMETER If String is NULL.
2520 @retval RETURN_UNSUPPORTED If String is not as the above format.
2526 IN CONST CHAR8
*String
,
2531 Convert a Null-terminated ASCII hexadecimal string to a byte array.
2533 This function outputs a byte array by interpreting the contents of
2534 the ASCII string specified by String in hexadecimal format. The format of
2535 the input ASCII string String is:
2539 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
2540 The function decodes every two hexadecimal digit characters as one byte. The
2541 decoding stops after Length of characters and outputs Buffer containing
2544 If String is NULL, then ASSERT().
2546 If Buffer is NULL, then ASSERT().
2548 If Length is not multiple of 2, then ASSERT().
2550 If PcdMaximumAsciiStringLength is not zero and Length is greater than
2551 PcdMaximumAsciiStringLength, then ASSERT().
2553 If MaxBufferSize is less than (Length / 2), then ASSERT().
2555 @param String Pointer to a Null-terminated ASCII string.
2556 @param Length The number of ASCII characters to decode.
2557 @param Buffer Pointer to the converted bytes array.
2558 @param MaxBufferSize The maximum size of Buffer.
2560 @retval RETURN_SUCCESS Buffer is translated from String.
2561 @retval RETURN_INVALID_PARAMETER If String is NULL.
2563 If Length is not multiple of 2.
2564 If PcdMaximumAsciiStringLength is not zero,
2565 and Length is greater than
2566 PcdMaximumAsciiStringLength.
2567 @retval RETURN_UNSUPPORTED If Length of characters from String contain
2568 a character that is not valid hexadecimal
2569 digit characters, or a Null-terminator.
2570 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
2574 AsciiStrHexToBytes (
2575 IN CONST CHAR8
*String
,
2578 IN UINTN MaxBufferSize
2581 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2584 [ATTENTION] This function is deprecated for security reason.
2586 Convert one Null-terminated ASCII string to a Null-terminated
2587 Unicode string and returns the Unicode string.
2589 This function converts the contents of the ASCII string Source to the Unicode
2590 string Destination, and returns Destination. The function terminates the
2591 Unicode string Destination by appending a Null-terminator character at the end.
2592 The caller is responsible to make sure Destination points to a buffer with size
2593 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2595 If Destination is NULL, then ASSERT().
2596 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2597 If Source is NULL, then ASSERT().
2598 If Source and Destination overlap, then ASSERT().
2599 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2600 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2602 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
2603 PcdMaximumUnicodeStringLength ASCII characters not including the
2604 Null-terminator, then ASSERT().
2606 @param Source The pointer to a Null-terminated ASCII string.
2607 @param Destination The pointer to a Null-terminated Unicode string.
2609 @return Destination.
2614 AsciiStrToUnicodeStr (
2615 IN CONST CHAR8
*Source
,
2616 OUT CHAR16
*Destination
2619 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
2622 Convert one Null-terminated ASCII string to a Null-terminated
2625 This function is similar to StrCpyS.
2627 This function converts the contents of the ASCII string Source to the Unicode
2628 string Destination. The function terminates the Unicode string Destination by
2629 appending a Null-terminator character at the end.
2631 The caller is responsible to make sure Destination points to a buffer with size
2632 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2634 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2635 If an error would be returned, then the function will also ASSERT().
2637 If an error is returned, then the Destination is unmodified.
2639 @param Source The pointer to a Null-terminated ASCII string.
2640 @param Destination The pointer to a Null-terminated Unicode string.
2641 @param DestMax The maximum number of Destination Unicode
2642 char, including terminating null char.
2644 @retval RETURN_SUCCESS String is converted.
2645 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2646 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2648 If PcdMaximumUnicodeStringLength is not zero,
2649 and DestMax is greater than
2650 PcdMaximumUnicodeStringLength.
2651 If PcdMaximumAsciiStringLength is not zero,
2652 and DestMax is greater than
2653 PcdMaximumAsciiStringLength.
2655 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2660 AsciiStrToUnicodeStrS (
2661 IN CONST CHAR8
*Source
,
2662 OUT CHAR16
*Destination
,
2667 Convert not more than Length successive characters from a Null-terminated
2668 Ascii string to a Null-terminated Unicode string. If no null char is copied
2669 from Source, then Destination[Length] is always set to null.
2671 This function converts not more than Length successive characters from the
2672 Ascii string Source to the Unicode string Destination. The function
2673 terminates the Unicode string Destination by appending a Null-terminator
2674 character at the end.
2676 The caller is responsible to make sure Destination points to a buffer with
2677 size not smaller than
2678 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2680 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2681 If an error would be returned, then the function will also ASSERT().
2683 If an error is returned, then Destination and DestinationLength are
2686 @param Source The pointer to a Null-terminated Ascii string.
2687 @param Length The maximum number of Ascii characters to convert.
2688 @param Destination The pointer to a Null-terminated Unicode string.
2689 @param DestMax The maximum number of Destination Unicode char,
2690 including terminating null char.
2691 @param DestinationLength The number of Ascii characters converted.
2693 @retval RETURN_SUCCESS String is converted.
2694 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2696 If DestinationLength is NULL.
2697 If PcdMaximumUnicodeStringLength is not
2698 zero, and Length or DestMax is greater than
2699 PcdMaximumUnicodeStringLength.
2700 If PcdMaximumAsciiStringLength is not zero,
2701 and Length or DestMax is greater than
2702 PcdMaximumAsciiStringLength.
2704 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2705 MIN(AsciiStrLen(Source), Length).
2706 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2711 AsciiStrnToUnicodeStrS (
2712 IN CONST CHAR8
*Source
,
2714 OUT CHAR16
*Destination
,
2716 OUT UINTN
*DestinationLength
2720 Convert a Unicode character to upper case only if
2721 it maps to a valid small-case ASCII character.
2723 This internal function only deal with Unicode character
2724 which maps to a valid small-case ASCII character, i.e.
2725 L'a' to L'z'. For other Unicode character, the input character
2726 is returned directly.
2728 @param Char The character to convert.
2730 @retval LowerCharacter If the Char is with range L'a' to L'z'.
2731 @retval Unchanged Otherwise.
2741 Converts a lowercase Ascii character to upper one.
2743 If Chr is lowercase Ascii character, then converts it to upper one.
2745 If Value >= 0xA0, then ASSERT().
2746 If (Value & 0x0F) >= 0x0A, then ASSERT().
2748 @param Chr one Ascii character
2750 @return The uppercase value of Ascii character
2760 Convert binary data to a Base64 encoded ascii string based on RFC4648.
2762 Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
2763 The Ascii string is produced by converting the data string specified by Source and SourceLength.
2765 @param Source Input UINT8 data
2766 @param SourceLength Number of UINT8 bytes of data
2767 @param Destination Pointer to output string buffer
2768 @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed.
2769 Caller is responsible for passing in buffer of DestinationSize
2771 @retval RETURN_SUCCESS When ascii buffer is filled in.
2772 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
2773 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
2774 @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1.
2775 @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize.
2781 IN CONST UINT8
*Source
,
2782 IN UINTN SourceLength
,
2783 OUT CHAR8
*Destination OPTIONAL
,
2784 IN OUT UINTN
*DestinationSize
2788 Convert Base64 ascii string to binary data based on RFC4648.
2790 Produce Null-terminated binary data in the output buffer specified by Destination and DestinationSize.
2791 The binary data is produced by converting the Base64 ascii string specified by Source and SourceLength.
2793 @param Source Input ASCII characters
2794 @param SourceLength Number of ASCII characters
2795 @param Destination Pointer to output buffer
2796 @param DestinationSize Caller is responsible for passing in buffer of at least DestinationSize.
2797 Set 0 to get the size needed. Set to bytes stored on return.
2799 @retval RETURN_SUCCESS When binary buffer is filled in.
2800 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
2801 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS -(UINTN)Destination ).
2802 @retval RETURN_INVALID_PARAMETER If there is any invalid character in input stream.
2803 @retval RETURN_BUFFER_TOO_SMALL If buffer length is smaller than required buffer size.
2809 IN CONST CHAR8
*Source
,
2810 IN UINTN SourceLength
,
2811 OUT UINT8
*Destination OPTIONAL
,
2812 IN OUT UINTN
*DestinationSize
2816 Converts an 8-bit value to an 8-bit BCD value.
2818 Converts the 8-bit value specified by Value to BCD. The BCD value is
2821 If Value >= 100, then ASSERT().
2823 @param Value The 8-bit value to convert to BCD. Range 0..99.
2825 @return The BCD value.
2836 Converts an 8-bit BCD value to an 8-bit value.
2838 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2841 If Value >= 0xA0, then ASSERT().
2842 If (Value & 0x0F) >= 0x0A, then ASSERT().
2844 @param Value The 8-bit BCD value to convert to an 8-bit value.
2846 @return The 8-bit value is returned.
2856 // File Path Manipulation Functions
2860 Removes the last directory or file entry in a path.
2862 @param[in, out] Path The pointer to the path to modify.
2864 @retval FALSE Nothing was found to remove.
2865 @retval TRUE A directory or file was removed.
2874 Function to clean up paths.
2875 - Single periods in the path are removed.
2876 - Double periods in the path are removed along with a single parent directory.
2877 - Forward slashes L'/' are converted to backward slashes L'\'.
2879 This will be done inline and the existing buffer may be larger than required
2882 @param[in] Path The pointer to the string containing the path.
2884 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2888 PathCleanUpDirectories(
2893 // Linked List Functions and Macros
2897 Initializes the head node of a doubly linked list that is declared as a
2898 global variable in a module.
2900 Initializes the forward and backward links of a new linked list. After
2901 initializing a linked list with this macro, the other linked list functions
2902 may be used to add and remove nodes from the linked list. This macro results
2903 in smaller executables by initializing the linked list in the data section,
2904 instead if calling the InitializeListHead() function to perform the
2905 equivalent operation.
2907 @param ListHead The head note of a list to initialize.
2910 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2914 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2917 If FirstEntry is NULL, then ASSERT().
2918 If FirstEntry->ForwardLink is NULL, then ASSERT().
2919 If FirstEntry->BackLink is NULL, then ASSERT().
2920 If SecondEntry is NULL, then ASSERT();
2921 If PcdMaximumLinkedListLength is not zero, and List contains more than
2922 PcdMaximumLinkedListLength nodes, then ASSERT().
2924 @param FirstEntry A pointer to a node in a linked list.
2925 @param SecondEntry A pointer to the node to locate.
2927 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.
2928 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,
2929 or FirstEntry is invalid.
2935 IN CONST LIST_ENTRY
*FirstEntry
,
2936 IN CONST LIST_ENTRY
*SecondEntry
2941 Initializes the head node of a doubly linked list, and returns the pointer to
2942 the head node of the doubly linked list.
2944 Initializes the forward and backward links of a new linked list. After
2945 initializing a linked list with this function, the other linked list
2946 functions may be used to add and remove nodes from the linked list. It is up
2947 to the caller of this function to allocate the memory for ListHead.
2949 If ListHead is NULL, then ASSERT().
2951 @param ListHead A pointer to the head node of a new doubly linked list.
2958 InitializeListHead (
2959 IN OUT LIST_ENTRY
*ListHead
2964 Adds a node to the beginning of a doubly linked list, and returns the pointer
2965 to the head node of the doubly linked list.
2967 Adds the node Entry at the beginning of the doubly linked list denoted by
2968 ListHead, and returns ListHead.
2970 If ListHead is NULL, then ASSERT().
2971 If Entry is NULL, then ASSERT().
2972 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2973 InitializeListHead(), then ASSERT().
2974 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2975 of nodes in ListHead, including the ListHead node, is greater than or
2976 equal to PcdMaximumLinkedListLength, then ASSERT().
2978 @param ListHead A pointer to the head node of a doubly linked list.
2979 @param Entry A pointer to a node that is to be inserted at the beginning
2980 of a doubly linked list.
2988 IN OUT LIST_ENTRY
*ListHead
,
2989 IN OUT LIST_ENTRY
*Entry
2994 Adds a node to the end of a doubly linked list, and returns the pointer to
2995 the head node of the doubly linked list.
2997 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2998 and returns ListHead.
3000 If ListHead is NULL, then ASSERT().
3001 If Entry is NULL, then ASSERT().
3002 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3003 InitializeListHead(), then ASSERT().
3004 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
3005 of nodes in ListHead, including the ListHead node, is greater than or
3006 equal to PcdMaximumLinkedListLength, then ASSERT().
3008 @param ListHead A pointer to the head node of a doubly linked list.
3009 @param Entry A pointer to a node that is to be added at the end of the
3018 IN OUT LIST_ENTRY
*ListHead
,
3019 IN OUT LIST_ENTRY
*Entry
3024 Retrieves the first node of a doubly linked list.
3026 Returns the first node of a doubly linked list. List must have been
3027 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3028 If List is empty, then List is returned.
3030 If List is NULL, then ASSERT().
3031 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3032 InitializeListHead(), then ASSERT().
3033 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3034 in List, including the List node, is greater than or equal to
3035 PcdMaximumLinkedListLength, then ASSERT().
3037 @param List A pointer to the head node of a doubly linked list.
3039 @return The first node of a doubly linked list.
3040 @retval List The list is empty.
3046 IN CONST LIST_ENTRY
*List
3051 Retrieves the next node of a doubly linked list.
3053 Returns the node of a doubly linked list that follows Node.
3054 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3055 or InitializeListHead(). If List is empty, then List is returned.
3057 If List is NULL, then ASSERT().
3058 If Node is NULL, then ASSERT().
3059 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3060 InitializeListHead(), then ASSERT().
3061 If PcdMaximumLinkedListLength is not zero, and List contains more than
3062 PcdMaximumLinkedListLength nodes, then ASSERT().
3063 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3065 @param List A pointer to the head node of a doubly linked list.
3066 @param Node A pointer to a node in the doubly linked list.
3068 @return The pointer to the next node if one exists. Otherwise List is returned.
3074 IN CONST LIST_ENTRY
*List
,
3075 IN CONST LIST_ENTRY
*Node
3080 Retrieves the previous node of a doubly linked list.
3082 Returns the node of a doubly linked list that precedes Node.
3083 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3084 or InitializeListHead(). If List is empty, then List is returned.
3086 If List is NULL, then ASSERT().
3087 If Node is NULL, then ASSERT().
3088 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3089 InitializeListHead(), then ASSERT().
3090 If PcdMaximumLinkedListLength is not zero, and List contains more than
3091 PcdMaximumLinkedListLength nodes, then ASSERT().
3092 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3094 @param List A pointer to the head node of a doubly linked list.
3095 @param Node A pointer to a node in the doubly linked list.
3097 @return The pointer to the previous node if one exists. Otherwise List is returned.
3103 IN CONST LIST_ENTRY
*List
,
3104 IN CONST LIST_ENTRY
*Node
3109 Checks to see if a doubly linked list is empty or not.
3111 Checks to see if the doubly linked list is empty. If the linked list contains
3112 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
3114 If ListHead is NULL, then ASSERT().
3115 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3116 InitializeListHead(), then ASSERT().
3117 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3118 in List, including the List node, is greater than or equal to
3119 PcdMaximumLinkedListLength, then ASSERT().
3121 @param ListHead A pointer to the head node of a doubly linked list.
3123 @retval TRUE The linked list is empty.
3124 @retval FALSE The linked list is not empty.
3130 IN CONST LIST_ENTRY
*ListHead
3135 Determines if a node in a doubly linked list is the head node of a the same
3136 doubly linked list. This function is typically used to terminate a loop that
3137 traverses all the nodes in a doubly linked list starting with the head node.
3139 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
3140 nodes in the doubly linked list specified by List. List must have been
3141 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3143 If List is NULL, then ASSERT().
3144 If Node is NULL, then ASSERT().
3145 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
3147 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3148 in List, including the List node, is greater than or equal to
3149 PcdMaximumLinkedListLength, then ASSERT().
3150 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
3151 to List, then ASSERT().
3153 @param List A pointer to the head node of a doubly linked list.
3154 @param Node A pointer to a node in the doubly linked list.
3156 @retval TRUE Node is the head of the doubly-linked list pointed by List.
3157 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
3163 IN CONST LIST_ENTRY
*List
,
3164 IN CONST LIST_ENTRY
*Node
3169 Determines if a node the last node in a doubly linked list.
3171 Returns TRUE if Node is the last node in the doubly linked list specified by
3172 List. Otherwise, FALSE is returned. List must have been initialized with
3173 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3175 If List is NULL, then ASSERT().
3176 If Node is NULL, then ASSERT().
3177 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3178 InitializeListHead(), then ASSERT().
3179 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3180 in List, including the List node, is greater than or equal to
3181 PcdMaximumLinkedListLength, then ASSERT().
3182 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3184 @param List A pointer to the head node of a doubly linked list.
3185 @param Node A pointer to a node in the doubly linked list.
3187 @retval TRUE Node is the last node in the linked list.
3188 @retval FALSE Node is not the last node in the linked list.
3194 IN CONST LIST_ENTRY
*List
,
3195 IN CONST LIST_ENTRY
*Node
3200 Swaps the location of two nodes in a doubly linked list, and returns the
3201 first node after the swap.
3203 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
3204 Otherwise, the location of the FirstEntry node is swapped with the location
3205 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
3206 same double linked list as FirstEntry and that double linked list must have
3207 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3208 SecondEntry is returned after the nodes are swapped.
3210 If FirstEntry is NULL, then ASSERT().
3211 If SecondEntry is NULL, then ASSERT().
3212 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
3213 same linked list, then ASSERT().
3214 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3215 linked list containing the FirstEntry and SecondEntry nodes, including
3216 the FirstEntry and SecondEntry nodes, is greater than or equal to
3217 PcdMaximumLinkedListLength, then ASSERT().
3219 @param FirstEntry A pointer to a node in a linked list.
3220 @param SecondEntry A pointer to another node in the same linked list.
3222 @return SecondEntry.
3228 IN OUT LIST_ENTRY
*FirstEntry
,
3229 IN OUT LIST_ENTRY
*SecondEntry
3234 Removes a node from a doubly linked list, and returns the node that follows
3237 Removes the node Entry from a doubly linked list. It is up to the caller of
3238 this function to release the memory used by this node if that is required. On
3239 exit, the node following Entry in the doubly linked list is returned. If
3240 Entry is the only node in the linked list, then the head node of the linked
3243 If Entry is NULL, then ASSERT().
3244 If Entry is the head node of an empty list, then ASSERT().
3245 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3246 linked list containing Entry, including the Entry node, is greater than
3247 or equal to PcdMaximumLinkedListLength, then ASSERT().
3249 @param Entry A pointer to a node in a linked list.
3257 IN CONST LIST_ENTRY
*Entry
3265 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
3266 with zeros. The shifted value is returned.
3268 This function shifts the 64-bit value Operand to the left by Count bits. The
3269 low Count bits are set to zero. The shifted value is returned.
3271 If Count is greater than 63, then ASSERT().
3273 @param Operand The 64-bit operand to shift left.
3274 @param Count The number of bits to shift left.
3276 @return Operand << Count.
3288 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
3289 filled with zeros. The shifted value is returned.
3291 This function shifts the 64-bit value Operand to the right by Count bits. The
3292 high Count bits are set to zero. The shifted value is returned.
3294 If Count is greater than 63, then ASSERT().
3296 @param Operand The 64-bit operand to shift right.
3297 @param Count The number of bits to shift right.
3299 @return Operand >> Count
3311 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
3312 with original integer's bit 63. The shifted value is returned.
3314 This function shifts the 64-bit value Operand to the right by Count bits. The
3315 high Count bits are set to bit 63 of Operand. The shifted value is returned.
3317 If Count is greater than 63, then ASSERT().
3319 @param Operand The 64-bit operand to shift right.
3320 @param Count The number of bits to shift right.
3322 @return Operand >> Count
3334 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
3335 with the high bits that were rotated.
3337 This function rotates the 32-bit value Operand to the left by Count bits. The
3338 low Count bits are fill with the high Count bits of Operand. The rotated
3341 If Count is greater than 31, then ASSERT().
3343 @param Operand The 32-bit operand to rotate left.
3344 @param Count The number of bits to rotate left.
3346 @return Operand << Count
3358 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
3359 with the low bits that were rotated.
3361 This function rotates the 32-bit value Operand to the right by Count bits.
3362 The high Count bits are fill with the low Count bits of Operand. The rotated
3365 If Count is greater than 31, then ASSERT().
3367 @param Operand The 32-bit operand to rotate right.
3368 @param Count The number of bits to rotate right.
3370 @return Operand >> Count
3382 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3383 with the high bits that were rotated.
3385 This function rotates the 64-bit value Operand to the left by Count bits. The
3386 low Count bits are fill with the high Count bits of Operand. The rotated
3389 If Count is greater than 63, then ASSERT().
3391 @param Operand The 64-bit operand to rotate left.
3392 @param Count The number of bits to rotate left.
3394 @return Operand << Count
3406 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3407 with the high low bits that were rotated.
3409 This function rotates the 64-bit value Operand to the right by Count bits.
3410 The high Count bits are fill with the low Count bits of Operand. The rotated
3413 If Count is greater than 63, then ASSERT().
3415 @param Operand The 64-bit operand to rotate right.
3416 @param Count The number of bits to rotate right.
3418 @return Operand >> Count
3430 Returns the bit position of the lowest bit set in a 32-bit value.
3432 This function computes the bit position of the lowest bit set in the 32-bit
3433 value specified by Operand. If Operand is zero, then -1 is returned.
3434 Otherwise, a value between 0 and 31 is returned.
3436 @param Operand The 32-bit operand to evaluate.
3438 @retval 0..31 The lowest bit set in Operand was found.
3439 @retval -1 Operand is zero.
3450 Returns the bit position of the lowest bit set in a 64-bit value.
3452 This function computes the bit position of the lowest bit set in the 64-bit
3453 value specified by Operand. If Operand is zero, then -1 is returned.
3454 Otherwise, a value between 0 and 63 is returned.
3456 @param Operand The 64-bit operand to evaluate.
3458 @retval 0..63 The lowest bit set in Operand was found.
3459 @retval -1 Operand is zero.
3471 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3474 This function computes the bit position of the highest bit set in the 32-bit
3475 value specified by Operand. If Operand is zero, then -1 is returned.
3476 Otherwise, a value between 0 and 31 is returned.
3478 @param Operand The 32-bit operand to evaluate.
3480 @retval 0..31 Position of the highest bit set in Operand if found.
3481 @retval -1 Operand is zero.
3492 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3495 This function computes the bit position of the highest bit set in the 64-bit
3496 value specified by Operand. If Operand is zero, then -1 is returned.
3497 Otherwise, a value between 0 and 63 is returned.
3499 @param Operand The 64-bit operand to evaluate.
3501 @retval 0..63 Position of the highest bit set in Operand if found.
3502 @retval -1 Operand is zero.
3513 Returns the value of the highest bit set in a 32-bit value. Equivalent to
3516 This function computes the value of the highest bit set in the 32-bit value
3517 specified by Operand. If Operand is zero, then zero is returned.
3519 @param Operand The 32-bit operand to evaluate.
3521 @return 1 << HighBitSet32(Operand)
3522 @retval 0 Operand is zero.
3533 Returns the value of the highest bit set in a 64-bit value. Equivalent to
3536 This function computes the value of the highest bit set in the 64-bit value
3537 specified by Operand. If Operand is zero, then zero is returned.
3539 @param Operand The 64-bit operand to evaluate.
3541 @return 1 << HighBitSet64(Operand)
3542 @retval 0 Operand is zero.
3553 Switches the endianness of a 16-bit integer.
3555 This function swaps the bytes in a 16-bit unsigned value to switch the value
3556 from little endian to big endian or vice versa. The byte swapped value is
3559 @param Value A 16-bit unsigned value.
3561 @return The byte swapped Value.
3572 Switches the endianness of a 32-bit integer.
3574 This function swaps the bytes in a 32-bit unsigned value to switch the value
3575 from little endian to big endian or vice versa. The byte swapped value is
3578 @param Value A 32-bit unsigned value.
3580 @return The byte swapped Value.
3591 Switches the endianness of a 64-bit integer.
3593 This function swaps the bytes in a 64-bit unsigned value to switch the value
3594 from little endian to big endian or vice versa. The byte swapped value is
3597 @param Value A 64-bit unsigned value.
3599 @return The byte swapped Value.
3610 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3611 generates a 64-bit unsigned result.
3613 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3614 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3615 bit unsigned result is returned.
3617 @param Multiplicand A 64-bit unsigned value.
3618 @param Multiplier A 32-bit unsigned value.
3620 @return Multiplicand * Multiplier
3626 IN UINT64 Multiplicand
,
3627 IN UINT32 Multiplier
3632 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3633 generates a 64-bit unsigned result.
3635 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3636 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3637 bit unsigned result is returned.
3639 @param Multiplicand A 64-bit unsigned value.
3640 @param Multiplier A 64-bit unsigned value.
3642 @return Multiplicand * Multiplier.
3648 IN UINT64 Multiplicand
,
3649 IN UINT64 Multiplier
3654 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3655 64-bit signed result.
3657 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3658 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3659 signed result is returned.
3661 @param Multiplicand A 64-bit signed value.
3662 @param Multiplier A 64-bit signed value.
3664 @return Multiplicand * Multiplier
3670 IN INT64 Multiplicand
,
3676 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3677 a 64-bit unsigned result.
3679 This function divides the 64-bit unsigned value Dividend by the 32-bit
3680 unsigned value Divisor and generates a 64-bit unsigned quotient. This
3681 function returns the 64-bit unsigned quotient.
3683 If Divisor is 0, then ASSERT().
3685 @param Dividend A 64-bit unsigned value.
3686 @param Divisor A 32-bit unsigned value.
3688 @return Dividend / Divisor.
3700 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3701 a 32-bit unsigned remainder.
3703 This function divides the 64-bit unsigned value Dividend by the 32-bit
3704 unsigned value Divisor and generates a 32-bit remainder. This function
3705 returns the 32-bit unsigned remainder.
3707 If Divisor is 0, then ASSERT().
3709 @param Dividend A 64-bit unsigned value.
3710 @param Divisor A 32-bit unsigned value.
3712 @return Dividend % Divisor.
3724 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3725 a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3727 This function divides the 64-bit unsigned value Dividend by the 32-bit
3728 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3729 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3730 This function returns the 64-bit unsigned quotient.
3732 If Divisor is 0, then ASSERT().
3734 @param Dividend A 64-bit unsigned value.
3735 @param Divisor A 32-bit unsigned value.
3736 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3737 optional and may be NULL.
3739 @return Dividend / Divisor.
3744 DivU64x32Remainder (
3747 OUT UINT32
*Remainder OPTIONAL
3752 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3753 a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3755 This function divides the 64-bit unsigned value Dividend by the 64-bit
3756 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3757 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3758 This function returns the 64-bit unsigned quotient.
3760 If Divisor is 0, then ASSERT().
3762 @param Dividend A 64-bit unsigned value.
3763 @param Divisor A 64-bit unsigned value.
3764 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3765 optional and may be NULL.
3767 @return Dividend / Divisor.
3772 DivU64x64Remainder (
3775 OUT UINT64
*Remainder OPTIONAL
3780 Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3781 64-bit signed result and a optional 64-bit signed remainder.
3783 This function divides the 64-bit signed value Dividend by the 64-bit signed
3784 value Divisor and generates a 64-bit signed quotient. If Remainder is not
3785 NULL, then the 64-bit signed remainder is returned in Remainder. This
3786 function returns the 64-bit signed quotient.
3788 It is the caller's responsibility to not call this function with a Divisor of 0.
3789 If Divisor is 0, then the quotient and remainder should be assumed to be
3790 the largest negative integer.
3792 If Divisor is 0, then ASSERT().
3794 @param Dividend A 64-bit signed value.
3795 @param Divisor A 64-bit signed value.
3796 @param Remainder A pointer to a 64-bit signed value. This parameter is
3797 optional and may be NULL.
3799 @return Dividend / Divisor.
3804 DivS64x64Remainder (
3807 OUT INT64
*Remainder OPTIONAL
3812 Reads a 16-bit value from memory that may be unaligned.
3814 This function returns the 16-bit value pointed to by Buffer. The function
3815 guarantees that the read operation does not produce an alignment fault.
3817 If the Buffer is NULL, then ASSERT().
3819 @param Buffer The pointer to a 16-bit value that may be unaligned.
3821 @return The 16-bit value read from Buffer.
3827 IN CONST UINT16
*Buffer
3832 Writes a 16-bit value to memory that may be unaligned.
3834 This function writes the 16-bit value specified by Value to Buffer. Value is
3835 returned. The function guarantees that the write operation does not produce
3838 If the Buffer is NULL, then ASSERT().
3840 @param Buffer The pointer to a 16-bit value that may be unaligned.
3841 @param Value 16-bit value to write to Buffer.
3843 @return The 16-bit value to write to Buffer.
3855 Reads a 24-bit value from memory that may be unaligned.
3857 This function returns the 24-bit value pointed to by Buffer. The function
3858 guarantees that the read operation does not produce an alignment fault.
3860 If the Buffer is NULL, then ASSERT().
3862 @param Buffer The pointer to a 24-bit value that may be unaligned.
3864 @return The 24-bit value read from Buffer.
3870 IN CONST UINT32
*Buffer
3875 Writes a 24-bit value to memory that may be unaligned.
3877 This function writes the 24-bit value specified by Value to Buffer. Value is
3878 returned. The function guarantees that the write operation does not produce
3881 If the Buffer is NULL, then ASSERT().
3883 @param Buffer The pointer to a 24-bit value that may be unaligned.
3884 @param Value 24-bit value to write to Buffer.
3886 @return The 24-bit value to write to Buffer.
3898 Reads a 32-bit value from memory that may be unaligned.
3900 This function returns the 32-bit value pointed to by Buffer. The function
3901 guarantees that the read operation does not produce an alignment fault.
3903 If the Buffer is NULL, then ASSERT().
3905 @param Buffer The pointer to a 32-bit value that may be unaligned.
3907 @return The 32-bit value read from Buffer.
3913 IN CONST UINT32
*Buffer
3918 Writes a 32-bit value to memory that may be unaligned.
3920 This function writes the 32-bit value specified by Value to Buffer. Value is
3921 returned. The function guarantees that the write operation does not produce
3924 If the Buffer is NULL, then ASSERT().
3926 @param Buffer The pointer to a 32-bit value that may be unaligned.
3927 @param Value 32-bit value to write to Buffer.
3929 @return The 32-bit value to write to Buffer.
3941 Reads a 64-bit value from memory that may be unaligned.
3943 This function returns the 64-bit value pointed to by Buffer. The function
3944 guarantees that the read operation does not produce an alignment fault.
3946 If the Buffer is NULL, then ASSERT().
3948 @param Buffer The pointer to a 64-bit value that may be unaligned.
3950 @return The 64-bit value read from Buffer.
3956 IN CONST UINT64
*Buffer
3961 Writes a 64-bit value to memory that may be unaligned.
3963 This function writes the 64-bit value specified by Value to Buffer. Value is
3964 returned. The function guarantees that the write operation does not produce
3967 If the Buffer is NULL, then ASSERT().
3969 @param Buffer The pointer to a 64-bit value that may be unaligned.
3970 @param Value 64-bit value to write to Buffer.
3972 @return The 64-bit value to write to Buffer.
3984 // Bit Field Functions
3988 Returns a bit field from an 8-bit value.
3990 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3992 If 8-bit operations are not supported, then ASSERT().
3993 If StartBit is greater than 7, then ASSERT().
3994 If EndBit is greater than 7, then ASSERT().
3995 If EndBit is less than StartBit, then ASSERT().
3997 @param Operand Operand on which to perform the bitfield operation.
3998 @param StartBit The ordinal of the least significant bit in the bit field.
4000 @param EndBit The ordinal of the most significant bit in the bit field.
4003 @return The bit field read.
4016 Writes a bit field to an 8-bit value, and returns the result.
4018 Writes Value to the bit field specified by the StartBit and the EndBit in
4019 Operand. All other bits in Operand are preserved. The new 8-bit value is
4022 If 8-bit operations are not supported, then ASSERT().
4023 If StartBit is greater than 7, then ASSERT().
4024 If EndBit is greater than 7, then ASSERT().
4025 If EndBit is less than StartBit, then ASSERT().
4026 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4028 @param Operand Operand on which to perform the bitfield operation.
4029 @param StartBit The ordinal of the least significant bit in the bit field.
4031 @param EndBit The ordinal of the most significant bit in the bit field.
4033 @param Value New value of the bit field.
4035 @return The new 8-bit value.
4049 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
4052 Performs a bitwise OR between the bit field specified by StartBit
4053 and EndBit in Operand and the value specified by OrData. All other bits in
4054 Operand are preserved. The new 8-bit value is returned.
4056 If 8-bit operations are not supported, then ASSERT().
4057 If StartBit is greater than 7, then ASSERT().
4058 If EndBit is greater than 7, then ASSERT().
4059 If EndBit is less than StartBit, then ASSERT().
4060 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4062 @param Operand Operand on which to perform the bitfield operation.
4063 @param StartBit The ordinal of the least significant bit in the bit field.
4065 @param EndBit The ordinal of the most significant bit in the bit field.
4067 @param OrData The value to OR with the read value from the value
4069 @return The new 8-bit value.
4083 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
4086 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4087 in Operand and the value specified by AndData. All other bits in Operand are
4088 preserved. The new 8-bit value is returned.
4090 If 8-bit operations are not supported, then ASSERT().
4091 If StartBit is greater than 7, then ASSERT().
4092 If EndBit is greater than 7, then ASSERT().
4093 If EndBit is less than StartBit, then ASSERT().
4094 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4096 @param Operand Operand on which to perform the bitfield operation.
4097 @param StartBit The ordinal of the least significant bit in the bit field.
4099 @param EndBit The ordinal of the most significant bit in the bit field.
4101 @param AndData The value to AND with the read value from the value.
4103 @return The new 8-bit value.
4117 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
4118 bitwise OR, and returns the result.
4120 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4121 in Operand and the value specified by AndData, followed by a bitwise
4122 OR with value specified by OrData. All other bits in Operand are
4123 preserved. The new 8-bit value is returned.
4125 If 8-bit operations are not supported, then ASSERT().
4126 If StartBit is greater than 7, then ASSERT().
4127 If EndBit is greater than 7, then ASSERT().
4128 If EndBit is less than StartBit, then ASSERT().
4129 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4130 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4132 @param Operand Operand on which to perform the bitfield operation.
4133 @param StartBit The ordinal of the least significant bit in the bit field.
4135 @param EndBit The ordinal of the most significant bit in the bit field.
4137 @param AndData The value to AND with the read value from the value.
4138 @param OrData The value to OR with the result of the AND operation.
4140 @return The new 8-bit value.
4145 BitFieldAndThenOr8 (
4155 Returns a bit field from a 16-bit value.
4157 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4159 If 16-bit operations are not supported, then ASSERT().
4160 If StartBit is greater than 15, then ASSERT().
4161 If EndBit is greater than 15, then ASSERT().
4162 If EndBit is less than StartBit, then ASSERT().
4164 @param Operand Operand on which to perform the bitfield operation.
4165 @param StartBit The ordinal of the least significant bit in the bit field.
4167 @param EndBit The ordinal of the most significant bit in the bit field.
4170 @return The bit field read.
4183 Writes a bit field to a 16-bit value, and returns the result.
4185 Writes Value to the bit field specified by the StartBit and the EndBit in
4186 Operand. All other bits in Operand are preserved. The new 16-bit value is
4189 If 16-bit operations are not supported, then ASSERT().
4190 If StartBit is greater than 15, then ASSERT().
4191 If EndBit is greater than 15, then ASSERT().
4192 If EndBit is less than StartBit, then ASSERT().
4193 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4195 @param Operand Operand on which to perform the bitfield operation.
4196 @param StartBit The ordinal of the least significant bit in the bit field.
4198 @param EndBit The ordinal of the most significant bit in the bit field.
4200 @param Value New value of the bit field.
4202 @return The new 16-bit value.
4216 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
4219 Performs a bitwise OR between the bit field specified by StartBit
4220 and EndBit in Operand and the value specified by OrData. All other bits in
4221 Operand are preserved. The new 16-bit value is returned.
4223 If 16-bit operations are not supported, then ASSERT().
4224 If StartBit is greater than 15, then ASSERT().
4225 If EndBit is greater than 15, then ASSERT().
4226 If EndBit is less than StartBit, then ASSERT().
4227 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4229 @param Operand Operand on which to perform the bitfield operation.
4230 @param StartBit The ordinal of the least significant bit in the bit field.
4232 @param EndBit The ordinal of the most significant bit in the bit field.
4234 @param OrData The value to OR with the read value from the value
4236 @return The new 16-bit value.
4250 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
4253 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4254 in Operand and the value specified by AndData. All other bits in Operand are
4255 preserved. The new 16-bit value is returned.
4257 If 16-bit operations are not supported, then ASSERT().
4258 If StartBit is greater than 15, then ASSERT().
4259 If EndBit is greater than 15, then ASSERT().
4260 If EndBit is less than StartBit, then ASSERT().
4261 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4263 @param Operand Operand on which to perform the bitfield operation.
4264 @param StartBit The ordinal of the least significant bit in the bit field.
4266 @param EndBit The ordinal of the most significant bit in the bit field.
4268 @param AndData The value to AND with the read value from the value
4270 @return The new 16-bit value.
4284 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
4285 bitwise OR, and returns the result.
4287 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4288 in Operand and the value specified by AndData, followed by a bitwise
4289 OR with value specified by OrData. All other bits in Operand are
4290 preserved. The new 16-bit value is returned.
4292 If 16-bit operations are not supported, then ASSERT().
4293 If StartBit is greater than 15, then ASSERT().
4294 If EndBit is greater than 15, then ASSERT().
4295 If EndBit is less than StartBit, then ASSERT().
4296 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4297 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4299 @param Operand Operand on which to perform the bitfield operation.
4300 @param StartBit The ordinal of the least significant bit in the bit field.
4302 @param EndBit The ordinal of the most significant bit in the bit field.
4304 @param AndData The value to AND with the read value from the value.
4305 @param OrData The value to OR with the result of the AND operation.
4307 @return The new 16-bit value.
4312 BitFieldAndThenOr16 (
4322 Returns a bit field from a 32-bit value.
4324 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4326 If 32-bit operations are not supported, then ASSERT().
4327 If StartBit is greater than 31, then ASSERT().
4328 If EndBit is greater than 31, then ASSERT().
4329 If EndBit is less than StartBit, then ASSERT().
4331 @param Operand Operand on which to perform the bitfield operation.
4332 @param StartBit The ordinal of the least significant bit in the bit field.
4334 @param EndBit The ordinal of the most significant bit in the bit field.
4337 @return The bit field read.
4350 Writes a bit field to a 32-bit value, and returns the result.
4352 Writes Value to the bit field specified by the StartBit and the EndBit in
4353 Operand. All other bits in Operand are preserved. The new 32-bit value is
4356 If 32-bit operations are not supported, then ASSERT().
4357 If StartBit is greater than 31, then ASSERT().
4358 If EndBit is greater than 31, then ASSERT().
4359 If EndBit is less than StartBit, then ASSERT().
4360 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4362 @param Operand Operand on which to perform the bitfield operation.
4363 @param StartBit The ordinal of the least significant bit in the bit field.
4365 @param EndBit The ordinal of the most significant bit in the bit field.
4367 @param Value New value of the bit field.
4369 @return The new 32-bit value.
4383 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
4386 Performs a bitwise OR between the bit field specified by StartBit
4387 and EndBit in Operand and the value specified by OrData. All other bits in
4388 Operand are preserved. The new 32-bit value is returned.
4390 If 32-bit operations are not supported, then ASSERT().
4391 If StartBit is greater than 31, then ASSERT().
4392 If EndBit is greater than 31, then ASSERT().
4393 If EndBit is less than StartBit, then ASSERT().
4394 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4396 @param Operand Operand on which to perform the bitfield operation.
4397 @param StartBit The ordinal of the least significant bit in the bit field.
4399 @param EndBit The ordinal of the most significant bit in the bit field.
4401 @param OrData The value to OR with the read value from the value.
4403 @return The new 32-bit value.
4417 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
4420 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4421 in Operand and the value specified by AndData. All other bits in Operand are
4422 preserved. The new 32-bit value is returned.
4424 If 32-bit operations are not supported, then ASSERT().
4425 If StartBit is greater than 31, then ASSERT().
4426 If EndBit is greater than 31, then ASSERT().
4427 If EndBit is less than StartBit, then ASSERT().
4428 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4430 @param Operand Operand on which to perform the bitfield operation.
4431 @param StartBit The ordinal of the least significant bit in the bit field.
4433 @param EndBit The ordinal of the most significant bit in the bit field.
4435 @param AndData The value to AND with the read value from the value
4437 @return The new 32-bit value.
4451 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4452 bitwise OR, and returns the result.
4454 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4455 in Operand and the value specified by AndData, followed by a bitwise
4456 OR with value specified by OrData. All other bits in Operand are
4457 preserved. The new 32-bit value is returned.
4459 If 32-bit operations are not supported, then ASSERT().
4460 If StartBit is greater than 31, then ASSERT().
4461 If EndBit is greater than 31, then ASSERT().
4462 If EndBit is less than StartBit, then ASSERT().
4463 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4464 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4466 @param Operand Operand on which to perform the bitfield operation.
4467 @param StartBit The ordinal of the least significant bit in the bit field.
4469 @param EndBit The ordinal of the most significant bit in the bit field.
4471 @param AndData The value to AND with the read value from the value.
4472 @param OrData The value to OR with the result of the AND operation.
4474 @return The new 32-bit value.
4479 BitFieldAndThenOr32 (
4489 Returns a bit field from a 64-bit value.
4491 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4493 If 64-bit operations are not supported, then ASSERT().
4494 If StartBit is greater than 63, then ASSERT().
4495 If EndBit is greater than 63, then ASSERT().
4496 If EndBit is less than StartBit, then ASSERT().
4498 @param Operand Operand on which to perform the bitfield operation.
4499 @param StartBit The ordinal of the least significant bit in the bit field.
4501 @param EndBit The ordinal of the most significant bit in the bit field.
4504 @return The bit field read.
4517 Writes a bit field to a 64-bit value, and returns the result.
4519 Writes Value to the bit field specified by the StartBit and the EndBit in
4520 Operand. All other bits in Operand are preserved. The new 64-bit value is
4523 If 64-bit operations are not supported, then ASSERT().
4524 If StartBit is greater than 63, then ASSERT().
4525 If EndBit is greater than 63, then ASSERT().
4526 If EndBit is less than StartBit, then ASSERT().
4527 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4529 @param Operand Operand on which to perform the bitfield operation.
4530 @param StartBit The ordinal of the least significant bit in the bit field.
4532 @param EndBit The ordinal of the most significant bit in the bit field.
4534 @param Value New value of the bit field.
4536 @return The new 64-bit value.
4550 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4553 Performs a bitwise OR between the bit field specified by StartBit
4554 and EndBit in Operand and the value specified by OrData. All other bits in
4555 Operand are preserved. The new 64-bit value is returned.
4557 If 64-bit operations are not supported, then ASSERT().
4558 If StartBit is greater than 63, then ASSERT().
4559 If EndBit is greater than 63, then ASSERT().
4560 If EndBit is less than StartBit, then ASSERT().
4561 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4563 @param Operand Operand on which to perform the bitfield operation.
4564 @param StartBit The ordinal of the least significant bit in the bit field.
4566 @param EndBit The ordinal of the most significant bit in the bit field.
4568 @param OrData The value to OR with the read value from the value
4570 @return The new 64-bit value.
4584 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4587 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4588 in Operand and the value specified by AndData. All other bits in Operand are
4589 preserved. The new 64-bit value is returned.
4591 If 64-bit operations are not supported, then ASSERT().
4592 If StartBit is greater than 63, then ASSERT().
4593 If EndBit is greater than 63, then ASSERT().
4594 If EndBit is less than StartBit, then ASSERT().
4595 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4597 @param Operand Operand on which to perform the bitfield operation.
4598 @param StartBit The ordinal of the least significant bit in the bit field.
4600 @param EndBit The ordinal of the most significant bit in the bit field.
4602 @param AndData The value to AND with the read value from the value
4604 @return The new 64-bit value.
4618 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4619 bitwise OR, and returns the result.
4621 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4622 in Operand and the value specified by AndData, followed by a bitwise
4623 OR with value specified by OrData. All other bits in Operand are
4624 preserved. The new 64-bit value is returned.
4626 If 64-bit operations are not supported, then ASSERT().
4627 If StartBit is greater than 63, then ASSERT().
4628 If EndBit is greater than 63, then ASSERT().
4629 If EndBit is less than StartBit, then ASSERT().
4630 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4631 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4633 @param Operand Operand on which to perform the bitfield operation.
4634 @param StartBit The ordinal of the least significant bit in the bit field.
4636 @param EndBit The ordinal of the most significant bit in the bit field.
4638 @param AndData The value to AND with the read value from the value.
4639 @param OrData The value to OR with the result of the AND operation.
4641 @return The new 64-bit value.
4646 BitFieldAndThenOr64 (
4655 Reads a bit field from a 32-bit value, counts and returns
4656 the number of set bits.
4658 Counts the number of set bits in the bit field specified by
4659 StartBit and EndBit in Operand. The count is returned.
4661 If StartBit is greater than 31, then ASSERT().
4662 If EndBit is greater than 31, then ASSERT().
4663 If EndBit is less than StartBit, then ASSERT().
4665 @param Operand Operand on which to perform the bitfield operation.
4666 @param StartBit The ordinal of the least significant bit in the bit field.
4668 @param EndBit The ordinal of the most significant bit in the bit field.
4671 @return The number of bits set between StartBit and EndBit.
4676 BitFieldCountOnes32 (
4683 Reads a bit field from a 64-bit value, counts and returns
4684 the number of set bits.
4686 Counts the number of set bits in the bit field specified by
4687 StartBit and EndBit in Operand. The count is returned.
4689 If StartBit is greater than 63, then ASSERT().
4690 If EndBit is greater than 63, then ASSERT().
4691 If EndBit is less than StartBit, then ASSERT().
4693 @param Operand Operand on which to perform the bitfield operation.
4694 @param StartBit The ordinal of the least significant bit in the bit field.
4696 @param EndBit The ordinal of the most significant bit in the bit field.
4699 @return The number of bits set between StartBit and EndBit.
4704 BitFieldCountOnes64 (
4711 // Base Library Checksum Functions
4715 Returns the sum of all elements in a buffer in unit of UINT8.
4716 During calculation, the carry bits are dropped.
4718 This function calculates the sum of all elements in a buffer
4719 in unit of UINT8. The carry bits in result of addition are dropped.
4720 The result is returned as UINT8. If Length is Zero, then Zero is
4723 If Buffer is NULL, then ASSERT().
4724 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4726 @param Buffer The pointer to the buffer to carry out the sum operation.
4727 @param Length The size, in bytes, of Buffer.
4729 @return Sum The sum of Buffer with carry bits dropped during additions.
4735 IN CONST UINT8
*Buffer
,
4741 Returns the two's complement checksum of all elements in a buffer
4744 This function first calculates the sum of the 8-bit values in the
4745 buffer specified by Buffer and Length. The carry bits in the result
4746 of addition are dropped. Then, the two's complement of the sum is
4747 returned. If Length is 0, then 0 is returned.
4749 If Buffer is NULL, then ASSERT().
4750 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4752 @param Buffer The pointer to the buffer to carry out the checksum operation.
4753 @param Length The size, in bytes, of Buffer.
4755 @return Checksum The two's complement checksum of Buffer.
4760 CalculateCheckSum8 (
4761 IN CONST UINT8
*Buffer
,
4767 Returns the sum of all elements in a buffer of 16-bit values. During
4768 calculation, the carry bits are dropped.
4770 This function calculates the sum of the 16-bit values in the buffer
4771 specified by Buffer and Length. The carry bits in result of addition are dropped.
4772 The 16-bit result is returned. If Length is 0, then 0 is returned.
4774 If Buffer is NULL, then ASSERT().
4775 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4776 If Length is not aligned on a 16-bit boundary, then ASSERT().
4777 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4779 @param Buffer The pointer to the buffer to carry out the sum operation.
4780 @param Length The size, in bytes, of Buffer.
4782 @return Sum The sum of Buffer with carry bits dropped during additions.
4788 IN CONST UINT16
*Buffer
,
4794 Returns the two's complement checksum of all elements in a buffer of
4797 This function first calculates the sum of the 16-bit values in the buffer
4798 specified by Buffer and Length. The carry bits in the result of addition
4799 are dropped. Then, the two's complement of the sum is returned. If Length
4800 is 0, then 0 is returned.
4802 If Buffer is NULL, then ASSERT().
4803 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4804 If Length is not aligned on a 16-bit boundary, then ASSERT().
4805 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4807 @param Buffer The pointer to the buffer to carry out the checksum operation.
4808 @param Length The size, in bytes, of Buffer.
4810 @return Checksum The two's complement checksum of Buffer.
4815 CalculateCheckSum16 (
4816 IN CONST UINT16
*Buffer
,
4822 Returns the sum of all elements in a buffer of 32-bit values. During
4823 calculation, the carry bits are dropped.
4825 This function calculates the sum of the 32-bit values in the buffer
4826 specified by Buffer and Length. The carry bits in result of addition are dropped.
4827 The 32-bit result is returned. If Length is 0, then 0 is returned.
4829 If Buffer is NULL, then ASSERT().
4830 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4831 If Length is not aligned on a 32-bit boundary, then ASSERT().
4832 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4834 @param Buffer The pointer to the buffer to carry out the sum operation.
4835 @param Length The size, in bytes, of Buffer.
4837 @return Sum The sum of Buffer with carry bits dropped during additions.
4843 IN CONST UINT32
*Buffer
,
4849 Returns the two's complement checksum of all elements in a buffer of
4852 This function first calculates the sum of the 32-bit values in the buffer
4853 specified by Buffer and Length. The carry bits in the result of addition
4854 are dropped. Then, the two's complement of the sum is returned. If Length
4855 is 0, then 0 is returned.
4857 If Buffer is NULL, then ASSERT().
4858 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4859 If Length is not aligned on a 32-bit boundary, then ASSERT().
4860 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4862 @param Buffer The pointer to the buffer to carry out the checksum operation.
4863 @param Length The size, in bytes, of Buffer.
4865 @return Checksum The two's complement checksum of Buffer.
4870 CalculateCheckSum32 (
4871 IN CONST UINT32
*Buffer
,
4877 Returns the sum of all elements in a buffer of 64-bit values. During
4878 calculation, the carry bits are dropped.
4880 This function calculates the sum of the 64-bit values in the buffer
4881 specified by Buffer and Length. The carry bits in result of addition are dropped.
4882 The 64-bit result is returned. If Length is 0, then 0 is returned.
4884 If Buffer is NULL, then ASSERT().
4885 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4886 If Length is not aligned on a 64-bit boundary, then ASSERT().
4887 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4889 @param Buffer The pointer to the buffer to carry out the sum operation.
4890 @param Length The size, in bytes, of Buffer.
4892 @return Sum The sum of Buffer with carry bits dropped during additions.
4898 IN CONST UINT64
*Buffer
,
4904 Returns the two's complement checksum of all elements in a buffer of
4907 This function first calculates the sum of the 64-bit values in the buffer
4908 specified by Buffer and Length. The carry bits in the result of addition
4909 are dropped. Then, the two's complement of the sum is returned. If Length
4910 is 0, then 0 is returned.
4912 If Buffer is NULL, then ASSERT().
4913 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4914 If Length is not aligned on a 64-bit boundary, then ASSERT().
4915 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4917 @param Buffer The pointer to the buffer to carry out the checksum operation.
4918 @param Length The size, in bytes, of Buffer.
4920 @return Checksum The two's complement checksum of Buffer.
4925 CalculateCheckSum64 (
4926 IN CONST UINT64
*Buffer
,
4931 Computes and returns a 32-bit CRC for a data buffer.
4932 CRC32 value bases on ITU-T V.42.
4934 If Buffer is NULL, then ASSERT().
4935 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4937 @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed.
4938 @param[in] Length The number of bytes in the buffer Data.
4940 @retval Crc32 The 32-bit CRC was computed for the data buffer.
4951 // Base Library CPU Functions
4955 Function entry point used when a stack switch is requested with SwitchStack()
4957 @param Context1 Context1 parameter passed into SwitchStack().
4958 @param Context2 Context2 parameter passed into SwitchStack().
4963 (EFIAPI
*SWITCH_STACK_ENTRY_POINT
)(
4964 IN VOID
*Context1
, OPTIONAL
4965 IN VOID
*Context2 OPTIONAL
4970 Used to serialize load and store operations.
4972 All loads and stores that proceed calls to this function are guaranteed to be
4973 globally visible when this function returns.
4984 Saves the current CPU context that can be restored with a call to LongJump()
4987 Saves the current CPU context in the buffer specified by JumpBuffer and
4988 returns 0. The initial call to SetJump() must always return 0. Subsequent
4989 calls to LongJump() cause a non-zero value to be returned by SetJump().
4991 If JumpBuffer is NULL, then ASSERT().
4992 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4994 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
4995 The same structure must never be used for more than one CPU architecture context.
4996 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
4997 SetJump()/LongJump() is not currently supported for the EBC processor type.
4999 @param JumpBuffer A pointer to CPU context buffer.
5001 @retval 0 Indicates a return from SetJump().
5008 OUT BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
5013 Restores the CPU context that was saved with SetJump().
5015 Restores the CPU context from the buffer specified by JumpBuffer. This
5016 function never returns to the caller. Instead is resumes execution based on
5017 the state of JumpBuffer.
5019 If JumpBuffer is NULL, then ASSERT().
5020 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
5021 If Value is 0, then ASSERT().
5023 @param JumpBuffer A pointer to CPU context buffer.
5024 @param Value The value to return when the SetJump() context is
5025 restored and must be non-zero.
5031 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
5037 Enables CPU interrupts.
5048 Disables CPU interrupts.
5059 Disables CPU interrupts and returns the interrupt state prior to the disable
5062 @retval TRUE CPU interrupts were enabled on entry to this call.
5063 @retval FALSE CPU interrupts were disabled on entry to this call.
5068 SaveAndDisableInterrupts (
5074 Enables CPU interrupts for the smallest window required to capture any
5080 EnableDisableInterrupts (
5086 Retrieves the current CPU interrupt state.
5088 Returns TRUE if interrupts are currently enabled. Otherwise
5091 @retval TRUE CPU interrupts are enabled.
5092 @retval FALSE CPU interrupts are disabled.
5103 Set the current CPU interrupt state.
5105 Sets the current CPU interrupt state to the state specified by
5106 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
5107 InterruptState is FALSE, then interrupts are disabled. InterruptState is
5110 @param InterruptState TRUE if interrupts should enabled. FALSE if
5111 interrupts should be disabled.
5113 @return InterruptState
5119 IN BOOLEAN InterruptState
5124 Requests CPU to pause for a short period of time.
5126 Requests CPU to pause for a short period of time. Typically used in MP
5127 systems to prevent memory starvation while waiting for a spin lock.
5138 Transfers control to a function starting with a new stack.
5140 Transfers control to the function specified by EntryPoint using the
5141 new stack specified by NewStack and passing in the parameters specified
5142 by Context1 and Context2. Context1 and Context2 are optional and may
5143 be NULL. The function EntryPoint must never return. This function
5144 supports a variable number of arguments following the NewStack parameter.
5145 These additional arguments are ignored on IA-32, x64, and EBC architectures.
5146 Itanium processors expect one additional parameter of type VOID * that specifies
5147 the new backing store pointer.
5149 If EntryPoint is NULL, then ASSERT().
5150 If NewStack is NULL, then ASSERT().
5152 @param EntryPoint A pointer to function to call with the new stack.
5153 @param Context1 A pointer to the context to pass into the EntryPoint
5155 @param Context2 A pointer to the context to pass into the EntryPoint
5157 @param NewStack A pointer to the new stack to use for the EntryPoint
5159 @param ... This variable argument list is ignored for IA-32, x64, and
5160 EBC architectures. For Itanium processors, this variable
5161 argument list is expected to contain a single parameter of
5162 type VOID * that specifies the new backing store pointer.
5169 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
5170 IN VOID
*Context1
, OPTIONAL
5171 IN VOID
*Context2
, OPTIONAL
5178 Generates a breakpoint on the CPU.
5180 Generates a breakpoint on the CPU. The breakpoint must be implemented such
5181 that code can resume normal execution after the breakpoint.
5192 Executes an infinite loop.
5194 Forces the CPU to execute an infinite loop. A debugger may be used to skip
5195 past the loop and the code that follows the loop must execute properly. This
5196 implies that the infinite loop must not cause the code that follow it to be
5208 Uses as a barrier to stop speculative execution.
5210 Ensures that no later instruction will execute speculatively, until all prior
5211 instructions have completed.
5216 SpeculationBarrier (
5221 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
5223 /// IA32 and x64 Specific Functions.
5224 /// Byte packed structure for 16-bit Real Mode EFLAGS.
5228 UINT32 CF
:1; ///< Carry Flag.
5229 UINT32 Reserved_0
:1; ///< Reserved.
5230 UINT32 PF
:1; ///< Parity Flag.
5231 UINT32 Reserved_1
:1; ///< Reserved.
5232 UINT32 AF
:1; ///< Auxiliary Carry Flag.
5233 UINT32 Reserved_2
:1; ///< Reserved.
5234 UINT32 ZF
:1; ///< Zero Flag.
5235 UINT32 SF
:1; ///< Sign Flag.
5236 UINT32 TF
:1; ///< Trap Flag.
5237 UINT32 IF
:1; ///< Interrupt Enable Flag.
5238 UINT32 DF
:1; ///< Direction Flag.
5239 UINT32 OF
:1; ///< Overflow Flag.
5240 UINT32 IOPL
:2; ///< I/O Privilege Level.
5241 UINT32 NT
:1; ///< Nested Task.
5242 UINT32 Reserved_3
:1; ///< Reserved.
5248 /// Byte packed structure for EFLAGS/RFLAGS.
5249 /// 32-bits on IA-32.
5250 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5254 UINT32 CF
:1; ///< Carry Flag.
5255 UINT32 Reserved_0
:1; ///< Reserved.
5256 UINT32 PF
:1; ///< Parity Flag.
5257 UINT32 Reserved_1
:1; ///< Reserved.
5258 UINT32 AF
:1; ///< Auxiliary Carry Flag.
5259 UINT32 Reserved_2
:1; ///< Reserved.
5260 UINT32 ZF
:1; ///< Zero Flag.
5261 UINT32 SF
:1; ///< Sign Flag.
5262 UINT32 TF
:1; ///< Trap Flag.
5263 UINT32 IF
:1; ///< Interrupt Enable Flag.
5264 UINT32 DF
:1; ///< Direction Flag.
5265 UINT32 OF
:1; ///< Overflow Flag.
5266 UINT32 IOPL
:2; ///< I/O Privilege Level.
5267 UINT32 NT
:1; ///< Nested Task.
5268 UINT32 Reserved_3
:1; ///< Reserved.
5269 UINT32 RF
:1; ///< Resume Flag.
5270 UINT32 VM
:1; ///< Virtual 8086 Mode.
5271 UINT32 AC
:1; ///< Alignment Check.
5272 UINT32 VIF
:1; ///< Virtual Interrupt Flag.
5273 UINT32 VIP
:1; ///< Virtual Interrupt Pending.
5274 UINT32 ID
:1; ///< ID Flag.
5275 UINT32 Reserved_4
:10; ///< Reserved.
5281 /// Byte packed structure for Control Register 0 (CR0).
5282 /// 32-bits on IA-32.
5283 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5287 UINT32 PE
:1; ///< Protection Enable.
5288 UINT32 MP
:1; ///< Monitor Coprocessor.
5289 UINT32 EM
:1; ///< Emulation.
5290 UINT32 TS
:1; ///< Task Switched.
5291 UINT32 ET
:1; ///< Extension Type.
5292 UINT32 NE
:1; ///< Numeric Error.
5293 UINT32 Reserved_0
:10; ///< Reserved.
5294 UINT32 WP
:1; ///< Write Protect.
5295 UINT32 Reserved_1
:1; ///< Reserved.
5296 UINT32 AM
:1; ///< Alignment Mask.
5297 UINT32 Reserved_2
:10; ///< Reserved.
5298 UINT32 NW
:1; ///< Mot Write-through.
5299 UINT32 CD
:1; ///< Cache Disable.
5300 UINT32 PG
:1; ///< Paging.
5306 /// Byte packed structure for Control Register 4 (CR4).
5307 /// 32-bits on IA-32.
5308 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5312 UINT32 VME
:1; ///< Virtual-8086 Mode Extensions.
5313 UINT32 PVI
:1; ///< Protected-Mode Virtual Interrupts.
5314 UINT32 TSD
:1; ///< Time Stamp Disable.
5315 UINT32 DE
:1; ///< Debugging Extensions.
5316 UINT32 PSE
:1; ///< Page Size Extensions.
5317 UINT32 PAE
:1; ///< Physical Address Extension.
5318 UINT32 MCE
:1; ///< Machine Check Enable.
5319 UINT32 PGE
:1; ///< Page Global Enable.
5320 UINT32 PCE
:1; ///< Performance Monitoring Counter
5322 UINT32 OSFXSR
:1; ///< Operating System Support for
5323 ///< FXSAVE and FXRSTOR instructions
5324 UINT32 OSXMMEXCPT
:1; ///< Operating System Support for
5325 ///< Unmasked SIMD Floating Point
5327 UINT32 Reserved_2
:1; ///< Reserved.
5328 UINT32 LA57
:1; ///< Linear Address 57bit.
5329 UINT32 VMXE
:1; ///< VMX Enable
5330 UINT32 Reserved_1
:18; ///< Reserved.
5336 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5355 } IA32_SEGMENT_DESCRIPTOR
;
5358 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5367 #define IA32_IDT_GATE_TYPE_TASK 0x85
5368 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5369 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5370 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5371 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5373 #define IA32_GDT_TYPE_TSS 0x9
5374 #define IA32_GDT_ALIGNMENT 8
5376 #if defined (MDE_CPU_IA32)
5378 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5382 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5383 UINT32 Selector
:16; ///< Selector.
5384 UINT32 Reserved_0
:8; ///< Reserved.
5385 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5386 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5389 } IA32_IDT_GATE_DESCRIPTOR
;
5393 // IA32 Task-State Segment Definition
5396 UINT16 PreviousTaskLink
;
5430 UINT16 LDTSegmentSelector
;
5433 UINT16 IOMapBaseAddress
;
5434 } IA32_TASK_STATE_SEGMENT
;
5438 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5439 UINT32 BaseLow
:16; ///< Base Address 15..00
5440 UINT32 BaseMid
:8; ///< Base Address 23..16
5441 UINT32 Type
:4; ///< Type (1 0 B 1)
5442 UINT32 Reserved_43
:1; ///< 0
5443 UINT32 DPL
:2; ///< Descriptor Privilege Level
5444 UINT32 P
:1; ///< Segment Present
5445 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5446 UINT32 AVL
:1; ///< Available for use by system software
5447 UINT32 Reserved_52
:2; ///< 0 0
5448 UINT32 G
:1; ///< Granularity
5449 UINT32 BaseHigh
:8; ///< Base Address 31..24
5452 } IA32_TSS_DESCRIPTOR
;
5455 #endif // defined (MDE_CPU_IA32)
5457 #if defined (MDE_CPU_X64)
5459 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5463 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5464 UINT32 Selector
:16; ///< Selector.
5465 UINT32 Reserved_0
:8; ///< Reserved.
5466 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5467 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5468 UINT32 OffsetUpper
:32; ///< Offset bits 63..32.
5469 UINT32 Reserved_1
:32; ///< Reserved.
5475 } IA32_IDT_GATE_DESCRIPTOR
;
5479 // IA32 Task-State Segment Definition
5489 UINT16 Reserved_100
;
5490 UINT16 IOMapBaseAddress
;
5491 } IA32_TASK_STATE_SEGMENT
;
5495 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5496 UINT32 BaseLow
:16; ///< Base Address 15..00
5497 UINT32 BaseMidl
:8; ///< Base Address 23..16
5498 UINT32 Type
:4; ///< Type (1 0 B 1)
5499 UINT32 Reserved_43
:1; ///< 0
5500 UINT32 DPL
:2; ///< Descriptor Privilege Level
5501 UINT32 P
:1; ///< Segment Present
5502 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5503 UINT32 AVL
:1; ///< Available for use by system software
5504 UINT32 Reserved_52
:2; ///< 0 0
5505 UINT32 G
:1; ///< Granularity
5506 UINT32 BaseMidh
:8; ///< Base Address 31..24
5507 UINT32 BaseHigh
:32; ///< Base Address 63..32
5508 UINT32 Reserved_96
:32; ///< Reserved
5514 } IA32_TSS_DESCRIPTOR
;
5517 #endif // defined (MDE_CPU_X64)
5520 /// Byte packed structure for an FP/SSE/SSE2 context.
5527 /// Structures for the 16-bit real mode thunks.
5580 IA32_EFLAGS32 EFLAGS
;
5590 } IA32_REGISTER_SET
;
5593 /// Byte packed structure for an 16-bit real mode thunks.
5596 IA32_REGISTER_SET
*RealModeState
;
5597 VOID
*RealModeBuffer
;
5598 UINT32 RealModeBufferSize
;
5599 UINT32 ThunkAttributes
;
5602 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5603 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5604 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5607 /// Type definition for representing labels in NASM source code that allow for
5608 /// the patching of immediate operands of IA32 and X64 instructions.
5610 /// While the type is technically defined as a function type (note: not a
5611 /// pointer-to-function type), such labels in NASM source code never stand for
5612 /// actual functions, and identifiers declared with this function type should
5613 /// never be called. This is also why the EFIAPI calling convention specifier
5614 /// is missing from the typedef, and why the typedef does not follow the usual
5615 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5616 /// return type and the VOID argument list are merely artifacts.
5618 typedef VOID (X86_ASSEMBLY_PATCH_LABEL
) (VOID
);
5621 Retrieves CPUID information.
5623 Executes the CPUID instruction with EAX set to the value specified by Index.
5624 This function always returns Index.
5625 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5626 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5627 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5628 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5629 This function is only available on IA-32 and x64.
5631 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5633 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5634 instruction. This is an optional parameter that may be NULL.
5635 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5636 instruction. This is an optional parameter that may be NULL.
5637 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5638 instruction. This is an optional parameter that may be NULL.
5639 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5640 instruction. This is an optional parameter that may be NULL.
5649 OUT UINT32
*Eax
, OPTIONAL
5650 OUT UINT32
*Ebx
, OPTIONAL
5651 OUT UINT32
*Ecx
, OPTIONAL
5652 OUT UINT32
*Edx OPTIONAL
5657 Retrieves CPUID information using an extended leaf identifier.
5659 Executes the CPUID instruction with EAX set to the value specified by Index
5660 and ECX set to the value specified by SubIndex. This function always returns
5661 Index. This function is only available on IA-32 and x64.
5663 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5664 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5665 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5666 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5668 @param Index The 32-bit value to load into EAX prior to invoking the
5670 @param SubIndex The 32-bit value to load into ECX prior to invoking the
5672 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5673 instruction. This is an optional parameter that may be
5675 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5676 instruction. This is an optional parameter that may be
5678 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5679 instruction. This is an optional parameter that may be
5681 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5682 instruction. This is an optional parameter that may be
5693 OUT UINT32
*Eax
, OPTIONAL
5694 OUT UINT32
*Ebx
, OPTIONAL
5695 OUT UINT32
*Ecx
, OPTIONAL
5696 OUT UINT32
*Edx OPTIONAL
5701 Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5703 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5704 and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5715 Perform a WBINVD and clear both the CD and NW bits of CR0.
5717 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5718 bits of CR0 to 0. This function is only available on IA-32 and x64.
5729 Returns the lower 32-bits of a Machine Specific Register(MSR).
5731 Reads and returns the lower 32-bits of the MSR specified by Index.
5732 No parameter checking is performed on Index, and some Index values may cause
5733 CPU exceptions. The caller must either guarantee that Index is valid, or the
5734 caller must set up exception handlers to catch the exceptions. This function
5735 is only available on IA-32 and x64.
5737 @param Index The 32-bit MSR index to read.
5739 @return The lower 32 bits of the MSR identified by Index.
5750 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5751 The upper 32-bits of the MSR are set to zero.
5753 Writes the 32-bit value specified by Value to the MSR specified by Index. The
5754 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5755 the MSR is returned. No parameter checking is performed on Index or Value,
5756 and some of these may cause CPU exceptions. The caller must either guarantee
5757 that Index and Value are valid, or the caller must establish proper exception
5758 handlers. This function is only available on IA-32 and x64.
5760 @param Index The 32-bit MSR index to write.
5761 @param Value The 32-bit value to write to the MSR.
5775 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5776 writes the result back to the 64-bit MSR.
5778 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5779 between the lower 32-bits of the read result and the value specified by
5780 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5781 32-bits of the value written to the MSR is returned. No parameter checking is
5782 performed on Index or OrData, and some of these may cause CPU exceptions. The
5783 caller must either guarantee that Index and OrData are valid, or the caller
5784 must establish proper exception handlers. This function is only available on
5787 @param Index The 32-bit MSR index to write.
5788 @param OrData The value to OR with the read value from the MSR.
5790 @return The lower 32-bit value written to the MSR.
5802 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5803 the result back to the 64-bit MSR.
5805 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5806 lower 32-bits of the read result and the value specified by AndData, and
5807 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5808 the value written to the MSR is returned. No parameter checking is performed
5809 on Index or AndData, and some of these may cause CPU exceptions. The caller
5810 must either guarantee that Index and AndData are valid, or the caller must
5811 establish proper exception handlers. This function is only available on IA-32
5814 @param Index The 32-bit MSR index to write.
5815 @param AndData The value to AND with the read value from the MSR.
5817 @return The lower 32-bit value written to the MSR.
5829 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5830 on the lower 32-bits, and writes the result back to the 64-bit MSR.
5832 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5833 lower 32-bits of the read result and the value specified by AndData
5834 preserving the upper 32-bits, performs a bitwise OR between the
5835 result of the AND operation and the value specified by OrData, and writes the
5836 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5837 written to the MSR is returned. No parameter checking is performed on Index,
5838 AndData, or OrData, and some of these may cause CPU exceptions. The caller
5839 must either guarantee that Index, AndData, and OrData are valid, or the
5840 caller must establish proper exception handlers. This function is only
5841 available on IA-32 and x64.
5843 @param Index The 32-bit MSR index to write.
5844 @param AndData The value to AND with the read value from the MSR.
5845 @param OrData The value to OR with the result of the AND operation.
5847 @return The lower 32-bit value written to the MSR.
5860 Reads a bit field of an MSR.
5862 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5863 specified by the StartBit and the EndBit. The value of the bit field is
5864 returned. The caller must either guarantee that Index is valid, or the caller
5865 must set up exception handlers to catch the exceptions. This function is only
5866 available on IA-32 and x64.
5868 If StartBit is greater than 31, then ASSERT().
5869 If EndBit is greater than 31, then ASSERT().
5870 If EndBit is less than StartBit, then ASSERT().
5872 @param Index The 32-bit MSR index to read.
5873 @param StartBit The ordinal of the least significant bit in the bit field.
5875 @param EndBit The ordinal of the most significant bit in the bit field.
5878 @return The bit field read from the MSR.
5883 AsmMsrBitFieldRead32 (
5891 Writes a bit field to an MSR.
5893 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5894 field is specified by the StartBit and the EndBit. All other bits in the
5895 destination MSR are preserved. The lower 32-bits of the MSR written is
5896 returned. The caller must either guarantee that Index and the data written
5897 is valid, or the caller must set up exception handlers to catch the exceptions.
5898 This function is only available on IA-32 and x64.
5900 If StartBit is greater than 31, then ASSERT().
5901 If EndBit is greater than 31, then ASSERT().
5902 If EndBit is less than StartBit, then ASSERT().
5903 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5905 @param Index The 32-bit MSR index to write.
5906 @param StartBit The ordinal of the least significant bit in the bit field.
5908 @param EndBit The ordinal of the most significant bit in the bit field.
5910 @param Value New value of the bit field.
5912 @return The lower 32-bit of the value written to the MSR.
5917 AsmMsrBitFieldWrite32 (
5926 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5927 result back to the bit field in the 64-bit MSR.
5929 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5930 between the read result and the value specified by OrData, and writes the
5931 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
5932 written to the MSR are returned. Extra left bits in OrData are stripped. The
5933 caller must either guarantee that Index and the data written is valid, or
5934 the caller must set up exception handlers to catch the exceptions. This
5935 function is only available on IA-32 and x64.
5937 If StartBit is greater than 31, then ASSERT().
5938 If EndBit is greater than 31, then ASSERT().
5939 If EndBit is less than StartBit, then ASSERT().
5940 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5942 @param Index The 32-bit MSR index to write.
5943 @param StartBit The ordinal of the least significant bit in the bit field.
5945 @param EndBit The ordinal of the most significant bit in the bit field.
5947 @param OrData The value to OR with the read value from the MSR.
5949 @return The lower 32-bit of the value written to the MSR.
5954 AsmMsrBitFieldOr32 (
5963 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5964 result back to the bit field in the 64-bit MSR.
5966 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5967 read result and the value specified by AndData, and writes the result to the
5968 64-bit MSR specified by Index. The lower 32-bits of the value written to the
5969 MSR are returned. Extra left bits in AndData are stripped. The caller must
5970 either guarantee that Index and the data written is valid, or the caller must
5971 set up exception handlers to catch the exceptions. This function is only
5972 available on IA-32 and x64.
5974 If StartBit is greater than 31, then ASSERT().
5975 If EndBit is greater than 31, then ASSERT().
5976 If EndBit is less than StartBit, then ASSERT().
5977 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5979 @param Index The 32-bit MSR index to write.
5980 @param StartBit The ordinal of the least significant bit in the bit field.
5982 @param EndBit The ordinal of the most significant bit in the bit field.
5984 @param AndData The value to AND with the read value from the MSR.
5986 @return The lower 32-bit of the value written to the MSR.
5991 AsmMsrBitFieldAnd32 (
6000 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6001 bitwise OR, and writes the result back to the bit field in the
6004 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
6005 bitwise OR between the read result and the value specified by
6006 AndData, and writes the result to the 64-bit MSR specified by Index. The
6007 lower 32-bits of the value written to the MSR are returned. Extra left bits
6008 in both AndData and OrData are stripped. The caller must either guarantee
6009 that Index and the data written is valid, or the caller must set up exception
6010 handlers to catch the exceptions. This function is only available on IA-32
6013 If StartBit is greater than 31, then ASSERT().
6014 If EndBit is greater than 31, then ASSERT().
6015 If EndBit is less than StartBit, then ASSERT().
6016 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6017 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6019 @param Index The 32-bit MSR index to write.
6020 @param StartBit The ordinal of the least significant bit in the bit field.
6022 @param EndBit The ordinal of the most significant bit in the bit field.
6024 @param AndData The value to AND with the read value from the MSR.
6025 @param OrData The value to OR with the result of the AND operation.
6027 @return The lower 32-bit of the value written to the MSR.
6032 AsmMsrBitFieldAndThenOr32 (
6042 Returns a 64-bit Machine Specific Register(MSR).
6044 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
6045 performed on Index, and some Index values may cause CPU exceptions. The
6046 caller must either guarantee that Index is valid, or the caller must set up
6047 exception handlers to catch the exceptions. This function is only available
6050 @param Index The 32-bit MSR index to read.
6052 @return The value of the MSR identified by Index.
6063 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
6066 Writes the 64-bit value specified by Value to the MSR specified by Index. The
6067 64-bit value written to the MSR is returned. No parameter checking is
6068 performed on Index or Value, and some of these may cause CPU exceptions. The
6069 caller must either guarantee that Index and Value are valid, or the caller
6070 must establish proper exception handlers. This function is only available on
6073 @param Index The 32-bit MSR index to write.
6074 @param Value The 64-bit value to write to the MSR.
6088 Reads a 64-bit MSR, performs a bitwise OR, and writes the result
6089 back to the 64-bit MSR.
6091 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6092 between the read result and the value specified by OrData, and writes the
6093 result to the 64-bit MSR specified by Index. The value written to the MSR is
6094 returned. No parameter checking is performed on Index or OrData, and some of
6095 these may cause CPU exceptions. The caller must either guarantee that Index
6096 and OrData are valid, or the caller must establish proper exception handlers.
6097 This function is only available on IA-32 and x64.
6099 @param Index The 32-bit MSR index to write.
6100 @param OrData The value to OR with the read value from the MSR.
6102 @return The value written back to the MSR.
6114 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
6117 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6118 read result and the value specified by OrData, and writes the result to the
6119 64-bit MSR specified by Index. The value written to the MSR is returned. No
6120 parameter checking is performed on Index or OrData, and some of these may
6121 cause CPU exceptions. The caller must either guarantee that Index and OrData
6122 are valid, or the caller must establish proper exception handlers. This
6123 function is only available on IA-32 and x64.
6125 @param Index The 32-bit MSR index to write.
6126 @param AndData The value to AND with the read value from the MSR.
6128 @return The value written back to the MSR.
6140 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
6141 OR, and writes the result back to the 64-bit MSR.
6143 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
6144 result and the value specified by AndData, performs a bitwise OR
6145 between the result of the AND operation and the value specified by OrData,
6146 and writes the result to the 64-bit MSR specified by Index. The value written
6147 to the MSR is returned. No parameter checking is performed on Index, AndData,
6148 or OrData, and some of these may cause CPU exceptions. The caller must either
6149 guarantee that Index, AndData, and OrData are valid, or the caller must
6150 establish proper exception handlers. This function is only available on IA-32
6153 @param Index The 32-bit MSR index to write.
6154 @param AndData The value to AND with the read value from the MSR.
6155 @param OrData The value to OR with the result of the AND operation.
6157 @return The value written back to the MSR.
6170 Reads a bit field of an MSR.
6172 Reads the bit field in the 64-bit MSR. The bit field is specified by the
6173 StartBit and the EndBit. The value of the bit field is returned. The caller
6174 must either guarantee that Index is valid, or the caller must set up
6175 exception handlers to catch the exceptions. This function is only available
6178 If StartBit is greater than 63, then ASSERT().
6179 If EndBit is greater than 63, then ASSERT().
6180 If EndBit is less than StartBit, then ASSERT().
6182 @param Index The 32-bit MSR index to read.
6183 @param StartBit The ordinal of the least significant bit in the bit field.
6185 @param EndBit The ordinal of the most significant bit in the bit field.
6188 @return The value read from the MSR.
6193 AsmMsrBitFieldRead64 (
6201 Writes a bit field to an MSR.
6203 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
6204 the StartBit and the EndBit. All other bits in the destination MSR are
6205 preserved. The MSR written is returned. The caller must either guarantee
6206 that Index and the data written is valid, or the caller must set up exception
6207 handlers to catch the exceptions. This function is only available on IA-32 and x64.
6209 If StartBit is greater than 63, then ASSERT().
6210 If EndBit is greater than 63, then ASSERT().
6211 If EndBit is less than StartBit, then ASSERT().
6212 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6214 @param Index The 32-bit MSR index to write.
6215 @param StartBit The ordinal of the least significant bit in the bit field.
6217 @param EndBit The ordinal of the most significant bit in the bit field.
6219 @param Value New value of the bit field.
6221 @return The value written back to the MSR.
6226 AsmMsrBitFieldWrite64 (
6235 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
6236 writes the result back to the bit field in the 64-bit MSR.
6238 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6239 between the read result and the value specified by OrData, and writes the
6240 result to the 64-bit MSR specified by Index. The value written to the MSR is
6241 returned. Extra left bits in OrData are stripped. The caller must either
6242 guarantee that Index and the data written is valid, or the caller must set up
6243 exception handlers to catch the exceptions. This function is only available
6246 If StartBit is greater than 63, then ASSERT().
6247 If EndBit is greater than 63, then ASSERT().
6248 If EndBit is less than StartBit, then ASSERT().
6249 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6251 @param Index The 32-bit MSR index to write.
6252 @param StartBit The ordinal of the least significant bit in the bit field.
6254 @param EndBit The ordinal of the most significant bit in the bit field.
6256 @param OrData The value to OR with the read value from the bit field.
6258 @return The value written back to the MSR.
6263 AsmMsrBitFieldOr64 (
6272 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6273 result back to the bit field in the 64-bit MSR.
6275 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6276 read result and the value specified by AndData, and writes the result to the
6277 64-bit MSR specified by Index. The value written to the MSR is returned.
6278 Extra left bits in AndData are stripped. The caller must either guarantee
6279 that Index and the data written is valid, or the caller must set up exception
6280 handlers to catch the exceptions. This function is only available on IA-32
6283 If StartBit is greater than 63, then ASSERT().
6284 If EndBit is greater than 63, then ASSERT().
6285 If EndBit is less than StartBit, then ASSERT().
6286 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6288 @param Index The 32-bit MSR index to write.
6289 @param StartBit The ordinal of the least significant bit in the bit field.
6291 @param EndBit The ordinal of the most significant bit in the bit field.
6293 @param AndData The value to AND with the read value from the bit field.
6295 @return The value written back to the MSR.
6300 AsmMsrBitFieldAnd64 (
6309 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6310 bitwise OR, and writes the result back to the bit field in the
6313 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6314 a bitwise OR between the read result and the value specified by
6315 AndData, and writes the result to the 64-bit MSR specified by Index. The
6316 value written to the MSR is returned. Extra left bits in both AndData and
6317 OrData are stripped. The caller must either guarantee that Index and the data
6318 written is valid, or the caller must set up exception handlers to catch the
6319 exceptions. This function is only available on IA-32 and x64.
6321 If StartBit is greater than 63, then ASSERT().
6322 If EndBit is greater than 63, then ASSERT().
6323 If EndBit is less than StartBit, then ASSERT().
6324 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6325 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6327 @param Index The 32-bit MSR index to write.
6328 @param StartBit The ordinal of the least significant bit in the bit field.
6330 @param EndBit The ordinal of the most significant bit in the bit field.
6332 @param AndData The value to AND with the read value from the bit field.
6333 @param OrData The value to OR with the result of the AND operation.
6335 @return The value written back to the MSR.
6340 AsmMsrBitFieldAndThenOr64 (
6350 Reads the current value of the EFLAGS register.
6352 Reads and returns the current value of the EFLAGS register. This function is
6353 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6354 64-bit value on x64.
6356 @return EFLAGS on IA-32 or RFLAGS on x64.
6367 Reads the current value of the Control Register 0 (CR0).
6369 Reads and returns the current value of CR0. This function is only available
6370 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6373 @return The value of the Control Register 0 (CR0).
6384 Reads the current value of the Control Register 2 (CR2).
6386 Reads and returns the current value of CR2. This function is only available
6387 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6390 @return The value of the Control Register 2 (CR2).
6401 Reads the current value of the Control Register 3 (CR3).
6403 Reads and returns the current value of CR3. This function is only available
6404 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6407 @return The value of the Control Register 3 (CR3).
6418 Reads the current value of the Control Register 4 (CR4).
6420 Reads and returns the current value of CR4. This function is only available
6421 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6424 @return The value of the Control Register 4 (CR4).
6435 Writes a value to Control Register 0 (CR0).
6437 Writes and returns a new value to CR0. This function is only available on
6438 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6440 @param Cr0 The value to write to CR0.
6442 @return The value written to CR0.
6453 Writes a value to Control Register 2 (CR2).
6455 Writes and returns a new value to CR2. This function is only available on
6456 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6458 @param Cr2 The value to write to CR2.
6460 @return The value written to CR2.
6471 Writes a value to Control Register 3 (CR3).
6473 Writes and returns a new value to CR3. This function is only available on
6474 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6476 @param Cr3 The value to write to CR3.
6478 @return The value written to CR3.
6489 Writes a value to Control Register 4 (CR4).
6491 Writes and returns a new value to CR4. This function is only available on
6492 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6494 @param Cr4 The value to write to CR4.
6496 @return The value written to CR4.
6507 Reads the current value of Debug Register 0 (DR0).
6509 Reads and returns the current value of DR0. This function is only available
6510 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6513 @return The value of Debug Register 0 (DR0).
6524 Reads the current value of Debug Register 1 (DR1).
6526 Reads and returns the current value of DR1. This function is only available
6527 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6530 @return The value of Debug Register 1 (DR1).
6541 Reads the current value of Debug Register 2 (DR2).
6543 Reads and returns the current value of DR2. This function is only available
6544 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6547 @return The value of Debug Register 2 (DR2).
6558 Reads the current value of Debug Register 3 (DR3).
6560 Reads and returns the current value of DR3. This function is only available
6561 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6564 @return The value of Debug Register 3 (DR3).
6575 Reads the current value of Debug Register 4 (DR4).
6577 Reads and returns the current value of DR4. This function is only available
6578 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6581 @return The value of Debug Register 4 (DR4).
6592 Reads the current value of Debug Register 5 (DR5).
6594 Reads and returns the current value of DR5. This function is only available
6595 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6598 @return The value of Debug Register 5 (DR5).
6609 Reads the current value of Debug Register 6 (DR6).
6611 Reads and returns the current value of DR6. This function is only available
6612 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6615 @return The value of Debug Register 6 (DR6).
6626 Reads the current value of Debug Register 7 (DR7).
6628 Reads and returns the current value of DR7. This function is only available
6629 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6632 @return The value of Debug Register 7 (DR7).
6643 Writes a value to Debug Register 0 (DR0).
6645 Writes and returns a new value to DR0. This function is only available on
6646 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6648 @param Dr0 The value to write to Dr0.
6650 @return The value written to Debug Register 0 (DR0).
6661 Writes a value to Debug Register 1 (DR1).
6663 Writes and returns a new value to DR1. This function is only available on
6664 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6666 @param Dr1 The value to write to Dr1.
6668 @return The value written to Debug Register 1 (DR1).
6679 Writes a value to Debug Register 2 (DR2).
6681 Writes and returns a new value to DR2. This function is only available on
6682 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6684 @param Dr2 The value to write to Dr2.
6686 @return The value written to Debug Register 2 (DR2).
6697 Writes a value to Debug Register 3 (DR3).
6699 Writes and returns a new value to DR3. This function is only available on
6700 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6702 @param Dr3 The value to write to Dr3.
6704 @return The value written to Debug Register 3 (DR3).
6715 Writes a value to Debug Register 4 (DR4).
6717 Writes and returns a new value to DR4. This function is only available on
6718 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6720 @param Dr4 The value to write to Dr4.
6722 @return The value written to Debug Register 4 (DR4).
6733 Writes a value to Debug Register 5 (DR5).
6735 Writes and returns a new value to DR5. This function is only available on
6736 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6738 @param Dr5 The value to write to Dr5.
6740 @return The value written to Debug Register 5 (DR5).
6751 Writes a value to Debug Register 6 (DR6).
6753 Writes and returns a new value to DR6. This function is only available on
6754 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6756 @param Dr6 The value to write to Dr6.
6758 @return The value written to Debug Register 6 (DR6).
6769 Writes a value to Debug Register 7 (DR7).
6771 Writes and returns a new value to DR7. This function is only available on
6772 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6774 @param Dr7 The value to write to Dr7.
6776 @return The value written to Debug Register 7 (DR7).
6787 Reads the current value of Code Segment Register (CS).
6789 Reads and returns the current value of CS. This function is only available on
6792 @return The current value of CS.
6803 Reads the current value of Data Segment Register (DS).
6805 Reads and returns the current value of DS. This function is only available on
6808 @return The current value of DS.
6819 Reads the current value of Extra Segment Register (ES).
6821 Reads and returns the current value of ES. This function is only available on
6824 @return The current value of ES.
6835 Reads the current value of FS Data Segment Register (FS).
6837 Reads and returns the current value of FS. This function is only available on
6840 @return The current value of FS.
6851 Reads the current value of GS Data Segment Register (GS).
6853 Reads and returns the current value of GS. This function is only available on
6856 @return The current value of GS.
6867 Reads the current value of Stack Segment Register (SS).
6869 Reads and returns the current value of SS. This function is only available on
6872 @return The current value of SS.
6883 Reads the current value of Task Register (TR).
6885 Reads and returns the current value of TR. This function is only available on
6888 @return The current value of TR.
6899 Reads the current Global Descriptor Table Register(GDTR) descriptor.
6901 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6902 function is only available on IA-32 and x64.
6904 If Gdtr is NULL, then ASSERT().
6906 @param Gdtr The pointer to a GDTR descriptor.
6912 OUT IA32_DESCRIPTOR
*Gdtr
6917 Writes the current Global Descriptor Table Register (GDTR) descriptor.
6919 Writes and the current GDTR descriptor specified by Gdtr. This function is
6920 only available on IA-32 and x64.
6922 If Gdtr is NULL, then ASSERT().
6924 @param Gdtr The pointer to a GDTR descriptor.
6930 IN CONST IA32_DESCRIPTOR
*Gdtr
6935 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
6937 Reads and returns the current IDTR descriptor and returns it in Idtr. This
6938 function is only available on IA-32 and x64.
6940 If Idtr is NULL, then ASSERT().
6942 @param Idtr The pointer to a IDTR descriptor.
6948 OUT IA32_DESCRIPTOR
*Idtr
6953 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
6955 Writes the current IDTR descriptor and returns it in Idtr. This function is
6956 only available on IA-32 and x64.
6958 If Idtr is NULL, then ASSERT().
6960 @param Idtr The pointer to a IDTR descriptor.
6966 IN CONST IA32_DESCRIPTOR
*Idtr
6971 Reads the current Local Descriptor Table Register(LDTR) selector.
6973 Reads and returns the current 16-bit LDTR descriptor value. This function is
6974 only available on IA-32 and x64.
6976 @return The current selector of LDT.
6987 Writes the current Local Descriptor Table Register (LDTR) selector.
6989 Writes and the current LDTR descriptor specified by Ldtr. This function is
6990 only available on IA-32 and x64.
6992 @param Ldtr 16-bit LDTR selector value.
7003 Save the current floating point/SSE/SSE2 context to a buffer.
7005 Saves the current floating point/SSE/SSE2 state to the buffer specified by
7006 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
7007 available on IA-32 and x64.
7009 If Buffer is NULL, then ASSERT().
7010 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7012 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7018 OUT IA32_FX_BUFFER
*Buffer
7023 Restores the current floating point/SSE/SSE2 context from a buffer.
7025 Restores the current floating point/SSE/SSE2 state from the buffer specified
7026 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
7027 only available on IA-32 and x64.
7029 If Buffer is NULL, then ASSERT().
7030 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7031 If Buffer was not saved with AsmFxSave(), then ASSERT().
7033 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7039 IN CONST IA32_FX_BUFFER
*Buffer
7044 Reads the current value of 64-bit MMX Register #0 (MM0).
7046 Reads and returns the current value of MM0. This function is only available
7049 @return The current value of MM0.
7060 Reads the current value of 64-bit MMX Register #1 (MM1).
7062 Reads and returns the current value of MM1. This function is only available
7065 @return The current value of MM1.
7076 Reads the current value of 64-bit MMX Register #2 (MM2).
7078 Reads and returns the current value of MM2. This function is only available
7081 @return The current value of MM2.
7092 Reads the current value of 64-bit MMX Register #3 (MM3).
7094 Reads and returns the current value of MM3. This function is only available
7097 @return The current value of MM3.
7108 Reads the current value of 64-bit MMX Register #4 (MM4).
7110 Reads and returns the current value of MM4. This function is only available
7113 @return The current value of MM4.
7124 Reads the current value of 64-bit MMX Register #5 (MM5).
7126 Reads and returns the current value of MM5. This function is only available
7129 @return The current value of MM5.
7140 Reads the current value of 64-bit MMX Register #6 (MM6).
7142 Reads and returns the current value of MM6. This function is only available
7145 @return The current value of MM6.
7156 Reads the current value of 64-bit MMX Register #7 (MM7).
7158 Reads and returns the current value of MM7. This function is only available
7161 @return The current value of MM7.
7172 Writes the current value of 64-bit MMX Register #0 (MM0).
7174 Writes the current value of MM0. This function is only available on IA32 and
7177 @param Value The 64-bit value to write to MM0.
7188 Writes the current value of 64-bit MMX Register #1 (MM1).
7190 Writes the current value of MM1. This function is only available on IA32 and
7193 @param Value The 64-bit value to write to MM1.
7204 Writes the current value of 64-bit MMX Register #2 (MM2).
7206 Writes the current value of MM2. This function is only available on IA32 and
7209 @param Value The 64-bit value to write to MM2.
7220 Writes the current value of 64-bit MMX Register #3 (MM3).
7222 Writes the current value of MM3. This function is only available on IA32 and
7225 @param Value The 64-bit value to write to MM3.
7236 Writes the current value of 64-bit MMX Register #4 (MM4).
7238 Writes the current value of MM4. This function is only available on IA32 and
7241 @param Value The 64-bit value to write to MM4.
7252 Writes the current value of 64-bit MMX Register #5 (MM5).
7254 Writes the current value of MM5. This function is only available on IA32 and
7257 @param Value The 64-bit value to write to MM5.
7268 Writes the current value of 64-bit MMX Register #6 (MM6).
7270 Writes the current value of MM6. This function is only available on IA32 and
7273 @param Value The 64-bit value to write to MM6.
7284 Writes the current value of 64-bit MMX Register #7 (MM7).
7286 Writes the current value of MM7. This function is only available on IA32 and
7289 @param Value The 64-bit value to write to MM7.
7300 Reads the current value of Time Stamp Counter (TSC).
7302 Reads and returns the current value of TSC. This function is only available
7305 @return The current value of TSC
7316 Reads the current value of a Performance Counter (PMC).
7318 Reads and returns the current value of performance counter specified by
7319 Index. This function is only available on IA-32 and x64.
7321 @param Index The 32-bit Performance Counter index to read.
7323 @return The value of the PMC specified by Index.
7334 Sets up a monitor buffer that is used by AsmMwait().
7336 Executes a MONITOR instruction with the register state specified by Eax, Ecx
7337 and Edx. Returns Eax. This function is only available on IA-32 and x64.
7339 @param Eax The value to load into EAX or RAX before executing the MONITOR
7341 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7343 @param Edx The value to load into EDX or RDX before executing the MONITOR
7359 Executes an MWAIT instruction.
7361 Executes an MWAIT instruction with the register state specified by Eax and
7362 Ecx. Returns Eax. This function is only available on IA-32 and x64.
7364 @param Eax The value to load into EAX or RAX before executing the MONITOR
7366 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7381 Executes a WBINVD instruction.
7383 Executes a WBINVD instruction. This function is only available on IA-32 and
7395 Executes a INVD instruction.
7397 Executes a INVD instruction. This function is only available on IA-32 and
7409 Flushes a cache line from all the instruction and data caches within the
7410 coherency domain of the CPU.
7412 Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7413 This function is only available on IA-32 and x64.
7415 @param LinearAddress The address of the cache line to flush. If the CPU is
7416 in a physical addressing mode, then LinearAddress is a
7417 physical address. If the CPU is in a virtual
7418 addressing mode, then LinearAddress is a virtual
7421 @return LinearAddress.
7426 IN VOID
*LinearAddress
7431 Enables the 32-bit paging mode on the CPU.
7433 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7434 must be properly initialized prior to calling this service. This function
7435 assumes the current execution mode is 32-bit protected mode. This function is
7436 only available on IA-32. After the 32-bit paging mode is enabled, control is
7437 transferred to the function specified by EntryPoint using the new stack
7438 specified by NewStack and passing in the parameters specified by Context1 and
7439 Context2. Context1 and Context2 are optional and may be NULL. The function
7440 EntryPoint must never return.
7442 If the current execution mode is not 32-bit protected mode, then ASSERT().
7443 If EntryPoint is NULL, then ASSERT().
7444 If NewStack is NULL, then ASSERT().
7446 There are a number of constraints that must be followed before calling this
7448 1) Interrupts must be disabled.
7449 2) The caller must be in 32-bit protected mode with flat descriptors. This
7450 means all descriptors must have a base of 0 and a limit of 4GB.
7451 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
7453 4) CR3 must point to valid page tables that will be used once the transition
7454 is complete, and those page tables must guarantee that the pages for this
7455 function and the stack are identity mapped.
7457 @param EntryPoint A pointer to function to call with the new stack after
7459 @param Context1 A pointer to the context to pass into the EntryPoint
7460 function as the first parameter after paging is enabled.
7461 @param Context2 A pointer to the context to pass into the EntryPoint
7462 function as the second parameter after paging is enabled.
7463 @param NewStack A pointer to the new stack to use for the EntryPoint
7464 function after paging is enabled.
7470 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7471 IN VOID
*Context1
, OPTIONAL
7472 IN VOID
*Context2
, OPTIONAL
7478 Disables the 32-bit paging mode on the CPU.
7480 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7481 mode. This function assumes the current execution mode is 32-paged protected
7482 mode. This function is only available on IA-32. After the 32-bit paging mode
7483 is disabled, control is transferred to the function specified by EntryPoint
7484 using the new stack specified by NewStack and passing in the parameters
7485 specified by Context1 and Context2. Context1 and Context2 are optional and
7486 may be NULL. The function EntryPoint must never return.
7488 If the current execution mode is not 32-bit paged mode, then ASSERT().
7489 If EntryPoint is NULL, then ASSERT().
7490 If NewStack is NULL, then ASSERT().
7492 There are a number of constraints that must be followed before calling this
7494 1) Interrupts must be disabled.
7495 2) The caller must be in 32-bit paged mode.
7496 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7497 4) CR3 must point to valid page tables that guarantee that the pages for
7498 this function and the stack are identity mapped.
7500 @param EntryPoint A pointer to function to call with the new stack after
7502 @param Context1 A pointer to the context to pass into the EntryPoint
7503 function as the first parameter after paging is disabled.
7504 @param Context2 A pointer to the context to pass into the EntryPoint
7505 function as the second parameter after paging is
7507 @param NewStack A pointer to the new stack to use for the EntryPoint
7508 function after paging is disabled.
7513 AsmDisablePaging32 (
7514 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7515 IN VOID
*Context1
, OPTIONAL
7516 IN VOID
*Context2
, OPTIONAL
7522 Enables the 64-bit paging mode on the CPU.
7524 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7525 must be properly initialized prior to calling this service. This function
7526 assumes the current execution mode is 32-bit protected mode with flat
7527 descriptors. This function is only available on IA-32. After the 64-bit
7528 paging mode is enabled, control is transferred to the function specified by
7529 EntryPoint using the new stack specified by NewStack and passing in the
7530 parameters specified by Context1 and Context2. Context1 and Context2 are
7531 optional and may be 0. The function EntryPoint must never return.
7533 If the current execution mode is not 32-bit protected mode with flat
7534 descriptors, then ASSERT().
7535 If EntryPoint is 0, then ASSERT().
7536 If NewStack is 0, then ASSERT().
7538 @param Cs The 16-bit selector to load in the CS before EntryPoint
7539 is called. The descriptor in the GDT that this selector
7540 references must be setup for long mode.
7541 @param EntryPoint The 64-bit virtual address of the function to call with
7542 the new stack after paging is enabled.
7543 @param Context1 The 64-bit virtual address of the context to pass into
7544 the EntryPoint function as the first parameter after
7546 @param Context2 The 64-bit virtual address of the context to pass into
7547 the EntryPoint function as the second parameter after
7549 @param NewStack The 64-bit virtual address of the new stack to use for
7550 the EntryPoint function after paging is enabled.
7557 IN UINT64 EntryPoint
,
7558 IN UINT64 Context1
, OPTIONAL
7559 IN UINT64 Context2
, OPTIONAL
7565 Disables the 64-bit paging mode on the CPU.
7567 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7568 mode. This function assumes the current execution mode is 64-paging mode.
7569 This function is only available on x64. After the 64-bit paging mode is
7570 disabled, control is transferred to the function specified by EntryPoint
7571 using the new stack specified by NewStack and passing in the parameters
7572 specified by Context1 and Context2. Context1 and Context2 are optional and
7573 may be 0. The function EntryPoint must never return.
7575 If the current execution mode is not 64-bit paged mode, then ASSERT().
7576 If EntryPoint is 0, then ASSERT().
7577 If NewStack is 0, then ASSERT().
7579 @param Cs The 16-bit selector to load in the CS before EntryPoint
7580 is called. The descriptor in the GDT that this selector
7581 references must be setup for 32-bit protected mode.
7582 @param EntryPoint The 64-bit virtual address of the function to call with
7583 the new stack after paging is disabled.
7584 @param Context1 The 64-bit virtual address of the context to pass into
7585 the EntryPoint function as the first parameter after
7587 @param Context2 The 64-bit virtual address of the context to pass into
7588 the EntryPoint function as the second parameter after
7590 @param NewStack The 64-bit virtual address of the new stack to use for
7591 the EntryPoint function after paging is disabled.
7596 AsmDisablePaging64 (
7598 IN UINT32 EntryPoint
,
7599 IN UINT32 Context1
, OPTIONAL
7600 IN UINT32 Context2
, OPTIONAL
7606 // 16-bit thunking services
7610 Retrieves the properties for 16-bit thunk functions.
7612 Computes the size of the buffer and stack below 1MB required to use the
7613 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7614 buffer size is returned in RealModeBufferSize, and the stack size is returned
7615 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7616 then the actual minimum stack size is ExtraStackSize plus the maximum number
7617 of bytes that need to be passed to the 16-bit real mode code.
7619 If RealModeBufferSize is NULL, then ASSERT().
7620 If ExtraStackSize is NULL, then ASSERT().
7622 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
7623 required to use the 16-bit thunk functions.
7624 @param ExtraStackSize A pointer to the extra size of stack below 1MB
7625 that the 16-bit thunk functions require for
7626 temporary storage in the transition to and from
7632 AsmGetThunk16Properties (
7633 OUT UINT32
*RealModeBufferSize
,
7634 OUT UINT32
*ExtraStackSize
7639 Prepares all structures a code required to use AsmThunk16().
7641 Prepares all structures and code required to use AsmThunk16().
7643 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7644 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7646 If ThunkContext is NULL, then ASSERT().
7648 @param ThunkContext A pointer to the context structure that describes the
7649 16-bit real mode code to call.
7655 IN OUT THUNK_CONTEXT
*ThunkContext
7660 Transfers control to a 16-bit real mode entry point and returns the results.
7662 Transfers control to a 16-bit real mode entry point and returns the results.
7663 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7664 This function must be called with interrupts disabled.
7666 The register state from the RealModeState field of ThunkContext is restored just prior
7667 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
7668 which is used to set the interrupt state when a 16-bit real mode entry point is called.
7669 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7670 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
7671 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7672 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7673 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7674 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7675 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7676 after the RETF instruction is executed.
7678 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7679 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7680 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7682 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7683 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7684 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7686 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7687 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7689 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7690 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7691 disable the A20 mask.
7693 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7694 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
7695 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7697 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7698 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7700 If ThunkContext is NULL, then ASSERT().
7701 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7702 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7703 ThunkAttributes, then ASSERT().
7705 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7706 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7708 @param ThunkContext A pointer to the context structure that describes the
7709 16-bit real mode code to call.
7715 IN OUT THUNK_CONTEXT
*ThunkContext
7720 Prepares all structures and code for a 16-bit real mode thunk, transfers
7721 control to a 16-bit real mode entry point, and returns the results.
7723 Prepares all structures and code for a 16-bit real mode thunk, transfers
7724 control to a 16-bit real mode entry point, and returns the results. If the
7725 caller only need to perform a single 16-bit real mode thunk, then this
7726 service should be used. If the caller intends to make more than one 16-bit
7727 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7728 once and AsmThunk16() can be called for each 16-bit real mode thunk.
7730 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7731 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7733 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7735 @param ThunkContext A pointer to the context structure that describes the
7736 16-bit real mode code to call.
7741 AsmPrepareAndThunk16 (
7742 IN OUT THUNK_CONTEXT
*ThunkContext
7746 Generates a 16-bit random number through RDRAND instruction.
7748 if Rand is NULL, then ASSERT().
7750 @param[out] Rand Buffer pointer to store the random result.
7752 @retval TRUE RDRAND call was successful.
7753 @retval FALSE Failed attempts to call RDRAND.
7763 Generates a 32-bit random number through RDRAND instruction.
7765 if Rand is NULL, then ASSERT().
7767 @param[out] Rand Buffer pointer to store the random result.
7769 @retval TRUE RDRAND call was successful.
7770 @retval FALSE Failed attempts to call RDRAND.
7780 Generates a 64-bit random number through RDRAND instruction.
7782 if Rand is NULL, then ASSERT().
7784 @param[out] Rand Buffer pointer to store the random result.
7786 @retval TRUE RDRAND call was successful.
7787 @retval FALSE Failed attempts to call RDRAND.
7797 Load given selector into TR register.
7799 @param[in] Selector Task segment selector
7808 Performs a serializing operation on all load-from-memory instructions that
7809 were issued prior the AsmLfence function.
7811 Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7821 Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7822 word, dword or qword operand is encoded at the end of the instruction's
7823 binary representation.
7825 This function should be used to update object code that was compiled with
7826 NASM from assembly source code. Example:
7830 mov eax, strict dword 0 ; the imm32 zero operand will be patched
7836 X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7837 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7839 @param[out] InstructionEnd Pointer right past the instruction to patch. The
7840 immediate operand to patch is expected to
7841 comprise the trailing bytes of the instruction.
7842 If InstructionEnd is closer to address 0 than
7843 ValueSize permits, then ASSERT().
7845 @param[in] PatchValue The constant to write to the immediate operand.
7846 The caller is responsible for ensuring that
7847 PatchValue can be represented in the byte, word,
7848 dword or qword operand (as indicated through
7849 ValueSize); otherwise ASSERT().
7851 @param[in] ValueSize The size of the operand in bytes; must be 1, 2,
7852 4, or 8. ASSERT() otherwise.
7856 PatchInstructionX86 (
7857 OUT X86_ASSEMBLY_PATCH_LABEL
*InstructionEnd
,
7858 IN UINT64 PatchValue
,
7862 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7863 #endif // !defined (__BASE_LIB__)