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 UMIP
:1; ///< User-Mode Instruction Prevention.
5391 UINT32 LA57
:1; ///< Linear Address 57bit.
5392 UINT32 VMXE
:1; ///< VMX Enable.
5393 UINT32 SMXE
:1; ///< SMX Enable.
5394 UINT32 Reserved_3
:1; ///< Reserved.
5395 UINT32 FSGSBASE
:1; ///< FSGSBASE Enable.
5396 UINT32 PCIDE
:1; ///< PCID Enable.
5397 UINT32 OSXSAVE
:1; ///< XSAVE and Processor Extended States Enable.
5398 UINT32 Reserved_4
:1; ///< Reserved.
5399 UINT32 SMEP
:1; ///< SMEP Enable.
5400 UINT32 SMAP
:1; ///< SMAP Enable.
5401 UINT32 PKE
:1; ///< Protection-Key Enable.
5402 UINT32 Reserved_5
:9; ///< Reserved.
5408 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5427 } IA32_SEGMENT_DESCRIPTOR
;
5430 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5439 #define IA32_IDT_GATE_TYPE_TASK 0x85
5440 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5441 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5442 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5443 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5445 #define IA32_GDT_TYPE_TSS 0x9
5446 #define IA32_GDT_ALIGNMENT 8
5448 #if defined (MDE_CPU_IA32)
5450 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5454 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5455 UINT32 Selector
:16; ///< Selector.
5456 UINT32 Reserved_0
:8; ///< Reserved.
5457 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5458 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5461 } IA32_IDT_GATE_DESCRIPTOR
;
5465 // IA32 Task-State Segment Definition
5468 UINT16 PreviousTaskLink
;
5502 UINT16 LDTSegmentSelector
;
5505 UINT16 IOMapBaseAddress
;
5506 } IA32_TASK_STATE_SEGMENT
;
5510 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5511 UINT32 BaseLow
:16; ///< Base Address 15..00
5512 UINT32 BaseMid
:8; ///< Base Address 23..16
5513 UINT32 Type
:4; ///< Type (1 0 B 1)
5514 UINT32 Reserved_43
:1; ///< 0
5515 UINT32 DPL
:2; ///< Descriptor Privilege Level
5516 UINT32 P
:1; ///< Segment Present
5517 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5518 UINT32 AVL
:1; ///< Available for use by system software
5519 UINT32 Reserved_52
:2; ///< 0 0
5520 UINT32 G
:1; ///< Granularity
5521 UINT32 BaseHigh
:8; ///< Base Address 31..24
5524 } IA32_TSS_DESCRIPTOR
;
5527 #endif // defined (MDE_CPU_IA32)
5529 #if defined (MDE_CPU_X64)
5531 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5535 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5536 UINT32 Selector
:16; ///< Selector.
5537 UINT32 Reserved_0
:8; ///< Reserved.
5538 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5539 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5540 UINT32 OffsetUpper
:32; ///< Offset bits 63..32.
5541 UINT32 Reserved_1
:32; ///< Reserved.
5547 } IA32_IDT_GATE_DESCRIPTOR
;
5551 // IA32 Task-State Segment Definition
5561 UINT16 Reserved_100
;
5562 UINT16 IOMapBaseAddress
;
5563 } IA32_TASK_STATE_SEGMENT
;
5567 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5568 UINT32 BaseLow
:16; ///< Base Address 15..00
5569 UINT32 BaseMidl
:8; ///< Base Address 23..16
5570 UINT32 Type
:4; ///< Type (1 0 B 1)
5571 UINT32 Reserved_43
:1; ///< 0
5572 UINT32 DPL
:2; ///< Descriptor Privilege Level
5573 UINT32 P
:1; ///< Segment Present
5574 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5575 UINT32 AVL
:1; ///< Available for use by system software
5576 UINT32 Reserved_52
:2; ///< 0 0
5577 UINT32 G
:1; ///< Granularity
5578 UINT32 BaseMidh
:8; ///< Base Address 31..24
5579 UINT32 BaseHigh
:32; ///< Base Address 63..32
5580 UINT32 Reserved_96
:32; ///< Reserved
5586 } IA32_TSS_DESCRIPTOR
;
5589 #endif // defined (MDE_CPU_X64)
5592 /// Byte packed structure for an FP/SSE/SSE2 context.
5599 /// Structures for the 16-bit real mode thunks.
5652 IA32_EFLAGS32 EFLAGS
;
5662 } IA32_REGISTER_SET
;
5665 /// Byte packed structure for an 16-bit real mode thunks.
5668 IA32_REGISTER_SET
*RealModeState
;
5669 VOID
*RealModeBuffer
;
5670 UINT32 RealModeBufferSize
;
5671 UINT32 ThunkAttributes
;
5674 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5675 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5676 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5679 /// Type definition for representing labels in NASM source code that allow for
5680 /// the patching of immediate operands of IA32 and X64 instructions.
5682 /// While the type is technically defined as a function type (note: not a
5683 /// pointer-to-function type), such labels in NASM source code never stand for
5684 /// actual functions, and identifiers declared with this function type should
5685 /// never be called. This is also why the EFIAPI calling convention specifier
5686 /// is missing from the typedef, and why the typedef does not follow the usual
5687 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5688 /// return type and the VOID argument list are merely artifacts.
5690 typedef VOID (X86_ASSEMBLY_PATCH_LABEL
) (VOID
);
5693 Retrieves CPUID information.
5695 Executes the CPUID instruction with EAX set to the value specified by Index.
5696 This function always returns Index.
5697 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5698 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5699 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5700 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5701 This function is only available on IA-32 and x64.
5703 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5705 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5706 instruction. This is an optional parameter that may be NULL.
5707 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5708 instruction. This is an optional parameter that may be NULL.
5709 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5710 instruction. This is an optional parameter that may be NULL.
5711 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5712 instruction. This is an optional parameter that may be NULL.
5721 OUT UINT32
*Eax
, OPTIONAL
5722 OUT UINT32
*Ebx
, OPTIONAL
5723 OUT UINT32
*Ecx
, OPTIONAL
5724 OUT UINT32
*Edx OPTIONAL
5729 Retrieves CPUID information using an extended leaf identifier.
5731 Executes the CPUID instruction with EAX set to the value specified by Index
5732 and ECX set to the value specified by SubIndex. This function always returns
5733 Index. This function is only available on IA-32 and x64.
5735 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5736 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5737 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5738 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5740 @param Index The 32-bit value to load into EAX prior to invoking the
5742 @param SubIndex The 32-bit value to load into ECX prior to invoking the
5744 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5745 instruction. This is an optional parameter that may be
5747 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5748 instruction. This is an optional parameter that may be
5750 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5751 instruction. This is an optional parameter that may be
5753 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5754 instruction. This is an optional parameter that may be
5765 OUT UINT32
*Eax
, OPTIONAL
5766 OUT UINT32
*Ebx
, OPTIONAL
5767 OUT UINT32
*Ecx
, OPTIONAL
5768 OUT UINT32
*Edx OPTIONAL
5773 Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5775 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5776 and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5787 Perform a WBINVD and clear both the CD and NW bits of CR0.
5789 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5790 bits of CR0 to 0. This function is only available on IA-32 and x64.
5801 Returns the lower 32-bits of a Machine Specific Register(MSR).
5803 Reads and returns the lower 32-bits of the MSR specified by Index.
5804 No parameter checking is performed on Index, and some Index values may cause
5805 CPU exceptions. The caller must either guarantee that Index is valid, or the
5806 caller must set up exception handlers to catch the exceptions. This function
5807 is only available on IA-32 and x64.
5809 @param Index The 32-bit MSR index to read.
5811 @return The lower 32 bits of the MSR identified by Index.
5822 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5823 The upper 32-bits of the MSR are set to zero.
5825 Writes the 32-bit value specified by Value to the MSR specified by Index. The
5826 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5827 the MSR is returned. No parameter checking is performed on Index or Value,
5828 and some of these may cause CPU exceptions. The caller must either guarantee
5829 that Index and Value are valid, or the caller must establish proper exception
5830 handlers. This function is only available on IA-32 and x64.
5832 @param Index The 32-bit MSR index to write.
5833 @param Value The 32-bit value to write to the MSR.
5847 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5848 writes the result back to the 64-bit MSR.
5850 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5851 between the lower 32-bits of the read result and the value specified by
5852 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5853 32-bits of the value written to the MSR is returned. No parameter checking is
5854 performed on Index or OrData, and some of these may cause CPU exceptions. The
5855 caller must either guarantee that Index and OrData are valid, or the caller
5856 must establish proper exception handlers. This function is only available on
5859 @param Index The 32-bit MSR index to write.
5860 @param OrData The value to OR with the read value from the MSR.
5862 @return The lower 32-bit value written to the MSR.
5874 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5875 the result back to the 64-bit MSR.
5877 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5878 lower 32-bits of the read result and the value specified by AndData, and
5879 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5880 the value written to the MSR is returned. No parameter checking is performed
5881 on Index or AndData, and some of these may cause CPU exceptions. The caller
5882 must either guarantee that Index and AndData are valid, or the caller must
5883 establish proper exception handlers. This function is only available on IA-32
5886 @param Index The 32-bit MSR index to write.
5887 @param AndData The value to AND with the read value from the MSR.
5889 @return The lower 32-bit value written to the MSR.
5901 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5902 on the lower 32-bits, and writes the result back to the 64-bit MSR.
5904 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5905 lower 32-bits of the read result and the value specified by AndData
5906 preserving the upper 32-bits, performs a bitwise OR between the
5907 result of the AND operation and the value specified by OrData, and writes the
5908 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5909 written to the MSR is returned. No parameter checking is performed on Index,
5910 AndData, or OrData, and some of these may cause CPU exceptions. The caller
5911 must either guarantee that Index, AndData, and OrData are valid, or the
5912 caller must establish proper exception handlers. This function is only
5913 available on IA-32 and x64.
5915 @param Index The 32-bit MSR index to write.
5916 @param AndData The value to AND with the read value from the MSR.
5917 @param OrData The value to OR with the result of the AND operation.
5919 @return The lower 32-bit value written to the MSR.
5932 Reads a bit field of an MSR.
5934 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5935 specified by the StartBit and the EndBit. The value of the bit field is
5936 returned. The caller must either guarantee that Index is valid, or the caller
5937 must set up exception handlers to catch the exceptions. This function is only
5938 available on IA-32 and x64.
5940 If StartBit is greater than 31, then ASSERT().
5941 If EndBit is greater than 31, then ASSERT().
5942 If EndBit is less than StartBit, then ASSERT().
5944 @param Index The 32-bit MSR index to read.
5945 @param StartBit The ordinal of the least significant bit in the bit field.
5947 @param EndBit The ordinal of the most significant bit in the bit field.
5950 @return The bit field read from the MSR.
5955 AsmMsrBitFieldRead32 (
5963 Writes a bit field to an MSR.
5965 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5966 field is specified by the StartBit and the EndBit. All other bits in the
5967 destination MSR are preserved. The lower 32-bits of the MSR written is
5968 returned. The caller must either guarantee that Index and the data written
5969 is valid, or the caller must set up exception handlers to catch the exceptions.
5970 This function is only available on IA-32 and x64.
5972 If StartBit is greater than 31, then ASSERT().
5973 If EndBit is greater than 31, then ASSERT().
5974 If EndBit is less than StartBit, then ASSERT().
5975 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5977 @param Index The 32-bit MSR index to write.
5978 @param StartBit The ordinal of the least significant bit in the bit field.
5980 @param EndBit The ordinal of the most significant bit in the bit field.
5982 @param Value New value of the bit field.
5984 @return The lower 32-bit of the value written to the MSR.
5989 AsmMsrBitFieldWrite32 (
5998 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5999 result back to the bit field in the 64-bit MSR.
6001 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6002 between the read result and the value specified by OrData, and writes the
6003 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
6004 written to the MSR are returned. Extra left bits in OrData are stripped. The
6005 caller must either guarantee that Index and the data written is valid, or
6006 the caller must set up exception handlers to catch the exceptions. This
6007 function is only available on IA-32 and x64.
6009 If StartBit is greater than 31, then ASSERT().
6010 If EndBit is greater than 31, then ASSERT().
6011 If EndBit is less than StartBit, then ASSERT().
6012 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6014 @param Index The 32-bit MSR index to write.
6015 @param StartBit The ordinal of the least significant bit in the bit field.
6017 @param EndBit The ordinal of the most significant bit in the bit field.
6019 @param OrData The value to OR with the read value from the MSR.
6021 @return The lower 32-bit of the value written to the MSR.
6026 AsmMsrBitFieldOr32 (
6035 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6036 result back to the bit field in the 64-bit MSR.
6038 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6039 read result and the value specified by AndData, and writes the result to the
6040 64-bit MSR specified by Index. The lower 32-bits of the value written to the
6041 MSR are returned. Extra left bits in AndData are stripped. The caller must
6042 either guarantee that Index and the data written is valid, or the caller must
6043 set up exception handlers to catch the exceptions. This function is only
6044 available on IA-32 and x64.
6046 If StartBit is greater than 31, then ASSERT().
6047 If EndBit is greater than 31, then ASSERT().
6048 If EndBit is less than StartBit, then ASSERT().
6049 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6051 @param Index The 32-bit MSR index to write.
6052 @param StartBit The ordinal of the least significant bit in the bit field.
6054 @param EndBit The ordinal of the most significant bit in the bit field.
6056 @param AndData The value to AND with the read value from the MSR.
6058 @return The lower 32-bit of the value written to the MSR.
6063 AsmMsrBitFieldAnd32 (
6072 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6073 bitwise OR, and writes the result back to the bit field in the
6076 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
6077 bitwise OR between the read result and the value specified by
6078 AndData, and writes the result to the 64-bit MSR specified by Index. The
6079 lower 32-bits of the value written to the MSR are returned. Extra left bits
6080 in both AndData and OrData are stripped. The caller must either guarantee
6081 that Index and the data written is valid, or the caller must set up exception
6082 handlers to catch the exceptions. This function is only available on IA-32
6085 If StartBit is greater than 31, then ASSERT().
6086 If EndBit is greater than 31, then ASSERT().
6087 If EndBit is less than StartBit, then ASSERT().
6088 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6089 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6091 @param Index The 32-bit MSR index to write.
6092 @param StartBit The ordinal of the least significant bit in the bit field.
6094 @param EndBit The ordinal of the most significant bit in the bit field.
6096 @param AndData The value to AND with the read value from the MSR.
6097 @param OrData The value to OR with the result of the AND operation.
6099 @return The lower 32-bit of the value written to the MSR.
6104 AsmMsrBitFieldAndThenOr32 (
6114 Returns a 64-bit Machine Specific Register(MSR).
6116 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
6117 performed on Index, and some Index values may cause CPU exceptions. The
6118 caller must either guarantee that Index is valid, or the caller must set up
6119 exception handlers to catch the exceptions. This function is only available
6122 @param Index The 32-bit MSR index to read.
6124 @return The value of the MSR identified by Index.
6135 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
6138 Writes the 64-bit value specified by Value to the MSR specified by Index. The
6139 64-bit value written to the MSR is returned. No parameter checking is
6140 performed on Index or Value, and some of these may cause CPU exceptions. The
6141 caller must either guarantee that Index and Value are valid, or the caller
6142 must establish proper exception handlers. This function is only available on
6145 @param Index The 32-bit MSR index to write.
6146 @param Value The 64-bit value to write to the MSR.
6160 Reads a 64-bit MSR, performs a bitwise OR, and writes the result
6161 back to the 64-bit MSR.
6163 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6164 between the read result and the value specified by OrData, and writes the
6165 result to the 64-bit MSR specified by Index. The value written to the MSR is
6166 returned. No parameter checking is performed on Index or OrData, and some of
6167 these may cause CPU exceptions. The caller must either guarantee that Index
6168 and OrData are valid, or the caller must establish proper exception handlers.
6169 This function is only available on IA-32 and x64.
6171 @param Index The 32-bit MSR index to write.
6172 @param OrData The value to OR with the read value from the MSR.
6174 @return The value written back to the MSR.
6186 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
6189 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6190 read result and the value specified by OrData, and writes the result to the
6191 64-bit MSR specified by Index. The value written to the MSR is returned. No
6192 parameter checking is performed on Index or OrData, and some of these may
6193 cause CPU exceptions. The caller must either guarantee that Index and OrData
6194 are valid, or the caller must establish proper exception handlers. This
6195 function is only available on IA-32 and x64.
6197 @param Index The 32-bit MSR index to write.
6198 @param AndData The value to AND with the read value from the MSR.
6200 @return The value written back to the MSR.
6212 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
6213 OR, and writes the result back to the 64-bit MSR.
6215 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
6216 result and the value specified by AndData, performs a bitwise OR
6217 between the result of the AND operation and the value specified by OrData,
6218 and writes the result to the 64-bit MSR specified by Index. The value written
6219 to the MSR is returned. No parameter checking is performed on Index, AndData,
6220 or OrData, and some of these may cause CPU exceptions. The caller must either
6221 guarantee that Index, AndData, and OrData are valid, or the caller must
6222 establish proper exception handlers. This function is only available on IA-32
6225 @param Index The 32-bit MSR index to write.
6226 @param AndData The value to AND with the read value from the MSR.
6227 @param OrData The value to OR with the result of the AND operation.
6229 @return The value written back to the MSR.
6242 Reads a bit field of an MSR.
6244 Reads the bit field in the 64-bit MSR. The bit field is specified by the
6245 StartBit and the EndBit. The value of the bit field is returned. The caller
6246 must either guarantee that Index is valid, or the caller must set up
6247 exception handlers to catch the exceptions. This function is only available
6250 If StartBit is greater than 63, then ASSERT().
6251 If EndBit is greater than 63, then ASSERT().
6252 If EndBit is less than StartBit, then ASSERT().
6254 @param Index The 32-bit MSR index to read.
6255 @param StartBit The ordinal of the least significant bit in the bit field.
6257 @param EndBit The ordinal of the most significant bit in the bit field.
6260 @return The value read from the MSR.
6265 AsmMsrBitFieldRead64 (
6273 Writes a bit field to an MSR.
6275 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
6276 the StartBit and the EndBit. All other bits in the destination MSR are
6277 preserved. The MSR written is returned. The caller must either guarantee
6278 that Index and the data written is valid, or the caller must set up exception
6279 handlers to catch the exceptions. This function is only available on IA-32 and x64.
6281 If StartBit is greater than 63, then ASSERT().
6282 If EndBit is greater than 63, then ASSERT().
6283 If EndBit is less than StartBit, then ASSERT().
6284 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6286 @param Index The 32-bit MSR index to write.
6287 @param StartBit The ordinal of the least significant bit in the bit field.
6289 @param EndBit The ordinal of the most significant bit in the bit field.
6291 @param Value New value of the bit field.
6293 @return The value written back to the MSR.
6298 AsmMsrBitFieldWrite64 (
6307 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
6308 writes the result back to the bit field in the 64-bit MSR.
6310 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6311 between the read result and the value specified by OrData, and writes the
6312 result to the 64-bit MSR specified by Index. The value written to the MSR is
6313 returned. Extra left bits in OrData are stripped. The caller must either
6314 guarantee that Index and the data written is valid, or the caller must set up
6315 exception handlers to catch the exceptions. This function is only available
6318 If StartBit is greater than 63, then ASSERT().
6319 If EndBit is greater than 63, then ASSERT().
6320 If EndBit is less than StartBit, then ASSERT().
6321 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6323 @param Index The 32-bit MSR index to write.
6324 @param StartBit The ordinal of the least significant bit in the bit field.
6326 @param EndBit The ordinal of the most significant bit in the bit field.
6328 @param OrData The value to OR with the read value from the bit field.
6330 @return The value written back to the MSR.
6335 AsmMsrBitFieldOr64 (
6344 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6345 result back to the bit field in the 64-bit MSR.
6347 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6348 read result and the value specified by AndData, and writes the result to the
6349 64-bit MSR specified by Index. The value written to the MSR is returned.
6350 Extra left bits in AndData are stripped. The caller must either guarantee
6351 that Index and the data written is valid, or the caller must set up exception
6352 handlers to catch the exceptions. This function is only available on IA-32
6355 If StartBit is greater than 63, then ASSERT().
6356 If EndBit is greater than 63, then ASSERT().
6357 If EndBit is less than StartBit, then ASSERT().
6358 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6360 @param Index The 32-bit MSR index to write.
6361 @param StartBit The ordinal of the least significant bit in the bit field.
6363 @param EndBit The ordinal of the most significant bit in the bit field.
6365 @param AndData The value to AND with the read value from the bit field.
6367 @return The value written back to the MSR.
6372 AsmMsrBitFieldAnd64 (
6381 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6382 bitwise OR, and writes the result back to the bit field in the
6385 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6386 a bitwise OR between the read result and the value specified by
6387 AndData, and writes the result to the 64-bit MSR specified by Index. The
6388 value written to the MSR is returned. Extra left bits in both AndData and
6389 OrData are stripped. The caller must either guarantee that Index and the data
6390 written is valid, or the caller must set up exception handlers to catch the
6391 exceptions. This function is only available on IA-32 and x64.
6393 If StartBit is greater than 63, then ASSERT().
6394 If EndBit is greater than 63, then ASSERT().
6395 If EndBit is less than StartBit, then ASSERT().
6396 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6397 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6399 @param Index The 32-bit MSR index to write.
6400 @param StartBit The ordinal of the least significant bit in the bit field.
6402 @param EndBit The ordinal of the most significant bit in the bit field.
6404 @param AndData The value to AND with the read value from the bit field.
6405 @param OrData The value to OR with the result of the AND operation.
6407 @return The value written back to the MSR.
6412 AsmMsrBitFieldAndThenOr64 (
6422 Reads the current value of the EFLAGS register.
6424 Reads and returns the current value of the EFLAGS register. This function is
6425 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6426 64-bit value on x64.
6428 @return EFLAGS on IA-32 or RFLAGS on x64.
6439 Reads the current value of the Control Register 0 (CR0).
6441 Reads and returns the current value of CR0. This function is only available
6442 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6445 @return The value of the Control Register 0 (CR0).
6456 Reads the current value of the Control Register 2 (CR2).
6458 Reads and returns the current value of CR2. This function is only available
6459 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6462 @return The value of the Control Register 2 (CR2).
6473 Reads the current value of the Control Register 3 (CR3).
6475 Reads and returns the current value of CR3. This function is only available
6476 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6479 @return The value of the Control Register 3 (CR3).
6490 Reads the current value of the Control Register 4 (CR4).
6492 Reads and returns the current value of CR4. This function is only available
6493 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6496 @return The value of the Control Register 4 (CR4).
6507 Writes a value to Control Register 0 (CR0).
6509 Writes and returns a new value to CR0. This function is only available on
6510 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6512 @param Cr0 The value to write to CR0.
6514 @return The value written to CR0.
6525 Writes a value to Control Register 2 (CR2).
6527 Writes and returns a new value to CR2. This function is only available on
6528 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6530 @param Cr2 The value to write to CR2.
6532 @return The value written to CR2.
6543 Writes a value to Control Register 3 (CR3).
6545 Writes and returns a new value to CR3. This function is only available on
6546 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6548 @param Cr3 The value to write to CR3.
6550 @return The value written to CR3.
6561 Writes a value to Control Register 4 (CR4).
6563 Writes and returns a new value to CR4. This function is only available on
6564 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6566 @param Cr4 The value to write to CR4.
6568 @return The value written to CR4.
6579 Reads the current value of Debug Register 0 (DR0).
6581 Reads and returns the current value of DR0. This function is only available
6582 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6585 @return The value of Debug Register 0 (DR0).
6596 Reads the current value of Debug Register 1 (DR1).
6598 Reads and returns the current value of DR1. This function is only available
6599 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6602 @return The value of Debug Register 1 (DR1).
6613 Reads the current value of Debug Register 2 (DR2).
6615 Reads and returns the current value of DR2. This function is only available
6616 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6619 @return The value of Debug Register 2 (DR2).
6630 Reads the current value of Debug Register 3 (DR3).
6632 Reads and returns the current value of DR3. This function is only available
6633 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6636 @return The value of Debug Register 3 (DR3).
6647 Reads the current value of Debug Register 4 (DR4).
6649 Reads and returns the current value of DR4. This function is only available
6650 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6653 @return The value of Debug Register 4 (DR4).
6664 Reads the current value of Debug Register 5 (DR5).
6666 Reads and returns the current value of DR5. This function is only available
6667 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6670 @return The value of Debug Register 5 (DR5).
6681 Reads the current value of Debug Register 6 (DR6).
6683 Reads and returns the current value of DR6. This function is only available
6684 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6687 @return The value of Debug Register 6 (DR6).
6698 Reads the current value of Debug Register 7 (DR7).
6700 Reads and returns the current value of DR7. This function is only available
6701 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6704 @return The value of Debug Register 7 (DR7).
6715 Writes a value to Debug Register 0 (DR0).
6717 Writes and returns a new value to DR0. This function is only available on
6718 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6720 @param Dr0 The value to write to Dr0.
6722 @return The value written to Debug Register 0 (DR0).
6733 Writes a value to Debug Register 1 (DR1).
6735 Writes and returns a new value to DR1. This function is only available on
6736 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6738 @param Dr1 The value to write to Dr1.
6740 @return The value written to Debug Register 1 (DR1).
6751 Writes a value to Debug Register 2 (DR2).
6753 Writes and returns a new value to DR2. This function is only available on
6754 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6756 @param Dr2 The value to write to Dr2.
6758 @return The value written to Debug Register 2 (DR2).
6769 Writes a value to Debug Register 3 (DR3).
6771 Writes and returns a new value to DR3. This function is only available on
6772 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6774 @param Dr3 The value to write to Dr3.
6776 @return The value written to Debug Register 3 (DR3).
6787 Writes a value to Debug Register 4 (DR4).
6789 Writes and returns a new value to DR4. This function is only available on
6790 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6792 @param Dr4 The value to write to Dr4.
6794 @return The value written to Debug Register 4 (DR4).
6805 Writes a value to Debug Register 5 (DR5).
6807 Writes and returns a new value to DR5. This function is only available on
6808 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6810 @param Dr5 The value to write to Dr5.
6812 @return The value written to Debug Register 5 (DR5).
6823 Writes a value to Debug Register 6 (DR6).
6825 Writes and returns a new value to DR6. This function is only available on
6826 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6828 @param Dr6 The value to write to Dr6.
6830 @return The value written to Debug Register 6 (DR6).
6841 Writes a value to Debug Register 7 (DR7).
6843 Writes and returns a new value to DR7. This function is only available on
6844 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6846 @param Dr7 The value to write to Dr7.
6848 @return The value written to Debug Register 7 (DR7).
6859 Reads the current value of Code Segment Register (CS).
6861 Reads and returns the current value of CS. This function is only available on
6864 @return The current value of CS.
6875 Reads the current value of Data Segment Register (DS).
6877 Reads and returns the current value of DS. This function is only available on
6880 @return The current value of DS.
6891 Reads the current value of Extra Segment Register (ES).
6893 Reads and returns the current value of ES. This function is only available on
6896 @return The current value of ES.
6907 Reads the current value of FS Data Segment Register (FS).
6909 Reads and returns the current value of FS. This function is only available on
6912 @return The current value of FS.
6923 Reads the current value of GS Data Segment Register (GS).
6925 Reads and returns the current value of GS. This function is only available on
6928 @return The current value of GS.
6939 Reads the current value of Stack Segment Register (SS).
6941 Reads and returns the current value of SS. This function is only available on
6944 @return The current value of SS.
6955 Reads the current value of Task Register (TR).
6957 Reads and returns the current value of TR. This function is only available on
6960 @return The current value of TR.
6971 Reads the current Global Descriptor Table Register(GDTR) descriptor.
6973 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6974 function is only available on IA-32 and x64.
6976 If Gdtr is NULL, then ASSERT().
6978 @param Gdtr The pointer to a GDTR descriptor.
6984 OUT IA32_DESCRIPTOR
*Gdtr
6989 Writes the current Global Descriptor Table Register (GDTR) descriptor.
6991 Writes and the current GDTR descriptor specified by Gdtr. This function is
6992 only available on IA-32 and x64.
6994 If Gdtr is NULL, then ASSERT().
6996 @param Gdtr The pointer to a GDTR descriptor.
7002 IN CONST IA32_DESCRIPTOR
*Gdtr
7007 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
7009 Reads and returns the current IDTR descriptor and returns it in Idtr. This
7010 function is only available on IA-32 and x64.
7012 If Idtr is NULL, then ASSERT().
7014 @param Idtr The pointer to a IDTR descriptor.
7020 OUT IA32_DESCRIPTOR
*Idtr
7025 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
7027 Writes the current IDTR descriptor and returns it in Idtr. This function is
7028 only available on IA-32 and x64.
7030 If Idtr is NULL, then ASSERT().
7032 @param Idtr The pointer to a IDTR descriptor.
7038 IN CONST IA32_DESCRIPTOR
*Idtr
7043 Reads the current Local Descriptor Table Register(LDTR) selector.
7045 Reads and returns the current 16-bit LDTR descriptor value. This function is
7046 only available on IA-32 and x64.
7048 @return The current selector of LDT.
7059 Writes the current Local Descriptor Table Register (LDTR) selector.
7061 Writes and the current LDTR descriptor specified by Ldtr. This function is
7062 only available on IA-32 and x64.
7064 @param Ldtr 16-bit LDTR selector value.
7075 Save the current floating point/SSE/SSE2 context to a buffer.
7077 Saves the current floating point/SSE/SSE2 state to the buffer specified by
7078 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
7079 available on IA-32 and x64.
7081 If Buffer is NULL, then ASSERT().
7082 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7084 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7090 OUT IA32_FX_BUFFER
*Buffer
7095 Restores the current floating point/SSE/SSE2 context from a buffer.
7097 Restores the current floating point/SSE/SSE2 state from the buffer specified
7098 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
7099 only available on IA-32 and x64.
7101 If Buffer is NULL, then ASSERT().
7102 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7103 If Buffer was not saved with AsmFxSave(), then ASSERT().
7105 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7111 IN CONST IA32_FX_BUFFER
*Buffer
7116 Reads the current value of 64-bit MMX Register #0 (MM0).
7118 Reads and returns the current value of MM0. This function is only available
7121 @return The current value of MM0.
7132 Reads the current value of 64-bit MMX Register #1 (MM1).
7134 Reads and returns the current value of MM1. This function is only available
7137 @return The current value of MM1.
7148 Reads the current value of 64-bit MMX Register #2 (MM2).
7150 Reads and returns the current value of MM2. This function is only available
7153 @return The current value of MM2.
7164 Reads the current value of 64-bit MMX Register #3 (MM3).
7166 Reads and returns the current value of MM3. This function is only available
7169 @return The current value of MM3.
7180 Reads the current value of 64-bit MMX Register #4 (MM4).
7182 Reads and returns the current value of MM4. This function is only available
7185 @return The current value of MM4.
7196 Reads the current value of 64-bit MMX Register #5 (MM5).
7198 Reads and returns the current value of MM5. This function is only available
7201 @return The current value of MM5.
7212 Reads the current value of 64-bit MMX Register #6 (MM6).
7214 Reads and returns the current value of MM6. This function is only available
7217 @return The current value of MM6.
7228 Reads the current value of 64-bit MMX Register #7 (MM7).
7230 Reads and returns the current value of MM7. This function is only available
7233 @return The current value of MM7.
7244 Writes the current value of 64-bit MMX Register #0 (MM0).
7246 Writes the current value of MM0. This function is only available on IA32 and
7249 @param Value The 64-bit value to write to MM0.
7260 Writes the current value of 64-bit MMX Register #1 (MM1).
7262 Writes the current value of MM1. This function is only available on IA32 and
7265 @param Value The 64-bit value to write to MM1.
7276 Writes the current value of 64-bit MMX Register #2 (MM2).
7278 Writes the current value of MM2. This function is only available on IA32 and
7281 @param Value The 64-bit value to write to MM2.
7292 Writes the current value of 64-bit MMX Register #3 (MM3).
7294 Writes the current value of MM3. This function is only available on IA32 and
7297 @param Value The 64-bit value to write to MM3.
7308 Writes the current value of 64-bit MMX Register #4 (MM4).
7310 Writes the current value of MM4. This function is only available on IA32 and
7313 @param Value The 64-bit value to write to MM4.
7324 Writes the current value of 64-bit MMX Register #5 (MM5).
7326 Writes the current value of MM5. This function is only available on IA32 and
7329 @param Value The 64-bit value to write to MM5.
7340 Writes the current value of 64-bit MMX Register #6 (MM6).
7342 Writes the current value of MM6. This function is only available on IA32 and
7345 @param Value The 64-bit value to write to MM6.
7356 Writes the current value of 64-bit MMX Register #7 (MM7).
7358 Writes the current value of MM7. This function is only available on IA32 and
7361 @param Value The 64-bit value to write to MM7.
7372 Reads the current value of Time Stamp Counter (TSC).
7374 Reads and returns the current value of TSC. This function is only available
7377 @return The current value of TSC
7388 Reads the current value of a Performance Counter (PMC).
7390 Reads and returns the current value of performance counter specified by
7391 Index. This function is only available on IA-32 and x64.
7393 @param Index The 32-bit Performance Counter index to read.
7395 @return The value of the PMC specified by Index.
7406 Sets up a monitor buffer that is used by AsmMwait().
7408 Executes a MONITOR instruction with the register state specified by Eax, Ecx
7409 and Edx. Returns Eax. This function is only available on IA-32 and x64.
7411 @param Eax The value to load into EAX or RAX before executing the MONITOR
7413 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7415 @param Edx The value to load into EDX or RDX before executing the MONITOR
7431 Executes an MWAIT instruction.
7433 Executes an MWAIT instruction with the register state specified by Eax and
7434 Ecx. Returns Eax. This function is only available on IA-32 and x64.
7436 @param Eax The value to load into EAX or RAX before executing the MONITOR
7438 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7453 Executes a WBINVD instruction.
7455 Executes a WBINVD instruction. This function is only available on IA-32 and
7467 Executes a INVD instruction.
7469 Executes a INVD instruction. This function is only available on IA-32 and
7481 Flushes a cache line from all the instruction and data caches within the
7482 coherency domain of the CPU.
7484 Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7485 This function is only available on IA-32 and x64.
7487 @param LinearAddress The address of the cache line to flush. If the CPU is
7488 in a physical addressing mode, then LinearAddress is a
7489 physical address. If the CPU is in a virtual
7490 addressing mode, then LinearAddress is a virtual
7493 @return LinearAddress.
7498 IN VOID
*LinearAddress
7503 Enables the 32-bit paging mode on the CPU.
7505 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7506 must be properly initialized prior to calling this service. This function
7507 assumes the current execution mode is 32-bit protected mode. This function is
7508 only available on IA-32. After the 32-bit paging mode is enabled, control is
7509 transferred to the function specified by EntryPoint using the new stack
7510 specified by NewStack and passing in the parameters specified by Context1 and
7511 Context2. Context1 and Context2 are optional and may be NULL. The function
7512 EntryPoint must never return.
7514 If the current execution mode is not 32-bit protected mode, then ASSERT().
7515 If EntryPoint is NULL, then ASSERT().
7516 If NewStack is NULL, then ASSERT().
7518 There are a number of constraints that must be followed before calling this
7520 1) Interrupts must be disabled.
7521 2) The caller must be in 32-bit protected mode with flat descriptors. This
7522 means all descriptors must have a base of 0 and a limit of 4GB.
7523 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
7525 4) CR3 must point to valid page tables that will be used once the transition
7526 is complete, and those page tables must guarantee that the pages for this
7527 function and the stack are identity mapped.
7529 @param EntryPoint A pointer to function to call with the new stack after
7531 @param Context1 A pointer to the context to pass into the EntryPoint
7532 function as the first parameter after paging is enabled.
7533 @param Context2 A pointer to the context to pass into the EntryPoint
7534 function as the second parameter after paging is enabled.
7535 @param NewStack A pointer to the new stack to use for the EntryPoint
7536 function after paging is enabled.
7542 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7543 IN VOID
*Context1
, OPTIONAL
7544 IN VOID
*Context2
, OPTIONAL
7550 Disables the 32-bit paging mode on the CPU.
7552 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7553 mode. This function assumes the current execution mode is 32-paged protected
7554 mode. This function is only available on IA-32. After the 32-bit paging mode
7555 is disabled, control is transferred to the function specified by EntryPoint
7556 using the new stack specified by NewStack and passing in the parameters
7557 specified by Context1 and Context2. Context1 and Context2 are optional and
7558 may be NULL. The function EntryPoint must never return.
7560 If the current execution mode is not 32-bit paged mode, then ASSERT().
7561 If EntryPoint is NULL, then ASSERT().
7562 If NewStack is NULL, then ASSERT().
7564 There are a number of constraints that must be followed before calling this
7566 1) Interrupts must be disabled.
7567 2) The caller must be in 32-bit paged mode.
7568 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7569 4) CR3 must point to valid page tables that guarantee that the pages for
7570 this function and the stack are identity mapped.
7572 @param EntryPoint A pointer to function to call with the new stack after
7574 @param Context1 A pointer to the context to pass into the EntryPoint
7575 function as the first parameter after paging is disabled.
7576 @param Context2 A pointer to the context to pass into the EntryPoint
7577 function as the second parameter after paging is
7579 @param NewStack A pointer to the new stack to use for the EntryPoint
7580 function after paging is disabled.
7585 AsmDisablePaging32 (
7586 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7587 IN VOID
*Context1
, OPTIONAL
7588 IN VOID
*Context2
, OPTIONAL
7594 Enables the 64-bit paging mode on the CPU.
7596 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7597 must be properly initialized prior to calling this service. This function
7598 assumes the current execution mode is 32-bit protected mode with flat
7599 descriptors. This function is only available on IA-32. After the 64-bit
7600 paging mode is enabled, control is transferred to the function specified by
7601 EntryPoint using the new stack specified by NewStack and passing in the
7602 parameters specified by Context1 and Context2. Context1 and Context2 are
7603 optional and may be 0. The function EntryPoint must never return.
7605 If the current execution mode is not 32-bit protected mode with flat
7606 descriptors, then ASSERT().
7607 If EntryPoint is 0, then ASSERT().
7608 If NewStack is 0, then ASSERT().
7610 @param Cs The 16-bit selector to load in the CS before EntryPoint
7611 is called. The descriptor in the GDT that this selector
7612 references must be setup for long mode.
7613 @param EntryPoint The 64-bit virtual address of the function to call with
7614 the new stack after paging is enabled.
7615 @param Context1 The 64-bit virtual address of the context to pass into
7616 the EntryPoint function as the first parameter after
7618 @param Context2 The 64-bit virtual address of the context to pass into
7619 the EntryPoint function as the second parameter after
7621 @param NewStack The 64-bit virtual address of the new stack to use for
7622 the EntryPoint function after paging is enabled.
7629 IN UINT64 EntryPoint
,
7630 IN UINT64 Context1
, OPTIONAL
7631 IN UINT64 Context2
, OPTIONAL
7637 Disables the 64-bit paging mode on the CPU.
7639 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7640 mode. This function assumes the current execution mode is 64-paging mode.
7641 This function is only available on x64. After the 64-bit paging mode is
7642 disabled, control is transferred to the function specified by EntryPoint
7643 using the new stack specified by NewStack and passing in the parameters
7644 specified by Context1 and Context2. Context1 and Context2 are optional and
7645 may be 0. The function EntryPoint must never return.
7647 If the current execution mode is not 64-bit paged mode, then ASSERT().
7648 If EntryPoint is 0, then ASSERT().
7649 If NewStack is 0, then ASSERT().
7651 @param Cs The 16-bit selector to load in the CS before EntryPoint
7652 is called. The descriptor in the GDT that this selector
7653 references must be setup for 32-bit protected mode.
7654 @param EntryPoint The 64-bit virtual address of the function to call with
7655 the new stack after paging is disabled.
7656 @param Context1 The 64-bit virtual address of the context to pass into
7657 the EntryPoint function as the first parameter after
7659 @param Context2 The 64-bit virtual address of the context to pass into
7660 the EntryPoint function as the second parameter after
7662 @param NewStack The 64-bit virtual address of the new stack to use for
7663 the EntryPoint function after paging is disabled.
7668 AsmDisablePaging64 (
7670 IN UINT32 EntryPoint
,
7671 IN UINT32 Context1
, OPTIONAL
7672 IN UINT32 Context2
, OPTIONAL
7678 // 16-bit thunking services
7682 Retrieves the properties for 16-bit thunk functions.
7684 Computes the size of the buffer and stack below 1MB required to use the
7685 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7686 buffer size is returned in RealModeBufferSize, and the stack size is returned
7687 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7688 then the actual minimum stack size is ExtraStackSize plus the maximum number
7689 of bytes that need to be passed to the 16-bit real mode code.
7691 If RealModeBufferSize is NULL, then ASSERT().
7692 If ExtraStackSize is NULL, then ASSERT().
7694 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
7695 required to use the 16-bit thunk functions.
7696 @param ExtraStackSize A pointer to the extra size of stack below 1MB
7697 that the 16-bit thunk functions require for
7698 temporary storage in the transition to and from
7704 AsmGetThunk16Properties (
7705 OUT UINT32
*RealModeBufferSize
,
7706 OUT UINT32
*ExtraStackSize
7711 Prepares all structures a code required to use AsmThunk16().
7713 Prepares all structures and code required to use AsmThunk16().
7715 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7716 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7718 If ThunkContext is NULL, then ASSERT().
7720 @param ThunkContext A pointer to the context structure that describes the
7721 16-bit real mode code to call.
7727 IN OUT THUNK_CONTEXT
*ThunkContext
7732 Transfers control to a 16-bit real mode entry point and returns the results.
7734 Transfers control to a 16-bit real mode entry point and returns the results.
7735 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7736 This function must be called with interrupts disabled.
7738 The register state from the RealModeState field of ThunkContext is restored just prior
7739 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
7740 which is used to set the interrupt state when a 16-bit real mode entry point is called.
7741 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7742 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
7743 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7744 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7745 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7746 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7747 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7748 after the RETF instruction is executed.
7750 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7751 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7752 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7754 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7755 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7756 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7758 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7759 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7761 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7762 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7763 disable the A20 mask.
7765 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7766 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
7767 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7769 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7770 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7772 If ThunkContext is NULL, then ASSERT().
7773 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7774 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7775 ThunkAttributes, then ASSERT().
7777 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7778 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7780 @param ThunkContext A pointer to the context structure that describes the
7781 16-bit real mode code to call.
7787 IN OUT THUNK_CONTEXT
*ThunkContext
7792 Prepares all structures and code for a 16-bit real mode thunk, transfers
7793 control to a 16-bit real mode entry point, and returns the results.
7795 Prepares all structures and code for a 16-bit real mode thunk, transfers
7796 control to a 16-bit real mode entry point, and returns the results. If the
7797 caller only need to perform a single 16-bit real mode thunk, then this
7798 service should be used. If the caller intends to make more than one 16-bit
7799 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7800 once and AsmThunk16() can be called for each 16-bit real mode thunk.
7802 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7803 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7805 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7807 @param ThunkContext A pointer to the context structure that describes the
7808 16-bit real mode code to call.
7813 AsmPrepareAndThunk16 (
7814 IN OUT THUNK_CONTEXT
*ThunkContext
7818 Generates a 16-bit random number through RDRAND instruction.
7820 if Rand is NULL, then ASSERT().
7822 @param[out] Rand Buffer pointer to store the random result.
7824 @retval TRUE RDRAND call was successful.
7825 @retval FALSE Failed attempts to call RDRAND.
7835 Generates a 32-bit random number through RDRAND instruction.
7837 if Rand is NULL, then ASSERT().
7839 @param[out] Rand Buffer pointer to store the random result.
7841 @retval TRUE RDRAND call was successful.
7842 @retval FALSE Failed attempts to call RDRAND.
7852 Generates a 64-bit random number through RDRAND instruction.
7854 if Rand is NULL, then ASSERT().
7856 @param[out] Rand Buffer pointer to store the random result.
7858 @retval TRUE RDRAND call was successful.
7859 @retval FALSE Failed attempts to call RDRAND.
7869 Load given selector into TR register.
7871 @param[in] Selector Task segment selector
7880 Performs a serializing operation on all load-from-memory instructions that
7881 were issued prior the AsmLfence function.
7883 Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7893 Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7894 word, dword or qword operand is encoded at the end of the instruction's
7895 binary representation.
7897 This function should be used to update object code that was compiled with
7898 NASM from assembly source code. Example:
7902 mov eax, strict dword 0 ; the imm32 zero operand will be patched
7908 X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7909 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7911 @param[out] InstructionEnd Pointer right past the instruction to patch. The
7912 immediate operand to patch is expected to
7913 comprise the trailing bytes of the instruction.
7914 If InstructionEnd is closer to address 0 than
7915 ValueSize permits, then ASSERT().
7917 @param[in] PatchValue The constant to write to the immediate operand.
7918 The caller is responsible for ensuring that
7919 PatchValue can be represented in the byte, word,
7920 dword or qword operand (as indicated through
7921 ValueSize); otherwise ASSERT().
7923 @param[in] ValueSize The size of the operand in bytes; must be 1, 2,
7924 4, or 8. ASSERT() otherwise.
7928 PatchInstructionX86 (
7929 OUT X86_ASSEMBLY_PATCH_LABEL
*InstructionEnd
,
7930 IN UINT64 PatchValue
,
7934 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7935 #endif // !defined (__BASE_LIB__)