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 Decode Base64 ASCII encoded data to 8-bit binary representation, based on
2791 Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648.
2793 Whitespace is ignored at all positions:
2794 - 0x09 ('\t') horizontal tab
2795 - 0x0A ('\n') new line
2796 - 0x0B ('\v') vertical tab
2797 - 0x0C ('\f') form feed
2798 - 0x0D ('\r') carriage return
2801 The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated
2802 and enforced at the end of the Base64 ASCII encoded data, and only there.
2804 Other characters outside of the encoding alphabet cause the function to
2805 reject the Base64 ASCII encoded data.
2807 @param[in] Source Array of CHAR8 elements containing the Base64
2808 ASCII encoding. May be NULL if SourceSize is
2811 @param[in] SourceSize Number of CHAR8 elements in Source.
2813 @param[out] Destination Array of UINT8 elements receiving the decoded
2814 8-bit binary representation. Allocated by the
2815 caller. May be NULL if DestinationSize is
2816 zero on input. If NULL, decoding is
2817 performed, but the 8-bit binary
2818 representation is not stored. If non-NULL and
2819 the function returns an error, the contents
2820 of Destination are indeterminate.
2822 @param[in,out] DestinationSize On input, the number of UINT8 elements that
2823 the caller allocated for Destination. On
2824 output, if the function returns
2825 RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL,
2826 the number of UINT8 elements that are
2827 required for decoding the Base64 ASCII
2828 representation. If the function returns a
2829 value different from both RETURN_SUCCESS and
2830 RETURN_BUFFER_TOO_SMALL, then DestinationSize
2831 is indeterminate on output.
2833 @retval RETURN_SUCCESS SourceSize CHAR8 elements at Source have
2834 been decoded to on-output DestinationSize
2835 UINT8 elements at Destination. Note that
2836 RETURN_SUCCESS covers the case when
2837 DestinationSize is zero on input, and
2838 Source decodes to zero bytes (due to
2839 containing at most ignored whitespace).
2841 @retval RETURN_BUFFER_TOO_SMALL The input value of DestinationSize is not
2842 large enough for decoding SourceSize CHAR8
2843 elements at Source. The required number of
2844 UINT8 elements has been stored to
2847 @retval RETURN_INVALID_PARAMETER DestinationSize is NULL.
2849 @retval RETURN_INVALID_PARAMETER Source is NULL, but SourceSize is not zero.
2851 @retval RETURN_INVALID_PARAMETER Destination is NULL, but DestinationSize is
2854 @retval RETURN_INVALID_PARAMETER Source is non-NULL, and (Source +
2855 SourceSize) would wrap around MAX_ADDRESS.
2857 @retval RETURN_INVALID_PARAMETER Destination is non-NULL, and (Destination +
2858 DestinationSize) would wrap around
2859 MAX_ADDRESS, as specified on input.
2861 @retval RETURN_INVALID_PARAMETER None of Source and Destination are NULL,
2862 and CHAR8[SourceSize] at Source overlaps
2863 UINT8[DestinationSize] at Destination, as
2866 @retval RETURN_INVALID_PARAMETER Invalid CHAR8 element encountered in
2872 IN CONST CHAR8
*Source OPTIONAL
,
2873 IN UINTN SourceSize
,
2874 OUT UINT8
*Destination OPTIONAL
,
2875 IN OUT UINTN
*DestinationSize
2879 Converts an 8-bit value to an 8-bit BCD value.
2881 Converts the 8-bit value specified by Value to BCD. The BCD value is
2884 If Value >= 100, then ASSERT().
2886 @param Value The 8-bit value to convert to BCD. Range 0..99.
2888 @return The BCD value.
2899 Converts an 8-bit BCD value to an 8-bit value.
2901 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2904 If Value >= 0xA0, then ASSERT().
2905 If (Value & 0x0F) >= 0x0A, then ASSERT().
2907 @param Value The 8-bit BCD value to convert to an 8-bit value.
2909 @return The 8-bit value is returned.
2919 // File Path Manipulation Functions
2923 Removes the last directory or file entry in a path.
2925 @param[in, out] Path The pointer to the path to modify.
2927 @retval FALSE Nothing was found to remove.
2928 @retval TRUE A directory or file was removed.
2937 Function to clean up paths.
2938 - Single periods in the path are removed.
2939 - Double periods in the path are removed along with a single parent directory.
2940 - Forward slashes L'/' are converted to backward slashes L'\'.
2942 This will be done inline and the existing buffer may be larger than required
2945 @param[in] Path The pointer to the string containing the path.
2947 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2951 PathCleanUpDirectories(
2956 // Linked List Functions and Macros
2960 Initializes the head node of a doubly linked list that is declared as a
2961 global variable in a module.
2963 Initializes the forward and backward links of a new linked list. After
2964 initializing a linked list with this macro, the other linked list functions
2965 may be used to add and remove nodes from the linked list. This macro results
2966 in smaller executables by initializing the linked list in the data section,
2967 instead if calling the InitializeListHead() function to perform the
2968 equivalent operation.
2970 @param ListHead The head note of a list to initialize.
2973 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2977 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2980 If FirstEntry is NULL, then ASSERT().
2981 If FirstEntry->ForwardLink is NULL, then ASSERT().
2982 If FirstEntry->BackLink is NULL, then ASSERT().
2983 If SecondEntry is NULL, then ASSERT();
2984 If PcdMaximumLinkedListLength is not zero, and List contains more than
2985 PcdMaximumLinkedListLength nodes, then ASSERT().
2987 @param FirstEntry A pointer to a node in a linked list.
2988 @param SecondEntry A pointer to the node to locate.
2990 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.
2991 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,
2992 or FirstEntry is invalid.
2998 IN CONST LIST_ENTRY
*FirstEntry
,
2999 IN CONST LIST_ENTRY
*SecondEntry
3004 Initializes the head node of a doubly linked list, and returns the pointer to
3005 the head node of the doubly linked list.
3007 Initializes the forward and backward links of a new linked list. After
3008 initializing a linked list with this function, the other linked list
3009 functions may be used to add and remove nodes from the linked list. It is up
3010 to the caller of this function to allocate the memory for ListHead.
3012 If ListHead is NULL, then ASSERT().
3014 @param ListHead A pointer to the head node of a new doubly linked list.
3021 InitializeListHead (
3022 IN OUT LIST_ENTRY
*ListHead
3027 Adds a node to the beginning of a doubly linked list, and returns the pointer
3028 to the head node of the doubly linked list.
3030 Adds the node Entry at the beginning of the doubly linked list denoted by
3031 ListHead, and returns ListHead.
3033 If ListHead is NULL, then ASSERT().
3034 If Entry is NULL, then ASSERT().
3035 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3036 InitializeListHead(), then ASSERT().
3037 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
3038 of nodes in ListHead, including the ListHead node, is greater than or
3039 equal to PcdMaximumLinkedListLength, then ASSERT().
3041 @param ListHead A pointer to the head node of a doubly linked list.
3042 @param Entry A pointer to a node that is to be inserted at the beginning
3043 of a doubly linked list.
3051 IN OUT LIST_ENTRY
*ListHead
,
3052 IN OUT LIST_ENTRY
*Entry
3057 Adds a node to the end of a doubly linked list, and returns the pointer to
3058 the head node of the doubly linked list.
3060 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
3061 and returns ListHead.
3063 If ListHead is NULL, then ASSERT().
3064 If Entry is NULL, then ASSERT().
3065 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3066 InitializeListHead(), then ASSERT().
3067 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
3068 of nodes in ListHead, including the ListHead node, is greater than or
3069 equal to PcdMaximumLinkedListLength, then ASSERT().
3071 @param ListHead A pointer to the head node of a doubly linked list.
3072 @param Entry A pointer to a node that is to be added at the end of the
3081 IN OUT LIST_ENTRY
*ListHead
,
3082 IN OUT LIST_ENTRY
*Entry
3087 Retrieves the first node of a doubly linked list.
3089 Returns the first node of a doubly linked list. List must have been
3090 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3091 If List is empty, then List is returned.
3093 If List is NULL, then ASSERT().
3094 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3095 InitializeListHead(), then ASSERT().
3096 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3097 in List, including the List node, is greater than or equal to
3098 PcdMaximumLinkedListLength, then ASSERT().
3100 @param List A pointer to the head node of a doubly linked list.
3102 @return The first node of a doubly linked list.
3103 @retval List The list is empty.
3109 IN CONST LIST_ENTRY
*List
3114 Retrieves the next node of a doubly linked list.
3116 Returns the node of a doubly linked list that follows Node.
3117 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3118 or InitializeListHead(). If List is empty, then List is returned.
3120 If List is NULL, then ASSERT().
3121 If Node is NULL, then ASSERT().
3122 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3123 InitializeListHead(), then ASSERT().
3124 If PcdMaximumLinkedListLength is not zero, and List contains more than
3125 PcdMaximumLinkedListLength nodes, then ASSERT().
3126 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3128 @param List A pointer to the head node of a doubly linked list.
3129 @param Node A pointer to a node in the doubly linked list.
3131 @return The pointer to the next node if one exists. Otherwise List is returned.
3137 IN CONST LIST_ENTRY
*List
,
3138 IN CONST LIST_ENTRY
*Node
3143 Retrieves the previous node of a doubly linked list.
3145 Returns the node of a doubly linked list that precedes Node.
3146 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3147 or InitializeListHead(). If List is empty, then List is returned.
3149 If List is NULL, then ASSERT().
3150 If Node is NULL, then ASSERT().
3151 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3152 InitializeListHead(), then ASSERT().
3153 If PcdMaximumLinkedListLength is not zero, and List contains more than
3154 PcdMaximumLinkedListLength nodes, then ASSERT().
3155 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3157 @param List A pointer to the head node of a doubly linked list.
3158 @param Node A pointer to a node in the doubly linked list.
3160 @return The pointer to the previous node if one exists. Otherwise List is returned.
3166 IN CONST LIST_ENTRY
*List
,
3167 IN CONST LIST_ENTRY
*Node
3172 Checks to see if a doubly linked list is empty or not.
3174 Checks to see if the doubly linked list is empty. If the linked list contains
3175 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
3177 If ListHead is NULL, then ASSERT().
3178 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3179 InitializeListHead(), then ASSERT().
3180 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3181 in List, including the List node, is greater than or equal to
3182 PcdMaximumLinkedListLength, then ASSERT().
3184 @param ListHead A pointer to the head node of a doubly linked list.
3186 @retval TRUE The linked list is empty.
3187 @retval FALSE The linked list is not empty.
3193 IN CONST LIST_ENTRY
*ListHead
3198 Determines if a node in a doubly linked list is the head node of a the same
3199 doubly linked list. This function is typically used to terminate a loop that
3200 traverses all the nodes in a doubly linked list starting with the head node.
3202 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
3203 nodes in the doubly linked list specified by List. List must have been
3204 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3206 If List is NULL, then ASSERT().
3207 If Node is NULL, then ASSERT().
3208 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
3210 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3211 in List, including the List node, is greater than or equal to
3212 PcdMaximumLinkedListLength, then ASSERT().
3213 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
3214 to List, then ASSERT().
3216 @param List A pointer to the head node of a doubly linked list.
3217 @param Node A pointer to a node in the doubly linked list.
3219 @retval TRUE Node is the head of the doubly-linked list pointed by List.
3220 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
3226 IN CONST LIST_ENTRY
*List
,
3227 IN CONST LIST_ENTRY
*Node
3232 Determines if a node the last node in a doubly linked list.
3234 Returns TRUE if Node is the last node in the doubly linked list specified by
3235 List. Otherwise, FALSE is returned. List must have been initialized with
3236 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3238 If List is NULL, then ASSERT().
3239 If Node is NULL, then ASSERT().
3240 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3241 InitializeListHead(), then ASSERT().
3242 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3243 in List, including the List node, is greater than or equal to
3244 PcdMaximumLinkedListLength, then ASSERT().
3245 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3247 @param List A pointer to the head node of a doubly linked list.
3248 @param Node A pointer to a node in the doubly linked list.
3250 @retval TRUE Node is the last node in the linked list.
3251 @retval FALSE Node is not the last node in the linked list.
3257 IN CONST LIST_ENTRY
*List
,
3258 IN CONST LIST_ENTRY
*Node
3263 Swaps the location of two nodes in a doubly linked list, and returns the
3264 first node after the swap.
3266 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
3267 Otherwise, the location of the FirstEntry node is swapped with the location
3268 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
3269 same double linked list as FirstEntry and that double linked list must have
3270 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3271 SecondEntry is returned after the nodes are swapped.
3273 If FirstEntry is NULL, then ASSERT().
3274 If SecondEntry is NULL, then ASSERT().
3275 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
3276 same linked list, then ASSERT().
3277 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3278 linked list containing the FirstEntry and SecondEntry nodes, including
3279 the FirstEntry and SecondEntry nodes, is greater than or equal to
3280 PcdMaximumLinkedListLength, then ASSERT().
3282 @param FirstEntry A pointer to a node in a linked list.
3283 @param SecondEntry A pointer to another node in the same linked list.
3285 @return SecondEntry.
3291 IN OUT LIST_ENTRY
*FirstEntry
,
3292 IN OUT LIST_ENTRY
*SecondEntry
3297 Removes a node from a doubly linked list, and returns the node that follows
3300 Removes the node Entry from a doubly linked list. It is up to the caller of
3301 this function to release the memory used by this node if that is required. On
3302 exit, the node following Entry in the doubly linked list is returned. If
3303 Entry is the only node in the linked list, then the head node of the linked
3306 If Entry is NULL, then ASSERT().
3307 If Entry is the head node of an empty list, then ASSERT().
3308 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3309 linked list containing Entry, including the Entry node, is greater than
3310 or equal to PcdMaximumLinkedListLength, then ASSERT().
3312 @param Entry A pointer to a node in a linked list.
3320 IN CONST LIST_ENTRY
*Entry
3328 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
3329 with zeros. The shifted value is returned.
3331 This function shifts the 64-bit value Operand to the left by Count bits. The
3332 low Count bits are set to zero. The shifted value is returned.
3334 If Count is greater than 63, then ASSERT().
3336 @param Operand The 64-bit operand to shift left.
3337 @param Count The number of bits to shift left.
3339 @return Operand << Count.
3351 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
3352 filled with zeros. The shifted value is returned.
3354 This function shifts the 64-bit value Operand to the right by Count bits. The
3355 high Count bits are set to zero. The shifted value is returned.
3357 If Count is greater than 63, then ASSERT().
3359 @param Operand The 64-bit operand to shift right.
3360 @param Count The number of bits to shift right.
3362 @return Operand >> Count
3374 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
3375 with original integer's bit 63. The shifted value is returned.
3377 This function shifts the 64-bit value Operand to the right by Count bits. The
3378 high Count bits are set to bit 63 of Operand. The shifted value is returned.
3380 If Count is greater than 63, then ASSERT().
3382 @param Operand The 64-bit operand to shift right.
3383 @param Count The number of bits to shift right.
3385 @return Operand >> Count
3397 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
3398 with the high bits that were rotated.
3400 This function rotates the 32-bit value Operand to the left by Count bits. The
3401 low Count bits are fill with the high Count bits of Operand. The rotated
3404 If Count is greater than 31, then ASSERT().
3406 @param Operand The 32-bit operand to rotate left.
3407 @param Count The number of bits to rotate left.
3409 @return Operand << Count
3421 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
3422 with the low bits that were rotated.
3424 This function rotates the 32-bit value Operand to the right by Count bits.
3425 The high Count bits are fill with the low Count bits of Operand. The rotated
3428 If Count is greater than 31, then ASSERT().
3430 @param Operand The 32-bit operand to rotate right.
3431 @param Count The number of bits to rotate right.
3433 @return Operand >> Count
3445 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3446 with the high bits that were rotated.
3448 This function rotates the 64-bit value Operand to the left by Count bits. The
3449 low Count bits are fill with the high Count bits of Operand. The rotated
3452 If Count is greater than 63, then ASSERT().
3454 @param Operand The 64-bit operand to rotate left.
3455 @param Count The number of bits to rotate left.
3457 @return Operand << Count
3469 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3470 with the high low bits that were rotated.
3472 This function rotates the 64-bit value Operand to the right by Count bits.
3473 The high Count bits are fill with the low Count bits of Operand. The rotated
3476 If Count is greater than 63, then ASSERT().
3478 @param Operand The 64-bit operand to rotate right.
3479 @param Count The number of bits to rotate right.
3481 @return Operand >> Count
3493 Returns the bit position of the lowest bit set in a 32-bit value.
3495 This function computes the bit position of the lowest bit set in the 32-bit
3496 value specified by Operand. If Operand is zero, then -1 is returned.
3497 Otherwise, a value between 0 and 31 is returned.
3499 @param Operand The 32-bit operand to evaluate.
3501 @retval 0..31 The lowest bit set in Operand was found.
3502 @retval -1 Operand is zero.
3513 Returns the bit position of the lowest bit set in a 64-bit value.
3515 This function computes the bit position of the lowest bit set in the 64-bit
3516 value specified by Operand. If Operand is zero, then -1 is returned.
3517 Otherwise, a value between 0 and 63 is returned.
3519 @param Operand The 64-bit operand to evaluate.
3521 @retval 0..63 The lowest bit set in Operand was found.
3522 @retval -1 Operand is zero.
3534 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3537 This function computes the bit position of the highest bit set in the 32-bit
3538 value specified by Operand. If Operand is zero, then -1 is returned.
3539 Otherwise, a value between 0 and 31 is returned.
3541 @param Operand The 32-bit operand to evaluate.
3543 @retval 0..31 Position of the highest bit set in Operand if found.
3544 @retval -1 Operand is zero.
3555 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3558 This function computes the bit position of the highest bit set in the 64-bit
3559 value specified by Operand. If Operand is zero, then -1 is returned.
3560 Otherwise, a value between 0 and 63 is returned.
3562 @param Operand The 64-bit operand to evaluate.
3564 @retval 0..63 Position of the highest bit set in Operand if found.
3565 @retval -1 Operand is zero.
3576 Returns the value of the highest bit set in a 32-bit value. Equivalent to
3579 This function computes the value of the highest bit set in the 32-bit value
3580 specified by Operand. If Operand is zero, then zero is returned.
3582 @param Operand The 32-bit operand to evaluate.
3584 @return 1 << HighBitSet32(Operand)
3585 @retval 0 Operand is zero.
3596 Returns the value of the highest bit set in a 64-bit value. Equivalent to
3599 This function computes the value of the highest bit set in the 64-bit value
3600 specified by Operand. If Operand is zero, then zero is returned.
3602 @param Operand The 64-bit operand to evaluate.
3604 @return 1 << HighBitSet64(Operand)
3605 @retval 0 Operand is zero.
3616 Switches the endianness of a 16-bit integer.
3618 This function swaps the bytes in a 16-bit unsigned value to switch the value
3619 from little endian to big endian or vice versa. The byte swapped value is
3622 @param Value A 16-bit unsigned value.
3624 @return The byte swapped Value.
3635 Switches the endianness of a 32-bit integer.
3637 This function swaps the bytes in a 32-bit unsigned value to switch the value
3638 from little endian to big endian or vice versa. The byte swapped value is
3641 @param Value A 32-bit unsigned value.
3643 @return The byte swapped Value.
3654 Switches the endianness of a 64-bit integer.
3656 This function swaps the bytes in a 64-bit unsigned value to switch the value
3657 from little endian to big endian or vice versa. The byte swapped value is
3660 @param Value A 64-bit unsigned value.
3662 @return The byte swapped Value.
3673 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3674 generates a 64-bit unsigned result.
3676 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3677 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3678 bit unsigned result is returned.
3680 @param Multiplicand A 64-bit unsigned value.
3681 @param Multiplier A 32-bit unsigned value.
3683 @return Multiplicand * Multiplier
3689 IN UINT64 Multiplicand
,
3690 IN UINT32 Multiplier
3695 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3696 generates a 64-bit unsigned result.
3698 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3699 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3700 bit unsigned result is returned.
3702 @param Multiplicand A 64-bit unsigned value.
3703 @param Multiplier A 64-bit unsigned value.
3705 @return Multiplicand * Multiplier.
3711 IN UINT64 Multiplicand
,
3712 IN UINT64 Multiplier
3717 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3718 64-bit signed result.
3720 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3721 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3722 signed result is returned.
3724 @param Multiplicand A 64-bit signed value.
3725 @param Multiplier A 64-bit signed value.
3727 @return Multiplicand * Multiplier
3733 IN INT64 Multiplicand
,
3739 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3740 a 64-bit unsigned result.
3742 This function divides the 64-bit unsigned value Dividend by the 32-bit
3743 unsigned value Divisor and generates a 64-bit unsigned quotient. This
3744 function returns the 64-bit unsigned quotient.
3746 If Divisor is 0, then ASSERT().
3748 @param Dividend A 64-bit unsigned value.
3749 @param Divisor A 32-bit unsigned value.
3751 @return Dividend / Divisor.
3763 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3764 a 32-bit unsigned remainder.
3766 This function divides the 64-bit unsigned value Dividend by the 32-bit
3767 unsigned value Divisor and generates a 32-bit remainder. This function
3768 returns the 32-bit unsigned remainder.
3770 If Divisor is 0, then ASSERT().
3772 @param Dividend A 64-bit unsigned value.
3773 @param Divisor A 32-bit unsigned value.
3775 @return Dividend % Divisor.
3787 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3788 a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3790 This function divides the 64-bit unsigned value Dividend by the 32-bit
3791 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3792 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3793 This function returns the 64-bit unsigned quotient.
3795 If Divisor is 0, then ASSERT().
3797 @param Dividend A 64-bit unsigned value.
3798 @param Divisor A 32-bit unsigned value.
3799 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3800 optional and may be NULL.
3802 @return Dividend / Divisor.
3807 DivU64x32Remainder (
3810 OUT UINT32
*Remainder OPTIONAL
3815 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3816 a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3818 This function divides the 64-bit unsigned value Dividend by the 64-bit
3819 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3820 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3821 This function returns the 64-bit unsigned quotient.
3823 If Divisor is 0, then ASSERT().
3825 @param Dividend A 64-bit unsigned value.
3826 @param Divisor A 64-bit unsigned value.
3827 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3828 optional and may be NULL.
3830 @return Dividend / Divisor.
3835 DivU64x64Remainder (
3838 OUT UINT64
*Remainder OPTIONAL
3843 Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3844 64-bit signed result and a optional 64-bit signed remainder.
3846 This function divides the 64-bit signed value Dividend by the 64-bit signed
3847 value Divisor and generates a 64-bit signed quotient. If Remainder is not
3848 NULL, then the 64-bit signed remainder is returned in Remainder. This
3849 function returns the 64-bit signed quotient.
3851 It is the caller's responsibility to not call this function with a Divisor of 0.
3852 If Divisor is 0, then the quotient and remainder should be assumed to be
3853 the largest negative integer.
3855 If Divisor is 0, then ASSERT().
3857 @param Dividend A 64-bit signed value.
3858 @param Divisor A 64-bit signed value.
3859 @param Remainder A pointer to a 64-bit signed value. This parameter is
3860 optional and may be NULL.
3862 @return Dividend / Divisor.
3867 DivS64x64Remainder (
3870 OUT INT64
*Remainder OPTIONAL
3875 Reads a 16-bit value from memory that may be unaligned.
3877 This function returns the 16-bit value pointed to by Buffer. The function
3878 guarantees that the read operation does not produce an alignment fault.
3880 If the Buffer is NULL, then ASSERT().
3882 @param Buffer The pointer to a 16-bit value that may be unaligned.
3884 @return The 16-bit value read from Buffer.
3890 IN CONST UINT16
*Buffer
3895 Writes a 16-bit value to memory that may be unaligned.
3897 This function writes the 16-bit value specified by Value to Buffer. Value is
3898 returned. The function guarantees that the write operation does not produce
3901 If the Buffer is NULL, then ASSERT().
3903 @param Buffer The pointer to a 16-bit value that may be unaligned.
3904 @param Value 16-bit value to write to Buffer.
3906 @return The 16-bit value to write to Buffer.
3918 Reads a 24-bit value from memory that may be unaligned.
3920 This function returns the 24-bit value pointed to by Buffer. The function
3921 guarantees that the read operation does not produce an alignment fault.
3923 If the Buffer is NULL, then ASSERT().
3925 @param Buffer The pointer to a 24-bit value that may be unaligned.
3927 @return The 24-bit value read from Buffer.
3933 IN CONST UINT32
*Buffer
3938 Writes a 24-bit value to memory that may be unaligned.
3940 This function writes the 24-bit value specified by Value to Buffer. Value is
3941 returned. The function guarantees that the write operation does not produce
3944 If the Buffer is NULL, then ASSERT().
3946 @param Buffer The pointer to a 24-bit value that may be unaligned.
3947 @param Value 24-bit value to write to Buffer.
3949 @return The 24-bit value to write to Buffer.
3961 Reads a 32-bit value from memory that may be unaligned.
3963 This function returns the 32-bit value pointed to by Buffer. The function
3964 guarantees that the read operation does not produce an alignment fault.
3966 If the Buffer is NULL, then ASSERT().
3968 @param Buffer The pointer to a 32-bit value that may be unaligned.
3970 @return The 32-bit value read from Buffer.
3976 IN CONST UINT32
*Buffer
3981 Writes a 32-bit value to memory that may be unaligned.
3983 This function writes the 32-bit value specified by Value to Buffer. Value is
3984 returned. The function guarantees that the write operation does not produce
3987 If the Buffer is NULL, then ASSERT().
3989 @param Buffer The pointer to a 32-bit value that may be unaligned.
3990 @param Value 32-bit value to write to Buffer.
3992 @return The 32-bit value to write to Buffer.
4004 Reads a 64-bit value from memory that may be unaligned.
4006 This function returns the 64-bit value pointed to by Buffer. The function
4007 guarantees that the read operation does not produce an alignment fault.
4009 If the Buffer is NULL, then ASSERT().
4011 @param Buffer The pointer to a 64-bit value that may be unaligned.
4013 @return The 64-bit value read from Buffer.
4019 IN CONST UINT64
*Buffer
4024 Writes a 64-bit value to memory that may be unaligned.
4026 This function writes the 64-bit value specified by Value to Buffer. Value is
4027 returned. The function guarantees that the write operation does not produce
4030 If the Buffer is NULL, then ASSERT().
4032 @param Buffer The pointer to a 64-bit value that may be unaligned.
4033 @param Value 64-bit value to write to Buffer.
4035 @return The 64-bit value to write to Buffer.
4047 // Bit Field Functions
4051 Returns a bit field from an 8-bit value.
4053 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4055 If 8-bit operations are not supported, then ASSERT().
4056 If StartBit is greater than 7, then ASSERT().
4057 If EndBit is greater than 7, then ASSERT().
4058 If EndBit is less than StartBit, then ASSERT().
4060 @param Operand Operand on which to perform the bitfield operation.
4061 @param StartBit The ordinal of the least significant bit in the bit field.
4063 @param EndBit The ordinal of the most significant bit in the bit field.
4066 @return The bit field read.
4079 Writes a bit field to an 8-bit value, and returns the result.
4081 Writes Value to the bit field specified by the StartBit and the EndBit in
4082 Operand. All other bits in Operand are preserved. The new 8-bit value is
4085 If 8-bit operations are not supported, then ASSERT().
4086 If StartBit is greater than 7, then ASSERT().
4087 If EndBit is greater than 7, then ASSERT().
4088 If EndBit is less than StartBit, then ASSERT().
4089 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4091 @param Operand Operand on which to perform the bitfield operation.
4092 @param StartBit The ordinal of the least significant bit in the bit field.
4094 @param EndBit The ordinal of the most significant bit in the bit field.
4096 @param Value New value of the bit field.
4098 @return The new 8-bit value.
4112 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
4115 Performs a bitwise OR between the bit field specified by StartBit
4116 and EndBit in Operand and the value specified by OrData. All other bits in
4117 Operand are preserved. The new 8-bit value is returned.
4119 If 8-bit operations are not supported, then ASSERT().
4120 If StartBit is greater than 7, then ASSERT().
4121 If EndBit is greater than 7, then ASSERT().
4122 If EndBit is less than StartBit, then ASSERT().
4123 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4125 @param Operand Operand on which to perform the bitfield operation.
4126 @param StartBit The ordinal of the least significant bit in the bit field.
4128 @param EndBit The ordinal of the most significant bit in the bit field.
4130 @param OrData The value to OR with the read value from the value
4132 @return The new 8-bit value.
4146 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
4149 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4150 in Operand and the value specified by AndData. All other bits in Operand are
4151 preserved. The new 8-bit value is returned.
4153 If 8-bit operations are not supported, then ASSERT().
4154 If StartBit is greater than 7, then ASSERT().
4155 If EndBit is greater than 7, then ASSERT().
4156 If EndBit is less than StartBit, then ASSERT().
4157 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4159 @param Operand Operand on which to perform the bitfield operation.
4160 @param StartBit The ordinal of the least significant bit in the bit field.
4162 @param EndBit The ordinal of the most significant bit in the bit field.
4164 @param AndData The value to AND with the read value from the value.
4166 @return The new 8-bit value.
4180 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
4181 bitwise OR, and returns the result.
4183 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4184 in Operand and the value specified by AndData, followed by a bitwise
4185 OR with value specified by OrData. All other bits in Operand are
4186 preserved. The new 8-bit value is returned.
4188 If 8-bit operations are not supported, then ASSERT().
4189 If StartBit is greater than 7, then ASSERT().
4190 If EndBit is greater than 7, then ASSERT().
4191 If EndBit is less than StartBit, then ASSERT().
4192 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4193 If OrData 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 AndData The value to AND with the read value from the value.
4201 @param OrData The value to OR with the result of the AND operation.
4203 @return The new 8-bit value.
4208 BitFieldAndThenOr8 (
4218 Returns a bit field from a 16-bit value.
4220 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4222 If 16-bit operations are not supported, then ASSERT().
4223 If StartBit is greater than 15, then ASSERT().
4224 If EndBit is greater than 15, then ASSERT().
4225 If EndBit is less than StartBit, then ASSERT().
4227 @param Operand Operand on which to perform the bitfield operation.
4228 @param StartBit The ordinal of the least significant bit in the bit field.
4230 @param EndBit The ordinal of the most significant bit in the bit field.
4233 @return The bit field read.
4246 Writes a bit field to a 16-bit value, and returns the result.
4248 Writes Value to the bit field specified by the StartBit and the EndBit in
4249 Operand. All other bits in Operand are preserved. The new 16-bit value is
4252 If 16-bit operations are not supported, then ASSERT().
4253 If StartBit is greater than 15, then ASSERT().
4254 If EndBit is greater than 15, then ASSERT().
4255 If EndBit is less than StartBit, then ASSERT().
4256 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4258 @param Operand Operand on which to perform the bitfield operation.
4259 @param StartBit The ordinal of the least significant bit in the bit field.
4261 @param EndBit The ordinal of the most significant bit in the bit field.
4263 @param Value New value of the bit field.
4265 @return The new 16-bit value.
4279 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
4282 Performs a bitwise OR between the bit field specified by StartBit
4283 and EndBit in Operand and the value specified by OrData. All other bits in
4284 Operand are preserved. The new 16-bit value is returned.
4286 If 16-bit operations are not supported, then ASSERT().
4287 If StartBit is greater than 15, then ASSERT().
4288 If EndBit is greater than 15, then ASSERT().
4289 If EndBit is less than StartBit, then ASSERT().
4290 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4292 @param Operand Operand on which to perform the bitfield operation.
4293 @param StartBit The ordinal of the least significant bit in the bit field.
4295 @param EndBit The ordinal of the most significant bit in the bit field.
4297 @param OrData The value to OR with the read value from the value
4299 @return The new 16-bit value.
4313 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
4316 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4317 in Operand and the value specified by AndData. All other bits in Operand are
4318 preserved. The new 16-bit value is returned.
4320 If 16-bit operations are not supported, then ASSERT().
4321 If StartBit is greater than 15, then ASSERT().
4322 If EndBit is greater than 15, then ASSERT().
4323 If EndBit is less than StartBit, then ASSERT().
4324 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4326 @param Operand Operand on which to perform the bitfield operation.
4327 @param StartBit The ordinal of the least significant bit in the bit field.
4329 @param EndBit The ordinal of the most significant bit in the bit field.
4331 @param AndData The value to AND with the read value from the value
4333 @return The new 16-bit value.
4347 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
4348 bitwise OR, and returns the result.
4350 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4351 in Operand and the value specified by AndData, followed by a bitwise
4352 OR with value specified by OrData. All other bits in Operand are
4353 preserved. The new 16-bit value is returned.
4355 If 16-bit operations are not supported, then ASSERT().
4356 If StartBit is greater than 15, then ASSERT().
4357 If EndBit is greater than 15, then ASSERT().
4358 If EndBit is less than StartBit, then ASSERT().
4359 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4360 If OrData 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 AndData The value to AND with the read value from the value.
4368 @param OrData The value to OR with the result of the AND operation.
4370 @return The new 16-bit value.
4375 BitFieldAndThenOr16 (
4385 Returns a bit field from a 32-bit value.
4387 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4389 If 32-bit operations are not supported, then ASSERT().
4390 If StartBit is greater than 31, then ASSERT().
4391 If EndBit is greater than 31, then ASSERT().
4392 If EndBit is less than StartBit, then ASSERT().
4394 @param Operand Operand on which to perform the bitfield operation.
4395 @param StartBit The ordinal of the least significant bit in the bit field.
4397 @param EndBit The ordinal of the most significant bit in the bit field.
4400 @return The bit field read.
4413 Writes a bit field to a 32-bit value, and returns the result.
4415 Writes Value to the bit field specified by the StartBit and the EndBit in
4416 Operand. All other bits in Operand are preserved. The new 32-bit value is
4419 If 32-bit operations are not supported, then ASSERT().
4420 If StartBit is greater than 31, then ASSERT().
4421 If EndBit is greater than 31, then ASSERT().
4422 If EndBit is less than StartBit, then ASSERT().
4423 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4425 @param Operand Operand on which to perform the bitfield operation.
4426 @param StartBit The ordinal of the least significant bit in the bit field.
4428 @param EndBit The ordinal of the most significant bit in the bit field.
4430 @param Value New value of the bit field.
4432 @return The new 32-bit value.
4446 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
4449 Performs a bitwise OR between the bit field specified by StartBit
4450 and EndBit in Operand and the value specified by OrData. All other bits in
4451 Operand are preserved. The new 32-bit value is returned.
4453 If 32-bit operations are not supported, then ASSERT().
4454 If StartBit is greater than 31, then ASSERT().
4455 If EndBit is greater than 31, then ASSERT().
4456 If EndBit is less than StartBit, then ASSERT().
4457 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4459 @param Operand Operand on which to perform the bitfield operation.
4460 @param StartBit The ordinal of the least significant bit in the bit field.
4462 @param EndBit The ordinal of the most significant bit in the bit field.
4464 @param OrData The value to OR with the read value from the value.
4466 @return The new 32-bit value.
4480 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
4483 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4484 in Operand and the value specified by AndData. All other bits in Operand are
4485 preserved. The new 32-bit value is returned.
4487 If 32-bit operations are not supported, then ASSERT().
4488 If StartBit is greater than 31, then ASSERT().
4489 If EndBit is greater than 31, then ASSERT().
4490 If EndBit is less than StartBit, then ASSERT().
4491 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4493 @param Operand Operand on which to perform the bitfield operation.
4494 @param StartBit The ordinal of the least significant bit in the bit field.
4496 @param EndBit The ordinal of the most significant bit in the bit field.
4498 @param AndData The value to AND with the read value from the value
4500 @return The new 32-bit value.
4514 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4515 bitwise OR, and returns the result.
4517 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4518 in Operand and the value specified by AndData, followed by a bitwise
4519 OR with value specified by OrData. All other bits in Operand are
4520 preserved. The new 32-bit value is returned.
4522 If 32-bit operations are not supported, then ASSERT().
4523 If StartBit is greater than 31, then ASSERT().
4524 If EndBit is greater than 31, then ASSERT().
4525 If EndBit is less than StartBit, then ASSERT().
4526 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4527 If OrData 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 AndData The value to AND with the read value from the value.
4535 @param OrData The value to OR with the result of the AND operation.
4537 @return The new 32-bit value.
4542 BitFieldAndThenOr32 (
4552 Returns a bit field from a 64-bit value.
4554 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4556 If 64-bit operations are not supported, then ASSERT().
4557 If StartBit is greater than 63, then ASSERT().
4558 If EndBit is greater than 63, then ASSERT().
4559 If EndBit is less than StartBit, then ASSERT().
4561 @param Operand Operand on which to perform the bitfield operation.
4562 @param StartBit The ordinal of the least significant bit in the bit field.
4564 @param EndBit The ordinal of the most significant bit in the bit field.
4567 @return The bit field read.
4580 Writes a bit field to a 64-bit value, and returns the result.
4582 Writes Value to the bit field specified by the StartBit and the EndBit in
4583 Operand. All other bits in Operand are preserved. The new 64-bit value is
4586 If 64-bit operations are not supported, then ASSERT().
4587 If StartBit is greater than 63, then ASSERT().
4588 If EndBit is greater than 63, then ASSERT().
4589 If EndBit is less than StartBit, then ASSERT().
4590 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4592 @param Operand Operand on which to perform the bitfield operation.
4593 @param StartBit The ordinal of the least significant bit in the bit field.
4595 @param EndBit The ordinal of the most significant bit in the bit field.
4597 @param Value New value of the bit field.
4599 @return The new 64-bit value.
4613 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4616 Performs a bitwise OR between the bit field specified by StartBit
4617 and EndBit in Operand and the value specified by OrData. All other bits in
4618 Operand are preserved. The new 64-bit value is returned.
4620 If 64-bit operations are not supported, then ASSERT().
4621 If StartBit is greater than 63, then ASSERT().
4622 If EndBit is greater than 63, then ASSERT().
4623 If EndBit is less than StartBit, then ASSERT().
4624 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4626 @param Operand Operand on which to perform the bitfield operation.
4627 @param StartBit The ordinal of the least significant bit in the bit field.
4629 @param EndBit The ordinal of the most significant bit in the bit field.
4631 @param OrData The value to OR with the read value from the value
4633 @return The new 64-bit value.
4647 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4650 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4651 in Operand and the value specified by AndData. All other bits in Operand are
4652 preserved. The new 64-bit value is returned.
4654 If 64-bit operations are not supported, then ASSERT().
4655 If StartBit is greater than 63, then ASSERT().
4656 If EndBit is greater than 63, then ASSERT().
4657 If EndBit is less than StartBit, then ASSERT().
4658 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4660 @param Operand Operand on which to perform the bitfield operation.
4661 @param StartBit The ordinal of the least significant bit in the bit field.
4663 @param EndBit The ordinal of the most significant bit in the bit field.
4665 @param AndData The value to AND with the read value from the value
4667 @return The new 64-bit value.
4681 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4682 bitwise OR, and returns the result.
4684 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4685 in Operand and the value specified by AndData, followed by a bitwise
4686 OR with value specified by OrData. All other bits in Operand are
4687 preserved. The new 64-bit value is returned.
4689 If 64-bit operations are not supported, then ASSERT().
4690 If StartBit is greater than 63, then ASSERT().
4691 If EndBit is greater than 63, then ASSERT().
4692 If EndBit is less than StartBit, then ASSERT().
4693 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4694 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4696 @param Operand Operand on which to perform the bitfield operation.
4697 @param StartBit The ordinal of the least significant bit in the bit field.
4699 @param EndBit The ordinal of the most significant bit in the bit field.
4701 @param AndData The value to AND with the read value from the value.
4702 @param OrData The value to OR with the result of the AND operation.
4704 @return The new 64-bit value.
4709 BitFieldAndThenOr64 (
4718 Reads a bit field from a 32-bit value, counts and returns
4719 the number of set bits.
4721 Counts the number of set bits in the bit field specified by
4722 StartBit and EndBit in Operand. The count is returned.
4724 If StartBit is greater than 31, then ASSERT().
4725 If EndBit is greater than 31, then ASSERT().
4726 If EndBit is less than StartBit, then ASSERT().
4728 @param Operand Operand on which to perform the bitfield operation.
4729 @param StartBit The ordinal of the least significant bit in the bit field.
4731 @param EndBit The ordinal of the most significant bit in the bit field.
4734 @return The number of bits set between StartBit and EndBit.
4739 BitFieldCountOnes32 (
4746 Reads a bit field from a 64-bit value, counts and returns
4747 the number of set bits.
4749 Counts the number of set bits in the bit field specified by
4750 StartBit and EndBit in Operand. The count is returned.
4752 If StartBit is greater than 63, then ASSERT().
4753 If EndBit is greater than 63, then ASSERT().
4754 If EndBit is less than StartBit, then ASSERT().
4756 @param Operand Operand on which to perform the bitfield operation.
4757 @param StartBit The ordinal of the least significant bit in the bit field.
4759 @param EndBit The ordinal of the most significant bit in the bit field.
4762 @return The number of bits set between StartBit and EndBit.
4767 BitFieldCountOnes64 (
4774 // Base Library Checksum Functions
4778 Returns the sum of all elements in a buffer in unit of UINT8.
4779 During calculation, the carry bits are dropped.
4781 This function calculates the sum of all elements in a buffer
4782 in unit of UINT8. The carry bits in result of addition are dropped.
4783 The result is returned as UINT8. If Length is Zero, then Zero is
4786 If Buffer is NULL, then ASSERT().
4787 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4789 @param Buffer The pointer to the buffer to carry out the sum operation.
4790 @param Length The size, in bytes, of Buffer.
4792 @return Sum The sum of Buffer with carry bits dropped during additions.
4798 IN CONST UINT8
*Buffer
,
4804 Returns the two's complement checksum of all elements in a buffer
4807 This function first calculates the sum of the 8-bit values in the
4808 buffer specified by Buffer and Length. The carry bits in the result
4809 of addition are dropped. Then, the two's complement of the sum is
4810 returned. If Length is 0, then 0 is returned.
4812 If Buffer is NULL, then ASSERT().
4813 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4815 @param Buffer The pointer to the buffer to carry out the checksum operation.
4816 @param Length The size, in bytes, of Buffer.
4818 @return Checksum The two's complement checksum of Buffer.
4823 CalculateCheckSum8 (
4824 IN CONST UINT8
*Buffer
,
4830 Returns the sum of all elements in a buffer of 16-bit values. During
4831 calculation, the carry bits are dropped.
4833 This function calculates the sum of the 16-bit values in the buffer
4834 specified by Buffer and Length. The carry bits in result of addition are dropped.
4835 The 16-bit result is returned. If Length is 0, then 0 is returned.
4837 If Buffer is NULL, then ASSERT().
4838 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4839 If Length is not aligned on a 16-bit boundary, then ASSERT().
4840 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4842 @param Buffer The pointer to the buffer to carry out the sum operation.
4843 @param Length The size, in bytes, of Buffer.
4845 @return Sum The sum of Buffer with carry bits dropped during additions.
4851 IN CONST UINT16
*Buffer
,
4857 Returns the two's complement checksum of all elements in a buffer of
4860 This function first calculates the sum of the 16-bit values in the buffer
4861 specified by Buffer and Length. The carry bits in the result of addition
4862 are dropped. Then, the two's complement of the sum is returned. If Length
4863 is 0, then 0 is returned.
4865 If Buffer is NULL, then ASSERT().
4866 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4867 If Length is not aligned on a 16-bit boundary, then ASSERT().
4868 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4870 @param Buffer The pointer to the buffer to carry out the checksum operation.
4871 @param Length The size, in bytes, of Buffer.
4873 @return Checksum The two's complement checksum of Buffer.
4878 CalculateCheckSum16 (
4879 IN CONST UINT16
*Buffer
,
4885 Returns the sum of all elements in a buffer of 32-bit values. During
4886 calculation, the carry bits are dropped.
4888 This function calculates the sum of the 32-bit values in the buffer
4889 specified by Buffer and Length. The carry bits in result of addition are dropped.
4890 The 32-bit result is returned. If Length is 0, then 0 is returned.
4892 If Buffer is NULL, then ASSERT().
4893 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4894 If Length is not aligned on a 32-bit boundary, then ASSERT().
4895 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4897 @param Buffer The pointer to the buffer to carry out the sum operation.
4898 @param Length The size, in bytes, of Buffer.
4900 @return Sum The sum of Buffer with carry bits dropped during additions.
4906 IN CONST UINT32
*Buffer
,
4912 Returns the two's complement checksum of all elements in a buffer of
4915 This function first calculates the sum of the 32-bit values in the buffer
4916 specified by Buffer and Length. The carry bits in the result of addition
4917 are dropped. Then, the two's complement of the sum is returned. If Length
4918 is 0, then 0 is returned.
4920 If Buffer is NULL, then ASSERT().
4921 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4922 If Length is not aligned on a 32-bit boundary, then ASSERT().
4923 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4925 @param Buffer The pointer to the buffer to carry out the checksum operation.
4926 @param Length The size, in bytes, of Buffer.
4928 @return Checksum The two's complement checksum of Buffer.
4933 CalculateCheckSum32 (
4934 IN CONST UINT32
*Buffer
,
4940 Returns the sum of all elements in a buffer of 64-bit values. During
4941 calculation, the carry bits are dropped.
4943 This function calculates the sum of the 64-bit values in the buffer
4944 specified by Buffer and Length. The carry bits in result of addition are dropped.
4945 The 64-bit result is returned. If Length is 0, then 0 is returned.
4947 If Buffer is NULL, then ASSERT().
4948 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4949 If Length is not aligned on a 64-bit boundary, then ASSERT().
4950 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4952 @param Buffer The pointer to the buffer to carry out the sum operation.
4953 @param Length The size, in bytes, of Buffer.
4955 @return Sum The sum of Buffer with carry bits dropped during additions.
4961 IN CONST UINT64
*Buffer
,
4967 Returns the two's complement checksum of all elements in a buffer of
4970 This function first calculates the sum of the 64-bit values in the buffer
4971 specified by Buffer and Length. The carry bits in the result of addition
4972 are dropped. Then, the two's complement of the sum is returned. If Length
4973 is 0, then 0 is returned.
4975 If Buffer is NULL, then ASSERT().
4976 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4977 If Length is not aligned on a 64-bit boundary, then ASSERT().
4978 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4980 @param Buffer The pointer to the buffer to carry out the checksum operation.
4981 @param Length The size, in bytes, of Buffer.
4983 @return Checksum The two's complement checksum of Buffer.
4988 CalculateCheckSum64 (
4989 IN CONST UINT64
*Buffer
,
4994 Computes and returns a 32-bit CRC for a data buffer.
4995 CRC32 value bases on ITU-T V.42.
4997 If Buffer is NULL, then ASSERT().
4998 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
5000 @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed.
5001 @param[in] Length The number of bytes in the buffer Data.
5003 @retval Crc32 The 32-bit CRC was computed for the data buffer.
5014 // Base Library CPU Functions
5018 Function entry point used when a stack switch is requested with SwitchStack()
5020 @param Context1 Context1 parameter passed into SwitchStack().
5021 @param Context2 Context2 parameter passed into SwitchStack().
5026 (EFIAPI
*SWITCH_STACK_ENTRY_POINT
)(
5027 IN VOID
*Context1
, OPTIONAL
5028 IN VOID
*Context2 OPTIONAL
5033 Used to serialize load and store operations.
5035 All loads and stores that proceed calls to this function are guaranteed to be
5036 globally visible when this function returns.
5047 Saves the current CPU context that can be restored with a call to LongJump()
5050 Saves the current CPU context in the buffer specified by JumpBuffer and
5051 returns 0. The initial call to SetJump() must always return 0. Subsequent
5052 calls to LongJump() cause a non-zero value to be returned by SetJump().
5054 If JumpBuffer is NULL, then ASSERT().
5055 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
5057 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
5058 The same structure must never be used for more than one CPU architecture context.
5059 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
5060 SetJump()/LongJump() is not currently supported for the EBC processor type.
5062 @param JumpBuffer A pointer to CPU context buffer.
5064 @retval 0 Indicates a return from SetJump().
5071 OUT BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
5076 Restores the CPU context that was saved with SetJump().
5078 Restores the CPU context from the buffer specified by JumpBuffer. This
5079 function never returns to the caller. Instead is resumes execution based on
5080 the state of JumpBuffer.
5082 If JumpBuffer is NULL, then ASSERT().
5083 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
5084 If Value is 0, then ASSERT().
5086 @param JumpBuffer A pointer to CPU context buffer.
5087 @param Value The value to return when the SetJump() context is
5088 restored and must be non-zero.
5094 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
5100 Enables CPU interrupts.
5111 Disables CPU interrupts.
5122 Disables CPU interrupts and returns the interrupt state prior to the disable
5125 @retval TRUE CPU interrupts were enabled on entry to this call.
5126 @retval FALSE CPU interrupts were disabled on entry to this call.
5131 SaveAndDisableInterrupts (
5137 Enables CPU interrupts for the smallest window required to capture any
5143 EnableDisableInterrupts (
5149 Retrieves the current CPU interrupt state.
5151 Returns TRUE if interrupts are currently enabled. Otherwise
5154 @retval TRUE CPU interrupts are enabled.
5155 @retval FALSE CPU interrupts are disabled.
5166 Set the current CPU interrupt state.
5168 Sets the current CPU interrupt state to the state specified by
5169 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
5170 InterruptState is FALSE, then interrupts are disabled. InterruptState is
5173 @param InterruptState TRUE if interrupts should enabled. FALSE if
5174 interrupts should be disabled.
5176 @return InterruptState
5182 IN BOOLEAN InterruptState
5187 Requests CPU to pause for a short period of time.
5189 Requests CPU to pause for a short period of time. Typically used in MP
5190 systems to prevent memory starvation while waiting for a spin lock.
5201 Transfers control to a function starting with a new stack.
5203 Transfers control to the function specified by EntryPoint using the
5204 new stack specified by NewStack and passing in the parameters specified
5205 by Context1 and Context2. Context1 and Context2 are optional and may
5206 be NULL. The function EntryPoint must never return. This function
5207 supports a variable number of arguments following the NewStack parameter.
5208 These additional arguments are ignored on IA-32, x64, and EBC architectures.
5209 Itanium processors expect one additional parameter of type VOID * that specifies
5210 the new backing store pointer.
5212 If EntryPoint is NULL, then ASSERT().
5213 If NewStack is NULL, then ASSERT().
5215 @param EntryPoint A pointer to function to call with the new stack.
5216 @param Context1 A pointer to the context to pass into the EntryPoint
5218 @param Context2 A pointer to the context to pass into the EntryPoint
5220 @param NewStack A pointer to the new stack to use for the EntryPoint
5222 @param ... This variable argument list is ignored for IA-32, x64, and
5223 EBC architectures. For Itanium processors, this variable
5224 argument list is expected to contain a single parameter of
5225 type VOID * that specifies the new backing store pointer.
5232 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
5233 IN VOID
*Context1
, OPTIONAL
5234 IN VOID
*Context2
, OPTIONAL
5241 Generates a breakpoint on the CPU.
5243 Generates a breakpoint on the CPU. The breakpoint must be implemented such
5244 that code can resume normal execution after the breakpoint.
5255 Executes an infinite loop.
5257 Forces the CPU to execute an infinite loop. A debugger may be used to skip
5258 past the loop and the code that follows the loop must execute properly. This
5259 implies that the infinite loop must not cause the code that follow it to be
5271 Uses as a barrier to stop speculative execution.
5273 Ensures that no later instruction will execute speculatively, until all prior
5274 instructions have completed.
5279 SpeculationBarrier (
5284 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
5286 /// IA32 and x64 Specific Functions.
5287 /// Byte packed structure for 16-bit Real Mode EFLAGS.
5291 UINT32 CF
:1; ///< Carry Flag.
5292 UINT32 Reserved_0
:1; ///< Reserved.
5293 UINT32 PF
:1; ///< Parity Flag.
5294 UINT32 Reserved_1
:1; ///< Reserved.
5295 UINT32 AF
:1; ///< Auxiliary Carry Flag.
5296 UINT32 Reserved_2
:1; ///< Reserved.
5297 UINT32 ZF
:1; ///< Zero Flag.
5298 UINT32 SF
:1; ///< Sign Flag.
5299 UINT32 TF
:1; ///< Trap Flag.
5300 UINT32 IF
:1; ///< Interrupt Enable Flag.
5301 UINT32 DF
:1; ///< Direction Flag.
5302 UINT32 OF
:1; ///< Overflow Flag.
5303 UINT32 IOPL
:2; ///< I/O Privilege Level.
5304 UINT32 NT
:1; ///< Nested Task.
5305 UINT32 Reserved_3
:1; ///< Reserved.
5311 /// Byte packed structure for EFLAGS/RFLAGS.
5312 /// 32-bits on IA-32.
5313 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5317 UINT32 CF
:1; ///< Carry Flag.
5318 UINT32 Reserved_0
:1; ///< Reserved.
5319 UINT32 PF
:1; ///< Parity Flag.
5320 UINT32 Reserved_1
:1; ///< Reserved.
5321 UINT32 AF
:1; ///< Auxiliary Carry Flag.
5322 UINT32 Reserved_2
:1; ///< Reserved.
5323 UINT32 ZF
:1; ///< Zero Flag.
5324 UINT32 SF
:1; ///< Sign Flag.
5325 UINT32 TF
:1; ///< Trap Flag.
5326 UINT32 IF
:1; ///< Interrupt Enable Flag.
5327 UINT32 DF
:1; ///< Direction Flag.
5328 UINT32 OF
:1; ///< Overflow Flag.
5329 UINT32 IOPL
:2; ///< I/O Privilege Level.
5330 UINT32 NT
:1; ///< Nested Task.
5331 UINT32 Reserved_3
:1; ///< Reserved.
5332 UINT32 RF
:1; ///< Resume Flag.
5333 UINT32 VM
:1; ///< Virtual 8086 Mode.
5334 UINT32 AC
:1; ///< Alignment Check.
5335 UINT32 VIF
:1; ///< Virtual Interrupt Flag.
5336 UINT32 VIP
:1; ///< Virtual Interrupt Pending.
5337 UINT32 ID
:1; ///< ID Flag.
5338 UINT32 Reserved_4
:10; ///< Reserved.
5344 /// Byte packed structure for Control Register 0 (CR0).
5345 /// 32-bits on IA-32.
5346 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5350 UINT32 PE
:1; ///< Protection Enable.
5351 UINT32 MP
:1; ///< Monitor Coprocessor.
5352 UINT32 EM
:1; ///< Emulation.
5353 UINT32 TS
:1; ///< Task Switched.
5354 UINT32 ET
:1; ///< Extension Type.
5355 UINT32 NE
:1; ///< Numeric Error.
5356 UINT32 Reserved_0
:10; ///< Reserved.
5357 UINT32 WP
:1; ///< Write Protect.
5358 UINT32 Reserved_1
:1; ///< Reserved.
5359 UINT32 AM
:1; ///< Alignment Mask.
5360 UINT32 Reserved_2
:10; ///< Reserved.
5361 UINT32 NW
:1; ///< Mot Write-through.
5362 UINT32 CD
:1; ///< Cache Disable.
5363 UINT32 PG
:1; ///< Paging.
5369 /// Byte packed structure for Control Register 4 (CR4).
5370 /// 32-bits on IA-32.
5371 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5375 UINT32 VME
:1; ///< Virtual-8086 Mode Extensions.
5376 UINT32 PVI
:1; ///< Protected-Mode Virtual Interrupts.
5377 UINT32 TSD
:1; ///< Time Stamp Disable.
5378 UINT32 DE
:1; ///< Debugging Extensions.
5379 UINT32 PSE
:1; ///< Page Size Extensions.
5380 UINT32 PAE
:1; ///< Physical Address Extension.
5381 UINT32 MCE
:1; ///< Machine Check Enable.
5382 UINT32 PGE
:1; ///< Page Global Enable.
5383 UINT32 PCE
:1; ///< Performance Monitoring Counter
5385 UINT32 OSFXSR
:1; ///< Operating System Support for
5386 ///< FXSAVE and FXRSTOR instructions
5387 UINT32 OSXMMEXCPT
:1; ///< Operating System Support for
5388 ///< Unmasked SIMD Floating Point
5390 UINT32 Reserved_2
:1; ///< Reserved.
5391 UINT32 LA57
:1; ///< Linear Address 57bit.
5392 UINT32 VMXE
:1; ///< VMX Enable
5393 UINT32 Reserved_1
:18; ///< Reserved.
5399 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5418 } IA32_SEGMENT_DESCRIPTOR
;
5421 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5430 #define IA32_IDT_GATE_TYPE_TASK 0x85
5431 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5432 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5433 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5434 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5436 #define IA32_GDT_TYPE_TSS 0x9
5437 #define IA32_GDT_ALIGNMENT 8
5439 #if defined (MDE_CPU_IA32)
5441 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5445 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5446 UINT32 Selector
:16; ///< Selector.
5447 UINT32 Reserved_0
:8; ///< Reserved.
5448 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5449 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5452 } IA32_IDT_GATE_DESCRIPTOR
;
5456 // IA32 Task-State Segment Definition
5459 UINT16 PreviousTaskLink
;
5493 UINT16 LDTSegmentSelector
;
5496 UINT16 IOMapBaseAddress
;
5497 } IA32_TASK_STATE_SEGMENT
;
5501 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5502 UINT32 BaseLow
:16; ///< Base Address 15..00
5503 UINT32 BaseMid
:8; ///< Base Address 23..16
5504 UINT32 Type
:4; ///< Type (1 0 B 1)
5505 UINT32 Reserved_43
:1; ///< 0
5506 UINT32 DPL
:2; ///< Descriptor Privilege Level
5507 UINT32 P
:1; ///< Segment Present
5508 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5509 UINT32 AVL
:1; ///< Available for use by system software
5510 UINT32 Reserved_52
:2; ///< 0 0
5511 UINT32 G
:1; ///< Granularity
5512 UINT32 BaseHigh
:8; ///< Base Address 31..24
5515 } IA32_TSS_DESCRIPTOR
;
5518 #endif // defined (MDE_CPU_IA32)
5520 #if defined (MDE_CPU_X64)
5522 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5526 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5527 UINT32 Selector
:16; ///< Selector.
5528 UINT32 Reserved_0
:8; ///< Reserved.
5529 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5530 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5531 UINT32 OffsetUpper
:32; ///< Offset bits 63..32.
5532 UINT32 Reserved_1
:32; ///< Reserved.
5538 } IA32_IDT_GATE_DESCRIPTOR
;
5542 // IA32 Task-State Segment Definition
5552 UINT16 Reserved_100
;
5553 UINT16 IOMapBaseAddress
;
5554 } IA32_TASK_STATE_SEGMENT
;
5558 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5559 UINT32 BaseLow
:16; ///< Base Address 15..00
5560 UINT32 BaseMidl
:8; ///< Base Address 23..16
5561 UINT32 Type
:4; ///< Type (1 0 B 1)
5562 UINT32 Reserved_43
:1; ///< 0
5563 UINT32 DPL
:2; ///< Descriptor Privilege Level
5564 UINT32 P
:1; ///< Segment Present
5565 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5566 UINT32 AVL
:1; ///< Available for use by system software
5567 UINT32 Reserved_52
:2; ///< 0 0
5568 UINT32 G
:1; ///< Granularity
5569 UINT32 BaseMidh
:8; ///< Base Address 31..24
5570 UINT32 BaseHigh
:32; ///< Base Address 63..32
5571 UINT32 Reserved_96
:32; ///< Reserved
5577 } IA32_TSS_DESCRIPTOR
;
5580 #endif // defined (MDE_CPU_X64)
5583 /// Byte packed structure for an FP/SSE/SSE2 context.
5590 /// Structures for the 16-bit real mode thunks.
5643 IA32_EFLAGS32 EFLAGS
;
5653 } IA32_REGISTER_SET
;
5656 /// Byte packed structure for an 16-bit real mode thunks.
5659 IA32_REGISTER_SET
*RealModeState
;
5660 VOID
*RealModeBuffer
;
5661 UINT32 RealModeBufferSize
;
5662 UINT32 ThunkAttributes
;
5665 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5666 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5667 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5670 /// Type definition for representing labels in NASM source code that allow for
5671 /// the patching of immediate operands of IA32 and X64 instructions.
5673 /// While the type is technically defined as a function type (note: not a
5674 /// pointer-to-function type), such labels in NASM source code never stand for
5675 /// actual functions, and identifiers declared with this function type should
5676 /// never be called. This is also why the EFIAPI calling convention specifier
5677 /// is missing from the typedef, and why the typedef does not follow the usual
5678 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5679 /// return type and the VOID argument list are merely artifacts.
5681 typedef VOID (X86_ASSEMBLY_PATCH_LABEL
) (VOID
);
5684 Retrieves CPUID information.
5686 Executes the CPUID instruction with EAX set to the value specified by Index.
5687 This function always returns Index.
5688 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5689 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5690 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5691 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5692 This function is only available on IA-32 and x64.
5694 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5696 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5697 instruction. This is an optional parameter that may be NULL.
5698 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5699 instruction. This is an optional parameter that may be NULL.
5700 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5701 instruction. This is an optional parameter that may be NULL.
5702 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5703 instruction. This is an optional parameter that may be NULL.
5712 OUT UINT32
*Eax
, OPTIONAL
5713 OUT UINT32
*Ebx
, OPTIONAL
5714 OUT UINT32
*Ecx
, OPTIONAL
5715 OUT UINT32
*Edx OPTIONAL
5720 Retrieves CPUID information using an extended leaf identifier.
5722 Executes the CPUID instruction with EAX set to the value specified by Index
5723 and ECX set to the value specified by SubIndex. This function always returns
5724 Index. This function is only available on IA-32 and x64.
5726 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5727 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5728 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5729 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5731 @param Index The 32-bit value to load into EAX prior to invoking the
5733 @param SubIndex The 32-bit value to load into ECX prior to invoking the
5735 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5736 instruction. This is an optional parameter that may be
5738 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5739 instruction. This is an optional parameter that may be
5741 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5742 instruction. This is an optional parameter that may be
5744 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5745 instruction. This is an optional parameter that may be
5756 OUT UINT32
*Eax
, OPTIONAL
5757 OUT UINT32
*Ebx
, OPTIONAL
5758 OUT UINT32
*Ecx
, OPTIONAL
5759 OUT UINT32
*Edx OPTIONAL
5764 Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5766 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5767 and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5778 Perform a WBINVD and clear both the CD and NW bits of CR0.
5780 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5781 bits of CR0 to 0. This function is only available on IA-32 and x64.
5792 Returns the lower 32-bits of a Machine Specific Register(MSR).
5794 Reads and returns the lower 32-bits of the MSR specified by Index.
5795 No parameter checking is performed on Index, and some Index values may cause
5796 CPU exceptions. The caller must either guarantee that Index is valid, or the
5797 caller must set up exception handlers to catch the exceptions. This function
5798 is only available on IA-32 and x64.
5800 @param Index The 32-bit MSR index to read.
5802 @return The lower 32 bits of the MSR identified by Index.
5813 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5814 The upper 32-bits of the MSR are set to zero.
5816 Writes the 32-bit value specified by Value to the MSR specified by Index. The
5817 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5818 the MSR is returned. No parameter checking is performed on Index or Value,
5819 and some of these may cause CPU exceptions. The caller must either guarantee
5820 that Index and Value are valid, or the caller must establish proper exception
5821 handlers. This function is only available on IA-32 and x64.
5823 @param Index The 32-bit MSR index to write.
5824 @param Value The 32-bit value to write to the MSR.
5838 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5839 writes the result back to the 64-bit MSR.
5841 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5842 between the lower 32-bits of the read result and the value specified by
5843 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5844 32-bits of the value written to the MSR is returned. No parameter checking is
5845 performed on Index or OrData, and some of these may cause CPU exceptions. The
5846 caller must either guarantee that Index and OrData are valid, or the caller
5847 must establish proper exception handlers. This function is only available on
5850 @param Index The 32-bit MSR index to write.
5851 @param OrData The value to OR with the read value from the MSR.
5853 @return The lower 32-bit value written to the MSR.
5865 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5866 the result back to the 64-bit MSR.
5868 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5869 lower 32-bits of the read result and the value specified by AndData, and
5870 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5871 the value written to the MSR is returned. No parameter checking is performed
5872 on Index or AndData, and some of these may cause CPU exceptions. The caller
5873 must either guarantee that Index and AndData are valid, or the caller must
5874 establish proper exception handlers. This function is only available on IA-32
5877 @param Index The 32-bit MSR index to write.
5878 @param AndData The value to AND with the read value from the MSR.
5880 @return The lower 32-bit value written to the MSR.
5892 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5893 on the lower 32-bits, and writes the result back to the 64-bit MSR.
5895 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5896 lower 32-bits of the read result and the value specified by AndData
5897 preserving the upper 32-bits, performs a bitwise OR between the
5898 result of the AND operation and the value specified by OrData, and writes the
5899 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5900 written to the MSR is returned. No parameter checking is performed on Index,
5901 AndData, or OrData, and some of these may cause CPU exceptions. The caller
5902 must either guarantee that Index, AndData, and OrData are valid, or the
5903 caller must establish proper exception handlers. This function is only
5904 available on IA-32 and x64.
5906 @param Index The 32-bit MSR index to write.
5907 @param AndData The value to AND with the read value from the MSR.
5908 @param OrData The value to OR with the result of the AND operation.
5910 @return The lower 32-bit value written to the MSR.
5923 Reads a bit field of an MSR.
5925 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5926 specified by the StartBit and the EndBit. The value of the bit field is
5927 returned. The caller must either guarantee that Index is valid, or the caller
5928 must set up exception handlers to catch the exceptions. This function is only
5929 available on IA-32 and x64.
5931 If StartBit is greater than 31, then ASSERT().
5932 If EndBit is greater than 31, then ASSERT().
5933 If EndBit is less than StartBit, then ASSERT().
5935 @param Index The 32-bit MSR index to read.
5936 @param StartBit The ordinal of the least significant bit in the bit field.
5938 @param EndBit The ordinal of the most significant bit in the bit field.
5941 @return The bit field read from the MSR.
5946 AsmMsrBitFieldRead32 (
5954 Writes a bit field to an MSR.
5956 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5957 field is specified by the StartBit and the EndBit. All other bits in the
5958 destination MSR are preserved. The lower 32-bits of the MSR written is
5959 returned. The caller must either guarantee that Index and the data written
5960 is valid, or the caller must set up exception handlers to catch the exceptions.
5961 This function is only available on IA-32 and x64.
5963 If StartBit is greater than 31, then ASSERT().
5964 If EndBit is greater than 31, then ASSERT().
5965 If EndBit is less than StartBit, then ASSERT().
5966 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5968 @param Index The 32-bit MSR index to write.
5969 @param StartBit The ordinal of the least significant bit in the bit field.
5971 @param EndBit The ordinal of the most significant bit in the bit field.
5973 @param Value New value of the bit field.
5975 @return The lower 32-bit of the value written to the MSR.
5980 AsmMsrBitFieldWrite32 (
5989 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5990 result back to the bit field in the 64-bit MSR.
5992 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5993 between the read result and the value specified by OrData, and writes the
5994 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
5995 written to the MSR are returned. Extra left bits in OrData are stripped. The
5996 caller must either guarantee that Index and the data written is valid, or
5997 the caller must set up exception handlers to catch the exceptions. This
5998 function is only available on IA-32 and x64.
6000 If StartBit is greater than 31, then ASSERT().
6001 If EndBit is greater than 31, then ASSERT().
6002 If EndBit is less than StartBit, then ASSERT().
6003 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6005 @param Index The 32-bit MSR index to write.
6006 @param StartBit The ordinal of the least significant bit in the bit field.
6008 @param EndBit The ordinal of the most significant bit in the bit field.
6010 @param OrData The value to OR with the read value from the MSR.
6012 @return The lower 32-bit of the value written to the MSR.
6017 AsmMsrBitFieldOr32 (
6026 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6027 result back to the bit field in the 64-bit MSR.
6029 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6030 read result and the value specified by AndData, and writes the result to the
6031 64-bit MSR specified by Index. The lower 32-bits of the value written to the
6032 MSR are returned. Extra left bits in AndData are stripped. The caller must
6033 either guarantee that Index and the data written is valid, or the caller must
6034 set up exception handlers to catch the exceptions. This function is only
6035 available on IA-32 and x64.
6037 If StartBit is greater than 31, then ASSERT().
6038 If EndBit is greater than 31, then ASSERT().
6039 If EndBit is less than StartBit, then ASSERT().
6040 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6042 @param Index The 32-bit MSR index to write.
6043 @param StartBit The ordinal of the least significant bit in the bit field.
6045 @param EndBit The ordinal of the most significant bit in the bit field.
6047 @param AndData The value to AND with the read value from the MSR.
6049 @return The lower 32-bit of the value written to the MSR.
6054 AsmMsrBitFieldAnd32 (
6063 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6064 bitwise OR, and writes the result back to the bit field in the
6067 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
6068 bitwise OR between the read result and the value specified by
6069 AndData, and writes the result to the 64-bit MSR specified by Index. The
6070 lower 32-bits of the value written to the MSR are returned. Extra left bits
6071 in both AndData and OrData are stripped. The caller must either guarantee
6072 that Index and the data written is valid, or the caller must set up exception
6073 handlers to catch the exceptions. This function is only available on IA-32
6076 If StartBit is greater than 31, then ASSERT().
6077 If EndBit is greater than 31, then ASSERT().
6078 If EndBit is less than StartBit, then ASSERT().
6079 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6080 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6082 @param Index The 32-bit MSR index to write.
6083 @param StartBit The ordinal of the least significant bit in the bit field.
6085 @param EndBit The ordinal of the most significant bit in the bit field.
6087 @param AndData The value to AND with the read value from the MSR.
6088 @param OrData The value to OR with the result of the AND operation.
6090 @return The lower 32-bit of the value written to the MSR.
6095 AsmMsrBitFieldAndThenOr32 (
6105 Returns a 64-bit Machine Specific Register(MSR).
6107 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
6108 performed on Index, and some Index values may cause CPU exceptions. The
6109 caller must either guarantee that Index is valid, or the caller must set up
6110 exception handlers to catch the exceptions. This function is only available
6113 @param Index The 32-bit MSR index to read.
6115 @return The value of the MSR identified by Index.
6126 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
6129 Writes the 64-bit value specified by Value to the MSR specified by Index. The
6130 64-bit value written to the MSR is returned. No parameter checking is
6131 performed on Index or Value, and some of these may cause CPU exceptions. The
6132 caller must either guarantee that Index and Value are valid, or the caller
6133 must establish proper exception handlers. This function is only available on
6136 @param Index The 32-bit MSR index to write.
6137 @param Value The 64-bit value to write to the MSR.
6151 Reads a 64-bit MSR, performs a bitwise OR, and writes the result
6152 back to the 64-bit MSR.
6154 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6155 between the read result and the value specified by OrData, and writes the
6156 result to the 64-bit MSR specified by Index. The value written to the MSR is
6157 returned. No parameter checking is performed on Index or OrData, and some of
6158 these may cause CPU exceptions. The caller must either guarantee that Index
6159 and OrData are valid, or the caller must establish proper exception handlers.
6160 This function is only available on IA-32 and x64.
6162 @param Index The 32-bit MSR index to write.
6163 @param OrData The value to OR with the read value from the MSR.
6165 @return The value written back to the MSR.
6177 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
6180 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6181 read result and the value specified by OrData, and writes the result to the
6182 64-bit MSR specified by Index. The value written to the MSR is returned. No
6183 parameter checking is performed on Index or OrData, and some of these may
6184 cause CPU exceptions. The caller must either guarantee that Index and OrData
6185 are valid, or the caller must establish proper exception handlers. This
6186 function is only available on IA-32 and x64.
6188 @param Index The 32-bit MSR index to write.
6189 @param AndData The value to AND with the read value from the MSR.
6191 @return The value written back to the MSR.
6203 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
6204 OR, and writes the result back to the 64-bit MSR.
6206 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
6207 result and the value specified by AndData, performs a bitwise OR
6208 between the result of the AND operation and the value specified by OrData,
6209 and writes the result to the 64-bit MSR specified by Index. The value written
6210 to the MSR is returned. No parameter checking is performed on Index, AndData,
6211 or OrData, and some of these may cause CPU exceptions. The caller must either
6212 guarantee that Index, AndData, and OrData are valid, or the caller must
6213 establish proper exception handlers. This function is only available on IA-32
6216 @param Index The 32-bit MSR index to write.
6217 @param AndData The value to AND with the read value from the MSR.
6218 @param OrData The value to OR with the result of the AND operation.
6220 @return The value written back to the MSR.
6233 Reads a bit field of an MSR.
6235 Reads the bit field in the 64-bit MSR. The bit field is specified by the
6236 StartBit and the EndBit. The value of the bit field is returned. The caller
6237 must either guarantee that Index is valid, or the caller must set up
6238 exception handlers to catch the exceptions. This function is only available
6241 If StartBit is greater than 63, then ASSERT().
6242 If EndBit is greater than 63, then ASSERT().
6243 If EndBit is less than StartBit, then ASSERT().
6245 @param Index The 32-bit MSR index to read.
6246 @param StartBit The ordinal of the least significant bit in the bit field.
6248 @param EndBit The ordinal of the most significant bit in the bit field.
6251 @return The value read from the MSR.
6256 AsmMsrBitFieldRead64 (
6264 Writes a bit field to an MSR.
6266 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
6267 the StartBit and the EndBit. All other bits in the destination MSR are
6268 preserved. The MSR written is returned. The caller must either guarantee
6269 that Index and the data written is valid, or the caller must set up exception
6270 handlers to catch the exceptions. This function is only available on IA-32 and x64.
6272 If StartBit is greater than 63, then ASSERT().
6273 If EndBit is greater than 63, then ASSERT().
6274 If EndBit is less than StartBit, then ASSERT().
6275 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6277 @param Index The 32-bit MSR index to write.
6278 @param StartBit The ordinal of the least significant bit in the bit field.
6280 @param EndBit The ordinal of the most significant bit in the bit field.
6282 @param Value New value of the bit field.
6284 @return The value written back to the MSR.
6289 AsmMsrBitFieldWrite64 (
6298 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
6299 writes the result back to the bit field in the 64-bit MSR.
6301 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6302 between the read result and the value specified by OrData, and writes the
6303 result to the 64-bit MSR specified by Index. The value written to the MSR is
6304 returned. Extra left bits in OrData are stripped. The caller must either
6305 guarantee that Index and the data written is valid, or the caller must set up
6306 exception handlers to catch the exceptions. This function is only available
6309 If StartBit is greater than 63, then ASSERT().
6310 If EndBit is greater than 63, then ASSERT().
6311 If EndBit is less than StartBit, then ASSERT().
6312 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6314 @param Index The 32-bit MSR index to write.
6315 @param StartBit The ordinal of the least significant bit in the bit field.
6317 @param EndBit The ordinal of the most significant bit in the bit field.
6319 @param OrData The value to OR with the read value from the bit field.
6321 @return The value written back to the MSR.
6326 AsmMsrBitFieldOr64 (
6335 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6336 result back to the bit field in the 64-bit MSR.
6338 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6339 read result and the value specified by AndData, and writes the result to the
6340 64-bit MSR specified by Index. The value written to the MSR is returned.
6341 Extra left bits in AndData are stripped. The caller must either guarantee
6342 that Index and the data written is valid, or the caller must set up exception
6343 handlers to catch the exceptions. This function is only available on IA-32
6346 If StartBit is greater than 63, then ASSERT().
6347 If EndBit is greater than 63, then ASSERT().
6348 If EndBit is less than StartBit, then ASSERT().
6349 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6351 @param Index The 32-bit MSR index to write.
6352 @param StartBit The ordinal of the least significant bit in the bit field.
6354 @param EndBit The ordinal of the most significant bit in the bit field.
6356 @param AndData The value to AND with the read value from the bit field.
6358 @return The value written back to the MSR.
6363 AsmMsrBitFieldAnd64 (
6372 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6373 bitwise OR, and writes the result back to the bit field in the
6376 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6377 a bitwise OR between the read result and the value specified by
6378 AndData, and writes the result to the 64-bit MSR specified by Index. The
6379 value written to the MSR is returned. Extra left bits in both AndData and
6380 OrData are stripped. The caller must either guarantee that Index and the data
6381 written is valid, or the caller must set up exception handlers to catch the
6382 exceptions. This function is only available on IA-32 and x64.
6384 If StartBit is greater than 63, then ASSERT().
6385 If EndBit is greater than 63, then ASSERT().
6386 If EndBit is less than StartBit, then ASSERT().
6387 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6388 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6390 @param Index The 32-bit MSR index to write.
6391 @param StartBit The ordinal of the least significant bit in the bit field.
6393 @param EndBit The ordinal of the most significant bit in the bit field.
6395 @param AndData The value to AND with the read value from the bit field.
6396 @param OrData The value to OR with the result of the AND operation.
6398 @return The value written back to the MSR.
6403 AsmMsrBitFieldAndThenOr64 (
6413 Reads the current value of the EFLAGS register.
6415 Reads and returns the current value of the EFLAGS register. This function is
6416 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6417 64-bit value on x64.
6419 @return EFLAGS on IA-32 or RFLAGS on x64.
6430 Reads the current value of the Control Register 0 (CR0).
6432 Reads and returns the current value of CR0. This function is only available
6433 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6436 @return The value of the Control Register 0 (CR0).
6447 Reads the current value of the Control Register 2 (CR2).
6449 Reads and returns the current value of CR2. This function is only available
6450 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6453 @return The value of the Control Register 2 (CR2).
6464 Reads the current value of the Control Register 3 (CR3).
6466 Reads and returns the current value of CR3. This function is only available
6467 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6470 @return The value of the Control Register 3 (CR3).
6481 Reads the current value of the Control Register 4 (CR4).
6483 Reads and returns the current value of CR4. This function is only available
6484 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6487 @return The value of the Control Register 4 (CR4).
6498 Writes a value to Control Register 0 (CR0).
6500 Writes and returns a new value to CR0. This function is only available on
6501 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6503 @param Cr0 The value to write to CR0.
6505 @return The value written to CR0.
6516 Writes a value to Control Register 2 (CR2).
6518 Writes and returns a new value to CR2. This function is only available on
6519 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6521 @param Cr2 The value to write to CR2.
6523 @return The value written to CR2.
6534 Writes a value to Control Register 3 (CR3).
6536 Writes and returns a new value to CR3. This function is only available on
6537 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6539 @param Cr3 The value to write to CR3.
6541 @return The value written to CR3.
6552 Writes a value to Control Register 4 (CR4).
6554 Writes and returns a new value to CR4. This function is only available on
6555 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6557 @param Cr4 The value to write to CR4.
6559 @return The value written to CR4.
6570 Reads the current value of Debug Register 0 (DR0).
6572 Reads and returns the current value of DR0. This function is only available
6573 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6576 @return The value of Debug Register 0 (DR0).
6587 Reads the current value of Debug Register 1 (DR1).
6589 Reads and returns the current value of DR1. This function is only available
6590 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6593 @return The value of Debug Register 1 (DR1).
6604 Reads the current value of Debug Register 2 (DR2).
6606 Reads and returns the current value of DR2. This function is only available
6607 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6610 @return The value of Debug Register 2 (DR2).
6621 Reads the current value of Debug Register 3 (DR3).
6623 Reads and returns the current value of DR3. This function is only available
6624 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6627 @return The value of Debug Register 3 (DR3).
6638 Reads the current value of Debug Register 4 (DR4).
6640 Reads and returns the current value of DR4. This function is only available
6641 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6644 @return The value of Debug Register 4 (DR4).
6655 Reads the current value of Debug Register 5 (DR5).
6657 Reads and returns the current value of DR5. This function is only available
6658 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6661 @return The value of Debug Register 5 (DR5).
6672 Reads the current value of Debug Register 6 (DR6).
6674 Reads and returns the current value of DR6. This function is only available
6675 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6678 @return The value of Debug Register 6 (DR6).
6689 Reads the current value of Debug Register 7 (DR7).
6691 Reads and returns the current value of DR7. This function is only available
6692 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6695 @return The value of Debug Register 7 (DR7).
6706 Writes a value to Debug Register 0 (DR0).
6708 Writes and returns a new value to DR0. This function is only available on
6709 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6711 @param Dr0 The value to write to Dr0.
6713 @return The value written to Debug Register 0 (DR0).
6724 Writes a value to Debug Register 1 (DR1).
6726 Writes and returns a new value to DR1. This function is only available on
6727 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6729 @param Dr1 The value to write to Dr1.
6731 @return The value written to Debug Register 1 (DR1).
6742 Writes a value to Debug Register 2 (DR2).
6744 Writes and returns a new value to DR2. This function is only available on
6745 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6747 @param Dr2 The value to write to Dr2.
6749 @return The value written to Debug Register 2 (DR2).
6760 Writes a value to Debug Register 3 (DR3).
6762 Writes and returns a new value to DR3. This function is only available on
6763 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6765 @param Dr3 The value to write to Dr3.
6767 @return The value written to Debug Register 3 (DR3).
6778 Writes a value to Debug Register 4 (DR4).
6780 Writes and returns a new value to DR4. This function is only available on
6781 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6783 @param Dr4 The value to write to Dr4.
6785 @return The value written to Debug Register 4 (DR4).
6796 Writes a value to Debug Register 5 (DR5).
6798 Writes and returns a new value to DR5. This function is only available on
6799 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6801 @param Dr5 The value to write to Dr5.
6803 @return The value written to Debug Register 5 (DR5).
6814 Writes a value to Debug Register 6 (DR6).
6816 Writes and returns a new value to DR6. This function is only available on
6817 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6819 @param Dr6 The value to write to Dr6.
6821 @return The value written to Debug Register 6 (DR6).
6832 Writes a value to Debug Register 7 (DR7).
6834 Writes and returns a new value to DR7. This function is only available on
6835 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6837 @param Dr7 The value to write to Dr7.
6839 @return The value written to Debug Register 7 (DR7).
6850 Reads the current value of Code Segment Register (CS).
6852 Reads and returns the current value of CS. This function is only available on
6855 @return The current value of CS.
6866 Reads the current value of Data Segment Register (DS).
6868 Reads and returns the current value of DS. This function is only available on
6871 @return The current value of DS.
6882 Reads the current value of Extra Segment Register (ES).
6884 Reads and returns the current value of ES. This function is only available on
6887 @return The current value of ES.
6898 Reads the current value of FS Data Segment Register (FS).
6900 Reads and returns the current value of FS. This function is only available on
6903 @return The current value of FS.
6914 Reads the current value of GS Data Segment Register (GS).
6916 Reads and returns the current value of GS. This function is only available on
6919 @return The current value of GS.
6930 Reads the current value of Stack Segment Register (SS).
6932 Reads and returns the current value of SS. This function is only available on
6935 @return The current value of SS.
6946 Reads the current value of Task Register (TR).
6948 Reads and returns the current value of TR. This function is only available on
6951 @return The current value of TR.
6962 Reads the current Global Descriptor Table Register(GDTR) descriptor.
6964 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6965 function is only available on IA-32 and x64.
6967 If Gdtr is NULL, then ASSERT().
6969 @param Gdtr The pointer to a GDTR descriptor.
6975 OUT IA32_DESCRIPTOR
*Gdtr
6980 Writes the current Global Descriptor Table Register (GDTR) descriptor.
6982 Writes and the current GDTR descriptor specified by Gdtr. This function is
6983 only available on IA-32 and x64.
6985 If Gdtr is NULL, then ASSERT().
6987 @param Gdtr The pointer to a GDTR descriptor.
6993 IN CONST IA32_DESCRIPTOR
*Gdtr
6998 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
7000 Reads and returns the current IDTR descriptor and returns it in Idtr. This
7001 function is only available on IA-32 and x64.
7003 If Idtr is NULL, then ASSERT().
7005 @param Idtr The pointer to a IDTR descriptor.
7011 OUT IA32_DESCRIPTOR
*Idtr
7016 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
7018 Writes the current IDTR descriptor and returns it in Idtr. This function is
7019 only available on IA-32 and x64.
7021 If Idtr is NULL, then ASSERT().
7023 @param Idtr The pointer to a IDTR descriptor.
7029 IN CONST IA32_DESCRIPTOR
*Idtr
7034 Reads the current Local Descriptor Table Register(LDTR) selector.
7036 Reads and returns the current 16-bit LDTR descriptor value. This function is
7037 only available on IA-32 and x64.
7039 @return The current selector of LDT.
7050 Writes the current Local Descriptor Table Register (LDTR) selector.
7052 Writes and the current LDTR descriptor specified by Ldtr. This function is
7053 only available on IA-32 and x64.
7055 @param Ldtr 16-bit LDTR selector value.
7066 Save the current floating point/SSE/SSE2 context to a buffer.
7068 Saves the current floating point/SSE/SSE2 state to the buffer specified by
7069 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
7070 available on IA-32 and x64.
7072 If Buffer is NULL, then ASSERT().
7073 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7075 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7081 OUT IA32_FX_BUFFER
*Buffer
7086 Restores the current floating point/SSE/SSE2 context from a buffer.
7088 Restores the current floating point/SSE/SSE2 state from the buffer specified
7089 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
7090 only available on IA-32 and x64.
7092 If Buffer is NULL, then ASSERT().
7093 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7094 If Buffer was not saved with AsmFxSave(), then ASSERT().
7096 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7102 IN CONST IA32_FX_BUFFER
*Buffer
7107 Reads the current value of 64-bit MMX Register #0 (MM0).
7109 Reads and returns the current value of MM0. This function is only available
7112 @return The current value of MM0.
7123 Reads the current value of 64-bit MMX Register #1 (MM1).
7125 Reads and returns the current value of MM1. This function is only available
7128 @return The current value of MM1.
7139 Reads the current value of 64-bit MMX Register #2 (MM2).
7141 Reads and returns the current value of MM2. This function is only available
7144 @return The current value of MM2.
7155 Reads the current value of 64-bit MMX Register #3 (MM3).
7157 Reads and returns the current value of MM3. This function is only available
7160 @return The current value of MM3.
7171 Reads the current value of 64-bit MMX Register #4 (MM4).
7173 Reads and returns the current value of MM4. This function is only available
7176 @return The current value of MM4.
7187 Reads the current value of 64-bit MMX Register #5 (MM5).
7189 Reads and returns the current value of MM5. This function is only available
7192 @return The current value of MM5.
7203 Reads the current value of 64-bit MMX Register #6 (MM6).
7205 Reads and returns the current value of MM6. This function is only available
7208 @return The current value of MM6.
7219 Reads the current value of 64-bit MMX Register #7 (MM7).
7221 Reads and returns the current value of MM7. This function is only available
7224 @return The current value of MM7.
7235 Writes the current value of 64-bit MMX Register #0 (MM0).
7237 Writes the current value of MM0. This function is only available on IA32 and
7240 @param Value The 64-bit value to write to MM0.
7251 Writes the current value of 64-bit MMX Register #1 (MM1).
7253 Writes the current value of MM1. This function is only available on IA32 and
7256 @param Value The 64-bit value to write to MM1.
7267 Writes the current value of 64-bit MMX Register #2 (MM2).
7269 Writes the current value of MM2. This function is only available on IA32 and
7272 @param Value The 64-bit value to write to MM2.
7283 Writes the current value of 64-bit MMX Register #3 (MM3).
7285 Writes the current value of MM3. This function is only available on IA32 and
7288 @param Value The 64-bit value to write to MM3.
7299 Writes the current value of 64-bit MMX Register #4 (MM4).
7301 Writes the current value of MM4. This function is only available on IA32 and
7304 @param Value The 64-bit value to write to MM4.
7315 Writes the current value of 64-bit MMX Register #5 (MM5).
7317 Writes the current value of MM5. This function is only available on IA32 and
7320 @param Value The 64-bit value to write to MM5.
7331 Writes the current value of 64-bit MMX Register #6 (MM6).
7333 Writes the current value of MM6. This function is only available on IA32 and
7336 @param Value The 64-bit value to write to MM6.
7347 Writes the current value of 64-bit MMX Register #7 (MM7).
7349 Writes the current value of MM7. This function is only available on IA32 and
7352 @param Value The 64-bit value to write to MM7.
7363 Reads the current value of Time Stamp Counter (TSC).
7365 Reads and returns the current value of TSC. This function is only available
7368 @return The current value of TSC
7379 Reads the current value of a Performance Counter (PMC).
7381 Reads and returns the current value of performance counter specified by
7382 Index. This function is only available on IA-32 and x64.
7384 @param Index The 32-bit Performance Counter index to read.
7386 @return The value of the PMC specified by Index.
7397 Sets up a monitor buffer that is used by AsmMwait().
7399 Executes a MONITOR instruction with the register state specified by Eax, Ecx
7400 and Edx. Returns Eax. This function is only available on IA-32 and x64.
7402 @param Eax The value to load into EAX or RAX before executing the MONITOR
7404 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7406 @param Edx The value to load into EDX or RDX before executing the MONITOR
7422 Executes an MWAIT instruction.
7424 Executes an MWAIT instruction with the register state specified by Eax and
7425 Ecx. Returns Eax. This function is only available on IA-32 and x64.
7427 @param Eax The value to load into EAX or RAX before executing the MONITOR
7429 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7444 Executes a WBINVD instruction.
7446 Executes a WBINVD instruction. This function is only available on IA-32 and
7458 Executes a INVD instruction.
7460 Executes a INVD instruction. This function is only available on IA-32 and
7472 Flushes a cache line from all the instruction and data caches within the
7473 coherency domain of the CPU.
7475 Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7476 This function is only available on IA-32 and x64.
7478 @param LinearAddress The address of the cache line to flush. If the CPU is
7479 in a physical addressing mode, then LinearAddress is a
7480 physical address. If the CPU is in a virtual
7481 addressing mode, then LinearAddress is a virtual
7484 @return LinearAddress.
7489 IN VOID
*LinearAddress
7494 Enables the 32-bit paging mode on the CPU.
7496 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7497 must be properly initialized prior to calling this service. This function
7498 assumes the current execution mode is 32-bit protected mode. This function is
7499 only available on IA-32. After the 32-bit paging mode is enabled, control is
7500 transferred to the function specified by EntryPoint using the new stack
7501 specified by NewStack and passing in the parameters specified by Context1 and
7502 Context2. Context1 and Context2 are optional and may be NULL. The function
7503 EntryPoint must never return.
7505 If the current execution mode is not 32-bit protected mode, then ASSERT().
7506 If EntryPoint is NULL, then ASSERT().
7507 If NewStack is NULL, then ASSERT().
7509 There are a number of constraints that must be followed before calling this
7511 1) Interrupts must be disabled.
7512 2) The caller must be in 32-bit protected mode with flat descriptors. This
7513 means all descriptors must have a base of 0 and a limit of 4GB.
7514 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
7516 4) CR3 must point to valid page tables that will be used once the transition
7517 is complete, and those page tables must guarantee that the pages for this
7518 function and the stack are identity mapped.
7520 @param EntryPoint A pointer to function to call with the new stack after
7522 @param Context1 A pointer to the context to pass into the EntryPoint
7523 function as the first parameter after paging is enabled.
7524 @param Context2 A pointer to the context to pass into the EntryPoint
7525 function as the second parameter after paging is enabled.
7526 @param NewStack A pointer to the new stack to use for the EntryPoint
7527 function after paging is enabled.
7533 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7534 IN VOID
*Context1
, OPTIONAL
7535 IN VOID
*Context2
, OPTIONAL
7541 Disables the 32-bit paging mode on the CPU.
7543 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7544 mode. This function assumes the current execution mode is 32-paged protected
7545 mode. This function is only available on IA-32. After the 32-bit paging mode
7546 is disabled, control is transferred to the function specified by EntryPoint
7547 using the new stack specified by NewStack and passing in the parameters
7548 specified by Context1 and Context2. Context1 and Context2 are optional and
7549 may be NULL. The function EntryPoint must never return.
7551 If the current execution mode is not 32-bit paged mode, then ASSERT().
7552 If EntryPoint is NULL, then ASSERT().
7553 If NewStack is NULL, then ASSERT().
7555 There are a number of constraints that must be followed before calling this
7557 1) Interrupts must be disabled.
7558 2) The caller must be in 32-bit paged mode.
7559 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7560 4) CR3 must point to valid page tables that guarantee that the pages for
7561 this function and the stack are identity mapped.
7563 @param EntryPoint A pointer to function to call with the new stack after
7565 @param Context1 A pointer to the context to pass into the EntryPoint
7566 function as the first parameter after paging is disabled.
7567 @param Context2 A pointer to the context to pass into the EntryPoint
7568 function as the second parameter after paging is
7570 @param NewStack A pointer to the new stack to use for the EntryPoint
7571 function after paging is disabled.
7576 AsmDisablePaging32 (
7577 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7578 IN VOID
*Context1
, OPTIONAL
7579 IN VOID
*Context2
, OPTIONAL
7585 Enables the 64-bit paging mode on the CPU.
7587 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7588 must be properly initialized prior to calling this service. This function
7589 assumes the current execution mode is 32-bit protected mode with flat
7590 descriptors. This function is only available on IA-32. After the 64-bit
7591 paging mode is enabled, control is transferred to the function specified by
7592 EntryPoint using the new stack specified by NewStack and passing in the
7593 parameters specified by Context1 and Context2. Context1 and Context2 are
7594 optional and may be 0. The function EntryPoint must never return.
7596 If the current execution mode is not 32-bit protected mode with flat
7597 descriptors, then ASSERT().
7598 If EntryPoint is 0, then ASSERT().
7599 If NewStack is 0, then ASSERT().
7601 @param Cs The 16-bit selector to load in the CS before EntryPoint
7602 is called. The descriptor in the GDT that this selector
7603 references must be setup for long mode.
7604 @param EntryPoint The 64-bit virtual address of the function to call with
7605 the new stack after paging is enabled.
7606 @param Context1 The 64-bit virtual address of the context to pass into
7607 the EntryPoint function as the first parameter after
7609 @param Context2 The 64-bit virtual address of the context to pass into
7610 the EntryPoint function as the second parameter after
7612 @param NewStack The 64-bit virtual address of the new stack to use for
7613 the EntryPoint function after paging is enabled.
7620 IN UINT64 EntryPoint
,
7621 IN UINT64 Context1
, OPTIONAL
7622 IN UINT64 Context2
, OPTIONAL
7628 Disables the 64-bit paging mode on the CPU.
7630 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7631 mode. This function assumes the current execution mode is 64-paging mode.
7632 This function is only available on x64. After the 64-bit paging mode is
7633 disabled, control is transferred to the function specified by EntryPoint
7634 using the new stack specified by NewStack and passing in the parameters
7635 specified by Context1 and Context2. Context1 and Context2 are optional and
7636 may be 0. The function EntryPoint must never return.
7638 If the current execution mode is not 64-bit paged mode, then ASSERT().
7639 If EntryPoint is 0, then ASSERT().
7640 If NewStack is 0, then ASSERT().
7642 @param Cs The 16-bit selector to load in the CS before EntryPoint
7643 is called. The descriptor in the GDT that this selector
7644 references must be setup for 32-bit protected mode.
7645 @param EntryPoint The 64-bit virtual address of the function to call with
7646 the new stack after paging is disabled.
7647 @param Context1 The 64-bit virtual address of the context to pass into
7648 the EntryPoint function as the first parameter after
7650 @param Context2 The 64-bit virtual address of the context to pass into
7651 the EntryPoint function as the second parameter after
7653 @param NewStack The 64-bit virtual address of the new stack to use for
7654 the EntryPoint function after paging is disabled.
7659 AsmDisablePaging64 (
7661 IN UINT32 EntryPoint
,
7662 IN UINT32 Context1
, OPTIONAL
7663 IN UINT32 Context2
, OPTIONAL
7669 // 16-bit thunking services
7673 Retrieves the properties for 16-bit thunk functions.
7675 Computes the size of the buffer and stack below 1MB required to use the
7676 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7677 buffer size is returned in RealModeBufferSize, and the stack size is returned
7678 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7679 then the actual minimum stack size is ExtraStackSize plus the maximum number
7680 of bytes that need to be passed to the 16-bit real mode code.
7682 If RealModeBufferSize is NULL, then ASSERT().
7683 If ExtraStackSize is NULL, then ASSERT().
7685 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
7686 required to use the 16-bit thunk functions.
7687 @param ExtraStackSize A pointer to the extra size of stack below 1MB
7688 that the 16-bit thunk functions require for
7689 temporary storage in the transition to and from
7695 AsmGetThunk16Properties (
7696 OUT UINT32
*RealModeBufferSize
,
7697 OUT UINT32
*ExtraStackSize
7702 Prepares all structures a code required to use AsmThunk16().
7704 Prepares all structures and code required to use AsmThunk16().
7706 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7707 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7709 If ThunkContext is NULL, then ASSERT().
7711 @param ThunkContext A pointer to the context structure that describes the
7712 16-bit real mode code to call.
7718 IN OUT THUNK_CONTEXT
*ThunkContext
7723 Transfers control to a 16-bit real mode entry point and returns the results.
7725 Transfers control to a 16-bit real mode entry point and returns the results.
7726 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7727 This function must be called with interrupts disabled.
7729 The register state from the RealModeState field of ThunkContext is restored just prior
7730 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
7731 which is used to set the interrupt state when a 16-bit real mode entry point is called.
7732 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7733 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
7734 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7735 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7736 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7737 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7738 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7739 after the RETF instruction is executed.
7741 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7742 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7743 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7745 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7746 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7747 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7749 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7750 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7752 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7753 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7754 disable the A20 mask.
7756 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7757 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
7758 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7760 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7761 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7763 If ThunkContext is NULL, then ASSERT().
7764 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7765 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7766 ThunkAttributes, then ASSERT().
7768 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7769 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7771 @param ThunkContext A pointer to the context structure that describes the
7772 16-bit real mode code to call.
7778 IN OUT THUNK_CONTEXT
*ThunkContext
7783 Prepares all structures and code for a 16-bit real mode thunk, transfers
7784 control to a 16-bit real mode entry point, and returns the results.
7786 Prepares all structures and code for a 16-bit real mode thunk, transfers
7787 control to a 16-bit real mode entry point, and returns the results. If the
7788 caller only need to perform a single 16-bit real mode thunk, then this
7789 service should be used. If the caller intends to make more than one 16-bit
7790 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7791 once and AsmThunk16() can be called for each 16-bit real mode thunk.
7793 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7794 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7796 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7798 @param ThunkContext A pointer to the context structure that describes the
7799 16-bit real mode code to call.
7804 AsmPrepareAndThunk16 (
7805 IN OUT THUNK_CONTEXT
*ThunkContext
7809 Generates a 16-bit random number through RDRAND instruction.
7811 if Rand is NULL, then ASSERT().
7813 @param[out] Rand Buffer pointer to store the random result.
7815 @retval TRUE RDRAND call was successful.
7816 @retval FALSE Failed attempts to call RDRAND.
7826 Generates a 32-bit random number through RDRAND instruction.
7828 if Rand is NULL, then ASSERT().
7830 @param[out] Rand Buffer pointer to store the random result.
7832 @retval TRUE RDRAND call was successful.
7833 @retval FALSE Failed attempts to call RDRAND.
7843 Generates a 64-bit random number through RDRAND instruction.
7845 if Rand is NULL, then ASSERT().
7847 @param[out] Rand Buffer pointer to store the random result.
7849 @retval TRUE RDRAND call was successful.
7850 @retval FALSE Failed attempts to call RDRAND.
7860 Load given selector into TR register.
7862 @param[in] Selector Task segment selector
7871 Performs a serializing operation on all load-from-memory instructions that
7872 were issued prior the AsmLfence function.
7874 Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7884 Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7885 word, dword or qword operand is encoded at the end of the instruction's
7886 binary representation.
7888 This function should be used to update object code that was compiled with
7889 NASM from assembly source code. Example:
7893 mov eax, strict dword 0 ; the imm32 zero operand will be patched
7899 X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7900 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7902 @param[out] InstructionEnd Pointer right past the instruction to patch. The
7903 immediate operand to patch is expected to
7904 comprise the trailing bytes of the instruction.
7905 If InstructionEnd is closer to address 0 than
7906 ValueSize permits, then ASSERT().
7908 @param[in] PatchValue The constant to write to the immediate operand.
7909 The caller is responsible for ensuring that
7910 PatchValue can be represented in the byte, word,
7911 dword or qword operand (as indicated through
7912 ValueSize); otherwise ASSERT().
7914 @param[in] ValueSize The size of the operand in bytes; must be 1, 2,
7915 4, or 8. ASSERT() otherwise.
7919 PatchInstructionX86 (
7920 OUT X86_ASSEMBLY_PATCH_LABEL
*InstructionEnd
,
7921 IN UINT64 PatchValue
,
7925 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7926 #endif // !defined (__BASE_LIB__)