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 This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php.
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
21 // Definitions for architecture-specific types
23 #if defined (MDE_CPU_IA32)
25 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
35 } BASE_LIBRARY_JUMP_BUFFER
;
37 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
39 #endif // defined (MDE_CPU_IA32)
41 #if defined (MDE_CPU_X64)
43 /// The x64 architecture context buffer used by SetJump() and LongJump().
57 UINT8 XmmBuffer
[160]; ///< XMM6-XMM15.
59 } BASE_LIBRARY_JUMP_BUFFER
;
61 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
63 #endif // defined (MDE_CPU_X64)
65 #if defined (MDE_CPU_EBC)
67 /// The EBC context buffer used by SetJump() and LongJump().
75 } BASE_LIBRARY_JUMP_BUFFER
;
77 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
79 #endif // defined (MDE_CPU_EBC)
81 #if defined (MDE_CPU_ARM)
84 UINT32 R3
; ///< A copy of R13.
95 } BASE_LIBRARY_JUMP_BUFFER
;
97 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
99 #endif // defined (MDE_CPU_ARM)
101 #if defined (MDE_CPU_AARCH64)
127 } BASE_LIBRARY_JUMP_BUFFER
;
129 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
131 #endif // defined (MDE_CPU_AARCH64)
140 Returns the length of a Null-terminated Unicode string.
142 This function is similar as strlen_s defined in C11.
144 If String is not aligned on a 16-bit boundary, then ASSERT().
146 @param String A pointer to a Null-terminated Unicode string.
147 @param MaxSize The maximum number of Destination Unicode
148 char, including terminating null char.
150 @retval 0 If String is NULL.
151 @retval MaxSize If there is no null character in the first MaxSize characters of String.
152 @return The number of characters that percede the terminating null character.
158 IN CONST CHAR16
*String
,
163 Returns the size of a Null-terminated Unicode string in bytes, including the
166 This function returns the size of the Null-terminated Unicode string
167 specified by String in bytes, including the Null terminator.
169 If String is not aligned on a 16-bit boundary, then ASSERT().
171 @param String A pointer to a Null-terminated Unicode string.
172 @param MaxSize The maximum number of Destination Unicode
173 char, including the Null terminator.
175 @retval 0 If String is NULL.
176 @retval (sizeof (CHAR16) * (MaxSize + 1))
177 If there is no Null terminator in the first MaxSize characters of
179 @return The size of the Null-terminated Unicode string in bytes, including
186 IN CONST CHAR16
*String
,
191 Copies the string pointed to by Source (including the terminating null char)
192 to the array pointed to by Destination.
194 This function is similar as strcpy_s defined in C11.
196 If Destination is not aligned on a 16-bit boundary, then ASSERT().
197 If Source is not aligned on a 16-bit boundary, then ASSERT().
198 If an error would be returned, then the function will also ASSERT().
200 If an error is returned, then the Destination is unmodified.
202 @param Destination A pointer to a Null-terminated Unicode string.
203 @param DestMax The maximum number of Destination Unicode
204 char, including terminating null char.
205 @param Source A pointer to a Null-terminated Unicode string.
207 @retval RETURN_SUCCESS String is copied.
208 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
209 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
211 If PcdMaximumUnicodeStringLength is not zero,
212 and DestMax is greater than
213 PcdMaximumUnicodeStringLength.
215 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
220 OUT CHAR16
*Destination
,
222 IN CONST CHAR16
*Source
226 Copies not more than Length successive char from the string pointed to by
227 Source to the array pointed to by Destination. If no null char is copied from
228 Source, then Destination[Length] is always set to null.
230 This function is similar as strncpy_s defined in C11.
232 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
233 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
234 If an error would be returned, then the function will also ASSERT().
236 If an error is returned, then the Destination is unmodified.
238 @param Destination A pointer to a Null-terminated Unicode string.
239 @param DestMax The maximum number of Destination Unicode
240 char, including terminating null char.
241 @param Source A pointer to a Null-terminated Unicode string.
242 @param Length The maximum number of Unicode characters to copy.
244 @retval RETURN_SUCCESS String is copied.
245 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
246 MIN(StrLen(Source), Length).
247 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
249 If PcdMaximumUnicodeStringLength is not zero,
250 and DestMax is greater than
251 PcdMaximumUnicodeStringLength.
253 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
258 OUT CHAR16
*Destination
,
260 IN CONST CHAR16
*Source
,
265 Appends a copy of the string pointed to by Source (including the terminating
266 null char) to the end of the string pointed to by Destination.
268 This function is similar as strcat_s defined in C11.
270 If Destination is not aligned on a 16-bit boundary, then ASSERT().
271 If Source is not aligned on a 16-bit boundary, then ASSERT().
272 If an error would be returned, then the function will also ASSERT().
274 If an error is returned, then the Destination is unmodified.
276 @param Destination A pointer to a Null-terminated Unicode string.
277 @param DestMax The maximum number of Destination Unicode
278 char, including terminating null char.
279 @param Source A pointer to a Null-terminated Unicode string.
281 @retval RETURN_SUCCESS String is appended.
282 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
284 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
285 greater than StrLen(Source).
286 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
288 If PcdMaximumUnicodeStringLength is not zero,
289 and DestMax is greater than
290 PcdMaximumUnicodeStringLength.
292 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
297 IN OUT CHAR16
*Destination
,
299 IN CONST CHAR16
*Source
303 Appends not more than Length successive char from the string pointed to by
304 Source to the end of the string pointed to by Destination. If no null char is
305 copied from Source, then Destination[StrLen(Destination) + Length] is always
308 This function is similar as strncat_s defined in C11.
310 If Destination is not aligned on a 16-bit boundary, then ASSERT().
311 If Source is not aligned on a 16-bit boundary, then ASSERT().
312 If an error would be returned, then the function will also ASSERT().
314 If an error is returned, then the Destination is unmodified.
316 @param Destination A pointer to a Null-terminated Unicode string.
317 @param DestMax The maximum number of Destination Unicode
318 char, including terminating null char.
319 @param Source A pointer to a Null-terminated Unicode string.
320 @param Length The maximum number of Unicode characters to copy.
322 @retval RETURN_SUCCESS String is appended.
323 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
325 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
326 greater than MIN(StrLen(Source), Length).
327 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
329 If PcdMaximumUnicodeStringLength is not zero,
330 and DestMax is greater than
331 PcdMaximumUnicodeStringLength.
333 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
338 IN OUT CHAR16
*Destination
,
340 IN CONST CHAR16
*Source
,
345 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
347 This function outputs a value of type UINTN by interpreting the contents of
348 the Unicode string specified by String as a decimal number. The format of the
349 input Unicode string String is:
351 [spaces] [decimal digits].
353 The valid decimal digit character is in the range [0-9]. The function will
354 ignore the pad space, which includes spaces or tab characters, before
355 [decimal digits]. The running zero in the beginning of [decimal digits] will
356 be ignored. Then, the function stops at the first character that is a not a
357 valid decimal character or a Null-terminator, whichever one comes first.
359 If String is NULL, then ASSERT().
360 If Data is NULL, then ASSERT().
361 If String is not aligned in a 16-bit boundary, then ASSERT().
362 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
363 PcdMaximumUnicodeStringLength Unicode characters, not including the
364 Null-terminator, then ASSERT().
366 If String has no valid decimal digits in the above format, then 0 is stored
367 at the location pointed to by Data.
368 If the number represented by String exceeds the range defined by UINTN, then
369 MAX_UINTN is stored at the location pointed to by Data.
371 If EndPointer is not NULL, a pointer to the character that stopped the scan
372 is stored at the location pointed to by EndPointer. If String has no valid
373 decimal digits right after the optional pad spaces, the value of String is
374 stored at the location pointed to by EndPointer.
376 @param String Pointer to a Null-terminated Unicode string.
377 @param EndPointer Pointer to character that stops scan.
378 @param Data Pointer to the converted value.
380 @retval RETURN_SUCCESS Value is translated from String.
381 @retval RETURN_INVALID_PARAMETER If String is NULL.
383 If PcdMaximumUnicodeStringLength is not
384 zero, and String contains more than
385 PcdMaximumUnicodeStringLength Unicode
386 characters, not including the
388 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
389 the range defined by UINTN.
395 IN CONST CHAR16
*String
,
396 OUT CHAR16
**EndPointer
, OPTIONAL
401 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
403 This function outputs a value of type UINT64 by interpreting the contents of
404 the Unicode string specified by String as a decimal number. The format of the
405 input Unicode string String is:
407 [spaces] [decimal digits].
409 The valid decimal digit character is in the range [0-9]. The function will
410 ignore the pad space, which includes spaces or tab characters, before
411 [decimal digits]. The running zero in the beginning of [decimal digits] will
412 be ignored. Then, the function stops at the first character that is a not a
413 valid decimal character or a Null-terminator, whichever one comes first.
415 If String is NULL, then ASSERT().
416 If Data is NULL, then ASSERT().
417 If String is not aligned in a 16-bit boundary, then ASSERT().
418 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
419 PcdMaximumUnicodeStringLength Unicode characters, not including the
420 Null-terminator, then ASSERT().
422 If String has no valid decimal digits in the above format, then 0 is stored
423 at the location pointed to by Data.
424 If the number represented by String exceeds the range defined by UINT64, then
425 MAX_UINT64 is stored at the location pointed to by Data.
427 If EndPointer is not NULL, a pointer to the character that stopped the scan
428 is stored at the location pointed to by EndPointer. If String has no valid
429 decimal digits right after the optional pad spaces, the value of String is
430 stored at the location pointed to by EndPointer.
432 @param String Pointer to a Null-terminated Unicode string.
433 @param EndPointer Pointer to character that stops scan.
434 @param Data Pointer to the converted value.
436 @retval RETURN_SUCCESS Value is translated from String.
437 @retval RETURN_INVALID_PARAMETER If String is NULL.
439 If PcdMaximumUnicodeStringLength is not
440 zero, and String contains more than
441 PcdMaximumUnicodeStringLength Unicode
442 characters, not including the
444 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
445 the range defined by UINT64.
450 StrDecimalToUint64S (
451 IN CONST CHAR16
*String
,
452 OUT CHAR16
**EndPointer
, OPTIONAL
457 Convert a Null-terminated Unicode hexadecimal string to a value of type
460 This function outputs a value of type UINTN by interpreting the contents of
461 the Unicode string specified by String as a hexadecimal number. The format of
462 the input Unicode string String is:
464 [spaces][zeros][x][hexadecimal digits].
466 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
467 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
468 If "x" appears in the input string, it must be prefixed with at least one 0.
469 The function will ignore the pad space, which includes spaces or tab
470 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
471 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
472 after [x] or the first valid hexadecimal digit. Then, the function stops at
473 the first character that is a not a valid hexadecimal character or NULL,
474 whichever one comes first.
476 If String is NULL, then ASSERT().
477 If Data is NULL, then ASSERT().
478 If String is not aligned in a 16-bit boundary, then ASSERT().
479 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
480 PcdMaximumUnicodeStringLength Unicode characters, not including the
481 Null-terminator, then ASSERT().
483 If String has no valid hexadecimal digits in the above format, then 0 is
484 stored at the location pointed to by Data.
485 If the number represented by String exceeds the range defined by UINTN, then
486 MAX_UINTN is stored at the location pointed to by Data.
488 If EndPointer is not NULL, a pointer to the character that stopped the scan
489 is stored at the location pointed to by EndPointer. If String has no valid
490 hexadecimal digits right after the optional pad spaces, the value of String
491 is stored at the location pointed to by EndPointer.
493 @param String Pointer to a Null-terminated Unicode string.
494 @param EndPointer Pointer to character that stops scan.
495 @param Data Pointer to the converted value.
497 @retval RETURN_SUCCESS Value is translated from String.
498 @retval RETURN_INVALID_PARAMETER If String is NULL.
500 If PcdMaximumUnicodeStringLength is not
501 zero, and String contains more than
502 PcdMaximumUnicodeStringLength Unicode
503 characters, not including the
505 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
506 the range defined by UINTN.
512 IN CONST CHAR16
*String
,
513 OUT CHAR16
**EndPointer
, OPTIONAL
518 Convert a Null-terminated Unicode hexadecimal string to a value of type
521 This function outputs a value of type UINT64 by interpreting the contents of
522 the Unicode string specified by String as a hexadecimal number. The format of
523 the input Unicode string String is:
525 [spaces][zeros][x][hexadecimal digits].
527 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
528 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
529 If "x" appears in the input string, it must be prefixed with at least one 0.
530 The function will ignore the pad space, which includes spaces or tab
531 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
532 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
533 after [x] or the first valid hexadecimal digit. Then, the function stops at
534 the first character that is a not a valid hexadecimal character or NULL,
535 whichever one comes first.
537 If String is NULL, then ASSERT().
538 If Data is NULL, then ASSERT().
539 If String is not aligned in a 16-bit boundary, then ASSERT().
540 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
541 PcdMaximumUnicodeStringLength Unicode characters, not including the
542 Null-terminator, then ASSERT().
544 If String has no valid hexadecimal digits in the above format, then 0 is
545 stored at the location pointed to by Data.
546 If the number represented by String exceeds the range defined by UINT64, then
547 MAX_UINT64 is stored at the location pointed to by Data.
549 If EndPointer is not NULL, a pointer to the character that stopped the scan
550 is stored at the location pointed to by EndPointer. If String has no valid
551 hexadecimal digits right after the optional pad spaces, the value of String
552 is stored at the location pointed to by EndPointer.
554 @param String Pointer to a Null-terminated Unicode string.
555 @param EndPointer Pointer to character that stops scan.
556 @param Data Pointer to the converted value.
558 @retval RETURN_SUCCESS Value is translated from String.
559 @retval RETURN_INVALID_PARAMETER If String is NULL.
561 If PcdMaximumUnicodeStringLength is not
562 zero, and String contains more than
563 PcdMaximumUnicodeStringLength Unicode
564 characters, not including the
566 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
567 the range defined by UINT64.
573 IN CONST CHAR16
*String
,
574 OUT CHAR16
**EndPointer
, OPTIONAL
579 Returns the length of a Null-terminated Ascii string.
581 This function is similar as strlen_s defined in C11.
583 @param String A pointer to a Null-terminated Ascii string.
584 @param MaxSize The maximum number of Destination Ascii
585 char, including terminating null char.
587 @retval 0 If String is NULL.
588 @retval MaxSize If there is no null character in the first MaxSize characters of String.
589 @return The number of characters that percede the terminating null character.
595 IN CONST CHAR8
*String
,
600 Returns the size of a Null-terminated Ascii string in bytes, including the
603 This function returns the size of the Null-terminated Ascii string specified
604 by String in bytes, including the Null terminator.
606 @param String A pointer to a Null-terminated Ascii string.
607 @param MaxSize The maximum number of Destination Ascii
608 char, including the Null terminator.
610 @retval 0 If String is NULL.
611 @retval (sizeof (CHAR8) * (MaxSize + 1))
612 If there is no Null terminator in the first MaxSize characters of
614 @return The size of the Null-terminated Ascii string in bytes, including the
621 IN CONST CHAR8
*String
,
626 Copies the string pointed to by Source (including the terminating null char)
627 to the array pointed to by Destination.
629 This function is similar as strcpy_s defined in C11.
631 If an error would be returned, then the function will also ASSERT().
633 If an error is returned, then the Destination is unmodified.
635 @param Destination A pointer to a Null-terminated Ascii string.
636 @param DestMax The maximum number of Destination Ascii
637 char, including terminating null char.
638 @param Source A pointer to a Null-terminated Ascii string.
640 @retval RETURN_SUCCESS String is copied.
641 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
642 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
644 If PcdMaximumAsciiStringLength is not zero,
645 and DestMax is greater than
646 PcdMaximumAsciiStringLength.
648 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
653 OUT CHAR8
*Destination
,
655 IN CONST CHAR8
*Source
659 Copies not more than Length successive char from the string pointed to by
660 Source to the array pointed to by Destination. If no null char is copied from
661 Source, then Destination[Length] is always set to null.
663 This function is similar as strncpy_s defined in C11.
665 If an error would be returned, then the function will also ASSERT().
667 If an error is returned, then the Destination is unmodified.
669 @param Destination A pointer to a Null-terminated Ascii string.
670 @param DestMax The maximum number of Destination Ascii
671 char, including terminating null char.
672 @param Source A pointer to a Null-terminated Ascii string.
673 @param Length The maximum number of Ascii characters to copy.
675 @retval RETURN_SUCCESS String is copied.
676 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
677 MIN(StrLen(Source), Length).
678 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
680 If PcdMaximumAsciiStringLength is not zero,
681 and DestMax is greater than
682 PcdMaximumAsciiStringLength.
684 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
689 OUT CHAR8
*Destination
,
691 IN CONST CHAR8
*Source
,
696 Appends a copy of the string pointed to by Source (including the terminating
697 null char) to the end of the string pointed to by Destination.
699 This function is similar as strcat_s defined in C11.
701 If an error would be returned, then the function will also ASSERT().
703 If an error is returned, then the Destination is unmodified.
705 @param Destination A pointer to a Null-terminated Ascii string.
706 @param DestMax The maximum number of Destination Ascii
707 char, including terminating null char.
708 @param Source A pointer to a Null-terminated Ascii string.
710 @retval RETURN_SUCCESS String is appended.
711 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
713 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
714 greater than StrLen(Source).
715 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
717 If PcdMaximumAsciiStringLength is not zero,
718 and DestMax is greater than
719 PcdMaximumAsciiStringLength.
721 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
726 IN OUT CHAR8
*Destination
,
728 IN CONST CHAR8
*Source
732 Appends not more than Length successive char from the string pointed to by
733 Source to the end of the string pointed to by Destination. If no null char is
734 copied from Source, then Destination[StrLen(Destination) + Length] is always
737 This function is similar as strncat_s defined in C11.
739 If an error would be returned, then the function will also ASSERT().
741 If an error is returned, then the Destination is unmodified.
743 @param Destination A pointer to a Null-terminated Ascii string.
744 @param DestMax The maximum number of Destination Ascii
745 char, including terminating null char.
746 @param Source A pointer to a Null-terminated Ascii string.
747 @param Length The maximum number of Ascii characters to copy.
749 @retval RETURN_SUCCESS String is appended.
750 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
752 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
753 greater than MIN(StrLen(Source), Length).
754 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
756 If PcdMaximumAsciiStringLength is not zero,
757 and DestMax is greater than
758 PcdMaximumAsciiStringLength.
760 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
765 IN OUT CHAR8
*Destination
,
767 IN CONST CHAR8
*Source
,
772 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
774 This function outputs a value of type UINTN by interpreting the contents of
775 the Ascii string specified by String as a decimal number. The format of the
776 input Ascii string String is:
778 [spaces] [decimal digits].
780 The valid decimal digit character is in the range [0-9]. The function will
781 ignore the pad space, which includes spaces or tab characters, before
782 [decimal digits]. The running zero in the beginning of [decimal digits] will
783 be ignored. Then, the function stops at the first character that is a not a
784 valid decimal character or a Null-terminator, whichever one comes first.
786 If String is NULL, then ASSERT().
787 If Data is NULL, then ASSERT().
788 If PcdMaximumAsciiStringLength is not zero, and String contains more than
789 PcdMaximumAsciiStringLength Ascii characters, not including the
790 Null-terminator, then ASSERT().
792 If String has no valid decimal digits in the above format, then 0 is stored
793 at the location pointed to by Data.
794 If the number represented by String exceeds the range defined by UINTN, then
795 MAX_UINTN is stored at the location pointed to by Data.
797 If EndPointer is not NULL, a pointer to the character that stopped the scan
798 is stored at the location pointed to by EndPointer. If String has no valid
799 decimal digits right after the optional pad spaces, the value of String is
800 stored at the location pointed to by EndPointer.
802 @param String Pointer to a Null-terminated Ascii string.
803 @param EndPointer Pointer to character that stops scan.
804 @param Data Pointer to the converted value.
806 @retval RETURN_SUCCESS Value is translated from String.
807 @retval RETURN_INVALID_PARAMETER If String is NULL.
809 If PcdMaximumAsciiStringLength is not zero,
810 and String contains more than
811 PcdMaximumAsciiStringLength Ascii
812 characters, not including the
814 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
815 the range defined by UINTN.
820 AsciiStrDecimalToUintnS (
821 IN CONST CHAR8
*String
,
822 OUT CHAR8
**EndPointer
, OPTIONAL
827 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
829 This function outputs a value of type UINT64 by interpreting the contents of
830 the Ascii string specified by String as a decimal number. The format of the
831 input Ascii string String is:
833 [spaces] [decimal digits].
835 The valid decimal digit character is in the range [0-9]. The function will
836 ignore the pad space, which includes spaces or tab characters, before
837 [decimal digits]. The running zero in the beginning of [decimal digits] will
838 be ignored. Then, the function stops at the first character that is a not a
839 valid decimal character or a Null-terminator, whichever one comes first.
841 If String is NULL, then ASSERT().
842 If Data is NULL, then ASSERT().
843 If PcdMaximumAsciiStringLength is not zero, and String contains more than
844 PcdMaximumAsciiStringLength Ascii characters, not including the
845 Null-terminator, then ASSERT().
847 If String has no valid decimal digits in the above format, then 0 is stored
848 at the location pointed to by Data.
849 If the number represented by String exceeds the range defined by UINT64, then
850 MAX_UINT64 is stored at the location pointed to by Data.
852 If EndPointer is not NULL, a pointer to the character that stopped the scan
853 is stored at the location pointed to by EndPointer. If String has no valid
854 decimal digits right after the optional pad spaces, the value of String is
855 stored at the location pointed to by EndPointer.
857 @param String Pointer to a Null-terminated Ascii string.
858 @param EndPointer Pointer to character that stops scan.
859 @param Data Pointer to the converted value.
861 @retval RETURN_SUCCESS Value is translated from String.
862 @retval RETURN_INVALID_PARAMETER If String is NULL.
864 If PcdMaximumAsciiStringLength is not zero,
865 and String contains more than
866 PcdMaximumAsciiStringLength Ascii
867 characters, not including the
869 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
870 the range defined by UINT64.
875 AsciiStrDecimalToUint64S (
876 IN CONST CHAR8
*String
,
877 OUT CHAR8
**EndPointer
, OPTIONAL
882 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
884 This function outputs a value of type UINTN by interpreting the contents of
885 the Ascii string specified by String as a hexadecimal number. The format of
886 the input Ascii string String is:
888 [spaces][zeros][x][hexadecimal digits].
890 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
891 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
892 "x" appears in the input string, it must be prefixed with at least one 0. The
893 function will ignore the pad space, which includes spaces or tab characters,
894 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
895 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
896 the first valid hexadecimal digit. Then, the function stops at the first
897 character that is a not a valid hexadecimal character or Null-terminator,
898 whichever on comes first.
900 If String is NULL, then ASSERT().
901 If Data is NULL, then ASSERT().
902 If PcdMaximumAsciiStringLength is not zero, and String contains more than
903 PcdMaximumAsciiStringLength Ascii characters, not including the
904 Null-terminator, then ASSERT().
906 If String has no valid hexadecimal digits in the above format, then 0 is
907 stored at the location pointed to by Data.
908 If the number represented by String exceeds the range defined by UINTN, then
909 MAX_UINTN is stored at the location pointed to by Data.
911 If EndPointer is not NULL, a pointer to the character that stopped the scan
912 is stored at the location pointed to by EndPointer. If String has no valid
913 hexadecimal digits right after the optional pad spaces, the value of String
914 is stored at the location pointed to by EndPointer.
916 @param String Pointer to a Null-terminated Ascii string.
917 @param EndPointer Pointer to character that stops scan.
918 @param Data Pointer to the converted value.
920 @retval RETURN_SUCCESS Value is translated from String.
921 @retval RETURN_INVALID_PARAMETER If String is NULL.
923 If PcdMaximumAsciiStringLength is not zero,
924 and String contains more than
925 PcdMaximumAsciiStringLength Ascii
926 characters, not including the
928 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
929 the range defined by UINTN.
934 AsciiStrHexToUintnS (
935 IN CONST CHAR8
*String
,
936 OUT CHAR8
**EndPointer
, OPTIONAL
941 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
943 This function outputs a value of type UINT64 by interpreting the contents of
944 the Ascii string specified by String as a hexadecimal number. The format of
945 the input Ascii string String is:
947 [spaces][zeros][x][hexadecimal digits].
949 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
950 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
951 "x" appears in the input string, it must be prefixed with at least one 0. The
952 function will ignore the pad space, which includes spaces or tab characters,
953 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
954 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
955 the first valid hexadecimal digit. Then, the function stops at the first
956 character that is a not a valid hexadecimal character or Null-terminator,
957 whichever on comes first.
959 If String is NULL, then ASSERT().
960 If Data is NULL, then ASSERT().
961 If PcdMaximumAsciiStringLength is not zero, and String contains more than
962 PcdMaximumAsciiStringLength Ascii characters, not including the
963 Null-terminator, then ASSERT().
965 If String has no valid hexadecimal digits in the above format, then 0 is
966 stored at the location pointed to by Data.
967 If the number represented by String exceeds the range defined by UINT64, then
968 MAX_UINT64 is stored at the location pointed to by Data.
970 If EndPointer is not NULL, a pointer to the character that stopped the scan
971 is stored at the location pointed to by EndPointer. If String has no valid
972 hexadecimal digits right after the optional pad spaces, the value of String
973 is stored at the location pointed to by EndPointer.
975 @param String Pointer to a Null-terminated Ascii string.
976 @param EndPointer Pointer to character that stops scan.
977 @param Data Pointer to the converted value.
979 @retval RETURN_SUCCESS Value is translated from String.
980 @retval RETURN_INVALID_PARAMETER If String is NULL.
982 If PcdMaximumAsciiStringLength is not zero,
983 and String contains more than
984 PcdMaximumAsciiStringLength Ascii
985 characters, not including the
987 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
988 the range defined by UINT64.
993 AsciiStrHexToUint64S (
994 IN CONST CHAR8
*String
,
995 OUT CHAR8
**EndPointer
, OPTIONAL
1000 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1003 [ATTENTION] This function is deprecated for security reason.
1005 Copies one Null-terminated Unicode string to another Null-terminated Unicode
1006 string and returns the new Unicode string.
1008 This function copies the contents of the Unicode string Source to the Unicode
1009 string Destination, and returns Destination. If Source and Destination
1010 overlap, then the results are undefined.
1012 If Destination is NULL, then ASSERT().
1013 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1014 If Source is NULL, then ASSERT().
1015 If Source is not aligned on a 16-bit boundary, then ASSERT().
1016 If Source and Destination overlap, then ASSERT().
1017 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1018 PcdMaximumUnicodeStringLength Unicode characters not including the
1019 Null-terminator, then ASSERT().
1021 @param Destination The pointer to a Null-terminated Unicode string.
1022 @param Source The pointer to a Null-terminated Unicode string.
1024 @return Destination.
1030 OUT CHAR16
*Destination
,
1031 IN CONST CHAR16
*Source
1036 [ATTENTION] This function is deprecated for security reason.
1038 Copies up to a specified length from one Null-terminated Unicode string to
1039 another Null-terminated Unicode string and returns the new Unicode string.
1041 This function copies the contents of the Unicode string Source to the Unicode
1042 string Destination, and returns Destination. At most, Length Unicode
1043 characters are copied from Source to Destination. If Length is 0, then
1044 Destination is returned unmodified. If Length is greater that the number of
1045 Unicode characters in Source, then Destination is padded with Null Unicode
1046 characters. If Source and Destination overlap, then the results are
1049 If Length > 0 and Destination is NULL, then ASSERT().
1050 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1051 If Length > 0 and Source is NULL, then ASSERT().
1052 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1053 If Source and Destination overlap, then ASSERT().
1054 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1055 PcdMaximumUnicodeStringLength, then ASSERT().
1056 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1057 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1060 @param Destination The pointer to a Null-terminated Unicode string.
1061 @param Source The pointer to a Null-terminated Unicode string.
1062 @param Length The maximum number of Unicode characters to copy.
1064 @return Destination.
1070 OUT CHAR16
*Destination
,
1071 IN CONST CHAR16
*Source
,
1074 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1077 Returns the length of a Null-terminated Unicode string.
1079 This function returns the number of Unicode characters in the Null-terminated
1080 Unicode string specified by String.
1082 If String is NULL, then ASSERT().
1083 If String is not aligned on a 16-bit boundary, then ASSERT().
1084 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1085 PcdMaximumUnicodeStringLength Unicode characters not including the
1086 Null-terminator, then ASSERT().
1088 @param String Pointer to a Null-terminated Unicode string.
1090 @return The length of String.
1096 IN CONST CHAR16
*String
1101 Returns the size of a Null-terminated Unicode string in bytes, including the
1104 This function returns the size, in bytes, of the Null-terminated Unicode string
1105 specified by String.
1107 If String is NULL, then ASSERT().
1108 If String is not aligned on a 16-bit boundary, then ASSERT().
1109 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1110 PcdMaximumUnicodeStringLength Unicode characters not including the
1111 Null-terminator, then ASSERT().
1113 @param String The pointer to a Null-terminated Unicode string.
1115 @return The size of String.
1121 IN CONST CHAR16
*String
1126 Compares two Null-terminated Unicode strings, and returns the difference
1127 between the first mismatched Unicode characters.
1129 This function compares the Null-terminated Unicode string FirstString to the
1130 Null-terminated Unicode string SecondString. If FirstString is identical to
1131 SecondString, then 0 is returned. Otherwise, the value returned is the first
1132 mismatched Unicode character in SecondString subtracted from the first
1133 mismatched Unicode character in FirstString.
1135 If FirstString is NULL, then ASSERT().
1136 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1137 If SecondString is NULL, then ASSERT().
1138 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1139 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1140 than PcdMaximumUnicodeStringLength Unicode characters not including the
1141 Null-terminator, then ASSERT().
1142 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1143 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1144 Null-terminator, then ASSERT().
1146 @param FirstString The pointer to a Null-terminated Unicode string.
1147 @param SecondString The pointer to a Null-terminated Unicode string.
1149 @retval 0 FirstString is identical to SecondString.
1150 @return others FirstString is not identical to SecondString.
1156 IN CONST CHAR16
*FirstString
,
1157 IN CONST CHAR16
*SecondString
1162 Compares up to a specified length the contents of two Null-terminated Unicode strings,
1163 and returns the difference between the first mismatched Unicode characters.
1165 This function compares the Null-terminated Unicode string FirstString to the
1166 Null-terminated Unicode string SecondString. At most, Length Unicode
1167 characters will be compared. If Length is 0, then 0 is returned. If
1168 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1169 value returned is the first mismatched Unicode character in SecondString
1170 subtracted from the first mismatched Unicode character in FirstString.
1172 If Length > 0 and FirstString is NULL, then ASSERT().
1173 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1174 If Length > 0 and SecondString is NULL, then ASSERT().
1175 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1176 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1177 PcdMaximumUnicodeStringLength, then ASSERT().
1178 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1179 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1181 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1182 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1185 @param FirstString The pointer to a Null-terminated Unicode string.
1186 @param SecondString The pointer to a Null-terminated Unicode string.
1187 @param Length The maximum number of Unicode characters to compare.
1189 @retval 0 FirstString is identical to SecondString.
1190 @return others FirstString is not identical to SecondString.
1196 IN CONST CHAR16
*FirstString
,
1197 IN CONST CHAR16
*SecondString
,
1202 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1205 [ATTENTION] This function is deprecated for security reason.
1207 Concatenates one Null-terminated Unicode string to another Null-terminated
1208 Unicode string, and returns the concatenated Unicode string.
1210 This function concatenates two Null-terminated Unicode strings. The contents
1211 of Null-terminated Unicode string Source are concatenated to the end of
1212 Null-terminated Unicode string Destination. The Null-terminated concatenated
1213 Unicode String is returned. If Source and Destination overlap, then the
1214 results are undefined.
1216 If Destination is NULL, then ASSERT().
1217 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1218 If Source is NULL, then ASSERT().
1219 If Source is not aligned on a 16-bit boundary, then ASSERT().
1220 If Source and Destination overlap, then ASSERT().
1221 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1222 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1223 Null-terminator, then ASSERT().
1224 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1225 PcdMaximumUnicodeStringLength Unicode characters, not including the
1226 Null-terminator, then ASSERT().
1227 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1228 and Source results in a Unicode string with more than
1229 PcdMaximumUnicodeStringLength Unicode characters, not including the
1230 Null-terminator, then ASSERT().
1232 @param Destination The pointer to a Null-terminated Unicode string.
1233 @param Source The pointer to a Null-terminated Unicode string.
1235 @return Destination.
1241 IN OUT CHAR16
*Destination
,
1242 IN CONST CHAR16
*Source
1247 [ATTENTION] This function is deprecated for security reason.
1249 Concatenates up to a specified length one Null-terminated Unicode to the end
1250 of another Null-terminated Unicode string, and returns the concatenated
1253 This function concatenates two Null-terminated Unicode strings. The contents
1254 of Null-terminated Unicode string Source are concatenated to the end of
1255 Null-terminated Unicode string Destination, and Destination is returned. At
1256 most, Length Unicode characters are concatenated from Source to the end of
1257 Destination, and Destination is always Null-terminated. If Length is 0, then
1258 Destination is returned unmodified. If Source and Destination overlap, then
1259 the results are undefined.
1261 If Destination is NULL, then ASSERT().
1262 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1263 If Length > 0 and Source is NULL, then ASSERT().
1264 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1265 If Source and Destination overlap, then ASSERT().
1266 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1267 PcdMaximumUnicodeStringLength, then ASSERT().
1268 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1269 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1270 Null-terminator, then ASSERT().
1271 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1272 PcdMaximumUnicodeStringLength Unicode characters, not including the
1273 Null-terminator, then ASSERT().
1274 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1275 and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength
1276 Unicode characters, not including the Null-terminator, then ASSERT().
1278 @param Destination The pointer to a Null-terminated Unicode string.
1279 @param Source The pointer to a Null-terminated Unicode string.
1280 @param Length The maximum number of Unicode characters to concatenate from
1283 @return Destination.
1289 IN OUT CHAR16
*Destination
,
1290 IN CONST CHAR16
*Source
,
1293 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1296 Returns the first occurrence of a Null-terminated Unicode sub-string
1297 in a Null-terminated Unicode string.
1299 This function scans the contents of the Null-terminated Unicode string
1300 specified by String and returns the first occurrence of SearchString.
1301 If SearchString is not found in String, then NULL is returned. If
1302 the length of SearchString is zero, then String is returned.
1304 If String is NULL, then ASSERT().
1305 If String is not aligned on a 16-bit boundary, then ASSERT().
1306 If SearchString is NULL, then ASSERT().
1307 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1309 If PcdMaximumUnicodeStringLength is not zero, and SearchString
1310 or String contains more than PcdMaximumUnicodeStringLength Unicode
1311 characters, not including the Null-terminator, then ASSERT().
1313 @param String The pointer to a Null-terminated Unicode string.
1314 @param SearchString The pointer to a Null-terminated Unicode string to search for.
1316 @retval NULL If the SearchString does not appear in String.
1317 @return others If there is a match.
1323 IN CONST CHAR16
*String
,
1324 IN CONST CHAR16
*SearchString
1328 Convert a Null-terminated Unicode decimal string to a value of
1331 This function returns a value of type UINTN by interpreting the contents
1332 of the Unicode string specified by String as a decimal number. The format
1333 of the input Unicode string String is:
1335 [spaces] [decimal digits].
1337 The valid decimal digit character is in the range [0-9]. The
1338 function will ignore the pad space, which includes spaces or
1339 tab characters, before [decimal digits]. The running zero in the
1340 beginning of [decimal digits] will be ignored. Then, the function
1341 stops at the first character that is a not a valid decimal character
1342 or a Null-terminator, whichever one comes first.
1344 If String is NULL, then ASSERT().
1345 If String is not aligned in a 16-bit boundary, then ASSERT().
1346 If String has only pad spaces, then 0 is returned.
1347 If String has no pad spaces or valid decimal digits,
1349 If the number represented by String overflows according
1350 to the range defined by UINTN, then MAX_UINTN is returned.
1352 If PcdMaximumUnicodeStringLength is not zero, and String contains
1353 more than PcdMaximumUnicodeStringLength Unicode characters not including
1354 the Null-terminator, then ASSERT().
1356 @param String The pointer to a Null-terminated Unicode string.
1358 @retval Value translated from String.
1364 IN CONST CHAR16
*String
1368 Convert a Null-terminated Unicode decimal string to a value of
1371 This function returns a value of type UINT64 by interpreting the contents
1372 of the Unicode string specified by String as a decimal number. The format
1373 of the input Unicode string String is:
1375 [spaces] [decimal digits].
1377 The valid decimal digit character is in the range [0-9]. The
1378 function will ignore the pad space, which includes spaces or
1379 tab characters, before [decimal digits]. The running zero in the
1380 beginning of [decimal digits] will be ignored. Then, the function
1381 stops at the first character that is a not a valid decimal character
1382 or a Null-terminator, whichever one comes first.
1384 If String is NULL, then ASSERT().
1385 If String is not aligned in a 16-bit boundary, then ASSERT().
1386 If String has only pad spaces, then 0 is returned.
1387 If String has no pad spaces or valid decimal digits,
1389 If the number represented by String overflows according
1390 to the range defined by UINT64, then MAX_UINT64 is returned.
1392 If PcdMaximumUnicodeStringLength is not zero, and String contains
1393 more than PcdMaximumUnicodeStringLength Unicode characters not including
1394 the Null-terminator, then ASSERT().
1396 @param String The pointer to a Null-terminated Unicode string.
1398 @retval Value translated from String.
1403 StrDecimalToUint64 (
1404 IN CONST CHAR16
*String
1409 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1411 This function returns a value of type UINTN by interpreting the contents
1412 of the Unicode string specified by String as a hexadecimal number.
1413 The format of the input Unicode string String is:
1415 [spaces][zeros][x][hexadecimal digits].
1417 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1418 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1419 If "x" appears in the input string, it must be prefixed with at least one 0.
1420 The function will ignore the pad space, which includes spaces or tab characters,
1421 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1422 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1423 first valid hexadecimal digit. Then, the function stops at the first character
1424 that is a not a valid hexadecimal character or NULL, whichever one comes first.
1426 If String is NULL, then ASSERT().
1427 If String is not aligned in a 16-bit boundary, then ASSERT().
1428 If String has only pad spaces, then zero is returned.
1429 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1430 then zero is returned.
1431 If the number represented by String overflows according to the range defined by
1432 UINTN, then MAX_UINTN is returned.
1434 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1435 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1438 @param String The pointer to a Null-terminated Unicode string.
1440 @retval Value translated from String.
1446 IN CONST CHAR16
*String
1451 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1453 This function returns a value of type UINT64 by interpreting the contents
1454 of the Unicode string specified by String as a hexadecimal number.
1455 The format of the input Unicode string String is
1457 [spaces][zeros][x][hexadecimal digits].
1459 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1460 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1461 If "x" appears in the input string, it must be prefixed with at least one 0.
1462 The function will ignore the pad space, which includes spaces or tab characters,
1463 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1464 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1465 first valid hexadecimal digit. Then, the function stops at the first character that is
1466 a not a valid hexadecimal character or NULL, whichever one comes first.
1468 If String is NULL, then ASSERT().
1469 If String is not aligned in a 16-bit boundary, then ASSERT().
1470 If String has only pad spaces, then zero is returned.
1471 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1472 then zero is returned.
1473 If the number represented by String overflows according to the range defined by
1474 UINT64, then MAX_UINT64 is returned.
1476 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1477 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1480 @param String The pointer to a Null-terminated Unicode string.
1482 @retval Value translated from String.
1488 IN CONST CHAR16
*String
1492 Convert a Null-terminated Unicode string to IPv6 address and prefix length.
1494 This function outputs a value of type IPv6_ADDRESS and may output a value
1495 of type UINT8 by interpreting the contents of the Unicode string specified
1496 by String. The format of the input Unicode string String is as follows:
1500 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
1501 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
1502 memory address and high byte is stored in high memory address. P contains decimal
1503 digit characters in the range [0-9]. The running zero in the beginning of P will
1504 be ignored. /P is optional.
1506 When /P is not in the String, the function stops at the first character that is
1507 not a valid hexadecimal digit character after eight X's are converted.
1509 When /P is in the String, the function stops at the first character that is not
1510 a valid decimal digit character after P is converted.
1512 "::" can be used to compress one or more groups of X when X contains only 0.
1513 The "::" can only appear once in the String.
1515 If String is NULL, then ASSERT().
1517 If Address is NULL, then ASSERT().
1519 If String is not aligned in a 16-bit boundary, then ASSERT().
1521 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1522 PcdMaximumUnicodeStringLength Unicode characters, not including the
1523 Null-terminator, then ASSERT().
1525 If EndPointer is not NULL and Address is translated from String, a pointer
1526 to the character that stopped the scan is stored at the location pointed to
1529 @param String Pointer to a Null-terminated Unicode string.
1530 @param EndPointer Pointer to character that stops scan.
1531 @param Address Pointer to the converted IPv6 address.
1532 @param PrefixLength Pointer to the converted IPv6 address prefix
1533 length. MAX_UINT8 is returned when /P is
1536 @retval RETURN_SUCCESS Address is translated from String.
1537 @retval RETURN_INVALID_PARAMETER If String is NULL.
1539 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
1541 If String contains "::" and number of X
1543 If P starts with character that is not a
1544 valid decimal digit character.
1545 If the decimal number converted from P
1552 IN CONST CHAR16
*String
,
1553 OUT CHAR16
**EndPointer
, OPTIONAL
1554 OUT IPv6_ADDRESS
*Address
,
1555 OUT UINT8
*PrefixLength OPTIONAL
1559 Convert a Null-terminated Unicode string to IPv4 address and prefix length.
1561 This function outputs a value of type IPv4_ADDRESS and may output a value
1562 of type UINT8 by interpreting the contents of the Unicode string specified
1563 by String. The format of the input Unicode string String is as follows:
1567 D and P are decimal digit characters in the range [0-9]. The running zero in
1568 the beginning of D and P will be ignored. /P is optional.
1570 When /P is not in the String, the function stops at the first character that is
1571 not a valid decimal digit character after four D's are converted.
1573 When /P is in the String, the function stops at the first character that is not
1574 a valid decimal digit character after P is converted.
1576 If String is NULL, then ASSERT().
1578 If Address is NULL, then ASSERT().
1580 If String is not aligned in a 16-bit boundary, then ASSERT().
1582 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1583 PcdMaximumUnicodeStringLength Unicode characters, not including the
1584 Null-terminator, then ASSERT().
1586 If EndPointer is not NULL and Address is translated from String, a pointer
1587 to the character that stopped the scan is stored at the location pointed to
1590 @param String Pointer to a Null-terminated Unicode string.
1591 @param EndPointer Pointer to character that stops scan.
1592 @param Address Pointer to the converted IPv4 address.
1593 @param PrefixLength Pointer to the converted IPv4 address prefix
1594 length. MAX_UINT8 is returned when /P is
1597 @retval RETURN_SUCCESS Address is translated from String.
1598 @retval RETURN_INVALID_PARAMETER If String is NULL.
1600 @retval RETURN_UNSUPPORTED If String is not in the correct format.
1601 If any decimal number converted from D
1603 If the decimal number converted from P
1610 IN CONST CHAR16
*String
,
1611 OUT CHAR16
**EndPointer
, OPTIONAL
1612 OUT IPv4_ADDRESS
*Address
,
1613 OUT UINT8
*PrefixLength OPTIONAL
1616 #define GUID_STRING_LENGTH 36
1619 Convert a Null-terminated Unicode GUID string to a value of type
1622 This function outputs a GUID value by interpreting the contents of
1623 the Unicode string specified by String. The format of the input
1624 Unicode string String consists of 36 characters, as follows:
1626 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
1628 The pairs aa - pp are two characters in the range [0-9], [a-f] and
1629 [A-F], with each pair representing a single byte hexadecimal value.
1631 The mapping between String and the EFI_GUID structure is as follows:
1649 If String is NULL, then ASSERT().
1650 If Guid is NULL, then ASSERT().
1651 If String is not aligned in a 16-bit boundary, then ASSERT().
1653 @param String Pointer to a Null-terminated Unicode string.
1654 @param Guid Pointer to the converted GUID.
1656 @retval RETURN_SUCCESS Guid is translated from String.
1657 @retval RETURN_INVALID_PARAMETER If String is NULL.
1659 @retval RETURN_UNSUPPORTED If String is not as the above format.
1665 IN CONST CHAR16
*String
,
1670 Convert a Null-terminated Unicode hexadecimal string to a byte array.
1672 This function outputs a byte array by interpreting the contents of
1673 the Unicode string specified by String in hexadecimal format. The format of
1674 the input Unicode string String is:
1678 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
1679 The function decodes every two hexadecimal digit characters as one byte. The
1680 decoding stops after Length of characters and outputs Buffer containing
1683 If String is not aligned in a 16-bit boundary, then ASSERT().
1685 If String is NULL, then ASSERT().
1687 If Buffer is NULL, then ASSERT().
1689 If Length is not multiple of 2, then ASSERT().
1691 If PcdMaximumUnicodeStringLength is not zero and Length is greater than
1692 PcdMaximumUnicodeStringLength, then ASSERT().
1694 If MaxBufferSize is less than (Length / 2), then ASSERT().
1696 @param String Pointer to a Null-terminated Unicode string.
1697 @param Length The number of Unicode characters to decode.
1698 @param Buffer Pointer to the converted bytes array.
1699 @param MaxBufferSize The maximum size of Buffer.
1701 @retval RETURN_SUCCESS Buffer is translated from String.
1702 @retval RETURN_INVALID_PARAMETER If String is NULL.
1704 If Length is not multiple of 2.
1705 If PcdMaximumUnicodeStringLength is not zero,
1706 and Length is greater than
1707 PcdMaximumUnicodeStringLength.
1708 @retval RETURN_UNSUPPORTED If Length of characters from String contain
1709 a character that is not valid hexadecimal
1710 digit characters, or a Null-terminator.
1711 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
1716 IN CONST CHAR16
*String
,
1719 IN UINTN MaxBufferSize
1722 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1725 [ATTENTION] This function is deprecated for security reason.
1727 Convert a Null-terminated Unicode string to a Null-terminated
1728 ASCII string and returns the ASCII string.
1730 This function converts the content of the Unicode string Source
1731 to the ASCII string Destination by copying the lower 8 bits of
1732 each Unicode character. It returns Destination.
1734 The caller is responsible to make sure Destination points to a buffer with size
1735 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1737 If any Unicode characters in Source contain non-zero value in
1738 the upper 8 bits, then ASSERT().
1740 If Destination is NULL, then ASSERT().
1741 If Source is NULL, then ASSERT().
1742 If Source is not aligned on a 16-bit boundary, then ASSERT().
1743 If Source and Destination overlap, then ASSERT().
1745 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1746 more than PcdMaximumUnicodeStringLength Unicode characters not including
1747 the Null-terminator, then ASSERT().
1749 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1750 than PcdMaximumAsciiStringLength Unicode characters not including the
1751 Null-terminator, then ASSERT().
1753 @param Source The pointer to a Null-terminated Unicode string.
1754 @param Destination The pointer to a Null-terminated ASCII string.
1756 @return Destination.
1761 UnicodeStrToAsciiStr (
1762 IN CONST CHAR16
*Source
,
1763 OUT CHAR8
*Destination
1766 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1769 Convert a Null-terminated Unicode string to a Null-terminated
1772 This function is similar to AsciiStrCpyS.
1774 This function converts the content of the Unicode string Source
1775 to the ASCII string Destination by copying the lower 8 bits of
1776 each Unicode character. The function terminates the ASCII string
1777 Destination by appending a Null-terminator character at the end.
1779 The caller is responsible to make sure Destination points to a buffer with size
1780 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1782 If any Unicode characters in Source contain non-zero value in
1783 the upper 8 bits, then ASSERT().
1785 If Source is not aligned on a 16-bit boundary, then ASSERT().
1786 If an error would be returned, then the function will also ASSERT().
1788 If an error is returned, then the Destination is unmodified.
1790 @param Source The pointer to a Null-terminated Unicode string.
1791 @param Destination The pointer to a Null-terminated ASCII string.
1792 @param DestMax The maximum number of Destination Ascii
1793 char, including terminating null char.
1795 @retval RETURN_SUCCESS String is converted.
1796 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1797 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1799 If PcdMaximumAsciiStringLength is not zero,
1800 and DestMax is greater than
1801 PcdMaximumAsciiStringLength.
1802 If PcdMaximumUnicodeStringLength is not zero,
1803 and DestMax is greater than
1804 PcdMaximumUnicodeStringLength.
1806 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1811 UnicodeStrToAsciiStrS (
1812 IN CONST CHAR16
*Source
,
1813 OUT CHAR8
*Destination
,
1818 Convert not more than Length successive characters from a Null-terminated
1819 Unicode string to a Null-terminated Ascii string. If no null char is copied
1820 from Source, then Destination[Length] is always set to null.
1822 This function converts not more than Length successive characters from the
1823 Unicode string Source to the Ascii string Destination by copying the lower 8
1824 bits of each Unicode character. The function terminates the Ascii string
1825 Destination by appending a Null-terminator character at the end.
1827 The caller is responsible to make sure Destination points to a buffer with size
1828 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1830 If any Unicode characters in Source contain non-zero value in the upper 8
1831 bits, then ASSERT().
1832 If Source is not aligned on a 16-bit boundary, then ASSERT().
1833 If an error would be returned, then the function will also ASSERT().
1835 If an error is returned, then the Destination is unmodified.
1837 @param Source The pointer to a Null-terminated Unicode string.
1838 @param Length The maximum number of Unicode characters to
1840 @param Destination The pointer to a Null-terminated Ascii string.
1841 @param DestMax The maximum number of Destination Ascii
1842 char, including terminating null char.
1843 @param DestinationLength The number of Unicode characters converted.
1845 @retval RETURN_SUCCESS String is converted.
1846 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1848 If DestinationLength is NULL.
1849 If PcdMaximumAsciiStringLength is not zero,
1850 and Length or DestMax is greater than
1851 PcdMaximumAsciiStringLength.
1852 If PcdMaximumUnicodeStringLength is not
1853 zero, and Length or DestMax is greater than
1854 PcdMaximumUnicodeStringLength.
1856 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
1857 MIN(StrLen(Source), Length).
1858 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1863 UnicodeStrnToAsciiStrS (
1864 IN CONST CHAR16
*Source
,
1866 OUT CHAR8
*Destination
,
1868 OUT UINTN
*DestinationLength
1871 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1874 [ATTENTION] This function is deprecated for security reason.
1876 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1877 string and returns the new ASCII string.
1879 This function copies the contents of the ASCII string Source to the ASCII
1880 string Destination, and returns Destination. If Source and Destination
1881 overlap, then the results are undefined.
1883 If Destination is NULL, then ASSERT().
1884 If Source is NULL, then ASSERT().
1885 If Source and Destination overlap, then ASSERT().
1886 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1887 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1890 @param Destination The pointer to a Null-terminated ASCII string.
1891 @param Source The pointer to a Null-terminated ASCII string.
1899 OUT CHAR8
*Destination
,
1900 IN CONST CHAR8
*Source
1905 [ATTENTION] This function is deprecated for security reason.
1907 Copies up to a specified length one Null-terminated ASCII string to another
1908 Null-terminated ASCII string and returns the new ASCII string.
1910 This function copies the contents of the ASCII string Source to the ASCII
1911 string Destination, and returns Destination. At most, Length ASCII characters
1912 are copied from Source to Destination. If Length is 0, then Destination is
1913 returned unmodified. If Length is greater that the number of ASCII characters
1914 in Source, then Destination is padded with Null ASCII characters. If Source
1915 and Destination overlap, then the results are undefined.
1917 If Destination is NULL, then ASSERT().
1918 If Source is NULL, then ASSERT().
1919 If Source and Destination overlap, then ASSERT().
1920 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1921 PcdMaximumAsciiStringLength, then ASSERT().
1922 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1923 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1926 @param Destination The pointer to a Null-terminated ASCII string.
1927 @param Source The pointer to a Null-terminated ASCII string.
1928 @param Length The maximum number of ASCII characters to copy.
1936 OUT CHAR8
*Destination
,
1937 IN CONST CHAR8
*Source
,
1940 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
1943 Returns the length of a Null-terminated ASCII string.
1945 This function returns the number of ASCII characters in the Null-terminated
1946 ASCII string specified by String.
1948 If Length > 0 and Destination is NULL, then ASSERT().
1949 If Length > 0 and Source is NULL, then ASSERT().
1950 If PcdMaximumAsciiStringLength is not zero and String contains more than
1951 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1954 @param String The pointer to a Null-terminated ASCII string.
1956 @return The length of String.
1962 IN CONST CHAR8
*String
1967 Returns the size of a Null-terminated ASCII string in bytes, including the
1970 This function returns the size, in bytes, of the Null-terminated ASCII string
1971 specified by String.
1973 If String is NULL, then ASSERT().
1974 If PcdMaximumAsciiStringLength is not zero and String contains more than
1975 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1978 @param String The pointer to a Null-terminated ASCII string.
1980 @return The size of String.
1986 IN CONST CHAR8
*String
1991 Compares two Null-terminated ASCII strings, and returns the difference
1992 between the first mismatched ASCII characters.
1994 This function compares the Null-terminated ASCII string FirstString to the
1995 Null-terminated ASCII string SecondString. If FirstString is identical to
1996 SecondString, then 0 is returned. Otherwise, the value returned is the first
1997 mismatched ASCII character in SecondString subtracted from the first
1998 mismatched ASCII character in FirstString.
2000 If FirstString is NULL, then ASSERT().
2001 If SecondString is NULL, then ASSERT().
2002 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
2003 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2005 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2006 than PcdMaximumAsciiStringLength ASCII characters not including the
2007 Null-terminator, then ASSERT().
2009 @param FirstString The pointer to a Null-terminated ASCII string.
2010 @param SecondString The pointer to a Null-terminated ASCII string.
2012 @retval ==0 FirstString is identical to SecondString.
2013 @retval !=0 FirstString is not identical to SecondString.
2019 IN CONST CHAR8
*FirstString
,
2020 IN CONST CHAR8
*SecondString
2025 Performs a case insensitive comparison of two Null-terminated ASCII strings,
2026 and returns the difference between the first mismatched ASCII characters.
2028 This function performs a case insensitive comparison of the Null-terminated
2029 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
2030 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
2031 value returned is the first mismatched lower case ASCII character in
2032 SecondString subtracted from the first mismatched lower case ASCII character
2035 If FirstString is NULL, then ASSERT().
2036 If SecondString is NULL, then ASSERT().
2037 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
2038 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2040 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
2041 than PcdMaximumAsciiStringLength ASCII characters not including the
2042 Null-terminator, then ASSERT().
2044 @param FirstString The pointer to a Null-terminated ASCII string.
2045 @param SecondString The pointer to a Null-terminated ASCII string.
2047 @retval ==0 FirstString is identical to SecondString using case insensitive
2049 @retval !=0 FirstString is not identical to SecondString using case
2050 insensitive comparisons.
2056 IN CONST CHAR8
*FirstString
,
2057 IN CONST CHAR8
*SecondString
2062 Compares two Null-terminated ASCII strings with maximum lengths, and returns
2063 the difference between the first mismatched ASCII characters.
2065 This function compares the Null-terminated ASCII string FirstString to the
2066 Null-terminated ASCII string SecondString. At most, Length ASCII characters
2067 will be compared. If Length is 0, then 0 is returned. If FirstString is
2068 identical to SecondString, then 0 is returned. Otherwise, the value returned
2069 is the first mismatched ASCII character in SecondString subtracted from the
2070 first mismatched ASCII character in FirstString.
2072 If Length > 0 and FirstString is NULL, then ASSERT().
2073 If Length > 0 and SecondString is NULL, then ASSERT().
2074 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
2075 PcdMaximumAsciiStringLength, then ASSERT().
2076 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
2077 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2079 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
2080 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2083 @param FirstString The pointer to a Null-terminated ASCII string.
2084 @param SecondString The pointer to a Null-terminated ASCII string.
2085 @param Length The maximum number of ASCII characters for compare.
2087 @retval ==0 FirstString is identical to SecondString.
2088 @retval !=0 FirstString is not identical to SecondString.
2094 IN CONST CHAR8
*FirstString
,
2095 IN CONST CHAR8
*SecondString
,
2100 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2103 [ATTENTION] This function is deprecated for security reason.
2105 Concatenates one Null-terminated ASCII string to another Null-terminated
2106 ASCII string, and returns the concatenated ASCII string.
2108 This function concatenates two Null-terminated ASCII strings. The contents of
2109 Null-terminated ASCII string Source are concatenated to the end of Null-
2110 terminated ASCII string Destination. The Null-terminated concatenated ASCII
2113 If Destination is NULL, then ASSERT().
2114 If Source is NULL, then ASSERT().
2115 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
2116 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2118 If PcdMaximumAsciiStringLength is not zero and Source contains more than
2119 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2121 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
2122 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
2123 ASCII characters, then ASSERT().
2125 @param Destination The pointer to a Null-terminated ASCII string.
2126 @param Source The pointer to a Null-terminated ASCII string.
2134 IN OUT CHAR8
*Destination
,
2135 IN CONST CHAR8
*Source
2140 [ATTENTION] This function is deprecated for security reason.
2142 Concatenates up to a specified length one Null-terminated ASCII string to
2143 the end of another Null-terminated ASCII string, and returns the
2144 concatenated ASCII string.
2146 This function concatenates two Null-terminated ASCII strings. The contents
2147 of Null-terminated ASCII string Source are concatenated to the end of Null-
2148 terminated ASCII string Destination, and Destination is returned. At most,
2149 Length ASCII characters are concatenated from Source to the end of
2150 Destination, and Destination is always Null-terminated. If Length is 0, then
2151 Destination is returned unmodified. If Source and Destination overlap, then
2152 the results are undefined.
2154 If Length > 0 and Destination is NULL, then ASSERT().
2155 If Length > 0 and Source is NULL, then ASSERT().
2156 If Source and Destination overlap, then ASSERT().
2157 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
2158 PcdMaximumAsciiStringLength, then ASSERT().
2159 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
2160 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2162 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2163 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
2165 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
2166 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
2167 ASCII characters, not including the Null-terminator, then ASSERT().
2169 @param Destination The pointer to a Null-terminated ASCII string.
2170 @param Source The pointer to a Null-terminated ASCII string.
2171 @param Length The maximum number of ASCII characters to concatenate from
2180 IN OUT CHAR8
*Destination
,
2181 IN CONST CHAR8
*Source
,
2184 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
2187 Returns the first occurrence of a Null-terminated ASCII sub-string
2188 in a Null-terminated ASCII string.
2190 This function scans the contents of the ASCII string specified by String
2191 and returns the first occurrence of SearchString. If SearchString is not
2192 found in String, then NULL is returned. If the length of SearchString is zero,
2193 then String is returned.
2195 If String is NULL, then ASSERT().
2196 If SearchString is NULL, then ASSERT().
2198 If PcdMaximumAsciiStringLength is not zero, and SearchString or
2199 String contains more than PcdMaximumAsciiStringLength Unicode characters
2200 not including the Null-terminator, then ASSERT().
2202 @param String The pointer to a Null-terminated ASCII string.
2203 @param SearchString The pointer to a Null-terminated ASCII string to search for.
2205 @retval NULL If the SearchString does not appear in String.
2206 @retval others If there is a match return the first occurrence of SearchingString.
2207 If the length of SearchString is zero,return String.
2213 IN CONST CHAR8
*String
,
2214 IN CONST CHAR8
*SearchString
2219 Convert a Null-terminated ASCII decimal string to a value of type
2222 This function returns a value of type UINTN by interpreting the contents
2223 of the ASCII string String as a decimal number. The format of the input
2224 ASCII string String is:
2226 [spaces] [decimal digits].
2228 The valid decimal digit character is in the range [0-9]. The function will
2229 ignore the pad space, which includes spaces or tab characters, before the digits.
2230 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2231 function stops at the first character that is a not a valid decimal character or
2232 Null-terminator, whichever on comes first.
2234 If String has only pad spaces, then 0 is returned.
2235 If String has no pad spaces or valid decimal digits, then 0 is returned.
2236 If the number represented by String overflows according to the range defined by
2237 UINTN, then MAX_UINTN is returned.
2238 If String is NULL, then ASSERT().
2239 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2240 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2243 @param String The pointer to a Null-terminated ASCII string.
2245 @retval The value translated from String.
2250 AsciiStrDecimalToUintn (
2251 IN CONST CHAR8
*String
2256 Convert a Null-terminated ASCII decimal string to a value of type
2259 This function returns a value of type UINT64 by interpreting the contents
2260 of the ASCII string String as a decimal number. The format of the input
2261 ASCII string String is:
2263 [spaces] [decimal digits].
2265 The valid decimal digit character is in the range [0-9]. The function will
2266 ignore the pad space, which includes spaces or tab characters, before the digits.
2267 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2268 function stops at the first character that is a not a valid decimal character or
2269 Null-terminator, whichever on comes first.
2271 If String has only pad spaces, then 0 is returned.
2272 If String has no pad spaces or valid decimal digits, then 0 is returned.
2273 If the number represented by String overflows according to the range defined by
2274 UINT64, then MAX_UINT64 is returned.
2275 If String is NULL, then ASSERT().
2276 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2277 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2280 @param String The pointer to a Null-terminated ASCII string.
2282 @retval Value translated from String.
2287 AsciiStrDecimalToUint64 (
2288 IN CONST CHAR8
*String
2293 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
2295 This function returns a value of type UINTN by interpreting the contents of
2296 the ASCII string String as a hexadecimal number. The format of the input ASCII
2299 [spaces][zeros][x][hexadecimal digits].
2301 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2302 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2303 appears in the input string, it must be prefixed with at least one 0. The function
2304 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2305 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2306 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2307 digit. Then, the function stops at the first character that is a not a valid
2308 hexadecimal character or Null-terminator, whichever on comes first.
2310 If String has only pad spaces, then 0 is returned.
2311 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2314 If the number represented by String overflows according to the range defined by UINTN,
2315 then MAX_UINTN is returned.
2316 If String is NULL, then ASSERT().
2317 If PcdMaximumAsciiStringLength is not zero,
2318 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2319 the Null-terminator, then ASSERT().
2321 @param String The pointer to a Null-terminated ASCII string.
2323 @retval Value translated from String.
2328 AsciiStrHexToUintn (
2329 IN CONST CHAR8
*String
2334 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
2336 This function returns a value of type UINT64 by interpreting the contents of
2337 the ASCII string String as a hexadecimal number. The format of the input ASCII
2340 [spaces][zeros][x][hexadecimal digits].
2342 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2343 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2344 appears in the input string, it must be prefixed with at least one 0. The function
2345 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2346 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2347 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2348 digit. Then, the function stops at the first character that is a not a valid
2349 hexadecimal character or Null-terminator, whichever on comes first.
2351 If String has only pad spaces, then 0 is returned.
2352 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2355 If the number represented by String overflows according to the range defined by UINT64,
2356 then MAX_UINT64 is returned.
2357 If String is NULL, then ASSERT().
2358 If PcdMaximumAsciiStringLength is not zero,
2359 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2360 the Null-terminator, then ASSERT().
2362 @param String The pointer to a Null-terminated ASCII string.
2364 @retval Value translated from String.
2369 AsciiStrHexToUint64 (
2370 IN CONST CHAR8
*String
2374 Convert a Null-terminated ASCII string to IPv6 address and prefix length.
2376 This function outputs a value of type IPv6_ADDRESS and may output a value
2377 of type UINT8 by interpreting the contents of the ASCII string specified
2378 by String. The format of the input ASCII string String is as follows:
2382 X contains one to four hexadecimal digit characters in the range [0-9], [a-f] and
2383 [A-F]. X is converted to a value of type UINT16, whose low byte is stored in low
2384 memory address and high byte is stored in high memory address. P contains decimal
2385 digit characters in the range [0-9]. The running zero in the beginning of P will
2386 be ignored. /P is optional.
2388 When /P is not in the String, the function stops at the first character that is
2389 not a valid hexadecimal digit character after eight X's are converted.
2391 When /P is in the String, the function stops at the first character that is not
2392 a valid decimal digit character after P is converted.
2394 "::" can be used to compress one or more groups of X when X contains only 0.
2395 The "::" can only appear once in the String.
2397 If String is NULL, then ASSERT().
2399 If Address is NULL, then ASSERT().
2401 If EndPointer is not NULL and Address is translated from String, a pointer
2402 to the character that stopped the scan is stored at the location pointed to
2405 @param String Pointer to a Null-terminated ASCII string.
2406 @param EndPointer Pointer to character that stops scan.
2407 @param Address Pointer to the converted IPv6 address.
2408 @param PrefixLength Pointer to the converted IPv6 address prefix
2409 length. MAX_UINT8 is returned when /P is
2412 @retval RETURN_SUCCESS Address is translated from String.
2413 @retval RETURN_INVALID_PARAMETER If String is NULL.
2415 @retval RETURN_UNSUPPORTED If X contains more than four hexadecimal
2417 If String contains "::" and number of X
2419 If P starts with character that is not a
2420 valid decimal digit character.
2421 If the decimal number converted from P
2427 AsciiStrToIpv6Address (
2428 IN CONST CHAR8
*String
,
2429 OUT CHAR8
**EndPointer
, OPTIONAL
2430 OUT IPv6_ADDRESS
*Address
,
2431 OUT UINT8
*PrefixLength OPTIONAL
2435 Convert a Null-terminated ASCII string to IPv4 address and prefix length.
2437 This function outputs a value of type IPv4_ADDRESS and may output a value
2438 of type UINT8 by interpreting the contents of the ASCII string specified
2439 by String. The format of the input ASCII string String is as follows:
2443 D and P are decimal digit characters in the range [0-9]. The running zero in
2444 the beginning of D and P will be ignored. /P is optional.
2446 When /P is not in the String, the function stops at the first character that is
2447 not a valid decimal digit character after four D's are converted.
2449 When /P is in the String, the function stops at the first character that is not
2450 a valid decimal digit character after P is converted.
2452 If String is NULL, then ASSERT().
2454 If Address is NULL, then ASSERT().
2456 If EndPointer is not NULL and Address is translated from String, a pointer
2457 to the character that stopped the scan is stored at the location pointed to
2460 @param String Pointer to a Null-terminated ASCII string.
2461 @param EndPointer Pointer to character that stops scan.
2462 @param Address Pointer to the converted IPv4 address.
2463 @param PrefixLength Pointer to the converted IPv4 address prefix
2464 length. MAX_UINT8 is returned when /P is
2467 @retval RETURN_SUCCESS Address is translated from String.
2468 @retval RETURN_INVALID_PARAMETER If String is NULL.
2470 @retval RETURN_UNSUPPORTED If String is not in the correct format.
2471 If any decimal number converted from D
2473 If the decimal number converted from P
2479 AsciiStrToIpv4Address (
2480 IN CONST CHAR8
*String
,
2481 OUT CHAR8
**EndPointer
, OPTIONAL
2482 OUT IPv4_ADDRESS
*Address
,
2483 OUT UINT8
*PrefixLength OPTIONAL
2487 Convert a Null-terminated ASCII GUID string to a value of type
2490 This function outputs a GUID value by interpreting the contents of
2491 the ASCII string specified by String. The format of the input
2492 ASCII string String consists of 36 characters, as follows:
2494 aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
2496 The pairs aa - pp are two characters in the range [0-9], [a-f] and
2497 [A-F], with each pair representing a single byte hexadecimal value.
2499 The mapping between String and the EFI_GUID structure is as follows:
2517 If String is NULL, then ASSERT().
2518 If Guid is NULL, then ASSERT().
2520 @param String Pointer to a Null-terminated ASCII string.
2521 @param Guid Pointer to the converted GUID.
2523 @retval RETURN_SUCCESS Guid is translated from String.
2524 @retval RETURN_INVALID_PARAMETER If String is NULL.
2526 @retval RETURN_UNSUPPORTED If String is not as the above format.
2532 IN CONST CHAR8
*String
,
2537 Convert a Null-terminated ASCII hexadecimal string to a byte array.
2539 This function outputs a byte array by interpreting the contents of
2540 the ASCII string specified by String in hexadecimal format. The format of
2541 the input ASCII string String is:
2545 X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
2546 The function decodes every two hexadecimal digit characters as one byte. The
2547 decoding stops after Length of characters and outputs Buffer containing
2550 If String is NULL, then ASSERT().
2552 If Buffer is NULL, then ASSERT().
2554 If Length is not multiple of 2, then ASSERT().
2556 If PcdMaximumAsciiStringLength is not zero and Length is greater than
2557 PcdMaximumAsciiStringLength, then ASSERT().
2559 If MaxBufferSize is less than (Length / 2), then ASSERT().
2561 @param String Pointer to a Null-terminated ASCII string.
2562 @param Length The number of ASCII characters to decode.
2563 @param Buffer Pointer to the converted bytes array.
2564 @param MaxBufferSize The maximum size of Buffer.
2566 @retval RETURN_SUCCESS Buffer is translated from String.
2567 @retval RETURN_INVALID_PARAMETER If String is NULL.
2569 If Length is not multiple of 2.
2570 If PcdMaximumAsciiStringLength is not zero,
2571 and Length is greater than
2572 PcdMaximumAsciiStringLength.
2573 @retval RETURN_UNSUPPORTED If Length of characters from String contain
2574 a character that is not valid hexadecimal
2575 digit characters, or a Null-terminator.
2576 @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than (Length / 2).
2580 AsciiStrHexToBytes (
2581 IN CONST CHAR8
*String
,
2584 IN UINTN MaxBufferSize
2587 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2590 [ATTENTION] This function is deprecated for security reason.
2592 Convert one Null-terminated ASCII string to a Null-terminated
2593 Unicode string and returns the Unicode string.
2595 This function converts the contents of the ASCII string Source to the Unicode
2596 string Destination, and returns Destination. The function terminates the
2597 Unicode string Destination by appending a Null-terminator character at the end.
2598 The caller is responsible to make sure Destination points to a buffer with size
2599 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2601 If Destination is NULL, then ASSERT().
2602 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2603 If Source is NULL, then ASSERT().
2604 If Source and Destination overlap, then ASSERT().
2605 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2606 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2608 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
2609 PcdMaximumUnicodeStringLength ASCII characters not including the
2610 Null-terminator, then ASSERT().
2612 @param Source The pointer to a Null-terminated ASCII string.
2613 @param Destination The pointer to a Null-terminated Unicode string.
2615 @return Destination.
2620 AsciiStrToUnicodeStr (
2621 IN CONST CHAR8
*Source
,
2622 OUT CHAR16
*Destination
2625 #endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES)
2628 Convert one Null-terminated ASCII string to a Null-terminated
2631 This function is similar to StrCpyS.
2633 This function converts the contents of the ASCII string Source to the Unicode
2634 string Destination. The function terminates the Unicode string Destination by
2635 appending a Null-terminator character at the end.
2637 The caller is responsible to make sure Destination points to a buffer with size
2638 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2640 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2641 If an error would be returned, then the function will also ASSERT().
2643 If an error is returned, then the Destination is unmodified.
2645 @param Source The pointer to a Null-terminated ASCII string.
2646 @param Destination The pointer to a Null-terminated Unicode string.
2647 @param DestMax The maximum number of Destination Unicode
2648 char, including terminating null char.
2650 @retval RETURN_SUCCESS String is converted.
2651 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2652 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2654 If PcdMaximumUnicodeStringLength is not zero,
2655 and DestMax is greater than
2656 PcdMaximumUnicodeStringLength.
2657 If PcdMaximumAsciiStringLength is not zero,
2658 and DestMax is greater than
2659 PcdMaximumAsciiStringLength.
2661 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2666 AsciiStrToUnicodeStrS (
2667 IN CONST CHAR8
*Source
,
2668 OUT CHAR16
*Destination
,
2673 Convert not more than Length successive characters from a Null-terminated
2674 Ascii string to a Null-terminated Unicode string. If no null char is copied
2675 from Source, then Destination[Length] is always set to null.
2677 This function converts not more than Length successive characters from the
2678 Ascii string Source to the Unicode string Destination. The function
2679 terminates the Unicode string Destination by appending a Null-terminator
2680 character at the end.
2682 The caller is responsible to make sure Destination points to a buffer with
2683 size not smaller than
2684 ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes.
2686 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2687 If an error would be returned, then the function will also ASSERT().
2689 If an error is returned, then Destination and DestinationLength are
2692 @param Source The pointer to a Null-terminated Ascii string.
2693 @param Length The maximum number of Ascii characters to convert.
2694 @param Destination The pointer to a Null-terminated Unicode string.
2695 @param DestMax The maximum number of Destination Unicode char,
2696 including terminating null char.
2697 @param DestinationLength The number of Ascii characters converted.
2699 @retval RETURN_SUCCESS String is converted.
2700 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2702 If DestinationLength is NULL.
2703 If PcdMaximumUnicodeStringLength is not
2704 zero, and Length or DestMax is greater than
2705 PcdMaximumUnicodeStringLength.
2706 If PcdMaximumAsciiStringLength is not zero,
2707 and Length or DestMax is greater than
2708 PcdMaximumAsciiStringLength.
2710 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
2711 MIN(AsciiStrLen(Source), Length).
2712 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2717 AsciiStrnToUnicodeStrS (
2718 IN CONST CHAR8
*Source
,
2720 OUT CHAR16
*Destination
,
2722 OUT UINTN
*DestinationLength
2726 Convert a Unicode character to upper case only if
2727 it maps to a valid small-case ASCII character.
2729 This internal function only deal with Unicode character
2730 which maps to a valid small-case ASCII character, i.e.
2731 L'a' to L'z'. For other Unicode character, the input character
2732 is returned directly.
2734 @param Char The character to convert.
2736 @retval LowerCharacter If the Char is with range L'a' to L'z'.
2737 @retval Unchanged Otherwise.
2747 Converts a lowercase Ascii character to upper one.
2749 If Chr is lowercase Ascii character, then converts it to upper one.
2751 If Value >= 0xA0, then ASSERT().
2752 If (Value & 0x0F) >= 0x0A, then ASSERT().
2754 @param Chr one Ascii character
2756 @return The uppercase value of Ascii character
2766 Convert binary data to a Base64 encoded ascii string based on RFC4648.
2768 Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize.
2769 The Ascii string is produced by converting the data string specified by Source and SourceLength.
2771 @param Source Input UINT8 data
2772 @param SourceLength Number of UINT8 bytes of data
2773 @param Destination Pointer to output string buffer
2774 @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed.
2775 Caller is responsible for passing in buffer of DestinationSize
2777 @retval RETURN_SUCCESS When ascii buffer is filled in.
2778 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
2779 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination).
2780 @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1.
2781 @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize.
2787 IN CONST UINT8
*Source
,
2788 IN UINTN SourceLength
,
2789 OUT CHAR8
*Destination OPTIONAL
,
2790 IN OUT UINTN
*DestinationSize
2794 Convert Base64 ascii string to binary data based on RFC4648.
2796 Produce Null-terminated binary data in the output buffer specified by Destination and DestinationSize.
2797 The binary data is produced by converting the Base64 ascii string specified by Source and SourceLength.
2799 @param Source Input ASCII characters
2800 @param SourceLength Number of ASCII characters
2801 @param Destination Pointer to output buffer
2802 @param DestinationSize Caller is responsible for passing in buffer of at least DestinationSize.
2803 Set 0 to get the size needed. Set to bytes stored on return.
2805 @retval RETURN_SUCCESS When binary buffer is filled in.
2806 @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL.
2807 @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS -(UINTN)Destination ).
2808 @retval RETURN_INVALID_PARAMETER If there is any invalid character in input stream.
2809 @retval RETURN_BUFFER_TOO_SMALL If buffer length is smaller than required buffer size.
2815 IN CONST CHAR8
*Source
,
2816 IN UINTN SourceLength
,
2817 OUT UINT8
*Destination OPTIONAL
,
2818 IN OUT UINTN
*DestinationSize
2822 Converts an 8-bit value to an 8-bit BCD value.
2824 Converts the 8-bit value specified by Value to BCD. The BCD value is
2827 If Value >= 100, then ASSERT().
2829 @param Value The 8-bit value to convert to BCD. Range 0..99.
2831 @return The BCD value.
2842 Converts an 8-bit BCD value to an 8-bit value.
2844 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2847 If Value >= 0xA0, then ASSERT().
2848 If (Value & 0x0F) >= 0x0A, then ASSERT().
2850 @param Value The 8-bit BCD value to convert to an 8-bit value.
2852 @return The 8-bit value is returned.
2862 // File Path Manipulation Functions
2866 Removes the last directory or file entry in a path.
2868 @param[in, out] Path The pointer to the path to modify.
2870 @retval FALSE Nothing was found to remove.
2871 @retval TRUE A directory or file was removed.
2880 Function to clean up paths.
2881 - Single periods in the path are removed.
2882 - Double periods in the path are removed along with a single parent directory.
2883 - Forward slashes L'/' are converted to backward slashes L'\'.
2885 This will be done inline and the existing buffer may be larger than required
2888 @param[in] Path The pointer to the string containing the path.
2890 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2894 PathCleanUpDirectories(
2899 // Linked List Functions and Macros
2903 Initializes the head node of a doubly linked list that is declared as a
2904 global variable in a module.
2906 Initializes the forward and backward links of a new linked list. After
2907 initializing a linked list with this macro, the other linked list functions
2908 may be used to add and remove nodes from the linked list. This macro results
2909 in smaller executables by initializing the linked list in the data section,
2910 instead if calling the InitializeListHead() function to perform the
2911 equivalent operation.
2913 @param ListHead The head note of a list to initialize.
2916 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2920 Checks whether FirstEntry and SecondEntry are part of the same doubly-linked
2923 If FirstEntry is NULL, then ASSERT().
2924 If FirstEntry->ForwardLink is NULL, then ASSERT().
2925 If FirstEntry->BackLink is NULL, then ASSERT().
2926 If SecondEntry is NULL, then ASSERT();
2927 If PcdMaximumLinkedListLength is not zero, and List contains more than
2928 PcdMaximumLinkedListLength nodes, then ASSERT().
2930 @param FirstEntry A pointer to a node in a linked list.
2931 @param SecondEntry A pointer to the node to locate.
2933 @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry.
2934 @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry,
2935 or FirstEntry is invalid.
2941 IN CONST LIST_ENTRY
*FirstEntry
,
2942 IN CONST LIST_ENTRY
*SecondEntry
2947 Initializes the head node of a doubly linked list, and returns the pointer to
2948 the head node of the doubly linked list.
2950 Initializes the forward and backward links of a new linked list. After
2951 initializing a linked list with this function, the other linked list
2952 functions may be used to add and remove nodes from the linked list. It is up
2953 to the caller of this function to allocate the memory for ListHead.
2955 If ListHead is NULL, then ASSERT().
2957 @param ListHead A pointer to the head node of a new doubly linked list.
2964 InitializeListHead (
2965 IN OUT LIST_ENTRY
*ListHead
2970 Adds a node to the beginning of a doubly linked list, and returns the pointer
2971 to the head node of the doubly linked list.
2973 Adds the node Entry at the beginning of the doubly linked list denoted by
2974 ListHead, and returns ListHead.
2976 If ListHead is NULL, then ASSERT().
2977 If Entry is NULL, then ASSERT().
2978 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2979 InitializeListHead(), then ASSERT().
2980 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2981 of nodes in ListHead, including the ListHead node, is greater than or
2982 equal to PcdMaximumLinkedListLength, then ASSERT().
2984 @param ListHead A pointer to the head node of a doubly linked list.
2985 @param Entry A pointer to a node that is to be inserted at the beginning
2986 of a doubly linked list.
2994 IN OUT LIST_ENTRY
*ListHead
,
2995 IN OUT LIST_ENTRY
*Entry
3000 Adds a node to the end of a doubly linked list, and returns the pointer to
3001 the head node of the doubly linked list.
3003 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
3004 and returns ListHead.
3006 If ListHead is NULL, then ASSERT().
3007 If Entry is NULL, then ASSERT().
3008 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3009 InitializeListHead(), then ASSERT().
3010 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
3011 of nodes in ListHead, including the ListHead node, is greater than or
3012 equal to PcdMaximumLinkedListLength, then ASSERT().
3014 @param ListHead A pointer to the head node of a doubly linked list.
3015 @param Entry A pointer to a node that is to be added at the end of the
3024 IN OUT LIST_ENTRY
*ListHead
,
3025 IN OUT LIST_ENTRY
*Entry
3030 Retrieves the first node of a doubly linked list.
3032 Returns the first node of a doubly linked list. List must have been
3033 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3034 If List is empty, then List is returned.
3036 If List is NULL, then ASSERT().
3037 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3038 InitializeListHead(), then ASSERT().
3039 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3040 in List, including the List node, is greater than or equal to
3041 PcdMaximumLinkedListLength, then ASSERT().
3043 @param List A pointer to the head node of a doubly linked list.
3045 @return The first node of a doubly linked list.
3046 @retval List The list is empty.
3052 IN CONST LIST_ENTRY
*List
3057 Retrieves the next node of a doubly linked list.
3059 Returns the node of a doubly linked list that follows Node.
3060 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3061 or InitializeListHead(). If List is empty, then List is returned.
3063 If List is NULL, then ASSERT().
3064 If Node is NULL, then ASSERT().
3065 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3066 InitializeListHead(), then ASSERT().
3067 If PcdMaximumLinkedListLength is not zero, and List contains more than
3068 PcdMaximumLinkedListLength nodes, then ASSERT().
3069 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3071 @param List A pointer to the head node of a doubly linked list.
3072 @param Node A pointer to a node in the doubly linked list.
3074 @return The pointer to the next node if one exists. Otherwise List is returned.
3080 IN CONST LIST_ENTRY
*List
,
3081 IN CONST LIST_ENTRY
*Node
3086 Retrieves the previous node of a doubly linked list.
3088 Returns the node of a doubly linked list that precedes Node.
3089 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
3090 or InitializeListHead(). If List is empty, then List is returned.
3092 If List is NULL, then ASSERT().
3093 If Node 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 List contains more than
3097 PcdMaximumLinkedListLength nodes, then ASSERT().
3098 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3100 @param List A pointer to the head node of a doubly linked list.
3101 @param Node A pointer to a node in the doubly linked list.
3103 @return The pointer to the previous node if one exists. Otherwise List is returned.
3109 IN CONST LIST_ENTRY
*List
,
3110 IN CONST LIST_ENTRY
*Node
3115 Checks to see if a doubly linked list is empty or not.
3117 Checks to see if the doubly linked list is empty. If the linked list contains
3118 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
3120 If ListHead is NULL, then ASSERT().
3121 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3122 InitializeListHead(), then ASSERT().
3123 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3124 in List, including the List node, is greater than or equal to
3125 PcdMaximumLinkedListLength, then ASSERT().
3127 @param ListHead A pointer to the head node of a doubly linked list.
3129 @retval TRUE The linked list is empty.
3130 @retval FALSE The linked list is not empty.
3136 IN CONST LIST_ENTRY
*ListHead
3141 Determines if a node in a doubly linked list is the head node of a the same
3142 doubly linked list. This function is typically used to terminate a loop that
3143 traverses all the nodes in a doubly linked list starting with the head node.
3145 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
3146 nodes in the doubly linked list specified by List. List must have been
3147 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
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 InitializeListHead(),
3153 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3154 in List, including the List node, is greater than or equal to
3155 PcdMaximumLinkedListLength, then ASSERT().
3156 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
3157 to List, then ASSERT().
3159 @param List A pointer to the head node of a doubly linked list.
3160 @param Node A pointer to a node in the doubly linked list.
3162 @retval TRUE Node is the head of the doubly-linked list pointed by List.
3163 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
3169 IN CONST LIST_ENTRY
*List
,
3170 IN CONST LIST_ENTRY
*Node
3175 Determines if a node the last node in a doubly linked list.
3177 Returns TRUE if Node is the last node in the doubly linked list specified by
3178 List. Otherwise, FALSE is returned. List must have been initialized with
3179 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3181 If List is NULL, then ASSERT().
3182 If Node is NULL, then ASSERT().
3183 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
3184 InitializeListHead(), then ASSERT().
3185 If PcdMaximumLinkedListLength is not zero, and the number of nodes
3186 in List, including the List node, is greater than or equal to
3187 PcdMaximumLinkedListLength, then ASSERT().
3188 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
3190 @param List A pointer to the head node of a doubly linked list.
3191 @param Node A pointer to a node in the doubly linked list.
3193 @retval TRUE Node is the last node in the linked list.
3194 @retval FALSE Node is not the last node in the linked list.
3200 IN CONST LIST_ENTRY
*List
,
3201 IN CONST LIST_ENTRY
*Node
3206 Swaps the location of two nodes in a doubly linked list, and returns the
3207 first node after the swap.
3209 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
3210 Otherwise, the location of the FirstEntry node is swapped with the location
3211 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
3212 same double linked list as FirstEntry and that double linked list must have
3213 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
3214 SecondEntry is returned after the nodes are swapped.
3216 If FirstEntry is NULL, then ASSERT().
3217 If SecondEntry is NULL, then ASSERT().
3218 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
3219 same linked list, then ASSERT().
3220 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3221 linked list containing the FirstEntry and SecondEntry nodes, including
3222 the FirstEntry and SecondEntry nodes, is greater than or equal to
3223 PcdMaximumLinkedListLength, then ASSERT().
3225 @param FirstEntry A pointer to a node in a linked list.
3226 @param SecondEntry A pointer to another node in the same linked list.
3228 @return SecondEntry.
3234 IN OUT LIST_ENTRY
*FirstEntry
,
3235 IN OUT LIST_ENTRY
*SecondEntry
3240 Removes a node from a doubly linked list, and returns the node that follows
3243 Removes the node Entry from a doubly linked list. It is up to the caller of
3244 this function to release the memory used by this node if that is required. On
3245 exit, the node following Entry in the doubly linked list is returned. If
3246 Entry is the only node in the linked list, then the head node of the linked
3249 If Entry is NULL, then ASSERT().
3250 If Entry is the head node of an empty list, then ASSERT().
3251 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
3252 linked list containing Entry, including the Entry node, is greater than
3253 or equal to PcdMaximumLinkedListLength, then ASSERT().
3255 @param Entry A pointer to a node in a linked list.
3263 IN CONST LIST_ENTRY
*Entry
3271 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
3272 with zeros. The shifted value is returned.
3274 This function shifts the 64-bit value Operand to the left by Count bits. The
3275 low Count bits are set to zero. The shifted value is returned.
3277 If Count is greater than 63, then ASSERT().
3279 @param Operand The 64-bit operand to shift left.
3280 @param Count The number of bits to shift left.
3282 @return Operand << Count.
3294 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
3295 filled with zeros. The shifted value is returned.
3297 This function shifts the 64-bit value Operand to the right by Count bits. The
3298 high Count bits are set to zero. The shifted value is returned.
3300 If Count is greater than 63, then ASSERT().
3302 @param Operand The 64-bit operand to shift right.
3303 @param Count The number of bits to shift right.
3305 @return Operand >> Count
3317 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
3318 with original integer's bit 63. The shifted value is returned.
3320 This function shifts the 64-bit value Operand to the right by Count bits. The
3321 high Count bits are set to bit 63 of Operand. The shifted value is returned.
3323 If Count is greater than 63, then ASSERT().
3325 @param Operand The 64-bit operand to shift right.
3326 @param Count The number of bits to shift right.
3328 @return Operand >> Count
3340 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
3341 with the high bits that were rotated.
3343 This function rotates the 32-bit value Operand to the left by Count bits. The
3344 low Count bits are fill with the high Count bits of Operand. The rotated
3347 If Count is greater than 31, then ASSERT().
3349 @param Operand The 32-bit operand to rotate left.
3350 @param Count The number of bits to rotate left.
3352 @return Operand << Count
3364 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
3365 with the low bits that were rotated.
3367 This function rotates the 32-bit value Operand to the right by Count bits.
3368 The high Count bits are fill with the low Count bits of Operand. The rotated
3371 If Count is greater than 31, then ASSERT().
3373 @param Operand The 32-bit operand to rotate right.
3374 @param Count The number of bits to rotate right.
3376 @return Operand >> Count
3388 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
3389 with the high bits that were rotated.
3391 This function rotates the 64-bit value Operand to the left by Count bits. The
3392 low Count bits are fill with the high Count bits of Operand. The rotated
3395 If Count is greater than 63, then ASSERT().
3397 @param Operand The 64-bit operand to rotate left.
3398 @param Count The number of bits to rotate left.
3400 @return Operand << Count
3412 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
3413 with the high low bits that were rotated.
3415 This function rotates the 64-bit value Operand to the right by Count bits.
3416 The high Count bits are fill with the low Count bits of Operand. The rotated
3419 If Count is greater than 63, then ASSERT().
3421 @param Operand The 64-bit operand to rotate right.
3422 @param Count The number of bits to rotate right.
3424 @return Operand >> Count
3436 Returns the bit position of the lowest bit set in a 32-bit value.
3438 This function computes the bit position of the lowest bit set in the 32-bit
3439 value specified by Operand. If Operand is zero, then -1 is returned.
3440 Otherwise, a value between 0 and 31 is returned.
3442 @param Operand The 32-bit operand to evaluate.
3444 @retval 0..31 The lowest bit set in Operand was found.
3445 @retval -1 Operand is zero.
3456 Returns the bit position of the lowest bit set in a 64-bit value.
3458 This function computes the bit position of the lowest bit set in the 64-bit
3459 value specified by Operand. If Operand is zero, then -1 is returned.
3460 Otherwise, a value between 0 and 63 is returned.
3462 @param Operand The 64-bit operand to evaluate.
3464 @retval 0..63 The lowest bit set in Operand was found.
3465 @retval -1 Operand is zero.
3477 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
3480 This function computes the bit position of the highest bit set in the 32-bit
3481 value specified by Operand. If Operand is zero, then -1 is returned.
3482 Otherwise, a value between 0 and 31 is returned.
3484 @param Operand The 32-bit operand to evaluate.
3486 @retval 0..31 Position of the highest bit set in Operand if found.
3487 @retval -1 Operand is zero.
3498 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
3501 This function computes the bit position of the highest bit set in the 64-bit
3502 value specified by Operand. If Operand is zero, then -1 is returned.
3503 Otherwise, a value between 0 and 63 is returned.
3505 @param Operand The 64-bit operand to evaluate.
3507 @retval 0..63 Position of the highest bit set in Operand if found.
3508 @retval -1 Operand is zero.
3519 Returns the value of the highest bit set in a 32-bit value. Equivalent to
3522 This function computes the value of the highest bit set in the 32-bit value
3523 specified by Operand. If Operand is zero, then zero is returned.
3525 @param Operand The 32-bit operand to evaluate.
3527 @return 1 << HighBitSet32(Operand)
3528 @retval 0 Operand is zero.
3539 Returns the value of the highest bit set in a 64-bit value. Equivalent to
3542 This function computes the value of the highest bit set in the 64-bit value
3543 specified by Operand. If Operand is zero, then zero is returned.
3545 @param Operand The 64-bit operand to evaluate.
3547 @return 1 << HighBitSet64(Operand)
3548 @retval 0 Operand is zero.
3559 Switches the endianness of a 16-bit integer.
3561 This function swaps the bytes in a 16-bit unsigned value to switch the value
3562 from little endian to big endian or vice versa. The byte swapped value is
3565 @param Value A 16-bit unsigned value.
3567 @return The byte swapped Value.
3578 Switches the endianness of a 32-bit integer.
3580 This function swaps the bytes in a 32-bit unsigned value to switch the value
3581 from little endian to big endian or vice versa. The byte swapped value is
3584 @param Value A 32-bit unsigned value.
3586 @return The byte swapped Value.
3597 Switches the endianness of a 64-bit integer.
3599 This function swaps the bytes in a 64-bit unsigned value to switch the value
3600 from little endian to big endian or vice versa. The byte swapped value is
3603 @param Value A 64-bit unsigned value.
3605 @return The byte swapped Value.
3616 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
3617 generates a 64-bit unsigned result.
3619 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
3620 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3621 bit unsigned result is returned.
3623 @param Multiplicand A 64-bit unsigned value.
3624 @param Multiplier A 32-bit unsigned value.
3626 @return Multiplicand * Multiplier
3632 IN UINT64 Multiplicand
,
3633 IN UINT32 Multiplier
3638 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3639 generates a 64-bit unsigned result.
3641 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3642 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3643 bit unsigned result is returned.
3645 @param Multiplicand A 64-bit unsigned value.
3646 @param Multiplier A 64-bit unsigned value.
3648 @return Multiplicand * Multiplier.
3654 IN UINT64 Multiplicand
,
3655 IN UINT64 Multiplier
3660 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3661 64-bit signed result.
3663 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3664 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3665 signed result is returned.
3667 @param Multiplicand A 64-bit signed value.
3668 @param Multiplier A 64-bit signed value.
3670 @return Multiplicand * Multiplier
3676 IN INT64 Multiplicand
,
3682 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3683 a 64-bit unsigned result.
3685 This function divides the 64-bit unsigned value Dividend by the 32-bit
3686 unsigned value Divisor and generates a 64-bit unsigned quotient. This
3687 function returns the 64-bit unsigned quotient.
3689 If Divisor is 0, then ASSERT().
3691 @param Dividend A 64-bit unsigned value.
3692 @param Divisor A 32-bit unsigned value.
3694 @return Dividend / Divisor.
3706 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3707 a 32-bit unsigned remainder.
3709 This function divides the 64-bit unsigned value Dividend by the 32-bit
3710 unsigned value Divisor and generates a 32-bit remainder. This function
3711 returns the 32-bit unsigned remainder.
3713 If Divisor is 0, then ASSERT().
3715 @param Dividend A 64-bit unsigned value.
3716 @param Divisor A 32-bit unsigned value.
3718 @return Dividend % Divisor.
3730 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3731 a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3733 This function divides the 64-bit unsigned value Dividend by the 32-bit
3734 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3735 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3736 This function returns the 64-bit unsigned quotient.
3738 If Divisor is 0, then ASSERT().
3740 @param Dividend A 64-bit unsigned value.
3741 @param Divisor A 32-bit unsigned value.
3742 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3743 optional and may be NULL.
3745 @return Dividend / Divisor.
3750 DivU64x32Remainder (
3753 OUT UINT32
*Remainder OPTIONAL
3758 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3759 a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3761 This function divides the 64-bit unsigned value Dividend by the 64-bit
3762 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3763 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3764 This function returns the 64-bit unsigned quotient.
3766 If Divisor is 0, then ASSERT().
3768 @param Dividend A 64-bit unsigned value.
3769 @param Divisor A 64-bit unsigned value.
3770 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3771 optional and may be NULL.
3773 @return Dividend / Divisor.
3778 DivU64x64Remainder (
3781 OUT UINT64
*Remainder OPTIONAL
3786 Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3787 64-bit signed result and a optional 64-bit signed remainder.
3789 This function divides the 64-bit signed value Dividend by the 64-bit signed
3790 value Divisor and generates a 64-bit signed quotient. If Remainder is not
3791 NULL, then the 64-bit signed remainder is returned in Remainder. This
3792 function returns the 64-bit signed quotient.
3794 It is the caller's responsibility to not call this function with a Divisor of 0.
3795 If Divisor is 0, then the quotient and remainder should be assumed to be
3796 the largest negative integer.
3798 If Divisor is 0, then ASSERT().
3800 @param Dividend A 64-bit signed value.
3801 @param Divisor A 64-bit signed value.
3802 @param Remainder A pointer to a 64-bit signed value. This parameter is
3803 optional and may be NULL.
3805 @return Dividend / Divisor.
3810 DivS64x64Remainder (
3813 OUT INT64
*Remainder OPTIONAL
3818 Reads a 16-bit value from memory that may be unaligned.
3820 This function returns the 16-bit value pointed to by Buffer. The function
3821 guarantees that the read operation does not produce an alignment fault.
3823 If the Buffer is NULL, then ASSERT().
3825 @param Buffer The pointer to a 16-bit value that may be unaligned.
3827 @return The 16-bit value read from Buffer.
3833 IN CONST UINT16
*Buffer
3838 Writes a 16-bit value to memory that may be unaligned.
3840 This function writes the 16-bit value specified by Value to Buffer. Value is
3841 returned. The function guarantees that the write operation does not produce
3844 If the Buffer is NULL, then ASSERT().
3846 @param Buffer The pointer to a 16-bit value that may be unaligned.
3847 @param Value 16-bit value to write to Buffer.
3849 @return The 16-bit value to write to Buffer.
3861 Reads a 24-bit value from memory that may be unaligned.
3863 This function returns the 24-bit value pointed to by Buffer. The function
3864 guarantees that the read operation does not produce an alignment fault.
3866 If the Buffer is NULL, then ASSERT().
3868 @param Buffer The pointer to a 24-bit value that may be unaligned.
3870 @return The 24-bit value read from Buffer.
3876 IN CONST UINT32
*Buffer
3881 Writes a 24-bit value to memory that may be unaligned.
3883 This function writes the 24-bit value specified by Value to Buffer. Value is
3884 returned. The function guarantees that the write operation does not produce
3887 If the Buffer is NULL, then ASSERT().
3889 @param Buffer The pointer to a 24-bit value that may be unaligned.
3890 @param Value 24-bit value to write to Buffer.
3892 @return The 24-bit value to write to Buffer.
3904 Reads a 32-bit value from memory that may be unaligned.
3906 This function returns the 32-bit value pointed to by Buffer. The function
3907 guarantees that the read operation does not produce an alignment fault.
3909 If the Buffer is NULL, then ASSERT().
3911 @param Buffer The pointer to a 32-bit value that may be unaligned.
3913 @return The 32-bit value read from Buffer.
3919 IN CONST UINT32
*Buffer
3924 Writes a 32-bit value to memory that may be unaligned.
3926 This function writes the 32-bit value specified by Value to Buffer. Value is
3927 returned. The function guarantees that the write operation does not produce
3930 If the Buffer is NULL, then ASSERT().
3932 @param Buffer The pointer to a 32-bit value that may be unaligned.
3933 @param Value 32-bit value to write to Buffer.
3935 @return The 32-bit value to write to Buffer.
3947 Reads a 64-bit value from memory that may be unaligned.
3949 This function returns the 64-bit value pointed to by Buffer. The function
3950 guarantees that the read operation does not produce an alignment fault.
3952 If the Buffer is NULL, then ASSERT().
3954 @param Buffer The pointer to a 64-bit value that may be unaligned.
3956 @return The 64-bit value read from Buffer.
3962 IN CONST UINT64
*Buffer
3967 Writes a 64-bit value to memory that may be unaligned.
3969 This function writes the 64-bit value specified by Value to Buffer. Value is
3970 returned. The function guarantees that the write operation does not produce
3973 If the Buffer is NULL, then ASSERT().
3975 @param Buffer The pointer to a 64-bit value that may be unaligned.
3976 @param Value 64-bit value to write to Buffer.
3978 @return The 64-bit value to write to Buffer.
3990 // Bit Field Functions
3994 Returns a bit field from an 8-bit value.
3996 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3998 If 8-bit operations are not supported, then ASSERT().
3999 If StartBit is greater than 7, then ASSERT().
4000 If EndBit is greater than 7, then ASSERT().
4001 If EndBit is less than StartBit, then ASSERT().
4003 @param Operand Operand on which to perform the bitfield operation.
4004 @param StartBit The ordinal of the least significant bit in the bit field.
4006 @param EndBit The ordinal of the most significant bit in the bit field.
4009 @return The bit field read.
4022 Writes a bit field to an 8-bit value, and returns the result.
4024 Writes Value to the bit field specified by the StartBit and the EndBit in
4025 Operand. All other bits in Operand are preserved. The new 8-bit value is
4028 If 8-bit operations are not supported, then ASSERT().
4029 If StartBit is greater than 7, then ASSERT().
4030 If EndBit is greater than 7, then ASSERT().
4031 If EndBit is less than StartBit, then ASSERT().
4032 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4034 @param Operand Operand on which to perform the bitfield operation.
4035 @param StartBit The ordinal of the least significant bit in the bit field.
4037 @param EndBit The ordinal of the most significant bit in the bit field.
4039 @param Value New value of the bit field.
4041 @return The new 8-bit value.
4055 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
4058 Performs a bitwise OR between the bit field specified by StartBit
4059 and EndBit in Operand and the value specified by OrData. All other bits in
4060 Operand are preserved. The new 8-bit value is returned.
4062 If 8-bit operations are not supported, then ASSERT().
4063 If StartBit is greater than 7, then ASSERT().
4064 If EndBit is greater than 7, then ASSERT().
4065 If EndBit is less than StartBit, then ASSERT().
4066 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4068 @param Operand Operand on which to perform the bitfield operation.
4069 @param StartBit The ordinal of the least significant bit in the bit field.
4071 @param EndBit The ordinal of the most significant bit in the bit field.
4073 @param OrData The value to OR with the read value from the value
4075 @return The new 8-bit value.
4089 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
4092 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4093 in Operand and the value specified by AndData. All other bits in Operand are
4094 preserved. The new 8-bit value is returned.
4096 If 8-bit operations are not supported, then ASSERT().
4097 If StartBit is greater than 7, then ASSERT().
4098 If EndBit is greater than 7, then ASSERT().
4099 If EndBit is less than StartBit, then ASSERT().
4100 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4102 @param Operand Operand on which to perform the bitfield operation.
4103 @param StartBit The ordinal of the least significant bit in the bit field.
4105 @param EndBit The ordinal of the most significant bit in the bit field.
4107 @param AndData The value to AND with the read value from the value.
4109 @return The new 8-bit value.
4123 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
4124 bitwise OR, and returns the result.
4126 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4127 in Operand and the value specified by AndData, followed by a bitwise
4128 OR with value specified by OrData. All other bits in Operand are
4129 preserved. The new 8-bit value is returned.
4131 If 8-bit operations are not supported, then ASSERT().
4132 If StartBit is greater than 7, then ASSERT().
4133 If EndBit is greater than 7, then ASSERT().
4134 If EndBit is less than StartBit, then ASSERT().
4135 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4136 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4138 @param Operand Operand on which to perform the bitfield operation.
4139 @param StartBit The ordinal of the least significant bit in the bit field.
4141 @param EndBit The ordinal of the most significant bit in the bit field.
4143 @param AndData The value to AND with the read value from the value.
4144 @param OrData The value to OR with the result of the AND operation.
4146 @return The new 8-bit value.
4151 BitFieldAndThenOr8 (
4161 Returns a bit field from a 16-bit value.
4163 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4165 If 16-bit operations are not supported, then ASSERT().
4166 If StartBit is greater than 15, then ASSERT().
4167 If EndBit is greater than 15, then ASSERT().
4168 If EndBit is less than StartBit, then ASSERT().
4170 @param Operand Operand on which to perform the bitfield operation.
4171 @param StartBit The ordinal of the least significant bit in the bit field.
4173 @param EndBit The ordinal of the most significant bit in the bit field.
4176 @return The bit field read.
4189 Writes a bit field to a 16-bit value, and returns the result.
4191 Writes Value to the bit field specified by the StartBit and the EndBit in
4192 Operand. All other bits in Operand are preserved. The new 16-bit value is
4195 If 16-bit operations are not supported, then ASSERT().
4196 If StartBit is greater than 15, then ASSERT().
4197 If EndBit is greater than 15, then ASSERT().
4198 If EndBit is less than StartBit, then ASSERT().
4199 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4201 @param Operand Operand on which to perform the bitfield operation.
4202 @param StartBit The ordinal of the least significant bit in the bit field.
4204 @param EndBit The ordinal of the most significant bit in the bit field.
4206 @param Value New value of the bit field.
4208 @return The new 16-bit value.
4222 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
4225 Performs a bitwise OR between the bit field specified by StartBit
4226 and EndBit in Operand and the value specified by OrData. All other bits in
4227 Operand are preserved. The new 16-bit value is returned.
4229 If 16-bit operations are not supported, then ASSERT().
4230 If StartBit is greater than 15, then ASSERT().
4231 If EndBit is greater than 15, then ASSERT().
4232 If EndBit is less than StartBit, then ASSERT().
4233 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4235 @param Operand Operand on which to perform the bitfield operation.
4236 @param StartBit The ordinal of the least significant bit in the bit field.
4238 @param EndBit The ordinal of the most significant bit in the bit field.
4240 @param OrData The value to OR with the read value from the value
4242 @return The new 16-bit value.
4256 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
4259 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4260 in Operand and the value specified by AndData. All other bits in Operand are
4261 preserved. The new 16-bit value is returned.
4263 If 16-bit operations are not supported, then ASSERT().
4264 If StartBit is greater than 15, then ASSERT().
4265 If EndBit is greater than 15, then ASSERT().
4266 If EndBit is less than StartBit, then ASSERT().
4267 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4269 @param Operand Operand on which to perform the bitfield operation.
4270 @param StartBit The ordinal of the least significant bit in the bit field.
4272 @param EndBit The ordinal of the most significant bit in the bit field.
4274 @param AndData The value to AND with the read value from the value
4276 @return The new 16-bit value.
4290 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
4291 bitwise OR, and returns the result.
4293 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4294 in Operand and the value specified by AndData, followed by a bitwise
4295 OR with value specified by OrData. All other bits in Operand are
4296 preserved. The new 16-bit value is returned.
4298 If 16-bit operations are not supported, then ASSERT().
4299 If StartBit is greater than 15, then ASSERT().
4300 If EndBit is greater than 15, then ASSERT().
4301 If EndBit is less than StartBit, then ASSERT().
4302 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4303 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4305 @param Operand Operand on which to perform the bitfield operation.
4306 @param StartBit The ordinal of the least significant bit in the bit field.
4308 @param EndBit The ordinal of the most significant bit in the bit field.
4310 @param AndData The value to AND with the read value from the value.
4311 @param OrData The value to OR with the result of the AND operation.
4313 @return The new 16-bit value.
4318 BitFieldAndThenOr16 (
4328 Returns a bit field from a 32-bit value.
4330 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4332 If 32-bit operations are not supported, then ASSERT().
4333 If StartBit is greater than 31, then ASSERT().
4334 If EndBit is greater than 31, then ASSERT().
4335 If EndBit is less than StartBit, then ASSERT().
4337 @param Operand Operand on which to perform the bitfield operation.
4338 @param StartBit The ordinal of the least significant bit in the bit field.
4340 @param EndBit The ordinal of the most significant bit in the bit field.
4343 @return The bit field read.
4356 Writes a bit field to a 32-bit value, and returns the result.
4358 Writes Value to the bit field specified by the StartBit and the EndBit in
4359 Operand. All other bits in Operand are preserved. The new 32-bit value is
4362 If 32-bit operations are not supported, then ASSERT().
4363 If StartBit is greater than 31, then ASSERT().
4364 If EndBit is greater than 31, then ASSERT().
4365 If EndBit is less than StartBit, then ASSERT().
4366 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4368 @param Operand Operand on which to perform the bitfield operation.
4369 @param StartBit The ordinal of the least significant bit in the bit field.
4371 @param EndBit The ordinal of the most significant bit in the bit field.
4373 @param Value New value of the bit field.
4375 @return The new 32-bit value.
4389 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
4392 Performs a bitwise OR between the bit field specified by StartBit
4393 and EndBit in Operand and the value specified by OrData. All other bits in
4394 Operand are preserved. The new 32-bit value is returned.
4396 If 32-bit operations are not supported, then ASSERT().
4397 If StartBit is greater than 31, then ASSERT().
4398 If EndBit is greater than 31, then ASSERT().
4399 If EndBit is less than StartBit, then ASSERT().
4400 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4402 @param Operand Operand on which to perform the bitfield operation.
4403 @param StartBit The ordinal of the least significant bit in the bit field.
4405 @param EndBit The ordinal of the most significant bit in the bit field.
4407 @param OrData The value to OR with the read value from the value.
4409 @return The new 32-bit value.
4423 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
4426 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4427 in Operand and the value specified by AndData. All other bits in Operand are
4428 preserved. The new 32-bit value is returned.
4430 If 32-bit operations are not supported, then ASSERT().
4431 If StartBit is greater than 31, then ASSERT().
4432 If EndBit is greater than 31, then ASSERT().
4433 If EndBit is less than StartBit, then ASSERT().
4434 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4436 @param Operand Operand on which to perform the bitfield operation.
4437 @param StartBit The ordinal of the least significant bit in the bit field.
4439 @param EndBit The ordinal of the most significant bit in the bit field.
4441 @param AndData The value to AND with the read value from the value
4443 @return The new 32-bit value.
4457 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
4458 bitwise OR, and returns the result.
4460 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4461 in Operand and the value specified by AndData, followed by a bitwise
4462 OR with value specified by OrData. All other bits in Operand are
4463 preserved. The new 32-bit value is returned.
4465 If 32-bit operations are not supported, then ASSERT().
4466 If StartBit is greater than 31, then ASSERT().
4467 If EndBit is greater than 31, then ASSERT().
4468 If EndBit is less than StartBit, then ASSERT().
4469 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4470 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4472 @param Operand Operand on which to perform the bitfield operation.
4473 @param StartBit The ordinal of the least significant bit in the bit field.
4475 @param EndBit The ordinal of the most significant bit in the bit field.
4477 @param AndData The value to AND with the read value from the value.
4478 @param OrData The value to OR with the result of the AND operation.
4480 @return The new 32-bit value.
4485 BitFieldAndThenOr32 (
4495 Returns a bit field from a 64-bit value.
4497 Returns the bitfield specified by the StartBit and the EndBit from Operand.
4499 If 64-bit operations are not supported, then ASSERT().
4500 If StartBit is greater than 63, then ASSERT().
4501 If EndBit is greater than 63, then ASSERT().
4502 If EndBit is less than StartBit, then ASSERT().
4504 @param Operand Operand on which to perform the bitfield operation.
4505 @param StartBit The ordinal of the least significant bit in the bit field.
4507 @param EndBit The ordinal of the most significant bit in the bit field.
4510 @return The bit field read.
4523 Writes a bit field to a 64-bit value, and returns the result.
4525 Writes Value to the bit field specified by the StartBit and the EndBit in
4526 Operand. All other bits in Operand are preserved. The new 64-bit value is
4529 If 64-bit operations are not supported, then ASSERT().
4530 If StartBit is greater than 63, then ASSERT().
4531 If EndBit is greater than 63, then ASSERT().
4532 If EndBit is less than StartBit, then ASSERT().
4533 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4535 @param Operand Operand on which to perform the bitfield operation.
4536 @param StartBit The ordinal of the least significant bit in the bit field.
4538 @param EndBit The ordinal of the most significant bit in the bit field.
4540 @param Value New value of the bit field.
4542 @return The new 64-bit value.
4556 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
4559 Performs a bitwise OR between the bit field specified by StartBit
4560 and EndBit in Operand and the value specified by OrData. All other bits in
4561 Operand are preserved. The new 64-bit value is returned.
4563 If 64-bit operations are not supported, then ASSERT().
4564 If StartBit is greater than 63, then ASSERT().
4565 If EndBit is greater than 63, then ASSERT().
4566 If EndBit is less than StartBit, then ASSERT().
4567 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4569 @param Operand Operand on which to perform the bitfield operation.
4570 @param StartBit The ordinal of the least significant bit in the bit field.
4572 @param EndBit The ordinal of the most significant bit in the bit field.
4574 @param OrData The value to OR with the read value from the value
4576 @return The new 64-bit value.
4590 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
4593 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4594 in Operand and the value specified by AndData. All other bits in Operand are
4595 preserved. The new 64-bit value is returned.
4597 If 64-bit operations are not supported, then ASSERT().
4598 If StartBit is greater than 63, then ASSERT().
4599 If EndBit is greater than 63, then ASSERT().
4600 If EndBit is less than StartBit, then ASSERT().
4601 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4603 @param Operand Operand on which to perform the bitfield operation.
4604 @param StartBit The ordinal of the least significant bit in the bit field.
4606 @param EndBit The ordinal of the most significant bit in the bit field.
4608 @param AndData The value to AND with the read value from the value
4610 @return The new 64-bit value.
4624 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
4625 bitwise OR, and returns the result.
4627 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4628 in Operand and the value specified by AndData, followed by a bitwise
4629 OR with value specified by OrData. All other bits in Operand are
4630 preserved. The new 64-bit value is returned.
4632 If 64-bit operations are not supported, then ASSERT().
4633 If StartBit is greater than 63, then ASSERT().
4634 If EndBit is greater than 63, then ASSERT().
4635 If EndBit is less than StartBit, then ASSERT().
4636 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4637 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4639 @param Operand Operand on which to perform the bitfield operation.
4640 @param StartBit The ordinal of the least significant bit in the bit field.
4642 @param EndBit The ordinal of the most significant bit in the bit field.
4644 @param AndData The value to AND with the read value from the value.
4645 @param OrData The value to OR with the result of the AND operation.
4647 @return The new 64-bit value.
4652 BitFieldAndThenOr64 (
4661 Reads a bit field from a 32-bit value, counts and returns
4662 the number of set bits.
4664 Counts the number of set bits in the bit field specified by
4665 StartBit and EndBit in Operand. The count is returned.
4667 If StartBit is greater than 31, then ASSERT().
4668 If EndBit is greater than 31, then ASSERT().
4669 If EndBit is less than StartBit, then ASSERT().
4671 @param Operand Operand on which to perform the bitfield operation.
4672 @param StartBit The ordinal of the least significant bit in the bit field.
4674 @param EndBit The ordinal of the most significant bit in the bit field.
4677 @return The number of bits set between StartBit and EndBit.
4682 BitFieldCountOnes32 (
4689 Reads a bit field from a 64-bit value, counts and returns
4690 the number of set bits.
4692 Counts the number of set bits in the bit field specified by
4693 StartBit and EndBit in Operand. The count is returned.
4695 If StartBit is greater than 63, then ASSERT().
4696 If EndBit is greater than 63, then ASSERT().
4697 If EndBit is less than StartBit, then ASSERT().
4699 @param Operand Operand on which to perform the bitfield operation.
4700 @param StartBit The ordinal of the least significant bit in the bit field.
4702 @param EndBit The ordinal of the most significant bit in the bit field.
4705 @return The number of bits set between StartBit and EndBit.
4710 BitFieldCountOnes64 (
4717 // Base Library Checksum Functions
4721 Returns the sum of all elements in a buffer in unit of UINT8.
4722 During calculation, the carry bits are dropped.
4724 This function calculates the sum of all elements in a buffer
4725 in unit of UINT8. The carry bits in result of addition are dropped.
4726 The result is returned as UINT8. If Length is Zero, then Zero is
4729 If Buffer is NULL, then ASSERT().
4730 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4732 @param Buffer The pointer to the buffer to carry out the sum operation.
4733 @param Length The size, in bytes, of Buffer.
4735 @return Sum The sum of Buffer with carry bits dropped during additions.
4741 IN CONST UINT8
*Buffer
,
4747 Returns the two's complement checksum of all elements in a buffer
4750 This function first calculates the sum of the 8-bit values in the
4751 buffer specified by Buffer and Length. The carry bits in the result
4752 of addition are dropped. Then, the two's complement of the sum is
4753 returned. If Length is 0, then 0 is returned.
4755 If Buffer is NULL, then ASSERT().
4756 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4758 @param Buffer The pointer to the buffer to carry out the checksum operation.
4759 @param Length The size, in bytes, of Buffer.
4761 @return Checksum The two's complement checksum of Buffer.
4766 CalculateCheckSum8 (
4767 IN CONST UINT8
*Buffer
,
4773 Returns the sum of all elements in a buffer of 16-bit values. During
4774 calculation, the carry bits are dropped.
4776 This function calculates the sum of the 16-bit values in the buffer
4777 specified by Buffer and Length. The carry bits in result of addition are dropped.
4778 The 16-bit result is returned. If Length is 0, then 0 is returned.
4780 If Buffer is NULL, then ASSERT().
4781 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4782 If Length is not aligned on a 16-bit boundary, then ASSERT().
4783 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4785 @param Buffer The pointer to the buffer to carry out the sum operation.
4786 @param Length The size, in bytes, of Buffer.
4788 @return Sum The sum of Buffer with carry bits dropped during additions.
4794 IN CONST UINT16
*Buffer
,
4800 Returns the two's complement checksum of all elements in a buffer of
4803 This function first calculates the sum of the 16-bit values in the buffer
4804 specified by Buffer and Length. The carry bits in the result of addition
4805 are dropped. Then, the two's complement of the sum is returned. If Length
4806 is 0, then 0 is returned.
4808 If Buffer is NULL, then ASSERT().
4809 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4810 If Length is not aligned on a 16-bit boundary, then ASSERT().
4811 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4813 @param Buffer The pointer to the buffer to carry out the checksum operation.
4814 @param Length The size, in bytes, of Buffer.
4816 @return Checksum The two's complement checksum of Buffer.
4821 CalculateCheckSum16 (
4822 IN CONST UINT16
*Buffer
,
4828 Returns the sum of all elements in a buffer of 32-bit values. During
4829 calculation, the carry bits are dropped.
4831 This function calculates the sum of the 32-bit values in the buffer
4832 specified by Buffer and Length. The carry bits in result of addition are dropped.
4833 The 32-bit result is returned. If Length is 0, then 0 is returned.
4835 If Buffer is NULL, then ASSERT().
4836 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4837 If Length is not aligned on a 32-bit boundary, then ASSERT().
4838 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4840 @param Buffer The pointer to the buffer to carry out the sum operation.
4841 @param Length The size, in bytes, of Buffer.
4843 @return Sum The sum of Buffer with carry bits dropped during additions.
4849 IN CONST UINT32
*Buffer
,
4855 Returns the two's complement checksum of all elements in a buffer of
4858 This function first calculates the sum of the 32-bit values in the buffer
4859 specified by Buffer and Length. The carry bits in the result of addition
4860 are dropped. Then, the two's complement of the sum is returned. If Length
4861 is 0, then 0 is returned.
4863 If Buffer is NULL, then ASSERT().
4864 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4865 If Length is not aligned on a 32-bit boundary, then ASSERT().
4866 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4868 @param Buffer The pointer to the buffer to carry out the checksum operation.
4869 @param Length The size, in bytes, of Buffer.
4871 @return Checksum The two's complement checksum of Buffer.
4876 CalculateCheckSum32 (
4877 IN CONST UINT32
*Buffer
,
4883 Returns the sum of all elements in a buffer of 64-bit values. During
4884 calculation, the carry bits are dropped.
4886 This function calculates the sum of the 64-bit values in the buffer
4887 specified by Buffer and Length. The carry bits in result of addition are dropped.
4888 The 64-bit result is returned. If Length is 0, then 0 is returned.
4890 If Buffer is NULL, then ASSERT().
4891 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4892 If Length is not aligned on a 64-bit boundary, then ASSERT().
4893 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4895 @param Buffer The pointer to the buffer to carry out the sum operation.
4896 @param Length The size, in bytes, of Buffer.
4898 @return Sum The sum of Buffer with carry bits dropped during additions.
4904 IN CONST UINT64
*Buffer
,
4910 Returns the two's complement checksum of all elements in a buffer of
4913 This function first calculates the sum of the 64-bit values in the buffer
4914 specified by Buffer and Length. The carry bits in the result of addition
4915 are dropped. Then, the two's complement of the sum is returned. If Length
4916 is 0, then 0 is returned.
4918 If Buffer is NULL, then ASSERT().
4919 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4920 If Length is not aligned on a 64-bit boundary, then ASSERT().
4921 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4923 @param Buffer The pointer to the buffer to carry out the checksum operation.
4924 @param Length The size, in bytes, of Buffer.
4926 @return Checksum The two's complement checksum of Buffer.
4931 CalculateCheckSum64 (
4932 IN CONST UINT64
*Buffer
,
4937 Computes and returns a 32-bit CRC for a data buffer.
4938 CRC32 value bases on ITU-T V.42.
4940 If Buffer is NULL, then ASSERT().
4941 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4943 @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed.
4944 @param[in] Length The number of bytes in the buffer Data.
4946 @retval Crc32 The 32-bit CRC was computed for the data buffer.
4957 // Base Library CPU Functions
4961 Function entry point used when a stack switch is requested with SwitchStack()
4963 @param Context1 Context1 parameter passed into SwitchStack().
4964 @param Context2 Context2 parameter passed into SwitchStack().
4969 (EFIAPI
*SWITCH_STACK_ENTRY_POINT
)(
4970 IN VOID
*Context1
, OPTIONAL
4971 IN VOID
*Context2 OPTIONAL
4976 Used to serialize load and store operations.
4978 All loads and stores that proceed calls to this function are guaranteed to be
4979 globally visible when this function returns.
4990 Saves the current CPU context that can be restored with a call to LongJump()
4993 Saves the current CPU context in the buffer specified by JumpBuffer and
4994 returns 0. The initial call to SetJump() must always return 0. Subsequent
4995 calls to LongJump() cause a non-zero value to be returned by SetJump().
4997 If JumpBuffer is NULL, then ASSERT().
4998 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
5000 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
5001 The same structure must never be used for more than one CPU architecture context.
5002 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
5003 SetJump()/LongJump() is not currently supported for the EBC processor type.
5005 @param JumpBuffer A pointer to CPU context buffer.
5007 @retval 0 Indicates a return from SetJump().
5014 OUT BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
5019 Restores the CPU context that was saved with SetJump().
5021 Restores the CPU context from the buffer specified by JumpBuffer. This
5022 function never returns to the caller. Instead is resumes execution based on
5023 the state of JumpBuffer.
5025 If JumpBuffer is NULL, then ASSERT().
5026 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
5027 If Value is 0, then ASSERT().
5029 @param JumpBuffer A pointer to CPU context buffer.
5030 @param Value The value to return when the SetJump() context is
5031 restored and must be non-zero.
5037 IN BASE_LIBRARY_JUMP_BUFFER
*JumpBuffer
,
5043 Enables CPU interrupts.
5054 Disables CPU interrupts.
5065 Disables CPU interrupts and returns the interrupt state prior to the disable
5068 @retval TRUE CPU interrupts were enabled on entry to this call.
5069 @retval FALSE CPU interrupts were disabled on entry to this call.
5074 SaveAndDisableInterrupts (
5080 Enables CPU interrupts for the smallest window required to capture any
5086 EnableDisableInterrupts (
5092 Retrieves the current CPU interrupt state.
5094 Returns TRUE if interrupts are currently enabled. Otherwise
5097 @retval TRUE CPU interrupts are enabled.
5098 @retval FALSE CPU interrupts are disabled.
5109 Set the current CPU interrupt state.
5111 Sets the current CPU interrupt state to the state specified by
5112 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If
5113 InterruptState is FALSE, then interrupts are disabled. InterruptState is
5116 @param InterruptState TRUE if interrupts should enabled. FALSE if
5117 interrupts should be disabled.
5119 @return InterruptState
5125 IN BOOLEAN InterruptState
5130 Requests CPU to pause for a short period of time.
5132 Requests CPU to pause for a short period of time. Typically used in MP
5133 systems to prevent memory starvation while waiting for a spin lock.
5144 Transfers control to a function starting with a new stack.
5146 Transfers control to the function specified by EntryPoint using the
5147 new stack specified by NewStack and passing in the parameters specified
5148 by Context1 and Context2. Context1 and Context2 are optional and may
5149 be NULL. The function EntryPoint must never return. This function
5150 supports a variable number of arguments following the NewStack parameter.
5151 These additional arguments are ignored on IA-32, x64, and EBC architectures.
5152 Itanium processors expect one additional parameter of type VOID * that specifies
5153 the new backing store pointer.
5155 If EntryPoint is NULL, then ASSERT().
5156 If NewStack is NULL, then ASSERT().
5158 @param EntryPoint A pointer to function to call with the new stack.
5159 @param Context1 A pointer to the context to pass into the EntryPoint
5161 @param Context2 A pointer to the context to pass into the EntryPoint
5163 @param NewStack A pointer to the new stack to use for the EntryPoint
5165 @param ... This variable argument list is ignored for IA-32, x64, and
5166 EBC architectures. For Itanium processors, this variable
5167 argument list is expected to contain a single parameter of
5168 type VOID * that specifies the new backing store pointer.
5175 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
5176 IN VOID
*Context1
, OPTIONAL
5177 IN VOID
*Context2
, OPTIONAL
5184 Generates a breakpoint on the CPU.
5186 Generates a breakpoint on the CPU. The breakpoint must be implemented such
5187 that code can resume normal execution after the breakpoint.
5198 Executes an infinite loop.
5200 Forces the CPU to execute an infinite loop. A debugger may be used to skip
5201 past the loop and the code that follows the loop must execute properly. This
5202 implies that the infinite loop must not cause the code that follow it to be
5214 Uses as a barrier to stop speculative execution.
5216 Ensures that no later instruction will execute speculatively, until all prior
5217 instructions have completed.
5222 SpeculationBarrier (
5227 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
5229 /// IA32 and x64 Specific Functions.
5230 /// Byte packed structure for 16-bit Real Mode EFLAGS.
5234 UINT32 CF
:1; ///< Carry Flag.
5235 UINT32 Reserved_0
:1; ///< Reserved.
5236 UINT32 PF
:1; ///< Parity Flag.
5237 UINT32 Reserved_1
:1; ///< Reserved.
5238 UINT32 AF
:1; ///< Auxiliary Carry Flag.
5239 UINT32 Reserved_2
:1; ///< Reserved.
5240 UINT32 ZF
:1; ///< Zero Flag.
5241 UINT32 SF
:1; ///< Sign Flag.
5242 UINT32 TF
:1; ///< Trap Flag.
5243 UINT32 IF
:1; ///< Interrupt Enable Flag.
5244 UINT32 DF
:1; ///< Direction Flag.
5245 UINT32 OF
:1; ///< Overflow Flag.
5246 UINT32 IOPL
:2; ///< I/O Privilege Level.
5247 UINT32 NT
:1; ///< Nested Task.
5248 UINT32 Reserved_3
:1; ///< Reserved.
5254 /// Byte packed structure for EFLAGS/RFLAGS.
5255 /// 32-bits on IA-32.
5256 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5260 UINT32 CF
:1; ///< Carry Flag.
5261 UINT32 Reserved_0
:1; ///< Reserved.
5262 UINT32 PF
:1; ///< Parity Flag.
5263 UINT32 Reserved_1
:1; ///< Reserved.
5264 UINT32 AF
:1; ///< Auxiliary Carry Flag.
5265 UINT32 Reserved_2
:1; ///< Reserved.
5266 UINT32 ZF
:1; ///< Zero Flag.
5267 UINT32 SF
:1; ///< Sign Flag.
5268 UINT32 TF
:1; ///< Trap Flag.
5269 UINT32 IF
:1; ///< Interrupt Enable Flag.
5270 UINT32 DF
:1; ///< Direction Flag.
5271 UINT32 OF
:1; ///< Overflow Flag.
5272 UINT32 IOPL
:2; ///< I/O Privilege Level.
5273 UINT32 NT
:1; ///< Nested Task.
5274 UINT32 Reserved_3
:1; ///< Reserved.
5275 UINT32 RF
:1; ///< Resume Flag.
5276 UINT32 VM
:1; ///< Virtual 8086 Mode.
5277 UINT32 AC
:1; ///< Alignment Check.
5278 UINT32 VIF
:1; ///< Virtual Interrupt Flag.
5279 UINT32 VIP
:1; ///< Virtual Interrupt Pending.
5280 UINT32 ID
:1; ///< ID Flag.
5281 UINT32 Reserved_4
:10; ///< Reserved.
5287 /// Byte packed structure for Control Register 0 (CR0).
5288 /// 32-bits on IA-32.
5289 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5293 UINT32 PE
:1; ///< Protection Enable.
5294 UINT32 MP
:1; ///< Monitor Coprocessor.
5295 UINT32 EM
:1; ///< Emulation.
5296 UINT32 TS
:1; ///< Task Switched.
5297 UINT32 ET
:1; ///< Extension Type.
5298 UINT32 NE
:1; ///< Numeric Error.
5299 UINT32 Reserved_0
:10; ///< Reserved.
5300 UINT32 WP
:1; ///< Write Protect.
5301 UINT32 Reserved_1
:1; ///< Reserved.
5302 UINT32 AM
:1; ///< Alignment Mask.
5303 UINT32 Reserved_2
:10; ///< Reserved.
5304 UINT32 NW
:1; ///< Mot Write-through.
5305 UINT32 CD
:1; ///< Cache Disable.
5306 UINT32 PG
:1; ///< Paging.
5312 /// Byte packed structure for Control Register 4 (CR4).
5313 /// 32-bits on IA-32.
5314 /// 64-bits on x64. The upper 32-bits on x64 are reserved.
5318 UINT32 VME
:1; ///< Virtual-8086 Mode Extensions.
5319 UINT32 PVI
:1; ///< Protected-Mode Virtual Interrupts.
5320 UINT32 TSD
:1; ///< Time Stamp Disable.
5321 UINT32 DE
:1; ///< Debugging Extensions.
5322 UINT32 PSE
:1; ///< Page Size Extensions.
5323 UINT32 PAE
:1; ///< Physical Address Extension.
5324 UINT32 MCE
:1; ///< Machine Check Enable.
5325 UINT32 PGE
:1; ///< Page Global Enable.
5326 UINT32 PCE
:1; ///< Performance Monitoring Counter
5328 UINT32 OSFXSR
:1; ///< Operating System Support for
5329 ///< FXSAVE and FXRSTOR instructions
5330 UINT32 OSXMMEXCPT
:1; ///< Operating System Support for
5331 ///< Unmasked SIMD Floating Point
5333 UINT32 Reserved_0
:2; ///< Reserved.
5334 UINT32 VMXE
:1; ///< VMX Enable
5335 UINT32 Reserved_1
:18; ///< Reserved.
5341 /// Byte packed structure for a segment descriptor in a GDT/LDT.
5360 } IA32_SEGMENT_DESCRIPTOR
;
5363 /// Byte packed structure for an IDTR, GDTR, LDTR descriptor.
5372 #define IA32_IDT_GATE_TYPE_TASK 0x85
5373 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86
5374 #define IA32_IDT_GATE_TYPE_TRAP_16 0x87
5375 #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E
5376 #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F
5378 #define IA32_GDT_TYPE_TSS 0x9
5379 #define IA32_GDT_ALIGNMENT 8
5381 #if defined (MDE_CPU_IA32)
5383 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
5387 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5388 UINT32 Selector
:16; ///< Selector.
5389 UINT32 Reserved_0
:8; ///< Reserved.
5390 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5391 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5394 } IA32_IDT_GATE_DESCRIPTOR
;
5398 // IA32 Task-State Segment Definition
5401 UINT16 PreviousTaskLink
;
5435 UINT16 LDTSegmentSelector
;
5438 UINT16 IOMapBaseAddress
;
5439 } IA32_TASK_STATE_SEGMENT
;
5443 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5444 UINT32 BaseLow
:16; ///< Base Address 15..00
5445 UINT32 BaseMid
:8; ///< Base Address 23..16
5446 UINT32 Type
:4; ///< Type (1 0 B 1)
5447 UINT32 Reserved_43
:1; ///< 0
5448 UINT32 DPL
:2; ///< Descriptor Privilege Level
5449 UINT32 P
:1; ///< Segment Present
5450 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5451 UINT32 AVL
:1; ///< Available for use by system software
5452 UINT32 Reserved_52
:2; ///< 0 0
5453 UINT32 G
:1; ///< Granularity
5454 UINT32 BaseHigh
:8; ///< Base Address 31..24
5457 } IA32_TSS_DESCRIPTOR
;
5460 #endif // defined (MDE_CPU_IA32)
5462 #if defined (MDE_CPU_X64)
5464 /// Byte packed structure for an x64 Interrupt Gate Descriptor.
5468 UINT32 OffsetLow
:16; ///< Offset bits 15..0.
5469 UINT32 Selector
:16; ///< Selector.
5470 UINT32 Reserved_0
:8; ///< Reserved.
5471 UINT32 GateType
:8; ///< Gate Type. See #defines above.
5472 UINT32 OffsetHigh
:16; ///< Offset bits 31..16.
5473 UINT32 OffsetUpper
:32; ///< Offset bits 63..32.
5474 UINT32 Reserved_1
:32; ///< Reserved.
5480 } IA32_IDT_GATE_DESCRIPTOR
;
5484 // IA32 Task-State Segment Definition
5494 UINT16 Reserved_100
;
5495 UINT16 IOMapBaseAddress
;
5496 } IA32_TASK_STATE_SEGMENT
;
5500 UINT32 LimitLow
:16; ///< Segment Limit 15..00
5501 UINT32 BaseLow
:16; ///< Base Address 15..00
5502 UINT32 BaseMidl
:8; ///< Base Address 23..16
5503 UINT32 Type
:4; ///< Type (1 0 B 1)
5504 UINT32 Reserved_43
:1; ///< 0
5505 UINT32 DPL
:2; ///< Descriptor Privilege Level
5506 UINT32 P
:1; ///< Segment Present
5507 UINT32 LimitHigh
:4; ///< Segment Limit 19..16
5508 UINT32 AVL
:1; ///< Available for use by system software
5509 UINT32 Reserved_52
:2; ///< 0 0
5510 UINT32 G
:1; ///< Granularity
5511 UINT32 BaseMidh
:8; ///< Base Address 31..24
5512 UINT32 BaseHigh
:32; ///< Base Address 63..32
5513 UINT32 Reserved_96
:32; ///< Reserved
5519 } IA32_TSS_DESCRIPTOR
;
5522 #endif // defined (MDE_CPU_X64)
5525 /// Byte packed structure for an FP/SSE/SSE2 context.
5532 /// Structures for the 16-bit real mode thunks.
5585 IA32_EFLAGS32 EFLAGS
;
5595 } IA32_REGISTER_SET
;
5598 /// Byte packed structure for an 16-bit real mode thunks.
5601 IA32_REGISTER_SET
*RealModeState
;
5602 VOID
*RealModeBuffer
;
5603 UINT32 RealModeBufferSize
;
5604 UINT32 ThunkAttributes
;
5607 #define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001
5608 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002
5609 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004
5612 /// Type definition for representing labels in NASM source code that allow for
5613 /// the patching of immediate operands of IA32 and X64 instructions.
5615 /// While the type is technically defined as a function type (note: not a
5616 /// pointer-to-function type), such labels in NASM source code never stand for
5617 /// actual functions, and identifiers declared with this function type should
5618 /// never be called. This is also why the EFIAPI calling convention specifier
5619 /// is missing from the typedef, and why the typedef does not follow the usual
5620 /// edk2 coding style for function (or pointer-to-function) typedefs. The VOID
5621 /// return type and the VOID argument list are merely artifacts.
5623 typedef VOID (X86_ASSEMBLY_PATCH_LABEL
) (VOID
);
5626 Retrieves CPUID information.
5628 Executes the CPUID instruction with EAX set to the value specified by Index.
5629 This function always returns Index.
5630 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5631 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5632 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5633 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5634 This function is only available on IA-32 and x64.
5636 @param Index The 32-bit value to load into EAX prior to invoking the CPUID
5638 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5639 instruction. This is an optional parameter that may be NULL.
5640 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5641 instruction. This is an optional parameter that may be NULL.
5642 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5643 instruction. This is an optional parameter that may be NULL.
5644 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5645 instruction. This is an optional parameter that may be NULL.
5654 OUT UINT32
*Eax
, OPTIONAL
5655 OUT UINT32
*Ebx
, OPTIONAL
5656 OUT UINT32
*Ecx
, OPTIONAL
5657 OUT UINT32
*Edx OPTIONAL
5662 Retrieves CPUID information using an extended leaf identifier.
5664 Executes the CPUID instruction with EAX set to the value specified by Index
5665 and ECX set to the value specified by SubIndex. This function always returns
5666 Index. This function is only available on IA-32 and x64.
5668 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
5669 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
5670 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
5671 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
5673 @param Index The 32-bit value to load into EAX prior to invoking the
5675 @param SubIndex The 32-bit value to load into ECX prior to invoking the
5677 @param Eax The pointer to the 32-bit EAX value returned by the CPUID
5678 instruction. This is an optional parameter that may be
5680 @param Ebx The pointer to the 32-bit EBX value returned by the CPUID
5681 instruction. This is an optional parameter that may be
5683 @param Ecx The pointer to the 32-bit ECX value returned by the CPUID
5684 instruction. This is an optional parameter that may be
5686 @param Edx The pointer to the 32-bit EDX value returned by the CPUID
5687 instruction. This is an optional parameter that may be
5698 OUT UINT32
*Eax
, OPTIONAL
5699 OUT UINT32
*Ebx
, OPTIONAL
5700 OUT UINT32
*Ecx
, OPTIONAL
5701 OUT UINT32
*Edx OPTIONAL
5706 Set CD bit and clear NW bit of CR0 followed by a WBINVD.
5708 Disables the caches by setting the CD bit of CR0 to 1, clearing the NW bit of CR0 to 0,
5709 and executing a WBINVD instruction. This function is only available on IA-32 and x64.
5720 Perform a WBINVD and clear both the CD and NW bits of CR0.
5722 Enables the caches by executing a WBINVD instruction and then clear both the CD and NW
5723 bits of CR0 to 0. This function is only available on IA-32 and x64.
5734 Returns the lower 32-bits of a Machine Specific Register(MSR).
5736 Reads and returns the lower 32-bits of the MSR specified by Index.
5737 No parameter checking is performed on Index, and some Index values may cause
5738 CPU exceptions. The caller must either guarantee that Index is valid, or the
5739 caller must set up exception handlers to catch the exceptions. This function
5740 is only available on IA-32 and x64.
5742 @param Index The 32-bit MSR index to read.
5744 @return The lower 32 bits of the MSR identified by Index.
5755 Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.
5756 The upper 32-bits of the MSR are set to zero.
5758 Writes the 32-bit value specified by Value to the MSR specified by Index. The
5759 upper 32-bits of the MSR write are set to zero. The 32-bit value written to
5760 the MSR is returned. No parameter checking is performed on Index or Value,
5761 and some of these may cause CPU exceptions. The caller must either guarantee
5762 that Index and Value are valid, or the caller must establish proper exception
5763 handlers. This function is only available on IA-32 and x64.
5765 @param Index The 32-bit MSR index to write.
5766 @param Value The 32-bit value to write to the MSR.
5780 Reads a 64-bit MSR, performs a bitwise OR on the lower 32-bits, and
5781 writes the result back to the 64-bit MSR.
5783 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5784 between the lower 32-bits of the read result and the value specified by
5785 OrData, and writes the result to the 64-bit MSR specified by Index. The lower
5786 32-bits of the value written to the MSR is returned. No parameter checking is
5787 performed on Index or OrData, and some of these may cause CPU exceptions. The
5788 caller must either guarantee that Index and OrData are valid, or the caller
5789 must establish proper exception handlers. This function is only available on
5792 @param Index The 32-bit MSR index to write.
5793 @param OrData The value to OR with the read value from the MSR.
5795 @return The lower 32-bit value written to the MSR.
5807 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes
5808 the result back to the 64-bit MSR.
5810 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5811 lower 32-bits of the read result and the value specified by AndData, and
5812 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of
5813 the value written to the MSR is returned. No parameter checking is performed
5814 on Index or AndData, and some of these may cause CPU exceptions. The caller
5815 must either guarantee that Index and AndData are valid, or the caller must
5816 establish proper exception handlers. This function is only available on IA-32
5819 @param Index The 32-bit MSR index to write.
5820 @param AndData The value to AND with the read value from the MSR.
5822 @return The lower 32-bit value written to the MSR.
5834 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR
5835 on the lower 32-bits, and writes the result back to the 64-bit MSR.
5837 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5838 lower 32-bits of the read result and the value specified by AndData
5839 preserving the upper 32-bits, performs a bitwise OR between the
5840 result of the AND operation and the value specified by OrData, and writes the
5841 result to the 64-bit MSR specified by Address. The lower 32-bits of the value
5842 written to the MSR is returned. No parameter checking is performed on Index,
5843 AndData, or OrData, and some of these may cause CPU exceptions. The caller
5844 must either guarantee that Index, AndData, and OrData are valid, or the
5845 caller must establish proper exception handlers. This function is only
5846 available on IA-32 and x64.
5848 @param Index The 32-bit MSR index to write.
5849 @param AndData The value to AND with the read value from the MSR.
5850 @param OrData The value to OR with the result of the AND operation.
5852 @return The lower 32-bit value written to the MSR.
5865 Reads a bit field of an MSR.
5867 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is
5868 specified by the StartBit and the EndBit. The value of the bit field is
5869 returned. The caller must either guarantee that Index is valid, or the caller
5870 must set up exception handlers to catch the exceptions. This function is only
5871 available on IA-32 and x64.
5873 If StartBit is greater than 31, then ASSERT().
5874 If EndBit is greater than 31, then ASSERT().
5875 If EndBit is less than StartBit, then ASSERT().
5877 @param Index The 32-bit MSR index to read.
5878 @param StartBit The ordinal of the least significant bit in the bit field.
5880 @param EndBit The ordinal of the most significant bit in the bit field.
5883 @return The bit field read from the MSR.
5888 AsmMsrBitFieldRead32 (
5896 Writes a bit field to an MSR.
5898 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit
5899 field is specified by the StartBit and the EndBit. All other bits in the
5900 destination MSR are preserved. The lower 32-bits of the MSR written is
5901 returned. The caller must either guarantee that Index and the data written
5902 is valid, or the caller must set up exception handlers to catch the exceptions.
5903 This function is only available on IA-32 and x64.
5905 If StartBit is greater than 31, then ASSERT().
5906 If EndBit is greater than 31, then ASSERT().
5907 If EndBit is less than StartBit, then ASSERT().
5908 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5910 @param Index The 32-bit MSR index to write.
5911 @param StartBit The ordinal of the least significant bit in the bit field.
5913 @param EndBit The ordinal of the most significant bit in the bit field.
5915 @param Value New value of the bit field.
5917 @return The lower 32-bit of the value written to the MSR.
5922 AsmMsrBitFieldWrite32 (
5931 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the
5932 result back to the bit field in the 64-bit MSR.
5934 Reads the 64-bit MSR specified by Index, performs a bitwise OR
5935 between the read result and the value specified by OrData, and writes the
5936 result to the 64-bit MSR specified by Index. The lower 32-bits of the value
5937 written to the MSR are returned. Extra left bits in OrData are stripped. The
5938 caller must either guarantee that Index and the data written is valid, or
5939 the caller must set up exception handlers to catch the exceptions. This
5940 function is only available on IA-32 and x64.
5942 If StartBit is greater than 31, then ASSERT().
5943 If EndBit is greater than 31, then ASSERT().
5944 If EndBit is less than StartBit, then ASSERT().
5945 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5947 @param Index The 32-bit MSR index to write.
5948 @param StartBit The ordinal of the least significant bit in the bit field.
5950 @param EndBit The ordinal of the most significant bit in the bit field.
5952 @param OrData The value to OR with the read value from the MSR.
5954 @return The lower 32-bit of the value written to the MSR.
5959 AsmMsrBitFieldOr32 (
5968 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
5969 result back to the bit field in the 64-bit MSR.
5971 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
5972 read result and the value specified by AndData, and writes the result to the
5973 64-bit MSR specified by Index. The lower 32-bits of the value written to the
5974 MSR are returned. Extra left bits in AndData are stripped. The caller must
5975 either guarantee that Index and the data written is valid, or the caller must
5976 set up exception handlers to catch the exceptions. This function is only
5977 available on IA-32 and x64.
5979 If StartBit is greater than 31, then ASSERT().
5980 If EndBit is greater than 31, then ASSERT().
5981 If EndBit is less than StartBit, then ASSERT().
5982 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
5984 @param Index The 32-bit MSR index to write.
5985 @param StartBit The ordinal of the least significant bit in the bit field.
5987 @param EndBit The ordinal of the most significant bit in the bit field.
5989 @param AndData The value to AND with the read value from the MSR.
5991 @return The lower 32-bit of the value written to the MSR.
5996 AsmMsrBitFieldAnd32 (
6005 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6006 bitwise OR, and writes the result back to the bit field in the
6009 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by a
6010 bitwise OR between the read result and the value specified by
6011 AndData, and writes the result to the 64-bit MSR specified by Index. The
6012 lower 32-bits of the value written to the MSR are returned. Extra left bits
6013 in both AndData and OrData are stripped. The caller must either guarantee
6014 that Index and the data written is valid, or the caller must set up exception
6015 handlers to catch the exceptions. This function is only available on IA-32
6018 If StartBit is greater than 31, then ASSERT().
6019 If EndBit is greater than 31, then ASSERT().
6020 If EndBit is less than StartBit, then ASSERT().
6021 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6022 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6024 @param Index The 32-bit MSR index to write.
6025 @param StartBit The ordinal of the least significant bit in the bit field.
6027 @param EndBit The ordinal of the most significant bit in the bit field.
6029 @param AndData The value to AND with the read value from the MSR.
6030 @param OrData The value to OR with the result of the AND operation.
6032 @return The lower 32-bit of the value written to the MSR.
6037 AsmMsrBitFieldAndThenOr32 (
6047 Returns a 64-bit Machine Specific Register(MSR).
6049 Reads and returns the 64-bit MSR specified by Index. No parameter checking is
6050 performed on Index, and some Index values may cause CPU exceptions. The
6051 caller must either guarantee that Index is valid, or the caller must set up
6052 exception handlers to catch the exceptions. This function is only available
6055 @param Index The 32-bit MSR index to read.
6057 @return The value of the MSR identified by Index.
6068 Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
6071 Writes the 64-bit value specified by Value to the MSR specified by Index. The
6072 64-bit value written to the MSR is returned. No parameter checking is
6073 performed on Index or Value, and some of these may cause CPU exceptions. The
6074 caller must either guarantee that Index and Value are valid, or the caller
6075 must establish proper exception handlers. This function is only available on
6078 @param Index The 32-bit MSR index to write.
6079 @param Value The 64-bit value to write to the MSR.
6093 Reads a 64-bit MSR, performs a bitwise OR, and writes the result
6094 back to the 64-bit MSR.
6096 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6097 between the read result and the value specified by OrData, and writes the
6098 result to the 64-bit MSR specified by Index. The value written to the MSR is
6099 returned. No parameter checking is performed on Index or OrData, and some of
6100 these may cause CPU exceptions. The caller must either guarantee that Index
6101 and OrData are valid, or the caller must establish proper exception handlers.
6102 This function is only available on IA-32 and x64.
6104 @param Index The 32-bit MSR index to write.
6105 @param OrData The value to OR with the read value from the MSR.
6107 @return The value written back to the MSR.
6119 Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the
6122 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6123 read result and the value specified by OrData, and writes the result to the
6124 64-bit MSR specified by Index. The value written to the MSR is returned. No
6125 parameter checking is performed on Index or OrData, and some of these may
6126 cause CPU exceptions. The caller must either guarantee that Index and OrData
6127 are valid, or the caller must establish proper exception handlers. This
6128 function is only available on IA-32 and x64.
6130 @param Index The 32-bit MSR index to write.
6131 @param AndData The value to AND with the read value from the MSR.
6133 @return The value written back to the MSR.
6145 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise
6146 OR, and writes the result back to the 64-bit MSR.
6148 Reads the 64-bit MSR specified by Index, performs a bitwise AND between read
6149 result and the value specified by AndData, performs a bitwise OR
6150 between the result of the AND operation and the value specified by OrData,
6151 and writes the result to the 64-bit MSR specified by Index. The value written
6152 to the MSR is returned. No parameter checking is performed on Index, AndData,
6153 or OrData, and some of these may cause CPU exceptions. The caller must either
6154 guarantee that Index, AndData, and OrData are valid, or the caller must
6155 establish proper exception handlers. This function is only available on IA-32
6158 @param Index The 32-bit MSR index to write.
6159 @param AndData The value to AND with the read value from the MSR.
6160 @param OrData The value to OR with the result of the AND operation.
6162 @return The value written back to the MSR.
6175 Reads a bit field of an MSR.
6177 Reads the bit field in the 64-bit MSR. The bit field is specified by the
6178 StartBit and the EndBit. The value of the bit field is returned. The caller
6179 must either guarantee that Index is valid, or the caller must set up
6180 exception handlers to catch the exceptions. This function is only available
6183 If StartBit is greater than 63, then ASSERT().
6184 If EndBit is greater than 63, then ASSERT().
6185 If EndBit is less than StartBit, then ASSERT().
6187 @param Index The 32-bit MSR index to read.
6188 @param StartBit The ordinal of the least significant bit in the bit field.
6190 @param EndBit The ordinal of the most significant bit in the bit field.
6193 @return The value read from the MSR.
6198 AsmMsrBitFieldRead64 (
6206 Writes a bit field to an MSR.
6208 Writes Value to a bit field in a 64-bit MSR. The bit field is specified by
6209 the StartBit and the EndBit. All other bits in the destination MSR are
6210 preserved. The MSR written is returned. The caller must either guarantee
6211 that Index and the data written is valid, or the caller must set up exception
6212 handlers to catch the exceptions. This function is only available on IA-32 and x64.
6214 If StartBit is greater than 63, then ASSERT().
6215 If EndBit is greater than 63, then ASSERT().
6216 If EndBit is less than StartBit, then ASSERT().
6217 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6219 @param Index The 32-bit MSR index to write.
6220 @param StartBit The ordinal of the least significant bit in the bit field.
6222 @param EndBit The ordinal of the most significant bit in the bit field.
6224 @param Value New value of the bit field.
6226 @return The value written back to the MSR.
6231 AsmMsrBitFieldWrite64 (
6240 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and
6241 writes the result back to the bit field in the 64-bit MSR.
6243 Reads the 64-bit MSR specified by Index, performs a bitwise OR
6244 between the read result and the value specified by OrData, and writes the
6245 result to the 64-bit MSR specified by Index. The value written to the MSR is
6246 returned. Extra left bits in OrData are stripped. The caller must either
6247 guarantee that Index and the data written is valid, or the caller must set up
6248 exception handlers to catch the exceptions. This function is only available
6251 If StartBit is greater than 63, then ASSERT().
6252 If EndBit is greater than 63, then ASSERT().
6253 If EndBit is less than StartBit, then ASSERT().
6254 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6256 @param Index The 32-bit MSR index to write.
6257 @param StartBit The ordinal of the least significant bit in the bit field.
6259 @param EndBit The ordinal of the most significant bit in the bit field.
6261 @param OrData The value to OR with the read value from the bit field.
6263 @return The value written back to the MSR.
6268 AsmMsrBitFieldOr64 (
6277 Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the
6278 result back to the bit field in the 64-bit MSR.
6280 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the
6281 read result and the value specified by AndData, and writes the result to the
6282 64-bit MSR specified by Index. The value written to the MSR is returned.
6283 Extra left bits in AndData are stripped. The caller must either guarantee
6284 that Index and the data written is valid, or the caller must set up exception
6285 handlers to catch the exceptions. This function is only available on IA-32
6288 If StartBit is greater than 63, then ASSERT().
6289 If EndBit is greater than 63, then ASSERT().
6290 If EndBit is less than StartBit, then ASSERT().
6291 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6293 @param Index The 32-bit MSR index to write.
6294 @param StartBit The ordinal of the least significant bit in the bit field.
6296 @param EndBit The ordinal of the most significant bit in the bit field.
6298 @param AndData The value to AND with the read value from the bit field.
6300 @return The value written back to the MSR.
6305 AsmMsrBitFieldAnd64 (
6314 Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a
6315 bitwise OR, and writes the result back to the bit field in the
6318 Reads the 64-bit MSR specified by Index, performs a bitwise AND followed by
6319 a bitwise OR between the read result and the value specified by
6320 AndData, and writes the result to the 64-bit MSR specified by Index. The
6321 value written to the MSR is returned. Extra left bits in both AndData and
6322 OrData are stripped. The caller must either guarantee that Index and the data
6323 written is valid, or the caller must set up exception handlers to catch the
6324 exceptions. This function is only available on IA-32 and x64.
6326 If StartBit is greater than 63, then ASSERT().
6327 If EndBit is greater than 63, then ASSERT().
6328 If EndBit is less than StartBit, then ASSERT().
6329 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6330 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
6332 @param Index The 32-bit MSR index to write.
6333 @param StartBit The ordinal of the least significant bit in the bit field.
6335 @param EndBit The ordinal of the most significant bit in the bit field.
6337 @param AndData The value to AND with the read value from the bit field.
6338 @param OrData The value to OR with the result of the AND operation.
6340 @return The value written back to the MSR.
6345 AsmMsrBitFieldAndThenOr64 (
6355 Reads the current value of the EFLAGS register.
6357 Reads and returns the current value of the EFLAGS register. This function is
6358 only available on IA-32 and x64. This returns a 32-bit value on IA-32 and a
6359 64-bit value on x64.
6361 @return EFLAGS on IA-32 or RFLAGS on x64.
6372 Reads the current value of the Control Register 0 (CR0).
6374 Reads and returns the current value of CR0. This function is only available
6375 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6378 @return The value of the Control Register 0 (CR0).
6389 Reads the current value of the Control Register 2 (CR2).
6391 Reads and returns the current value of CR2. This function is only available
6392 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6395 @return The value of the Control Register 2 (CR2).
6406 Reads the current value of the Control Register 3 (CR3).
6408 Reads and returns the current value of CR3. This function is only available
6409 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6412 @return The value of the Control Register 3 (CR3).
6423 Reads the current value of the Control Register 4 (CR4).
6425 Reads and returns the current value of CR4. This function is only available
6426 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6429 @return The value of the Control Register 4 (CR4).
6440 Writes a value to Control Register 0 (CR0).
6442 Writes and returns a new value to CR0. This function is only available on
6443 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6445 @param Cr0 The value to write to CR0.
6447 @return The value written to CR0.
6458 Writes a value to Control Register 2 (CR2).
6460 Writes and returns a new value to CR2. This function is only available on
6461 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6463 @param Cr2 The value to write to CR2.
6465 @return The value written to CR2.
6476 Writes a value to Control Register 3 (CR3).
6478 Writes and returns a new value to CR3. This function is only available on
6479 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6481 @param Cr3 The value to write to CR3.
6483 @return The value written to CR3.
6494 Writes a value to Control Register 4 (CR4).
6496 Writes and returns a new value to CR4. This function is only available on
6497 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6499 @param Cr4 The value to write to CR4.
6501 @return The value written to CR4.
6512 Reads the current value of Debug Register 0 (DR0).
6514 Reads and returns the current value of DR0. This function is only available
6515 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6518 @return The value of Debug Register 0 (DR0).
6529 Reads the current value of Debug Register 1 (DR1).
6531 Reads and returns the current value of DR1. This function is only available
6532 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6535 @return The value of Debug Register 1 (DR1).
6546 Reads the current value of Debug Register 2 (DR2).
6548 Reads and returns the current value of DR2. This function is only available
6549 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6552 @return The value of Debug Register 2 (DR2).
6563 Reads the current value of Debug Register 3 (DR3).
6565 Reads and returns the current value of DR3. This function is only available
6566 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6569 @return The value of Debug Register 3 (DR3).
6580 Reads the current value of Debug Register 4 (DR4).
6582 Reads and returns the current value of DR4. This function is only available
6583 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6586 @return The value of Debug Register 4 (DR4).
6597 Reads the current value of Debug Register 5 (DR5).
6599 Reads and returns the current value of DR5. This function is only available
6600 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6603 @return The value of Debug Register 5 (DR5).
6614 Reads the current value of Debug Register 6 (DR6).
6616 Reads and returns the current value of DR6. This function is only available
6617 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6620 @return The value of Debug Register 6 (DR6).
6631 Reads the current value of Debug Register 7 (DR7).
6633 Reads and returns the current value of DR7. This function is only available
6634 on IA-32 and x64. This returns a 32-bit value on IA-32 and a 64-bit value on
6637 @return The value of Debug Register 7 (DR7).
6648 Writes a value to Debug Register 0 (DR0).
6650 Writes and returns a new value to DR0. This function is only available on
6651 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6653 @param Dr0 The value to write to Dr0.
6655 @return The value written to Debug Register 0 (DR0).
6666 Writes a value to Debug Register 1 (DR1).
6668 Writes and returns a new value to DR1. This function is only available on
6669 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6671 @param Dr1 The value to write to Dr1.
6673 @return The value written to Debug Register 1 (DR1).
6684 Writes a value to Debug Register 2 (DR2).
6686 Writes and returns a new value to DR2. This function is only available on
6687 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6689 @param Dr2 The value to write to Dr2.
6691 @return The value written to Debug Register 2 (DR2).
6702 Writes a value to Debug Register 3 (DR3).
6704 Writes and returns a new value to DR3. This function is only available on
6705 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6707 @param Dr3 The value to write to Dr3.
6709 @return The value written to Debug Register 3 (DR3).
6720 Writes a value to Debug Register 4 (DR4).
6722 Writes and returns a new value to DR4. This function is only available on
6723 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6725 @param Dr4 The value to write to Dr4.
6727 @return The value written to Debug Register 4 (DR4).
6738 Writes a value to Debug Register 5 (DR5).
6740 Writes and returns a new value to DR5. This function is only available on
6741 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6743 @param Dr5 The value to write to Dr5.
6745 @return The value written to Debug Register 5 (DR5).
6756 Writes a value to Debug Register 6 (DR6).
6758 Writes and returns a new value to DR6. This function is only available on
6759 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6761 @param Dr6 The value to write to Dr6.
6763 @return The value written to Debug Register 6 (DR6).
6774 Writes a value to Debug Register 7 (DR7).
6776 Writes and returns a new value to DR7. This function is only available on
6777 IA-32 and x64. This writes a 32-bit value on IA-32 and a 64-bit value on x64.
6779 @param Dr7 The value to write to Dr7.
6781 @return The value written to Debug Register 7 (DR7).
6792 Reads the current value of Code Segment Register (CS).
6794 Reads and returns the current value of CS. This function is only available on
6797 @return The current value of CS.
6808 Reads the current value of Data Segment Register (DS).
6810 Reads and returns the current value of DS. This function is only available on
6813 @return The current value of DS.
6824 Reads the current value of Extra Segment Register (ES).
6826 Reads and returns the current value of ES. This function is only available on
6829 @return The current value of ES.
6840 Reads the current value of FS Data Segment Register (FS).
6842 Reads and returns the current value of FS. This function is only available on
6845 @return The current value of FS.
6856 Reads the current value of GS Data Segment Register (GS).
6858 Reads and returns the current value of GS. This function is only available on
6861 @return The current value of GS.
6872 Reads the current value of Stack Segment Register (SS).
6874 Reads and returns the current value of SS. This function is only available on
6877 @return The current value of SS.
6888 Reads the current value of Task Register (TR).
6890 Reads and returns the current value of TR. This function is only available on
6893 @return The current value of TR.
6904 Reads the current Global Descriptor Table Register(GDTR) descriptor.
6906 Reads and returns the current GDTR descriptor and returns it in Gdtr. This
6907 function is only available on IA-32 and x64.
6909 If Gdtr is NULL, then ASSERT().
6911 @param Gdtr The pointer to a GDTR descriptor.
6917 OUT IA32_DESCRIPTOR
*Gdtr
6922 Writes the current Global Descriptor Table Register (GDTR) descriptor.
6924 Writes and the current GDTR descriptor specified by Gdtr. This function is
6925 only available on IA-32 and x64.
6927 If Gdtr is NULL, then ASSERT().
6929 @param Gdtr The pointer to a GDTR descriptor.
6935 IN CONST IA32_DESCRIPTOR
*Gdtr
6940 Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.
6942 Reads and returns the current IDTR descriptor and returns it in Idtr. This
6943 function is only available on IA-32 and x64.
6945 If Idtr is NULL, then ASSERT().
6947 @param Idtr The pointer to a IDTR descriptor.
6953 OUT IA32_DESCRIPTOR
*Idtr
6958 Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.
6960 Writes the current IDTR descriptor and returns it in Idtr. This function is
6961 only available on IA-32 and x64.
6963 If Idtr is NULL, then ASSERT().
6965 @param Idtr The pointer to a IDTR descriptor.
6971 IN CONST IA32_DESCRIPTOR
*Idtr
6976 Reads the current Local Descriptor Table Register(LDTR) selector.
6978 Reads and returns the current 16-bit LDTR descriptor value. This function is
6979 only available on IA-32 and x64.
6981 @return The current selector of LDT.
6992 Writes the current Local Descriptor Table Register (LDTR) selector.
6994 Writes and the current LDTR descriptor specified by Ldtr. This function is
6995 only available on IA-32 and x64.
6997 @param Ldtr 16-bit LDTR selector value.
7008 Save the current floating point/SSE/SSE2 context to a buffer.
7010 Saves the current floating point/SSE/SSE2 state to the buffer specified by
7011 Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
7012 available on IA-32 and x64.
7014 If Buffer is NULL, then ASSERT().
7015 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7017 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7023 OUT IA32_FX_BUFFER
*Buffer
7028 Restores the current floating point/SSE/SSE2 context from a buffer.
7030 Restores the current floating point/SSE/SSE2 state from the buffer specified
7031 by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
7032 only available on IA-32 and x64.
7034 If Buffer is NULL, then ASSERT().
7035 If Buffer is not aligned on a 16-byte boundary, then ASSERT().
7036 If Buffer was not saved with AsmFxSave(), then ASSERT().
7038 @param Buffer The pointer to a buffer to save the floating point/SSE/SSE2 context.
7044 IN CONST IA32_FX_BUFFER
*Buffer
7049 Reads the current value of 64-bit MMX Register #0 (MM0).
7051 Reads and returns the current value of MM0. This function is only available
7054 @return The current value of MM0.
7065 Reads the current value of 64-bit MMX Register #1 (MM1).
7067 Reads and returns the current value of MM1. This function is only available
7070 @return The current value of MM1.
7081 Reads the current value of 64-bit MMX Register #2 (MM2).
7083 Reads and returns the current value of MM2. This function is only available
7086 @return The current value of MM2.
7097 Reads the current value of 64-bit MMX Register #3 (MM3).
7099 Reads and returns the current value of MM3. This function is only available
7102 @return The current value of MM3.
7113 Reads the current value of 64-bit MMX Register #4 (MM4).
7115 Reads and returns the current value of MM4. This function is only available
7118 @return The current value of MM4.
7129 Reads the current value of 64-bit MMX Register #5 (MM5).
7131 Reads and returns the current value of MM5. This function is only available
7134 @return The current value of MM5.
7145 Reads the current value of 64-bit MMX Register #6 (MM6).
7147 Reads and returns the current value of MM6. This function is only available
7150 @return The current value of MM6.
7161 Reads the current value of 64-bit MMX Register #7 (MM7).
7163 Reads and returns the current value of MM7. This function is only available
7166 @return The current value of MM7.
7177 Writes the current value of 64-bit MMX Register #0 (MM0).
7179 Writes the current value of MM0. This function is only available on IA32 and
7182 @param Value The 64-bit value to write to MM0.
7193 Writes the current value of 64-bit MMX Register #1 (MM1).
7195 Writes the current value of MM1. This function is only available on IA32 and
7198 @param Value The 64-bit value to write to MM1.
7209 Writes the current value of 64-bit MMX Register #2 (MM2).
7211 Writes the current value of MM2. This function is only available on IA32 and
7214 @param Value The 64-bit value to write to MM2.
7225 Writes the current value of 64-bit MMX Register #3 (MM3).
7227 Writes the current value of MM3. This function is only available on IA32 and
7230 @param Value The 64-bit value to write to MM3.
7241 Writes the current value of 64-bit MMX Register #4 (MM4).
7243 Writes the current value of MM4. This function is only available on IA32 and
7246 @param Value The 64-bit value to write to MM4.
7257 Writes the current value of 64-bit MMX Register #5 (MM5).
7259 Writes the current value of MM5. This function is only available on IA32 and
7262 @param Value The 64-bit value to write to MM5.
7273 Writes the current value of 64-bit MMX Register #6 (MM6).
7275 Writes the current value of MM6. This function is only available on IA32 and
7278 @param Value The 64-bit value to write to MM6.
7289 Writes the current value of 64-bit MMX Register #7 (MM7).
7291 Writes the current value of MM7. This function is only available on IA32 and
7294 @param Value The 64-bit value to write to MM7.
7305 Reads the current value of Time Stamp Counter (TSC).
7307 Reads and returns the current value of TSC. This function is only available
7310 @return The current value of TSC
7321 Reads the current value of a Performance Counter (PMC).
7323 Reads and returns the current value of performance counter specified by
7324 Index. This function is only available on IA-32 and x64.
7326 @param Index The 32-bit Performance Counter index to read.
7328 @return The value of the PMC specified by Index.
7339 Sets up a monitor buffer that is used by AsmMwait().
7341 Executes a MONITOR instruction with the register state specified by Eax, Ecx
7342 and Edx. Returns Eax. This function is only available on IA-32 and x64.
7344 @param Eax The value to load into EAX or RAX before executing the MONITOR
7346 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7348 @param Edx The value to load into EDX or RDX before executing the MONITOR
7364 Executes an MWAIT instruction.
7366 Executes an MWAIT instruction with the register state specified by Eax and
7367 Ecx. Returns Eax. This function is only available on IA-32 and x64.
7369 @param Eax The value to load into EAX or RAX before executing the MONITOR
7371 @param Ecx The value to load into ECX or RCX before executing the MONITOR
7386 Executes a WBINVD instruction.
7388 Executes a WBINVD instruction. This function is only available on IA-32 and
7400 Executes a INVD instruction.
7402 Executes a INVD instruction. This function is only available on IA-32 and
7414 Flushes a cache line from all the instruction and data caches within the
7415 coherency domain of the CPU.
7417 Flushed the cache line specified by LinearAddress, and returns LinearAddress.
7418 This function is only available on IA-32 and x64.
7420 @param LinearAddress The address of the cache line to flush. If the CPU is
7421 in a physical addressing mode, then LinearAddress is a
7422 physical address. If the CPU is in a virtual
7423 addressing mode, then LinearAddress is a virtual
7426 @return LinearAddress.
7431 IN VOID
*LinearAddress
7436 Enables the 32-bit paging mode on the CPU.
7438 Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7439 must be properly initialized prior to calling this service. This function
7440 assumes the current execution mode is 32-bit protected mode. This function is
7441 only available on IA-32. After the 32-bit paging mode is enabled, control is
7442 transferred to the function specified by EntryPoint using the new stack
7443 specified by NewStack and passing in the parameters specified by Context1 and
7444 Context2. Context1 and Context2 are optional and may be NULL. The function
7445 EntryPoint must never return.
7447 If the current execution mode is not 32-bit protected mode, then ASSERT().
7448 If EntryPoint is NULL, then ASSERT().
7449 If NewStack is NULL, then ASSERT().
7451 There are a number of constraints that must be followed before calling this
7453 1) Interrupts must be disabled.
7454 2) The caller must be in 32-bit protected mode with flat descriptors. This
7455 means all descriptors must have a base of 0 and a limit of 4GB.
7456 3) CR0 and CR4 must be compatible with 32-bit protected mode with flat
7458 4) CR3 must point to valid page tables that will be used once the transition
7459 is complete, and those page tables must guarantee that the pages for this
7460 function and the stack are identity mapped.
7462 @param EntryPoint A pointer to function to call with the new stack after
7464 @param Context1 A pointer to the context to pass into the EntryPoint
7465 function as the first parameter after paging is enabled.
7466 @param Context2 A pointer to the context to pass into the EntryPoint
7467 function as the second parameter after paging is enabled.
7468 @param NewStack A pointer to the new stack to use for the EntryPoint
7469 function after paging is enabled.
7475 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7476 IN VOID
*Context1
, OPTIONAL
7477 IN VOID
*Context2
, OPTIONAL
7483 Disables the 32-bit paging mode on the CPU.
7485 Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
7486 mode. This function assumes the current execution mode is 32-paged protected
7487 mode. This function is only available on IA-32. After the 32-bit paging mode
7488 is disabled, control is transferred to the function specified by EntryPoint
7489 using the new stack specified by NewStack and passing in the parameters
7490 specified by Context1 and Context2. Context1 and Context2 are optional and
7491 may be NULL. The function EntryPoint must never return.
7493 If the current execution mode is not 32-bit paged mode, then ASSERT().
7494 If EntryPoint is NULL, then ASSERT().
7495 If NewStack is NULL, then ASSERT().
7497 There are a number of constraints that must be followed before calling this
7499 1) Interrupts must be disabled.
7500 2) The caller must be in 32-bit paged mode.
7501 3) CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
7502 4) CR3 must point to valid page tables that guarantee that the pages for
7503 this function and the stack are identity mapped.
7505 @param EntryPoint A pointer to function to call with the new stack after
7507 @param Context1 A pointer to the context to pass into the EntryPoint
7508 function as the first parameter after paging is disabled.
7509 @param Context2 A pointer to the context to pass into the EntryPoint
7510 function as the second parameter after paging is
7512 @param NewStack A pointer to the new stack to use for the EntryPoint
7513 function after paging is disabled.
7518 AsmDisablePaging32 (
7519 IN SWITCH_STACK_ENTRY_POINT EntryPoint
,
7520 IN VOID
*Context1
, OPTIONAL
7521 IN VOID
*Context2
, OPTIONAL
7527 Enables the 64-bit paging mode on the CPU.
7529 Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
7530 must be properly initialized prior to calling this service. This function
7531 assumes the current execution mode is 32-bit protected mode with flat
7532 descriptors. This function is only available on IA-32. After the 64-bit
7533 paging mode is enabled, control is transferred to the function specified by
7534 EntryPoint using the new stack specified by NewStack and passing in the
7535 parameters specified by Context1 and Context2. Context1 and Context2 are
7536 optional and may be 0. The function EntryPoint must never return.
7538 If the current execution mode is not 32-bit protected mode with flat
7539 descriptors, then ASSERT().
7540 If EntryPoint is 0, then ASSERT().
7541 If NewStack is 0, then ASSERT().
7543 @param Cs The 16-bit selector to load in the CS before EntryPoint
7544 is called. The descriptor in the GDT that this selector
7545 references must be setup for long mode.
7546 @param EntryPoint The 64-bit virtual address of the function to call with
7547 the new stack after paging is enabled.
7548 @param Context1 The 64-bit virtual address of the context to pass into
7549 the EntryPoint function as the first parameter after
7551 @param Context2 The 64-bit virtual address of the context to pass into
7552 the EntryPoint function as the second parameter after
7554 @param NewStack The 64-bit virtual address of the new stack to use for
7555 the EntryPoint function after paging is enabled.
7562 IN UINT64 EntryPoint
,
7563 IN UINT64 Context1
, OPTIONAL
7564 IN UINT64 Context2
, OPTIONAL
7570 Disables the 64-bit paging mode on the CPU.
7572 Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
7573 mode. This function assumes the current execution mode is 64-paging mode.
7574 This function is only available on x64. After the 64-bit paging mode is
7575 disabled, control is transferred to the function specified by EntryPoint
7576 using the new stack specified by NewStack and passing in the parameters
7577 specified by Context1 and Context2. Context1 and Context2 are optional and
7578 may be 0. The function EntryPoint must never return.
7580 If the current execution mode is not 64-bit paged mode, then ASSERT().
7581 If EntryPoint is 0, then ASSERT().
7582 If NewStack is 0, then ASSERT().
7584 @param Cs The 16-bit selector to load in the CS before EntryPoint
7585 is called. The descriptor in the GDT that this selector
7586 references must be setup for 32-bit protected mode.
7587 @param EntryPoint The 64-bit virtual address of the function to call with
7588 the new stack after paging is disabled.
7589 @param Context1 The 64-bit virtual address of the context to pass into
7590 the EntryPoint function as the first parameter after
7592 @param Context2 The 64-bit virtual address of the context to pass into
7593 the EntryPoint function as the second parameter after
7595 @param NewStack The 64-bit virtual address of the new stack to use for
7596 the EntryPoint function after paging is disabled.
7601 AsmDisablePaging64 (
7603 IN UINT32 EntryPoint
,
7604 IN UINT32 Context1
, OPTIONAL
7605 IN UINT32 Context2
, OPTIONAL
7611 // 16-bit thunking services
7615 Retrieves the properties for 16-bit thunk functions.
7617 Computes the size of the buffer and stack below 1MB required to use the
7618 AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
7619 buffer size is returned in RealModeBufferSize, and the stack size is returned
7620 in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
7621 then the actual minimum stack size is ExtraStackSize plus the maximum number
7622 of bytes that need to be passed to the 16-bit real mode code.
7624 If RealModeBufferSize is NULL, then ASSERT().
7625 If ExtraStackSize is NULL, then ASSERT().
7627 @param RealModeBufferSize A pointer to the size of the buffer below 1MB
7628 required to use the 16-bit thunk functions.
7629 @param ExtraStackSize A pointer to the extra size of stack below 1MB
7630 that the 16-bit thunk functions require for
7631 temporary storage in the transition to and from
7637 AsmGetThunk16Properties (
7638 OUT UINT32
*RealModeBufferSize
,
7639 OUT UINT32
*ExtraStackSize
7644 Prepares all structures a code required to use AsmThunk16().
7646 Prepares all structures and code required to use AsmThunk16().
7648 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7649 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7651 If ThunkContext is NULL, then ASSERT().
7653 @param ThunkContext A pointer to the context structure that describes the
7654 16-bit real mode code to call.
7660 IN OUT THUNK_CONTEXT
*ThunkContext
7665 Transfers control to a 16-bit real mode entry point and returns the results.
7667 Transfers control to a 16-bit real mode entry point and returns the results.
7668 AsmPrepareThunk16() must be called with ThunkContext before this function is used.
7669 This function must be called with interrupts disabled.
7671 The register state from the RealModeState field of ThunkContext is restored just prior
7672 to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState,
7673 which is used to set the interrupt state when a 16-bit real mode entry point is called.
7674 Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.
7675 The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to
7676 the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function.
7677 The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,
7678 so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment
7679 and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry
7680 point must exit with a RETF instruction. The register state is captured into RealModeState immediately
7681 after the RETF instruction is executed.
7683 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7684 or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure
7685 the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode.
7687 If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts,
7688 then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode.
7689 This includes the base vectors, the interrupt masks, and the edge/level trigger mode.
7691 If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code
7692 is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.
7694 If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7695 ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to
7696 disable the A20 mask.
7698 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in
7699 ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails,
7700 then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7702 If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in
7703 ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.
7705 If ThunkContext is NULL, then ASSERT().
7706 If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().
7707 If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in
7708 ThunkAttributes, then ASSERT().
7710 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7711 virtual to physical mappings for ThunkContext.RealModeBuffer are mapped 1:1.
7713 @param ThunkContext A pointer to the context structure that describes the
7714 16-bit real mode code to call.
7720 IN OUT THUNK_CONTEXT
*ThunkContext
7725 Prepares all structures and code for a 16-bit real mode thunk, transfers
7726 control to a 16-bit real mode entry point, and returns the results.
7728 Prepares all structures and code for a 16-bit real mode thunk, transfers
7729 control to a 16-bit real mode entry point, and returns the results. If the
7730 caller only need to perform a single 16-bit real mode thunk, then this
7731 service should be used. If the caller intends to make more than one 16-bit
7732 real mode thunk, then it is more efficient if AsmPrepareThunk16() is called
7733 once and AsmThunk16() can be called for each 16-bit real mode thunk.
7735 This interface is limited to be used in either physical mode or virtual modes with paging enabled where the
7736 virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1.
7738 See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.
7740 @param ThunkContext A pointer to the context structure that describes the
7741 16-bit real mode code to call.
7746 AsmPrepareAndThunk16 (
7747 IN OUT THUNK_CONTEXT
*ThunkContext
7751 Generates a 16-bit random number through RDRAND instruction.
7753 if Rand is NULL, then ASSERT().
7755 @param[out] Rand Buffer pointer to store the random result.
7757 @retval TRUE RDRAND call was successful.
7758 @retval FALSE Failed attempts to call RDRAND.
7768 Generates a 32-bit random number through RDRAND instruction.
7770 if Rand is NULL, then ASSERT().
7772 @param[out] Rand Buffer pointer to store the random result.
7774 @retval TRUE RDRAND call was successful.
7775 @retval FALSE Failed attempts to call RDRAND.
7785 Generates a 64-bit random number through RDRAND instruction.
7787 if Rand is NULL, then ASSERT().
7789 @param[out] Rand Buffer pointer to store the random result.
7791 @retval TRUE RDRAND call was successful.
7792 @retval FALSE Failed attempts to call RDRAND.
7802 Load given selector into TR register.
7804 @param[in] Selector Task segment selector
7813 Performs a serializing operation on all load-from-memory instructions that
7814 were issued prior the AsmLfence function.
7816 Executes a LFENCE instruction. This function is only available on IA-32 and x64.
7826 Patch the immediate operand of an IA32 or X64 instruction such that the byte,
7827 word, dword or qword operand is encoded at the end of the instruction's
7828 binary representation.
7830 This function should be used to update object code that was compiled with
7831 NASM from assembly source code. Example:
7835 mov eax, strict dword 0 ; the imm32 zero operand will be patched
7841 X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
7842 PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);
7844 @param[out] InstructionEnd Pointer right past the instruction to patch. The
7845 immediate operand to patch is expected to
7846 comprise the trailing bytes of the instruction.
7847 If InstructionEnd is closer to address 0 than
7848 ValueSize permits, then ASSERT().
7850 @param[in] PatchValue The constant to write to the immediate operand.
7851 The caller is responsible for ensuring that
7852 PatchValue can be represented in the byte, word,
7853 dword or qword operand (as indicated through
7854 ValueSize); otherwise ASSERT().
7856 @param[in] ValueSize The size of the operand in bytes; must be 1, 2,
7857 4, or 8. ASSERT() otherwise.
7861 PatchInstructionX86 (
7862 OUT X86_ASSEMBLY_PATCH_LABEL
*InstructionEnd
,
7863 IN UINT64 PatchValue
,
7867 #endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
7868 #endif // !defined (__BASE_LIB__)