X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdePkg%2FInclude%2FLibrary%2FBaseLib.h;h=24f93c9bb140226cd449a520bc53ccfeb13c6796;hb=aa0583c78369a5a85d7bf26c76240ae4e3086c42;hp=ff663c91b7eff435f42063295b37022e5a93d6a8;hpb=878ddf1fc3540a715f63594ed22b6929e881afb4;p=mirror_edk2.git diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h index ff663c91b7..24f93c9bb1 100644 --- a/MdePkg/Include/Library/BaseLib.h +++ b/MdePkg/Include/Library/BaseLib.h @@ -1,36 +1,32 @@ /** @file - Memory-only library functions with no library constructor/destructor + Memory-only library functions with no library constructor/destructor - Copyright (c) 2006, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2006 - 2008, Intel Corporation + All rights reserved. This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - Module Name: BaseLib.h + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ #ifndef __BASE_LIB__ #define __BASE_LIB__ -// -// Definitions for architecture specific types -// These include SPIN_LOCK and BASE_LIBRARY_JUMP_BUFFER -// +/// +/// Definitions for SPIN_LOCK +/// +typedef volatile UINTN SPIN_LOCK; // -// SPIN_LOCK +// Definitions for architecture specific types // -typedef UINTN SPIN_LOCK; - #if defined (MDE_CPU_IA32) -// -// IA32 context buffer used by SetJump() and LongJump() -// +/// +/// IA32 context buffer used by SetJump() and LongJump() +/// typedef struct { UINT32 Ebx; UINT32 Esi; @@ -40,76 +36,60 @@ typedef struct { UINT32 Eip; } BASE_LIBRARY_JUMP_BUFFER; +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4 + #elif defined (MDE_CPU_IPF) -// -// IPF context buffer used by SetJump() and LongJump() -// + +/// +/// IPF context buffer used by SetJump() and LongJump() +/// typedef struct { - UINT64 InitialUNAT; - UINT64 AfterSpillUNAT; - UINT64 PFS; - UINT64 BSP; - UINT64 RNAT; - UINT64 Predicates; - UINT64 LoopCount; + UINT64 F2[2]; + UINT64 F3[2]; + UINT64 F4[2]; + UINT64 F5[2]; + UINT64 F16[2]; + UINT64 F17[2]; + UINT64 F18[2]; + UINT64 F19[2]; + UINT64 F20[2]; + UINT64 F21[2]; + UINT64 F22[2]; + UINT64 F23[2]; + UINT64 F24[2]; + UINT64 F25[2]; + UINT64 F26[2]; + UINT64 F27[2]; + UINT64 F28[2]; + UINT64 F29[2]; + UINT64 F30[2]; + UINT64 F31[2]; UINT64 R4; UINT64 R5; UINT64 R6; UINT64 R7; UINT64 SP; - UINT64 F2Low; - UINT64 F2High; - UINT64 F3Low; - UINT64 F3High; - UINT64 F4Low; - UINT64 F4High; - UINT64 F5Low; - UINT64 F5High; - UINT64 F16Low; - UINT64 F16High; - UINT64 F17Low; - UINT64 F17High; - UINT64 F18Low; - UINT64 F18High; - UINT64 F19Low; - UINT64 F19High; - UINT64 F20Low; - UINT64 F20High; - UINT64 F21Low; - UINT64 F21High; - UINT64 F22Low; - UINT64 F22High; - UINT64 F23Low; - UINT64 F23High; - UINT64 F24Low; - UINT64 F24High; - UINT64 F25Low; - UINT64 F25High; - UINT64 F26Low; - UINT64 F26High; - UINT64 F27Low; - UINT64 F27High; - UINT64 F28Low; - UINT64 F28High; - UINT64 F29Low; - UINT64 F29High; - UINT64 F30Low; - UINT64 F30High; - UINT64 F31Low; - UINT64 F31High; - UINT64 FPSR; UINT64 BR0; UINT64 BR1; UINT64 BR2; UINT64 BR3; UINT64 BR4; UINT64 BR5; + UINT64 InitialUNAT; + UINT64 AfterSpillUNAT; + UINT64 PFS; + UINT64 BSP; + UINT64 Predicates; + UINT64 LoopCount; + UINT64 FPSR; } BASE_LIBRARY_JUMP_BUFFER; +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10 + #elif defined (MDE_CPU_X64) -// -// X64 context buffer used by SetJump() and LongJump() -// +/// +/// X64 context buffer used by SetJump() and LongJump() +/// typedef struct { UINT64 Rbx; UINT64 Rsp; @@ -123,10 +103,12 @@ typedef struct { UINT64 Rip; } BASE_LIBRARY_JUMP_BUFFER; +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 + #elif defined (MDE_CPU_EBC) -// -// EBC context buffer used by SetJump() and LongJump() -// +/// +/// EBC context buffer used by SetJump() and LongJump() +/// typedef struct { UINT64 R0; UINT64 R1; @@ -135,6 +117,8 @@ typedef struct { UINT64 IP; } BASE_LIBRARY_JUMP_BUFFER; +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 + #else #error Unknown Processor Type #endif @@ -152,10 +136,13 @@ typedef struct { overlap, then the results are undefined. If Destination is NULL, then ASSERT(). + If Destination is not aligned on a 16-bit boundary, then ASSERT(). If Source is NULL, then ASSERT(). + If Source is not aligned on a 16-bit boundary, then ASSERT(). If Source and Destination overlap, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and Source contains more than - PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). @param Destination Pointer to a Null-terminated Unicode string. @param Source Pointer to a Null-terminated Unicode string. @@ -170,6 +157,7 @@ StrCpy ( IN CONST CHAR16 *Source ); + /** Copies one Null-terminated Unicode string with a maximum length to another Null-terminated Unicode string with a maximum length and returns the new @@ -183,11 +171,14 @@ StrCpy ( characters. If Source and Destination overlap, then the results are undefined. - If Destination is NULL, then ASSERT(). - If Source is NULL, then ASSERT(). + If Length > 0 and Destination is NULL, then ASSERT(). + If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT(). + If Length > 0 and Source is NULL, then ASSERT(). + If Length > 0 and Source is not aligned on a 16-bit bounadry, then ASSERT(). If Source and Destination overlap, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and Source contains more than - PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). @param Destination Pointer to a Null-terminated Unicode string. @param Source Pointer to a Null-terminated Unicode string. @@ -204,6 +195,7 @@ StrnCpy ( IN UINTN Length ); + /** Returns the length of a Null-terminated Unicode string. @@ -211,8 +203,10 @@ StrnCpy ( Unicode string specified by String. If String is NULL, then ASSERT(). + If String is not aligned on a 16-bit boundary, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and String contains more than - PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). @param String Pointer to a Null-terminated Unicode string. @@ -225,6 +219,7 @@ StrLen ( IN CONST CHAR16 *String ); + /** Returns the size of a Null-terminated Unicode string in bytes, including the Null terminator. @@ -233,8 +228,10 @@ StrLen ( string specified by String. If String is NULL, then ASSERT(). + If String is not aligned on a 16-bit boundary, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and String contains more than - PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). @param String Pointer to a Null-terminated Unicode string. @@ -247,6 +244,7 @@ StrSize ( IN CONST CHAR16 *String ); + /** Compares two Null-terminated Unicode strings, and returns the difference between the first mismatched Unicode characters. @@ -258,17 +256,21 @@ StrSize ( mismatched Unicode character in FirstString. If FirstString is NULL, then ASSERT(). + If FirstString is not aligned on a 16-bit boundary, then ASSERT(). If SecondString is NULL, then ASSERT(). + If SecondString is not aligned on a 16-bit boundary, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more - than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + than PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more - than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + than PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). @param FirstString Pointer to a Null-terminated Unicode string. @param SecondString Pointer to a Null-terminated Unicode string. - @retval 0 FirstString is identical to SecondString. - @retval !=0 FirstString is not identical to SecondString. + @retval 0 FirstString is identical to SecondString. + @return others FirstString is not identical to SecondString. **/ INTN @@ -278,6 +280,7 @@ StrCmp ( IN CONST CHAR16 *SecondString ); + /** Compares two Null-terminated Unicode strings with maximum lengths, and returns the difference between the first mismatched Unicode characters. @@ -289,19 +292,23 @@ StrCmp ( value returned is the first mismatched Unicode character in SecondString subtracted from the first mismatched Unicode character in FirstString. - If FirstString is NULL, then ASSERT(). - If SecondString is NULL, then ASSERT(). + If Length > 0 and FirstString is NULL, then ASSERT(). + If Length > 0 and FirstString is not aligned on a 16-bit bounadary, then ASSERT(). + If Length > 0 and SecondString is NULL, then ASSERT(). + If Length > 0 and SecondString is not aligned on a 16-bit bounadary, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more - than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + than PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more - than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + than PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). @param FirstString Pointer to a Null-terminated Unicode string. @param SecondString Pointer to a Null-terminated Unicode string. @param Length Maximum number of Unicode characters to compare. - @retval 0 FirstString is identical to SecondString. - @retval !=0 FirstString is not identical to SecondString. + @retval 0 FirstString is identical to SecondString. + @return others FirstString is not identical to SecondString. **/ INTN @@ -312,6 +319,7 @@ StrnCmp ( IN UINTN Length ); + /** Concatenates one Null-terminated Unicode string to another Null-terminated Unicode string, and returns the concatenated Unicode string. @@ -323,15 +331,20 @@ StrnCmp ( results are undefined. If Destination is NULL, then ASSERT(). + If Destination is not aligned on a 16-bit bounadary, then ASSERT(). If Source is NULL, then ASSERT(). + If Source is not aligned on a 16-bit bounadary, then ASSERT(). If Source and Destination overlap, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and Destination contains more - than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + than PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and Source contains more than - PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination and Source results in a Unicode string with more than - PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). @param Destination Pointer to a Null-terminated Unicode string. @param Source Pointer to a Null-terminated Unicode string. @@ -346,6 +359,7 @@ StrCat ( IN CONST CHAR16 *Source ); + /** Concatenates one Null-terminated Unicode string with a maximum length to the end of another Null-terminated Unicode string, and returns the concatenated @@ -360,15 +374,20 @@ StrCat ( the results are undefined. If Destination is NULL, then ASSERT(). - If Source is NULL, then ASSERT(). + If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT(). + If Length > 0 and Source is NULL, then ASSERT(). + If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT(). If Source and Destination overlap, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and Destination contains more - than PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + than PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and Source contains more than - PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination and Source results in a Unicode string with more than - PcdMaximumUnicodeStringLength Unicode characters, then ASSERT(). + PcdMaximumUnicodeStringLength Unicode characters not including the + Null-terminator, then ASSERT(). @param Destination Pointer to a Null-terminated Unicode string. @param Source Pointer to a Null-terminated Unicode string. @@ -386,6 +405,370 @@ StrnCat ( IN UINTN Length ); +/** + Returns the first occurance of a Null-terminated Unicode sub-string + in a Null-terminated Unicode string. + + This function scans the contents of the Null-terminated Unicode string + specified by String and returns the first occurrence of SearchString. + If SearchString is not found in String, then NULL is returned. If + the length of SearchString is zero, then String is + returned. + + If String is NULL, then ASSERT(). + If String is not aligned on a 16-bit boundary, then ASSERT(). + If SearchString is NULL, then ASSERT(). + If SearchString is not aligned on a 16-bit boundary, then ASSERT(). + + If PcdMaximumUnicodeStringLength is not zero, and SearchString + or String contains more than PcdMaximumUnicodeStringLength Unicode + characters not including the Null-terminator, then ASSERT(). + + @param String Pointer to a Null-terminated Unicode string. + @param SearchString Pointer to a Null-terminated Unicode string to search for. + + @retval NULL If the SearchString does not appear in String. + @return others If there is a match. + +**/ +CHAR16 * +EFIAPI +StrStr ( + IN CONST CHAR16 *String, + IN CONST CHAR16 *SearchString + ); + +/** + Convert a Null-terminated Unicode decimal string to a value of + type UINTN. + + This function returns a value of type UINTN by interpreting the contents + of the Unicode string specified by String as a decimal number. The format + of the input Unicode string String is: + + [spaces] [decimal digits]. + + The valid decimal digit character is in the range [0-9]. The + function will ignore the pad space, which includes spaces or + tab characters, before [decimal digits]. The running zero in the + beginning of [decimal digits] will be ignored. Then, the function + stops at the first character that is a not a valid decimal character + or a Null-terminator, whichever one comes first. + + If String is NULL, then ASSERT(). + If String is not aligned in a 16-bit boundary, then ASSERT(). + If String has only pad spaces, then 0 is returned. + If String has no pad spaces or valid decimal digits, + then 0 is returned. + If the number represented by String overflows according + to the range defined by UINTN, then ASSERT(). + + If PcdMaximumUnicodeStringLength is not zero, and String contains + more than PcdMaximumUnicodeStringLength Unicode characters not including + the Null-terminator, then ASSERT(). + + @param String Pointer to a Null-terminated Unicode string. + + @retval Value translated from String. + +**/ +UINTN +EFIAPI +StrDecimalToUintn ( + IN CONST CHAR16 *String + ); + +/** + Convert a Null-terminated Unicode decimal string to a value of + type UINT64. + + This function returns a value of type UINT64 by interpreting the contents + of the Unicode string specified by String as a decimal number. The format + of the input Unicode string String is: + + [spaces] [decimal digits]. + + The valid decimal digit character is in the range [0-9]. The + function will ignore the pad space, which includes spaces or + tab characters, before [decimal digits]. The running zero in the + beginning of [decimal digits] will be ignored. Then, the function + stops at the first character that is a not a valid decimal character + or a Null-terminator, whichever one comes first. + + If String is NULL, then ASSERT(). + If String is not aligned in a 16-bit boundary, then ASSERT(). + If String has only pad spaces, then 0 is returned. + If String has no pad spaces or valid decimal digits, + then 0 is returned. + If the number represented by String overflows according + to the range defined by UINT64, then ASSERT(). + + If PcdMaximumUnicodeStringLength is not zero, and String contains + more than PcdMaximumUnicodeStringLength Unicode characters not including + the Null-terminator, then ASSERT(). + + @param String Pointer to a Null-terminated Unicode string. + + @retval Value translated from String. + +**/ +UINT64 +EFIAPI +StrDecimalToUint64 ( + IN CONST CHAR16 *String + ); + + +/** + Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN. + + This function returns a value of type UINTN by interpreting the contents + of the Unicode string specified by String as a hexadecimal number. + The format of the input Unicode string String is: + + [spaces][zeros][x][hexadecimal digits]. + + The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. + The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. + If "x" appears in the input string, it must be prefixed with at least one 0. + The function will ignore the pad space, which includes spaces or tab characters, + before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or + [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the + first valid hexadecimal digit. Then, the function stops at the first character that is + a not a valid hexadecimal character or NULL, whichever one comes first. + + If String is NULL, then ASSERT(). + If String is not aligned in a 16-bit boundary, then ASSERT(). + If String has only pad spaces, then zero is returned. + If String has no leading pad spaces, leading zeros or valid hexadecimal digits, + then zero is returned. + If the number represented by String overflows according to the range defined by + UINTN, then ASSERT(). + + If PcdMaximumUnicodeStringLength is not zero, and String contains more than + PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, + then ASSERT(). + + @param String Pointer to a Null-terminated Unicode string. + + @retval Value translated from String. + +**/ +UINTN +EFIAPI +StrHexToUintn ( + IN CONST CHAR16 *String + ); + + +/** + Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64. + + This function returns a value of type UINT64 by interpreting the contents + of the Unicode string specified by String as a hexadecimal number. + The format of the input Unicode string String is + + [spaces][zeros][x][hexadecimal digits]. + + The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. + The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. + If "x" appears in the input string, it must be prefixed with at least one 0. + The function will ignore the pad space, which includes spaces or tab characters, + before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or + [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the + first valid hexadecimal digit. Then, the function stops at the first character that is + a not a valid hexadecimal character or NULL, whichever one comes first. + + If String is NULL, then ASSERT(). + If String is not aligned in a 16-bit boundary, then ASSERT(). + If String has only pad spaces, then zero is returned. + If String has no leading pad spaces, leading zeros or valid hexadecimal digits, + then zero is returned. + If the number represented by String overflows according to the range defined by + UINT64, then ASSERT(). + + If PcdMaximumUnicodeStringLength is not zero, and String contains more than + PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, + then ASSERT(). + + @param String Pointer to a Null-terminated Unicode string. + + @retval Value translated from String. + +**/ +UINT64 +EFIAPI +StrHexToUint64 ( + IN CONST CHAR16 *String + ); + +/** + Convert a nibble in the low 4 bits of a byte to a Unicode hexadecimal character. + + This function converts a nibble in the low 4 bits of a byte to a Unicode hexadecimal + character For example, the nibble 0x01 and 0x0A will converted to L'1' and L'A' + respectively. + + The upper nibble in the input byte will be masked off. + + @param Nibble The nibble which is in the low 4 bits of the input byte. + + @retval CHAR16 The Unicode hexadecimal character. + +**/ +CHAR16 +EFIAPI +NibbleToHexChar ( + IN UINT8 Nibble + ); + +/** + Convert binary buffer to a Unicode String in a specified sequence. + + This function converts bytes in the memory block pointed by Buffer to a Unicode String Str. + Each byte will be represented by two Unicode characters. For example, byte 0xA1 will + be converted into two Unicode character L'A' and L'1'. In the output String, the Unicode Character + for the Most Significant Nibble will be put before the Unicode Character for the Least Significant + Nibble. The output string for the buffer containing a single byte 0xA1 will be L"A1". + For a buffer with multiple bytes, the Unicode character produced by the first byte will be put into the + the last character in the output string. The one next to first byte will be put into the + character before the last character. This rules applies to the rest of the bytes. The Unicode + character by the last byte will be put into the first character in the output string. For example, + the input buffer for a 64-bits unsigned integrer 0x12345678abcdef1234 will be converted to + a Unicode string equal to L"12345678abcdef1234". + + @param String On input, String is pointed to the buffer allocated for the convertion. + @param StringLen The Length of String buffer to hold the output String. The length must include the tailing '\0' character. + The StringLen required to convert a N bytes Buffer will be a least equal to or greater + than 2*N + 1. + @param Buffer The pointer to a input buffer. + @param BufferSizeInBytes Lenth in bytes of the input buffer. + + + @retval EFI_SUCCESS The convertion is successfull. All bytes in Buffer has been convert to the corresponding + Unicode character and placed into the right place in String. + @retval EFI_BUFFER_TOO_SMALL StringSizeInBytes is smaller than 2 * N + 1the number of bytes required to + complete the convertion. +**/ +RETURN_STATUS +EFIAPI +BufToHexString ( + IN OUT CHAR16 *String, + IN OUT UINTN *StringLen, + IN CONST UINT8 *Buffer, + IN UINTN BufferSizeInBytes + ); + + +/** + Convert a Unicode string consisting of hexadecimal characters to a output byte buffer. + + This function converts a Unicode string consisting of characters in the range of Hexadecimal + character (L'0' to L'9', L'A' to L'F' and L'a' to L'f') to a output byte buffer. The function will stop + at the first non-hexadecimal character or the NULL character. The convertion process can be + simply viewed as the reverse operations defined by BufToHexString. Two Unicode characters will be + converted into one byte. The first Unicode character represents the Most Significant Nibble and the + second Unicode character represents the Least Significant Nibble in the output byte. + The first pair of Unicode characters represents the last byte in the output buffer. The second pair of Unicode + characters represent the the byte preceding the last byte. This rule applies to the rest pairs of bytes. + The last pair represent the first byte in the output buffer. + + For example, a Unciode String L"12345678" will be converted into a buffer wil the following bytes + (first byte is the byte in the lowest memory address): "0x78, 0x56, 0x34, 0x12". + + If String has N valid hexadecimal characters for conversion, the caller must make sure Buffer is at least + N/2 (if N is even) or (N+1)/2 (if N if odd) bytes. + + @param Buffer The output buffer allocated by the caller. + @param BufferSizeInBytes On input, the size in bytes of Buffer. On output, it is updated to + contain the size of the Buffer which is actually used for the converstion. + For Unicode string with 2*N hexadecimal characters (not including the + tailing NULL character), N bytes of Buffer will be used for the output. + @param String The input hexadecimal string. + @param ConvertedStrLen The number of hexadecimal characters used to produce content in output + buffer Buffer. + + @retval RETURN_BUFFER_TOO_SMALL The input BufferSizeInBytes is too small to hold the output. BufferSizeInBytes + will be updated to the size required for the converstion. + @retval RETURN_SUCCESS The convertion is successful or the first Unicode character from String + is hexadecimal. If ConvertedStrLen is not NULL, it is updated + to the number of hexadecimal character used for the converstion. +**/ +RETURN_STATUS +EFIAPI +HexStringToBuf ( + OUT UINT8 *Buffer, + IN OUT UINTN *BufferSizeInBytes, + IN CONST CHAR16 *String, + OUT UINTN *ConvertedStrLen OPTIONAL + ); + + +/** + Test if a Unicode character is a hexadecimal digit. If true, the input + Unicode character is converted to a byte. + + This function tests if a Unicode character is a hexadecimal digit. If true, the input + Unicode character is converted to a byte. For example, Unicode character + L'A' will be converted to 0x0A. + + If Digit is NULL, then ASSERT. + + @param Digit The output hexadecimal digit. + + @param Char The input Unicode character. + + @retval TRUE Char is in the range of Hexadecimal number. Digit is updated + to the byte value of the number. + @retval FALSE Char is not in the range of Hexadecimal number. Digit is keep + intact. + +**/ +BOOLEAN +EFIAPI +IsHexDigit ( + OUT UINT8 *Digit, + IN CHAR16 Char + ); + +/** + Convert one Null-terminated Unicode string to a Null-terminated + ASCII string and returns the ASCII string. + + This function converts the content of the Unicode string Source + to the ASCII string Destination by copying the lower 8 bits of + each Unicode character. It returns Destination. + + If any Unicode characters in Source contain non-zero value in + the upper 8 bits, then ASSERT(). + + If Destination is NULL, then ASSERT(). + If Source is NULL, then ASSERT(). + If Source is not aligned on a 16-bit boundary, then ASSERT(). + If Source and Destination overlap, then ASSERT(). + + If PcdMaximumUnicodeStringLength is not zero, and Source contains + more than PcdMaximumUnicodeStringLength Unicode characters not including + the Null-terminator, then ASSERT(). + + If PcdMaximumAsciiStringLength is not zero, and Source contains more + than PcdMaximumAsciiStringLength Unicode characters not including the + Null-terminator, then ASSERT(). + + @param Source Pointer to a Null-terminated Unicode string. + @param Destination Pointer to a Null-terminated ASCII string. + + @return Destination + +**/ +CHAR8 * +EFIAPI +UnicodeStrToAsciiStr ( + IN CONST CHAR16 *Source, + OUT CHAR8 *Destination + ); + + /** Copies one Null-terminated ASCII string to another Null-terminated ASCII string and returns the new ASCII string. @@ -398,7 +781,8 @@ StrnCat ( If Source is NULL, then ASSERT(). If Source and Destination overlap, then ASSERT(). If PcdMaximumAsciiStringLength is not zero and Source contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). @param Destination Pointer to a Null-terminated ASCII string. @param Source Pointer to a Null-terminated ASCII string. @@ -413,6 +797,7 @@ AsciiStrCpy ( IN CONST CHAR8 *Source ); + /** Copies one Null-terminated ASCII string with a maximum length to another Null-terminated ASCII string with a maximum length and returns the new ASCII @@ -429,7 +814,8 @@ AsciiStrCpy ( If Source is NULL, then ASSERT(). If Source and Destination overlap, then ASSERT(). If PcdMaximumAsciiStringLength is not zero, and Source contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). @param Destination Pointer to a Null-terminated ASCII string. @param Source Pointer to a Null-terminated ASCII string. @@ -446,15 +832,18 @@ AsciiStrnCpy ( IN UINTN Length ); + /** Returns the length of a Null-terminated ASCII string. This function returns the number of ASCII characters in the Null-terminated ASCII string specified by String. - If String is NULL, then ASSERT(). + If Length > 0 and Destination is NULL, then ASSERT(). + If Length > 0 and Source is NULL, then ASSERT(). If PcdMaximumAsciiStringLength is not zero and String contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). @param String Pointer to a Null-terminated ASCII string. @@ -467,6 +856,7 @@ AsciiStrLen ( IN CONST CHAR8 *String ); + /** Returns the size of a Null-terminated ASCII string in bytes, including the Null terminator. @@ -476,7 +866,8 @@ AsciiStrLen ( If String is NULL, then ASSERT(). If PcdMaximumAsciiStringLength is not zero and String contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). @param String Pointer to a Null-terminated ASCII string. @@ -489,6 +880,7 @@ AsciiStrSize ( IN CONST CHAR8 *String ); + /** Compares two Null-terminated ASCII strings, and returns the difference between the first mismatched ASCII characters. @@ -502,15 +894,17 @@ AsciiStrSize ( If FirstString is NULL, then ASSERT(). If SecondString is NULL, then ASSERT(). If PcdMaximumAsciiStringLength is not zero and FirstString contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). If PcdMaximumAsciiStringLength is not zero and SecondString contains more - than PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + than PcdMaximumAsciiStringLength ASCII characters not including the + Null-terminator, then ASSERT(). @param FirstString Pointer to a Null-terminated ASCII string. @param SecondString Pointer to a Null-terminated ASCII string. - @retval 0 FirstString is identical to SecondString. - @retval !=0 FirstString is not identical to SecondString. + @retval 0 FirstString is identical to SecondString. + @return others FirstString is not identical to SecondString. **/ INTN @@ -520,6 +914,7 @@ AsciiStrCmp ( IN CONST CHAR8 *SecondString ); + /** Performs a case insensitive comparison of two Null-terminated ASCII strings, and returns the difference between the first mismatched ASCII characters. @@ -534,17 +929,19 @@ AsciiStrCmp ( If FirstString is NULL, then ASSERT(). If SecondString is NULL, then ASSERT(). If PcdMaximumAsciiStringLength is not zero and FirstString contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). If PcdMaximumAsciiStringLength is not zero and SecondString contains more - than PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + than PcdMaximumAsciiStringLength ASCII characters not including the + Null-terminator, then ASSERT(). @param FirstString Pointer to a Null-terminated ASCII string. @param SecondString Pointer to a Null-terminated ASCII string. - @retval 0 FirstString is identical to SecondString using case insensitive - comparisons. - @retval !=0 FirstString is not identical to SecondString using case - insensitive comparisons. + @retval 0 FirstString is identical to SecondString using case insensitive + comparisons. + @return others FirstString is not identical to SecondString using case + insensitive comparisons. **/ INTN @@ -554,6 +951,7 @@ AsciiStriCmp ( IN CONST CHAR8 *SecondString ); + /** Compares two Null-terminated ASCII strings with maximum lengths, and returns the difference between the first mismatched ASCII characters. @@ -565,18 +963,21 @@ AsciiStriCmp ( is the first mismatched ASCII character in SecondString subtracted from the first mismatched ASCII character in FirstString. - If FirstString is NULL, then ASSERT(). - If SecondString is NULL, then ASSERT(). + If Length > 0 and FirstString is NULL, then ASSERT(). + If Length > 0 and SecondString is NULL, then ASSERT(). If PcdMaximumAsciiStringLength is not zero and FirstString contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero and SecondString contains more - than PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). + If PcdMaximumAsciiStringLength is not zero and SecondString contains more than + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). @param FirstString Pointer to a Null-terminated ASCII string. @param SecondString Pointer to a Null-terminated ASCII string. - - @retval 0 FirstString is identical to SecondString. - @retval !=0 FirstString is not identical to SecondString. + @param Length Maximum number of ASCII characters for compare. + + @retval 0 FirstString is identical to SecondString. + @return others FirstString is not identical to SecondString. **/ INTN @@ -587,6 +988,7 @@ AsciiStrnCmp ( IN UINTN Length ); + /** Concatenates one Null-terminated ASCII string to another Null-terminated ASCII string, and returns the concatenated ASCII string. @@ -599,9 +1001,11 @@ AsciiStrnCmp ( If Destination is NULL, then ASSERT(). If Source is NULL, then ASSERT(). If PcdMaximumAsciiStringLength is not zero and Destination contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). If PcdMaximumAsciiStringLength is not zero and Source contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). If PcdMaximumAsciiStringLength is not zero and concatenating Destination and Source results in a ASCII string with more than PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). @@ -615,10 +1019,11 @@ AsciiStrnCmp ( CHAR8 * EFIAPI AsciiStrCat ( - IN OUT CHAR8 *Destination, - IN CONST CHAR8 *Source + IN OUT CHAR8 *Destination, + IN CONST CHAR8 *Source ); + /** Concatenates one Null-terminated ASCII string with a maximum length to the end of another Null-terminated ASCII string, and returns the concatenated @@ -632,16 +1037,18 @@ AsciiStrCat ( Destination is returned unmodified. If Source and Destination overlap, then the results are undefined. - If Destination is NULL, then ASSERT(). - If Source is NULL, then ASSERT(). + If Length > 0 and Destination is NULL, then ASSERT(). + If Length > 0 and Source is NULL, then ASSERT(). If Source and Destination overlap, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and Destination contains more - than PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + If PcdMaximumAsciiStringLength is not zero, and Destination contains more than + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). If PcdMaximumAsciiStringLength is not zero, and Source contains more than - PcdMaximumAsciiStringLength ASCII characters, then ASSERT(). + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and Source results in a ASCII string with more than PcdMaximumAsciiStringLength - ASCII characters, then ASSERT(). + ASCII characters not including the Null-terminator, then ASSERT(). @param Destination Pointer to a Null-terminated ASCII string. @param Source Pointer to a Null-terminated ASCII string. @@ -659,85 +1066,343 @@ AsciiStrnCat ( IN UINTN Length ); -// -// LIST_ENTRY definition -// -typedef struct _LIST_ENTRY LIST_ENTRY; -struct _LIST_ENTRY { - LIST_ENTRY *ForwardLink; - LIST_ENTRY *BackLink; -}; +/** + Returns the first occurance of a Null-terminated ASCII sub-string + in a Null-terminated ASCII string. -// -// Linked List Functions and Macros -// + This function scans the contents of the ASCII string specified by String + and returns the first occurrence of SearchString. If SearchString is not + found in String, then NULL is returned. If the length of SearchString is zero, + then String is returned. -/** - Initializes the head node of a doubly linked list that is declared as a - global variable in a module. + If String is NULL, then ASSERT(). + If SearchString is NULL, then ASSERT(). - Initializes the forward and backward links of a new linked list. After - initializing a linked list with this macro, the other linked list functions - may be used to add and remove nodes from the linked list. This macro results - in smaller executables by initializing the linked list in the data section, - instead if calling the InitializeListHead() function to perform the - equivalent operation. + If PcdMaximumAsciiStringLength is not zero, and SearchString or + String contains more than PcdMaximumAsciiStringLength Unicode characters + not including the Null-terminator, then ASSERT(). - @param ListHead The head note of a list to initiailize. + @param String Pointer to a Null-terminated ASCII string. + @param SearchString Pointer to a Null-terminated ASCII string to search for. + + @retval NULL If the SearchString does not appear in String. + @return others If there is a match. **/ -#define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&ListHead, &ListHead} +CHAR8 * +EFIAPI +AsciiStrStr ( + IN CONST CHAR8 *String, + IN CONST CHAR8 *SearchString + ); + /** - Initializes the head node of a doubly linked list, and returns the pointer to - the head node of the doubly linked list. + Convert a Null-terminated ASCII decimal string to a value of type + UINTN. - Initializes the forward and backward links of a new linked list. After - initializing a linked list with this function, the other linked list - functions may be used to add and remove nodes from the linked list. It is up - to the caller of this function to allocate the memory for ListHead. + This function returns a value of type UINTN by interpreting the contents + of the ASCII string String as a decimal number. The format of the input + ASCII string String is: - If ListHead is NULL, then ASSERT(). + [spaces] [decimal digits]. - @param ListHead A pointer to the head node of a new doubly linked list. + The valid decimal digit character is in the range [0-9]. The function will + ignore the pad space, which includes spaces or tab characters, before the digits. + The running zero in the beginning of [decimal digits] will be ignored. Then, the + function stops at the first character that is a not a valid decimal character or + Null-terminator, whichever on comes first. - @return ListHead + If String has only pad spaces, then 0 is returned. + If String has no pad spaces or valid decimal digits, then 0 is returned. + If the number represented by String overflows according to the range defined by + UINTN, then ASSERT(). + If String is NULL, then ASSERT(). + If PcdMaximumAsciiStringLength is not zero, and String contains more than + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). + + @param String Pointer to a Null-terminated ASCII string. + + @retval Value translated from String. **/ -LIST_ENTRY * +UINTN EFIAPI -InitializeListHead ( - IN LIST_ENTRY *ListHead +AsciiStrDecimalToUintn ( + IN CONST CHAR8 *String ); + /** - Adds a node to the beginning of a doubly linked list, and returns the pointer - to the head node of the doubly linked list. + Convert a Null-terminated ASCII decimal string to a value of type + UINT64. - Adds the node Entry at the beginning of the doubly linked list denoted by - ListHead, and returns ListHead. + This function returns a value of type UINT64 by interpreting the contents + of the ASCII string String as a decimal number. The format of the input + ASCII string String is: - If ListHead is NULL, then ASSERT(). - If Entry is NULL, then ASSERT(). - If ListHead was not initialized with InitializeListHead(), then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and ListHead contains more than - PcdMaximumLinkedListLenth nodes, then ASSERT(). + [spaces] [decimal digits]. - @param ListHead A pointer to the head node of a doubly linked list. - @param Entry A pointer to a node that is to be inserted at the beginning - of a doubly linked list. + The valid decimal digit character is in the range [0-9]. The function will + ignore the pad space, which includes spaces or tab characters, before the digits. + The running zero in the beginning of [decimal digits] will be ignored. Then, the + function stops at the first character that is a not a valid decimal character or + Null-terminator, whichever on comes first. - @return ListHead + If String has only pad spaces, then 0 is returned. + If String has no pad spaces or valid decimal digits, then 0 is returned. + If the number represented by String overflows according to the range defined by + UINT64, then ASSERT(). + If String is NULL, then ASSERT(). + If PcdMaximumAsciiStringLength is not zero, and String contains more than + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). + + @param String Pointer to a Null-terminated ASCII string. + + @retval Value translated from String. **/ -LIST_ENTRY * +UINT64 EFIAPI -InsertHeadList ( - IN LIST_ENTRY *ListHead, - IN LIST_ENTRY *Entry +AsciiStrDecimalToUint64 ( + IN CONST CHAR8 *String ); + +/** + Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN. + + This function returns a value of type UINTN by interpreting the contents of + the ASCII string String as a hexadecimal number. The format of the input ASCII + string String is: + + [spaces][zeros][x][hexadecimal digits]. + + The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. + The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" + appears in the input string, it must be prefixed with at least one 0. The function + will ignore the pad space, which includes spaces or tab characters, before [zeros], + [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] + will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal + digit. Then, the function stops at the first character that is a not a valid + hexadecimal character or Null-terminator, whichever on comes first. + + If String has only pad spaces, then 0 is returned. + If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then + 0 is returned. + + If the number represented by String overflows according to the range defined by UINTN, + then ASSERT(). + If String is NULL, then ASSERT(). + If PcdMaximumAsciiStringLength is not zero, + and String contains more than PcdMaximumAsciiStringLength ASCII characters not including + the Null-terminator, then ASSERT(). + + @param String Pointer to a Null-terminated ASCII string. + + @retval Value translated from String. + +**/ +UINTN +EFIAPI +AsciiStrHexToUintn ( + IN CONST CHAR8 *String + ); + + +/** + Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64. + + This function returns a value of type UINT64 by interpreting the contents of + the ASCII string String as a hexadecimal number. The format of the input ASCII + string String is: + + [spaces][zeros][x][hexadecimal digits]. + + The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. + The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x" + appears in the input string, it must be prefixed with at least one 0. The function + will ignore the pad space, which includes spaces or tab characters, before [zeros], + [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits] + will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal + digit. Then, the function stops at the first character that is a not a valid + hexadecimal character or Null-terminator, whichever on comes first. + + If String has only pad spaces, then 0 is returned. + If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then + 0 is returned. + + If the number represented by String overflows according to the range defined by UINT64, + then ASSERT(). + If String is NULL, then ASSERT(). + If PcdMaximumAsciiStringLength is not zero, + and String contains more than PcdMaximumAsciiStringLength ASCII characters not including + the Null-terminator, then ASSERT(). + + @param String Pointer to a Null-terminated ASCII string. + + @retval Value translated from String. + +**/ +UINT64 +EFIAPI +AsciiStrHexToUint64 ( + IN CONST CHAR8 *String + ); + + +/** + Convert one Null-terminated ASCII string to a Null-terminated + Unicode string and returns the Unicode string. + + This function converts the contents of the ASCII string Source to the Unicode + string Destination, and returns Destination. The function terminates the + Unicode string Destination by appending a Null-terminator character at the end. + The caller is responsible to make sure Destination points to a buffer with size + equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes. + + If Destination is NULL, then ASSERT(). + If Destination is not aligned on a 16-bit boundary, then ASSERT(). + If Source is NULL, then ASSERT(). + If Source and Destination overlap, then ASSERT(). + If PcdMaximumAsciiStringLength is not zero, and Source contains more than + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). + If PcdMaximumUnicodeStringLength is not zero, and Source contains more than + PcdMaximumUnicodeStringLength ASCII characters not including the + Null-terminator, then ASSERT(). + + @param Source Pointer to a Null-terminated ASCII string. + @param Destination Pointer to a Null-terminated Unicode string. + + @return Destination + +**/ +CHAR16 * +EFIAPI +AsciiStrToUnicodeStr ( + IN CONST CHAR8 *Source, + OUT CHAR16 *Destination + ); + + +/** + Converts an 8-bit value to an 8-bit BCD value. + + Converts the 8-bit value specified by Value to BCD. The BCD value is + returned. + + If Value >= 100, then ASSERT(). + + @param Value The 8-bit value to convert to BCD. Range 0..99. + + @return The BCD value + +**/ +UINT8 +EFIAPI +DecimalToBcd8 ( + IN UINT8 Value + ); + + +/** + Converts an 8-bit BCD value to an 8-bit value. + + Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit + value is returned. + + If Value >= 0xA0, then ASSERT(). + If (Value & 0x0F) >= 0x0A, then ASSERT(). + + @param Value The 8-bit BCD value to convert to an 8-bit value. + + @return The 8-bit value is returned. + +**/ +UINT8 +EFIAPI +BcdToDecimal8 ( + IN UINT8 Value + ); + + +// +// Linked List Functions and Macros +// + +/** + Initializes the head node of a doubly linked list that is declared as a + global variable in a module. + + Initializes the forward and backward links of a new linked list. After + initializing a linked list with this macro, the other linked list functions + may be used to add and remove nodes from the linked list. This macro results + in smaller executables by initializing the linked list in the data section, + instead if calling the InitializeListHead() function to perform the + equivalent operation. + + @param ListHead The head note of a list to initiailize. + +**/ +#define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&ListHead, &ListHead} + + +/** + Initializes the head node of a doubly linked list, and returns the pointer to + the head node of the doubly linked list. + + Initializes the forward and backward links of a new linked list. After + initializing a linked list with this function, the other linked list + functions may be used to add and remove nodes from the linked list. It is up + to the caller of this function to allocate the memory for ListHead. + + If ListHead is NULL, then ASSERT(). + + @param ListHead A pointer to the head node of a new doubly linked list. + + @return ListHead + +**/ +LIST_ENTRY * +EFIAPI +InitializeListHead ( + IN OUT LIST_ENTRY *ListHead + ); + + +/** + Adds a node to the beginning of a doubly linked list, and returns the pointer + to the head node of the doubly linked list. + + Adds the node Entry at the beginning of the doubly linked list denoted by + ListHead, and returns ListHead. + + If ListHead is NULL, then ASSERT(). + If Entry is NULL, then ASSERT(). + If ListHead was not initialized with InitializeListHead(), then ASSERT(). + If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number + of nodes in ListHead, including the ListHead node, is greater than or + equal to PcdMaximumLinkedListLength, then ASSERT(). + + @param ListHead A pointer to the head node of a doubly linked list. + @param Entry A pointer to a node that is to be inserted at the beginning + of a doubly linked list. + + @return ListHead + +**/ +LIST_ENTRY * +EFIAPI +InsertHeadList ( + IN OUT LIST_ENTRY *ListHead, + IN OUT LIST_ENTRY *Entry + ); + + /** Adds a node to the end of a doubly linked list, and returns the pointer to the head node of the doubly linked list. @@ -748,8 +1413,9 @@ InsertHeadList ( If ListHead is NULL, then ASSERT(). If Entry is NULL, then ASSERT(). If ListHead was not initialized with InitializeListHead(), then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and ListHead contains more than - PcdMaximumLinkedListLenth nodes, then ASSERT(). + If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number + of nodes in ListHead, including the ListHead node, is greater than or + equal to PcdMaximumLinkedListLength, then ASSERT(). @param ListHead A pointer to the head node of a doubly linked list. @param Entry A pointer to a node that is to be added at the end of the @@ -761,10 +1427,11 @@ InsertHeadList ( LIST_ENTRY * EFIAPI InsertTailList ( - IN LIST_ENTRY *ListHead, - IN LIST_ENTRY *Entry + IN OUT LIST_ENTRY *ListHead, + IN OUT LIST_ENTRY *Entry ); + /** Retrieves the first node of a doubly linked list. @@ -774,8 +1441,9 @@ InsertTailList ( If List is NULL, then ASSERT(). If List was not initialized with InitializeListHead(), then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and List contains more than - PcdMaximumLinkedListLenth nodes, then ASSERT(). + If PcdMaximumLinkedListLenth is not zero, and the number of nodes + in List, including the List node, is greater than or equal to + PcdMaximumLinkedListLength, then ASSERT(). @param List A pointer to the head node of a doubly linked list. @@ -789,6 +1457,7 @@ GetFirstNode ( IN CONST LIST_ENTRY *List ); + /** Retrieves the next node of a doubly linked list. @@ -817,6 +1486,7 @@ GetNextNode ( IN CONST LIST_ENTRY *Node ); + /** Checks to see if a doubly linked list is empty or not. @@ -825,8 +1495,9 @@ GetNextNode ( If ListHead is NULL, then ASSERT(). If ListHead was not initialized with InitializeListHead(), then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and List contains more than - PcdMaximumLinkedListLenth nodes, then ASSERT(). + If PcdMaximumLinkedListLenth is not zero, and the number of nodes + in List, including the List node, is greater than or equal to + PcdMaximumLinkedListLength, then ASSERT(). @param ListHead A pointer to the head node of a doubly linked list. @@ -840,22 +1511,26 @@ IsListEmpty ( IN CONST LIST_ENTRY *ListHead ); + /** - Determines if a node in a doubly linked list is null. + Determines if a node in a doubly linked list is the head node of a the same + doubly linked list. This function is typically used to terminate a loop that + traverses all the nodes in a doubly linked list starting with the head node. - Returns FALSE if Node is one of the nodes in the doubly linked list specified - by List. Otherwise, TRUE is returned. List must have been initialized with - InitializeListHead(). + Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the + nodes in the doubly linked list specified by List. List must have been + initialized with InitializeListHead(). If List is NULL, then ASSERT(). If Node is NULL, then ASSERT(). If List was not initialized with InitializeListHead(), then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and List contains more than - PcdMaximumLinkedListLenth nodes, then ASSERT(). + If PcdMaximumLinkedListLenth is not zero, and the number of nodes + in List, including the List node, is greater than or equal to + PcdMaximumLinkedListLength, then ASSERT(). If Node is not a node in List and Node is not equal to List, then ASSERT(). @param List A pointer to the head node of a doubly linked list. - @param Node A pointer to a node in the doubly linked list. + @param Node A pointer to a node in the doubly linked list. @retval TRUE Node is one of the nodes in the doubly linked list. @retval FALSE Node is not one of the nodes in the doubly linked list. @@ -868,6 +1543,7 @@ IsNull ( IN CONST LIST_ENTRY *Node ); + /** Determines if a node the last node in a doubly linked list. @@ -878,12 +1554,13 @@ IsNull ( If List is NULL, then ASSERT(). If Node is NULL, then ASSERT(). If List was not initialized with InitializeListHead(), then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and List contains more than - PcdMaximumLinkedListLenth nodes, then ASSERT(). + If PcdMaximumLinkedListLenth is not zero, and the number of nodes + in List, including the List node, is greater than or equal to + PcdMaximumLinkedListLength, then ASSERT(). If Node is not a node in List, then ASSERT(). @param List A pointer to the head node of a doubly linked list. - @param Node A pointer to a node in the doubly linked list. + @param Node A pointer to a node in the doubly linked list. @retval TRUE Node is the last node in the linked list. @retval FALSE Node is not the last node in the linked list. @@ -896,6 +1573,7 @@ IsNodeAtEnd ( IN CONST LIST_ENTRY *Node ); + /** Swaps the location of two nodes in a doubly linked list, and returns the first node after the swap. @@ -910,21 +1588,25 @@ IsNodeAtEnd ( If FirstEntry is NULL, then ASSERT(). If SecondEntry is NULL, then ASSERT(). If SecondEntry and FirstEntry are not in the same linked list, then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and the linked list containing - FirstEntry and SecondEntry contains more than PcdMaximumLinkedListLenth - nodes, then ASSERT(). + If PcdMaximumLinkedListLength is not zero, and the number of nodes in the + linked list containing the FirstEntry and SecondEntry nodes, including + the FirstEntry and SecondEntry nodes, is greater than or equal to + PcdMaximumLinkedListLength, then ASSERT(). @param FirstEntry A pointer to a node in a linked list. @param SecondEntry A pointer to another node in the same linked list. + + @return SecondEntry **/ LIST_ENTRY * EFIAPI SwapListEntries ( - IN LIST_ENTRY *FirstEntry, - IN LIST_ENTRY *SecondEntry + IN OUT LIST_ENTRY *FirstEntry, + IN OUT LIST_ENTRY *SecondEntry ); + /** Removes a node from a doubly linked list, and returns the node that follows the removed node. @@ -937,8 +1619,9 @@ SwapListEntries ( If Entry is NULL, then ASSERT(). If Entry is the head node of an empty list, then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and the linked list containing - Entry contains more than PcdMaximumLinkedListLenth nodes, then ASSERT(). + If PcdMaximumLinkedListLength is not zero, and the number of nodes in the + linked list containing Entry, including the Entry node, is greater than + or equal to PcdMaximumLinkedListLength, then ASSERT(). @param Entry A pointer to a node in a linked list @@ -977,6 +1660,7 @@ LShiftU64 ( IN UINTN Count ); + /** Shifts a 64-bit integer right between 0 and 63 bits. This high bits are filled with zeros. The shifted value is returned. @@ -999,6 +1683,7 @@ RShiftU64 ( IN UINTN Count ); + /** Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled with original integer's bit 63. The shifted value is returned. @@ -1021,6 +1706,7 @@ ARShiftU64 ( IN UINTN Count ); + /** Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits with the high bits that were rotated. @@ -1044,6 +1730,7 @@ LRotU32 ( IN UINTN Count ); + /** Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits with the low bits that were rotated. @@ -1067,6 +1754,7 @@ RRotU32 ( IN UINTN Count ); + /** Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits with the high bits that were rotated. @@ -1090,6 +1778,7 @@ LRotU64 ( IN UINTN Count ); + /** Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits with the high low bits that were rotated. @@ -1113,6 +1802,7 @@ RRotU64 ( IN UINTN Count ); + /** Returns the bit position of the lowest bit set in a 32-bit value. @@ -1132,6 +1822,7 @@ LowBitSet32 ( IN UINT32 Operand ); + /** Returns the bit position of the lowest bit set in a 64-bit value. @@ -1151,6 +1842,7 @@ LowBitSet64 ( IN UINT64 Operand ); + /** Returns the bit position of the highest bit set in a 32-bit value. Equivalent to log2(x). @@ -1171,6 +1863,7 @@ HighBitSet32 ( IN UINT32 Operand ); + /** Returns the bit position of the highest bit set in a 64-bit value. Equivalent to log2(x). @@ -1191,6 +1884,7 @@ HighBitSet64 ( IN UINT64 Operand ); + /** Returns the value of the highest bit set in a 32-bit value. Equivalent to 1 << HighBitSet32(x). @@ -1210,6 +1904,7 @@ GetPowerOfTwo32 ( IN UINT32 Operand ); + /** Returns the value of the highest bit set in a 64-bit value. Equivalent to 1 << HighBitSet64(x). @@ -1229,6 +1924,7 @@ GetPowerOfTwo64 ( IN UINT64 Operand ); + /** Switches the endianess of a 16-bit integer. @@ -1236,7 +1932,7 @@ GetPowerOfTwo64 ( from little endian to big endian or vice versa. The byte swapped value is returned. - @param Operand A 16-bit unsigned value. + @param Value Operand A 16-bit unsigned value. @return The byte swaped Operand. @@ -1247,6 +1943,7 @@ SwapBytes16 ( IN UINT16 Value ); + /** Switches the endianess of a 32-bit integer. @@ -1254,7 +1951,7 @@ SwapBytes16 ( from little endian to big endian or vice versa. The byte swapped value is returned. - @param Operand A 32-bit unsigned value. + @param Value Operand A 32-bit unsigned value. @return The byte swaped Operand. @@ -1265,6 +1962,7 @@ SwapBytes32 ( IN UINT32 Value ); + /** Switches the endianess of a 64-bit integer. @@ -1272,7 +1970,7 @@ SwapBytes32 ( from little endian to big endian or vice versa. The byte swapped value is returned. - @param Operand A 64-bit unsigned value. + @param Value Operand A 64-bit unsigned value. @return The byte swaped Operand. @@ -1283,6 +1981,7 @@ SwapBytes64 ( IN UINT64 Value ); + /** Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 64-bit unsigned result. @@ -1306,6 +2005,7 @@ MultU64x32 ( IN UINT32 Multiplier ); + /** Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and generates a 64-bit unsigned result. @@ -1329,6 +2029,7 @@ MultU64x64 ( IN UINT64 Multiplier ); + /** Multiples a 64-bit signed integer by a 64-bit signed integer and generates a 64-bit signed result. @@ -1352,6 +2053,7 @@ MultS64x64 ( IN INT64 Multiplier ); + /** Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 64-bit unsigned result. @@ -1375,6 +2077,7 @@ DivU64x32 ( IN UINT32 Divisor ); + /** Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 32-bit unsigned remainder. @@ -1398,6 +2101,7 @@ ModU64x32 ( IN UINT32 Divisor ); + /** Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 64-bit unsigned result and an optional 32-bit unsigned remainder. @@ -1425,6 +2129,7 @@ DivU64x32Remainder ( OUT UINT32 *Remainder OPTIONAL ); + /** Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates a 64-bit unsigned result and an optional 64-bit unsigned remainder. @@ -1452,6 +2157,7 @@ DivU64x64Remainder ( OUT UINT64 *Remainder OPTIONAL ); + /** Divides a 64-bit signed integer by a 64-bit signed integer and generates a 64-bit signed result and a optional 64-bit signed remainder. @@ -1479,6 +2185,7 @@ DivS64x64Remainder ( OUT INT64 *Remainder OPTIONAL ); + /** Reads a 16-bit value from memory that may be unaligned. @@ -1489,15 +2196,16 @@ DivS64x64Remainder ( @param Buffer Pointer to a 16-bit value that may be unaligned. - @return *Uint16 + @return The 16-bit value read from Buffer. **/ UINT16 EFIAPI ReadUnaligned16 ( - IN CONST UINT16 *Uint16 + IN CONST UINT16 *Buffer ); + /** Writes a 16-bit value to memory that may be unaligned. @@ -1510,16 +2218,17 @@ ReadUnaligned16 ( @param Buffer Pointer to a 16-bit value that may be unaligned. @param Value 16-bit value to write to Buffer. - @return Value + @return The 16-bit value to write to Buffer. **/ UINT16 EFIAPI WriteUnaligned16 ( - OUT UINT16 *Uint16, - IN UINT16 Value + OUT UINT16 *Buffer, + IN UINT16 Value ); + /** Reads a 24-bit value from memory that may be unaligned. @@ -1530,15 +2239,16 @@ WriteUnaligned16 ( @param Buffer Pointer to a 24-bit value that may be unaligned. - @return The value read. + @return The 24-bit value read from Buffer. **/ UINT32 EFIAPI ReadUnaligned24 ( - IN CONST UINT32 *Buffer + IN CONST UINT32 *Buffer ); + /** Writes a 24-bit value to memory that may be unaligned. @@ -1551,16 +2261,17 @@ ReadUnaligned24 ( @param Buffer Pointer to a 24-bit value that may be unaligned. @param Value 24-bit value to write to Buffer. - @return The value written. + @return The 24-bit value to write to Buffer. **/ UINT32 EFIAPI WriteUnaligned24 ( - OUT UINT32 *Buffer, - IN UINT32 Value + OUT UINT32 *Buffer, + IN UINT32 Value ); + /** Reads a 32-bit value from memory that may be unaligned. @@ -1571,15 +2282,16 @@ WriteUnaligned24 ( @param Buffer Pointer to a 32-bit value that may be unaligned. - @return *Uint32 + @return The 32-bit value read from Buffer. **/ UINT32 EFIAPI ReadUnaligned32 ( - IN CONST UINT32 *Uint32 + IN CONST UINT32 *Buffer ); + /** Writes a 32-bit value to memory that may be unaligned. @@ -1592,16 +2304,17 @@ ReadUnaligned32 ( @param Buffer Pointer to a 32-bit value that may be unaligned. @param Value 32-bit value to write to Buffer. - @return Value + @return The 32-bit value to write to Buffer. **/ UINT32 EFIAPI WriteUnaligned32 ( - OUT UINT32 *Uint32, - IN UINT32 Value + OUT UINT32 *Buffer, + IN UINT32 Value ); + /** Reads a 64-bit value from memory that may be unaligned. @@ -1612,15 +2325,16 @@ WriteUnaligned32 ( @param Buffer Pointer to a 64-bit value that may be unaligned. - @return *Uint64 + @return The 64-bit value read from Buffer. **/ UINT64 EFIAPI ReadUnaligned64 ( - IN CONST UINT64 *Uint64 + IN CONST UINT64 *Buffer ); + /** Writes a 64-bit value to memory that may be unaligned. @@ -1633,16 +2347,17 @@ ReadUnaligned64 ( @param Buffer Pointer to a 64-bit value that may be unaligned. @param Value 64-bit value to write to Buffer. - @return Value + @return The 64-bit value to write to Buffer. **/ UINT64 EFIAPI WriteUnaligned64 ( - OUT UINT64 *Uint64, - IN UINT64 Value + OUT UINT64 *Buffer, + IN UINT64 Value ); + // // Bit Field Functions // @@ -1655,7 +2370,7 @@ WriteUnaligned64 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1674,6 +2389,7 @@ BitFieldRead8 ( IN UINTN EndBit ); + /** Writes a bit field to an 8-bit value, and returns the result. @@ -1684,7 +2400,7 @@ BitFieldRead8 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1705,6 +2421,7 @@ BitFieldWrite8 ( IN UINT8 Value ); + /** Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the result. @@ -1716,7 +2433,7 @@ BitFieldWrite8 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1737,6 +2454,7 @@ BitFieldOr8 ( IN UINT8 OrData ); + /** Reads a bit field from an 8-bit value, performs a bitwise AND, and returns the result. @@ -1748,7 +2466,7 @@ BitFieldOr8 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1769,6 +2487,7 @@ BitFieldAnd8 ( IN UINT8 AndData ); + /** Reads a bit field from an 8-bit value, performs a bitwise AND followed by a bitwise OR, and returns the result. @@ -1781,7 +2500,7 @@ BitFieldAnd8 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1804,6 +2523,7 @@ BitFieldAndThenOr8 ( IN UINT8 OrData ); + /** Returns a bit field from a 16-bit value. @@ -1812,7 +2532,7 @@ BitFieldAndThenOr8 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1831,6 +2551,7 @@ BitFieldRead16 ( IN UINTN EndBit ); + /** Writes a bit field to a 16-bit value, and returns the result. @@ -1841,7 +2562,7 @@ BitFieldRead16 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1862,6 +2583,7 @@ BitFieldWrite16 ( IN UINT16 Value ); + /** Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the result. @@ -1873,7 +2595,7 @@ BitFieldWrite16 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1894,6 +2616,7 @@ BitFieldOr16 ( IN UINT16 OrData ); + /** Reads a bit field from a 16-bit value, performs a bitwise AND, and returns the result. @@ -1905,7 +2628,7 @@ BitFieldOr16 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1926,6 +2649,7 @@ BitFieldAnd16 ( IN UINT16 AndData ); + /** Reads a bit field from a 16-bit value, performs a bitwise AND followed by a bitwise OR, and returns the result. @@ -1938,7 +2662,7 @@ BitFieldAnd16 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1961,6 +2685,7 @@ BitFieldAndThenOr16 ( IN UINT16 OrData ); + /** Returns a bit field from a 32-bit value. @@ -1969,7 +2694,7 @@ BitFieldAndThenOr16 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1988,6 +2713,7 @@ BitFieldRead32 ( IN UINTN EndBit ); + /** Writes a bit field to a 32-bit value, and returns the result. @@ -1998,7 +2724,7 @@ BitFieldRead32 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2019,6 +2745,7 @@ BitFieldWrite32 ( IN UINT32 Value ); + /** Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the result. @@ -2030,7 +2757,7 @@ BitFieldWrite32 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2051,6 +2778,7 @@ BitFieldOr32 ( IN UINT32 OrData ); + /** Reads a bit field from a 32-bit value, performs a bitwise AND, and returns the result. @@ -2062,7 +2790,7 @@ BitFieldOr32 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2083,6 +2811,7 @@ BitFieldAnd32 ( IN UINT32 AndData ); + /** Reads a bit field from a 32-bit value, performs a bitwise AND followed by a bitwise OR, and returns the result. @@ -2095,7 +2824,7 @@ BitFieldAnd32 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2118,6 +2847,7 @@ BitFieldAndThenOr32 ( IN UINT32 OrData ); + /** Returns a bit field from a 64-bit value. @@ -2126,7 +2856,7 @@ BitFieldAndThenOr32 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2145,6 +2875,7 @@ BitFieldRead64 ( IN UINTN EndBit ); + /** Writes a bit field to a 64-bit value, and returns the result. @@ -2155,7 +2886,7 @@ BitFieldRead64 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2176,6 +2907,7 @@ BitFieldWrite64 ( IN UINT64 Value ); + /** Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the result. @@ -2187,7 +2919,7 @@ BitFieldWrite64 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2208,6 +2940,7 @@ BitFieldOr64 ( IN UINT64 OrData ); + /** Reads a bit field from a 64-bit value, performs a bitwise AND, and returns the result. @@ -2219,7 +2952,7 @@ BitFieldOr64 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2240,6 +2973,7 @@ BitFieldAnd64 ( IN UINT64 AndData ); + /** Reads a bit field from a 64-bit value, performs a bitwise AND followed by a bitwise OR, and returns the result. @@ -2252,7 +2986,7 @@ BitFieldAnd64 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2275,6 +3009,7 @@ BitFieldAndThenOr64 ( IN UINT64 OrData ); + // // Base Library Synchronization Functions // @@ -2301,6 +3036,7 @@ GetSpinLockProperties ( VOID ); + /** Initializes a spin lock to the released state and returns the spin lock. @@ -2314,7 +3050,7 @@ GetSpinLockProperties ( @param SpinLock A pointer to the spin lock to initialize to the released state. - @return SpinLock + @return SpinLock in release state. **/ SPIN_LOCK * @@ -2323,6 +3059,7 @@ InitializeSpinLock ( IN SPIN_LOCK *SpinLock ); + /** Waits until a spin lock can be placed in the acquired state. @@ -2340,15 +3077,16 @@ InitializeSpinLock ( @param SpinLock A pointer to the spin lock to place in the acquired state. - @return SpinLock + @return SpinLock accquired lock. **/ SPIN_LOCK * EFIAPI AcquireSpinLock ( - IN SPIN_LOCK *SpinLock + IN OUT SPIN_LOCK *SpinLock ); + /** Attempts to place a spin lock in the acquired state. @@ -2369,9 +3107,10 @@ AcquireSpinLock ( BOOLEAN EFIAPI AcquireSpinLockOrFail ( - IN SPIN_LOCK *SpinLock + IN OUT SPIN_LOCK *SpinLock ); + /** Releases a spin lock. @@ -2383,15 +3122,16 @@ AcquireSpinLockOrFail ( @param SpinLock A pointer to the spin lock to release. - @return SpinLock + @return SpinLock released lock. **/ SPIN_LOCK * EFIAPI ReleaseSpinLock ( - IN SPIN_LOCK *SpinLock + IN OUT SPIN_LOCK *SpinLock ); + /** Performs an atomic increment of an 32-bit unsigned integer. @@ -2413,6 +3153,7 @@ InterlockedIncrement ( IN UINT32 *Value ); + /** Performs an atomic decrement of an 32-bit unsigned integer. @@ -2434,9 +3175,18 @@ InterlockedDecrement ( IN UINT32 *Value ); + /** Performs an atomic compare exchange operation on a 32-bit unsigned integer. + Performs an atomic compare exchange operation on the 32-bit unsigned integer + specified by Value. If Value is equal to CompareValue, then Value is set to + ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue, + then Value is returned. The compare exchange operation must be performed using + MP safe mechanisms. + + If Value is NULL, then ASSERT(). + @param Value A pointer to the 32-bit value for the compare exchange operation. @param CompareValue 32-bit value used in compare operation. @@ -2448,14 +3198,22 @@ InterlockedDecrement ( UINT32 EFIAPI InterlockedCompareExchange32 ( - IN UINT32 *Value, + IN OUT UINT32 *Value, IN UINT32 CompareValue, IN UINT32 ExchangeValue ); + /** Performs an atomic compare exchange operation on a 64-bit unsigned integer. + Performs an atomic compare exchange operation on the 64-bit unsigned integer specified + by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and + CompareValue is returned. If Value is not equal to CompareValue, then Value is returned. + The compare exchange operation must be performed using MP safe mechanisms. + + If Value is NULL, then ASSERT(). + @param Value A pointer to the 64-bit value for the compare exchange operation. @param CompareValue 64-bit value used in compare operation. @@ -2467,11 +3225,12 @@ InterlockedCompareExchange32 ( UINT64 EFIAPI InterlockedCompareExchange64 ( - IN UINT64 *Value, + IN OUT UINT64 *Value, IN UINT64 CompareValue, IN UINT64 ExchangeValue ); + /** Performs an atomic compare exchange operation on a pointer value. @@ -2488,38 +3247,263 @@ InterlockedCompareExchange64 ( @param CompareValue Pointer value used in compare operation. @param ExchangeValue Pointer value used in exchange operation. + @return The original *Value before exchange. **/ VOID * EFIAPI InterlockedCompareExchangePointer ( - IN VOID **Value, + IN OUT VOID **Value, IN VOID *CompareValue, IN VOID *ExchangeValue ); + // -// Base Library CPU Functions +// Base Library Checksum Functions // -typedef -VOID -(EFIAPI *SWITCH_STACK_ENTRY_POINT) ( - IN VOID *Context1, OPTIONAL - IN VOID *Context2 OPTIONAL - ); /** - Used to serialize load and store operations. + Calculate the sum of all elements in a buffer in unit of UINT8. + During calculation, the carry bits are dropped. - All loads and stores that proceed calls to this function are guaranteed to be - globally visible when this function returns. + This function calculates the sum of all elements in a buffer + in unit of UINT8. The carry bits in result of addition are dropped. + The result is returned as UINT8. If Length is Zero, then Zero is + returned. -**/ -VOID -EFIAPI + If Buffer is NULL, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer Pointer to the buffer to carry out the sum operation. + @param Length The size, in bytes, of Buffer . + + @return Sum The sum of Buffer with carry bits dropped during additions. + +**/ +UINT8 +EFIAPI +CalculateSum8 ( + IN CONST UINT8 *Buffer, + IN UINTN Length + ); + + +/** + Returns the two's complement checksum of all elements in a buffer + of 8-bit values. + + This function first calculates the sum of the 8-bit values in the + buffer specified by Buffer and Length. The carry bits in the result + of addition are dropped. Then, the two's complement of the sum is + returned. If Length is 0, then 0 is returned. + + If Buffer is NULL, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer Pointer to the buffer to carry out the checksum operation. + @param Length The size, in bytes, of Buffer. + + @return Checksum The 2's complement checksum of Buffer. + +**/ +UINT8 +EFIAPI +CalculateCheckSum8 ( + IN CONST UINT8 *Buffer, + IN UINTN Length + ); + + +/** + Returns the sum of all elements in a buffer of 16-bit values. During + calculation, the carry bits are dropped. + + This function calculates the sum of the 16-bit values in the buffer + specified by Buffer and Length. The carry bits in result of addition are dropped. + The 16-bit result is returned. If Length is 0, then 0 is returned. + + If Buffer is NULL, then ASSERT(). + If Buffer is not aligned on a 16-bit boundary, then ASSERT(). + If Length is not aligned on a 16-bit boundary, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer Pointer to the buffer to carry out the sum operation. + @param Length The size, in bytes, of Buffer. + + @return Sum The sum of Buffer with carry bits dropped during additions. + +**/ +UINT16 +EFIAPI +CalculateSum16 ( + IN CONST UINT16 *Buffer, + IN UINTN Length + ); + + +/** + Returns the two's complement checksum of all elements in a buffer of + 16-bit values. + + This function first calculates the sum of the 16-bit values in the buffer + specified by Buffer and Length. The carry bits in the result of addition + are dropped. Then, the two's complement of the sum is returned. If Length + is 0, then 0 is returned. + + If Buffer is NULL, then ASSERT(). + If Buffer is not aligned on a 16-bit boundary, then ASSERT(). + If Length is not aligned on a 16-bit boundary, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer Pointer to the buffer to carry out the checksum operation. + @param Length The size, in bytes, of Buffer. + + @return Checksum The 2's complement checksum of Buffer. + +**/ +UINT16 +EFIAPI +CalculateCheckSum16 ( + IN CONST UINT16 *Buffer, + IN UINTN Length + ); + + +/** + Returns the sum of all elements in a buffer of 32-bit values. During + calculation, the carry bits are dropped. + + This function calculates the sum of the 32-bit values in the buffer + specified by Buffer and Length. The carry bits in result of addition are dropped. + The 32-bit result is returned. If Length is 0, then 0 is returned. + + If Buffer is NULL, then ASSERT(). + If Buffer is not aligned on a 32-bit boundary, then ASSERT(). + If Length is not aligned on a 32-bit boundary, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer Pointer to the buffer to carry out the sum operation. + @param Length The size, in bytes, of Buffer. + + @return Sum The sum of Buffer with carry bits dropped during additions. + +**/ +UINT32 +EFIAPI +CalculateSum32 ( + IN CONST UINT32 *Buffer, + IN UINTN Length + ); + + +/** + Returns the two's complement checksum of all elements in a buffer of + 32-bit values. + + This function first calculates the sum of the 32-bit values in the buffer + specified by Buffer and Length. The carry bits in the result of addition + are dropped. Then, the two's complement of the sum is returned. If Length + is 0, then 0 is returned. + + If Buffer is NULL, then ASSERT(). + If Buffer is not aligned on a 32-bit boundary, then ASSERT(). + If Length is not aligned on a 32-bit boundary, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer Pointer to the buffer to carry out the checksum operation. + @param Length The size, in bytes, of Buffer. + + @return Checksum The 2's complement checksum of Buffer. + +**/ +UINT32 +EFIAPI +CalculateCheckSum32 ( + IN CONST UINT32 *Buffer, + IN UINTN Length + ); + + +/** + Returns the sum of all elements in a buffer of 64-bit values. During + calculation, the carry bits are dropped. + + This function calculates the sum of the 64-bit values in the buffer + specified by Buffer and Length. The carry bits in result of addition are dropped. + The 64-bit result is returned. If Length is 0, then 0 is returned. + + If Buffer is NULL, then ASSERT(). + If Buffer is not aligned on a 64-bit boundary, then ASSERT(). + If Length is not aligned on a 64-bit boundary, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer Pointer to the buffer to carry out the sum operation. + @param Length The size, in bytes, of Buffer. + + @return Sum The sum of Buffer with carry bits dropped during additions. + +**/ +UINT64 +EFIAPI +CalculateSum64 ( + IN CONST UINT64 *Buffer, + IN UINTN Length + ); + + +/** + Returns the two's complement checksum of all elements in a buffer of + 64-bit values. + + This function first calculates the sum of the 64-bit values in the buffer + specified by Buffer and Length. The carry bits in the result of addition + are dropped. Then, the two's complement of the sum is returned. If Length + is 0, then 0 is returned. + + If Buffer is NULL, then ASSERT(). + If Buffer is not aligned on a 64-bit boundary, then ASSERT(). + If Length is not aligned on a 64-bit boundary, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer Pointer to the buffer to carry out the checksum operation. + @param Length The size, in bytes, of Buffer. + + @return Checksum The 2's complement checksum of Buffer. + +**/ +UINT64 +EFIAPI +CalculateCheckSum64 ( + IN CONST UINT64 *Buffer, + IN UINTN Length + ); + + +/// +/// Base Library CPU Functions +/// +typedef +VOID +(EFIAPI *SWITCH_STACK_ENTRY_POINT)( + IN VOID *Context1, OPTIONAL + IN VOID *Context2 OPTIONAL + ); + + +/** + Used to serialize load and store operations. + + All loads and stores that proceed calls to this function are guaranteed to be + globally visible when this function returns. + +**/ +VOID +EFIAPI MemoryFence ( VOID ); + /** Saves the current CPU context that can be restored with a call to LongJump() and returns 0. @@ -2529,6 +3513,7 @@ MemoryFence ( calls to LongJump() cause a non-zero value to be returned by SetJump(). If JumpBuffer is NULL, then ASSERT(). + For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT(). @param JumpBuffer A pointer to CPU context buffer. @@ -2541,6 +3526,7 @@ SetJump ( OUT BASE_LIBRARY_JUMP_BUFFER *JumpBuffer ); + /** Restores the CPU context that was saved with SetJump(). @@ -2549,150 +3535,1357 @@ SetJump ( the state of JumpBuffer. If JumpBuffer is NULL, then ASSERT(). + For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT(). If Value is 0, then ASSERT(). - @param JumpBuffer A pointer to CPU context buffer. - @param Value The value to return when the SetJump() context is - restored and must be non-zero. + @param JumpBuffer A pointer to CPU context buffer. + @param Value The value to return when the SetJump() context is + restored and must be non-zero. + +**/ +VOID +EFIAPI +LongJump ( + IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer, + IN UINTN Value + ); + + +/** + Enables CPU interrupts. + +**/ +VOID +EFIAPI +EnableInterrupts ( + VOID + ); + + +/** + Disables CPU interrupts. + +**/ +VOID +EFIAPI +DisableInterrupts ( + VOID + ); + + +/** + Disables CPU interrupts and returns the interrupt state prior to the disable + operation. + + @retval TRUE CPU interrupts were enabled on entry to this call. + @retval FALSE CPU interrupts were disabled on entry to this call. + +**/ +BOOLEAN +EFIAPI +SaveAndDisableInterrupts ( + VOID + ); + + +/** + Enables CPU interrupts for the smallest window required to capture any + pending interrupts. + +**/ +VOID +EFIAPI +EnableDisableInterrupts ( + VOID + ); + + +/** + Retrieves the current CPU interrupt state. + + Returns TRUE is interrupts are currently enabled. Otherwise + returns FALSE. + + @retval TRUE CPU interrupts are enabled. + @retval FALSE CPU interrupts are disabled. + +**/ +BOOLEAN +EFIAPI +GetInterruptState ( + VOID + ); + + +/** + Set the current CPU interrupt state. + + Sets the current CPU interrupt state to the state specified by + InterruptState. If InterruptState is TRUE, then interrupts are enabled. If + InterruptState is FALSE, then interrupts are disabled. InterruptState is + returned. + + @param InterruptState TRUE if interrupts should enabled. FALSE if + interrupts should be disabled. + + @return InterruptState + +**/ +BOOLEAN +EFIAPI +SetInterruptState ( + IN BOOLEAN InterruptState + ); + + +/** + Requests CPU to pause for a short period of time. + + Requests CPU to pause for a short period of time. Typically used in MP + systems to prevent memory starvation while waiting for a spin lock. + +**/ +VOID +EFIAPI +CpuPause ( + VOID + ); + + +/** + Transfers control to a function starting with a new stack. + + Transfers control to the function specified by EntryPoint using the + new stack specified by NewStack and passing in the parameters specified + by Context1 and Context2. Context1 and Context2 are optional and may + be NULL. The function EntryPoint must never return. This function + supports a variable number of arguments following the NewStack parameter. + These additional arguments are ignored on IA-32, x64, and EBC. + IPF CPUs expect one additional parameter of type VOID * that specifies + the new backing store pointer. + + If EntryPoint is NULL, then ASSERT(). + If NewStack is NULL, then ASSERT(). + + @param EntryPoint A pointer to function to call with the new stack. + @param Context1 A pointer to the context to pass into the EntryPoint + function. + @param Context2 A pointer to the context to pass into the EntryPoint + function. + @param NewStack A pointer to the new stack to use for the EntryPoint + function. + @param ... Extended parameters. + + +**/ +VOID +EFIAPI +SwitchStack ( + IN SWITCH_STACK_ENTRY_POINT EntryPoint, + IN VOID *Context1, OPTIONAL + IN VOID *Context2, OPTIONAL + IN VOID *NewStack, + ... + ); + + +/** + Generates a breakpoint on the CPU. + + Generates a breakpoint on the CPU. The breakpoint must be implemented such + that code can resume normal execution after the breakpoint. + +**/ +VOID +EFIAPI +CpuBreakpoint ( + VOID + ); + + +/** + Executes an infinite loop. + + Forces the CPU to execute an infinite loop. A debugger may be used to skip + past the loop and the code that follows the loop must execute properly. This + implies that the infinite loop must not cause the code that follow it to be + optimized away. + +**/ +VOID +EFIAPI +CpuDeadLoop ( + VOID + ); + + +#if defined (MDE_CPU_IPF) + +/** + Flush a range of cache lines in the cache coherency domain of the calling + CPU. + + Invalidates the cache lines specified by Address and Length. If Address is + not aligned on a cache line boundary, then entire cache line containing + Address is invalidated. If Address + Length is not aligned on a cache line + boundary, then the entire instruction cache line containing Address + Length + -1 is invalidated. This function may choose to invalidate the entire + instruction cache if that is more efficient than invalidating the specified + range. If Length is 0, the no instruction cache lines are invalidated. + Address is returned. + + If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT(). + + @param Address The base address of the instruction lines to invalidate. If + the CPU is in a physical addressing mode, then Address is a + physical address. If the CPU is in a virtual addressing mode, + then Address is a virtual address. + + @param Length The number of bytes to invalidate from the instruction cache. + + @return Address + +**/ +VOID * +EFIAPI +IpfFlushCacheRange ( + IN VOID *Address, + IN UINTN Length + ); + + +/** + Executes a FC instruction + Executes a FC instruction on the cache line specified by Address. + The cache line size affected is at least 32-bytes (aligned on a 32-byte boundary). + An implementation may flush a larger region. This function is only available on IPF. + + @param Address The Address of cache line to be flushed. + + @return The address of FC instruction executed. + +**/ +UINT64 +EFIAPI +AsmFc ( + IN UINT64 Address + ); + + +/** + Executes a FC.I instruction. + Executes a FC.I instruction on the cache line specified by Address. + The cache line size affected is at least 32-bytes (aligned on a 32-byte boundary). + An implementation may flush a larger region. This function is only available on IPF. + + @param Address The Address of cache line to be flushed. + + @return The address of FC.I instruction executed. + +**/ +UINT64 +EFIAPI +AsmFci ( + IN UINT64 Address + ); + + +/** + Reads the current value of a Processor Identifier Register (CPUID). + The Index of largest implemented CPUID (One less than the number of implemented CPUID + registers) is determined by CPUID [3] bits {7:0}. + No parameter checking is performed on Index. If the Index value is beyond the + implemented CPUID register range, a Reserved Register/Field fault may occur. The caller + must either guarantee that Index is valid, or the caller must set up fault handlers to + catch the faults. This function is only available on IPF. + + @param Index The 8-bit Processor Identifier Register index to read. + + @return The current value of Processor Identifier Register specified by Index. + +**/ +UINT64 +EFIAPI +AsmReadCpuid ( + IN UINT8 Index + ); + + +/** + Reads the current value of 64-bit Processor Status Register (PSR). + This function is only available on IPF. + + @return The current value of PSR. + +**/ +UINT64 +EFIAPI +AsmReadPsr ( + VOID + ); + + +/** + Writes the current value of 64-bit Processor Status Register (PSR). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of PSR must be 0 or a Reserved Register/Field fault may occur. The caller must either guarantee that Value is valid, or the caller must set up fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to PSR. + + @return The 64-bit value written to the PSR. + +**/ +UINT64 +EFIAPI +AsmWritePsr ( + IN UINT64 Value + ); + + +/** + Reads the current value of 64-bit Kernel Register #0 (KR0). + This function is only available on IPF. + + @return The current value of KR0. + +**/ +UINT64 +EFIAPI +AsmReadKr0 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #1 (KR1). + This function is only available on IPF. + + @return The current value of KR1. + +**/ +UINT64 +EFIAPI +AsmReadKr1 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #2 (KR2). + This function is only available on IPF. + + @return The current value of KR2. + +**/ +UINT64 +EFIAPI +AsmReadKr2 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #3 (KR3). + This function is only available on IPF. + + @return The current value of KR3. + +**/ +UINT64 +EFIAPI +AsmReadKr3 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #4 (KR4). + This function is only available on IPF. + + @return The current value of KR4. + +**/ +UINT64 +EFIAPI +AsmReadKr4 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #5 (KR5). + This function is only available on IPF. + + @return The current value of KR5. + +**/ +UINT64 +EFIAPI +AsmReadKr5 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #6 (KR6). + This function is only available on IPF. + + @return The current value of KR6. + +**/ +UINT64 +EFIAPI +AsmReadKr6 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #7 (KR7). + This function is only available on IPF. + + @return The current value of KR7. + +**/ +UINT64 +EFIAPI +AsmReadKr7 ( + VOID + ); + + +/** + Write the current value of 64-bit Kernel Register #0 (KR0). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR0. + + @return The 64-bit value written to the KR0. + +**/ +UINT64 +EFIAPI +AsmWriteKr0 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #1 (KR1). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR1. + + @return The 64-bit value written to the KR1. + +**/ +UINT64 +EFIAPI +AsmWriteKr1 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #2 (KR2). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR2. + + @return The 64-bit value written to the KR2. + +**/ +UINT64 +EFIAPI +AsmWriteKr2 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #3 (KR3). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR3. + + @return The 64-bit value written to the KR3. + +**/ +UINT64 +EFIAPI +AsmWriteKr3 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #4 (KR4). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR4. + + @return The 64-bit value written to the KR4. + +**/ +UINT64 +EFIAPI +AsmWriteKr4 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #5 (KR5). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR5. + + @return The 64-bit value written to the KR5. + +**/ +UINT64 +EFIAPI +AsmWriteKr5 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #6 (KR6). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR6. + + @return The 64-bit value written to the KR6. + +**/ +UINT64 +EFIAPI +AsmWriteKr6 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #7 (KR7). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR7. + + @return The 64-bit value written to the KR7. + +**/ +UINT64 +EFIAPI +AsmWriteKr7 ( + IN UINT64 Value + ); + + +/** + Reads the current value of Interval Timer Counter Register (ITC). + This function is only available on IPF. + + @return The current value of ITC. + +**/ +UINT64 +EFIAPI +AsmReadItc ( + VOID + ); + + +/** + Reads the current value of Interval Timer Vector Register (ITV). + This function is only available on IPF. + + @return The current value of ITV. + +**/ +UINT64 +EFIAPI +AsmReadItv ( + VOID + ); + + +/** + Reads the current value of Interval Timer Match Register (ITM). + This function is only available on IPF. + + @return The current value of ITM. +**/ +UINT64 +EFIAPI +AsmReadItm ( + VOID + ); + + +/** + Writes the current value of 64-bit Interval Timer Counter Register (ITC). + This function is only available on IPF. + + @param Value The 64-bit value to write to ITC. + + @return The 64-bit value written to the ITC. + +**/ +UINT64 +EFIAPI +AsmWriteItc ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Interval Timer Match Register (ITM). + This function is only available on IPF. + + @param Value The 64-bit value to write to ITM. + + @return The 64-bit value written to the ITM. + +**/ +UINT64 +EFIAPI +AsmWriteItm ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Interval Timer Vector Register (ITV). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of ITV must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to ITV. + + @return The 64-bit value written to the ITV. + +**/ +UINT64 +EFIAPI +AsmWriteItv ( + IN UINT64 Value + ); + + +/** + Reads the current value of Default Control Register (DCR). + This function is only available on IPF. + + @return The current value of DCR. + +**/ +UINT64 +EFIAPI +AsmReadDcr ( + VOID + ); + + +/** + Reads the current value of Interruption Vector Address Register (IVA). + This function is only available on IPF. + + @return The current value of IVA. +**/ +UINT64 +EFIAPI +AsmReadIva ( + VOID + ); + + +/** + Reads the current value of Page Table Address Register (PTA). + This function is only available on IPF. + + @return The current value of PTA. + +**/ +UINT64 +EFIAPI +AsmReadPta ( + VOID + ); + + +/** + Writes the current value of 64-bit Default Control Register (DCR). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of DCR must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to DCR. + + @return The 64-bit value written to the DCR. + +**/ +UINT64 +EFIAPI +AsmWriteDcr ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Interruption Vector Address Register (IVA). + The size of vector table is 32 K bytes and is 32 K bytes aligned + the low 15 bits of Value is ignored when written. + This function is only available on IPF. + + @param Value The 64-bit value to write to IVA. + + @return The 64-bit value written to the IVA. + +**/ +UINT64 +EFIAPI +AsmWriteIva ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Page Table Address Register (PTA). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of DCR must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to PTA. + + @return The 64-bit value written to the PTA. +**/ +UINT64 +EFIAPI +AsmWritePta ( + IN UINT64 Value + ); + + +/** + Reads the current value of Local Interrupt ID Register (LID). + This function is only available on IPF. + + @return The current value of LID. + +**/ +UINT64 +EFIAPI +AsmReadLid ( + VOID + ); + + +/** + Reads the current value of External Interrupt Vector Register (IVR). + This function is only available on IPF. + + @return The current value of IVR. + +**/ +UINT64 +EFIAPI +AsmReadIvr ( + VOID + ); + + +/** + Reads the current value of Task Priority Register (TPR). + This function is only available on IPF. + + @return The current value of TPR. + +**/ +UINT64 +EFIAPI +AsmReadTpr ( + VOID + ); + + +/** + Reads the current value of External Interrupt Request Register #0 (IRR0). + This function is only available on IPF. + + @return The current value of IRR0. + +**/ +UINT64 +EFIAPI +AsmReadIrr0 ( + VOID + ); + + +/** + Reads the current value of External Interrupt Request Register #1 (IRR1). + This function is only available on IPF. + + @return The current value of IRR1. + +**/ +UINT64 +EFIAPI +AsmReadIrr1 ( + VOID + ); + + +/** + Reads the current value of External Interrupt Request Register #2 (IRR2). + This function is only available on IPF. + + @return The current value of IRR2. + +**/ +UINT64 +EFIAPI +AsmReadIrr2 ( + VOID + ); + + +/** + Reads the current value of External Interrupt Request Register #3 (IRR3). + This function is only available on IPF. + + @return The current value of IRR3. + +**/ +UINT64 +EFIAPI +AsmReadIrr3 ( + VOID + ); + + +/** + Reads the current value of Performance Monitor Vector Register (PMV). + This function is only available on IPF. + + @return The current value of PMV. + +**/ +UINT64 +EFIAPI +AsmReadPmv ( + VOID + ); + + +/** + Reads the current value of Corrected Machine Check Vector Register (CMCV). + This function is only available on IPF. + + @return The current value of CMCV. + +**/ +UINT64 +EFIAPI +AsmReadCmcv ( + VOID + ); + + +/** + Reads the current value of Local Redirection Register #0 (LRR0). + This function is only available on IPF. + + @return The current value of LRR0. + +**/ +UINT64 +EFIAPI +AsmReadLrr0 ( + VOID + ); + + +/** + Reads the current value of Local Redirection Register #1 (LRR1). + This function is only available on IPF. + + @return The current value of LRR1. + +**/ +UINT64 +EFIAPI +AsmReadLrr1 ( + VOID + ); + + +/** + Writes the current value of 64-bit Page Local Interrupt ID Register (LID). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of LID must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to LID. + + @return The 64-bit value written to the LID. + +**/ +UINT64 +EFIAPI +AsmWriteLid ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Task Priority Register (TPR). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of TPR must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to TPR. + + @return The 64-bit value written to the TPR. + +**/ +UINT64 +EFIAPI +AsmWriteTpr ( + IN UINT64 Value + ); + + +/** + Performs a write operation on End OF External Interrupt Register (EOI). + Writes a value of 0 to the EOI Register. This function is only available on IPF. + +**/ +VOID +EFIAPI +AsmWriteEoi ( + VOID + ); + + +/** + Writes the current value of 64-bit Performance Monitor Vector Register (PMV). + No parameter checking is performed on Value. All bits of Value corresponding + to reserved fields of PMV must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to PMV. + + @return The 64-bit value written to the PMV. + +**/ +UINT64 +EFIAPI +AsmWritePmv ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Corrected Machine Check Vector Register (CMCV). + No parameter checking is performed on Value. All bits of Value corresponding + to reserved fields of CMCV must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to CMCV. + + @return The 64-bit value written to the CMCV. + +**/ +UINT64 +EFIAPI +AsmWriteCmcv ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Local Redirection Register #0 (LRR0). + No parameter checking is performed on Value. All bits of Value corresponding + to reserved fields of LRR0 must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to LRR0. + + @return The 64-bit value written to the LRR0. + +**/ +UINT64 +EFIAPI +AsmWriteLrr0 ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Local Redirection Register #1 (LRR1). + No parameter checking is performed on Value. All bits of Value corresponding + to reserved fields of LRR1 must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must + set up fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to LRR1. + + @return The 64-bit value written to the LRR1. + +**/ +UINT64 +EFIAPI +AsmWriteLrr1 ( + IN UINT64 Value + ); + + +/** + Reads the current value of Instruction Breakpoint Register (IBR). + + The Instruction Breakpoint Registers are used in pairs. The even numbered + registers contain breakpoint addresses, and the odd numbered registers contain + breakpoint mask conditions. At least 4 instruction registers pairs are implemented + on all processor models. Implemented registers are contiguous starting with + register 0. No parameter checking is performed on Index, and if the Index value + is beyond the implemented IBR register range, a Reserved Register/Field fault may + occur. The caller must either guarantee that Index is valid, or the caller must + set up fault handlers to catch the faults. + This function is only available on IPF. + + @param Index The 8-bit Instruction Breakpoint Register index to read. + + @return The current value of Instruction Breakpoint Register specified by Index. + +**/ +UINT64 +EFIAPI +AsmReadIbr ( + IN UINT8 Index + ); + + +/** + Reads the current value of Data Breakpoint Register (DBR). + + The Data Breakpoint Registers are used in pairs. The even numbered registers + contain breakpoint addresses, and odd numbered registers contain breakpoint + mask conditions. At least 4 data registers pairs are implemented on all processor + models. Implemented registers are contiguous starting with register 0. + No parameter checking is performed on Index. If the Index value is beyond + the implemented DBR register range, a Reserved Register/Field fault may occur. + The caller must either guarantee that Index is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Index The 8-bit Data Breakpoint Register index to read. + + @return The current value of Data Breakpoint Register specified by Index. + +**/ +UINT64 +EFIAPI +AsmReadDbr ( + IN UINT8 Index + ); + + +/** + Reads the current value of Performance Monitor Configuration Register (PMC). + + All processor implementations provide at least 4 performance counters + (PMC/PMD [4]...PMC/PMD [7] pairs), and 4 performance monitor counter overflow + status registers (PMC [0]... PMC [3]). Processor implementations may provide + additional implementation-dependent PMC and PMD to increase the number of + 'generic' performance counters (PMC/PMD pairs). The remainder of PMC and PMD + register set is implementation dependent. No parameter checking is performed + on Index. If the Index value is beyond the implemented PMC register range, + zero value will be returned. + This function is only available on IPF. + + @param Index The 8-bit Performance Monitor Configuration Register index to read. + + @return The current value of Performance Monitor Configuration Register + specified by Index. + +**/ +UINT64 +EFIAPI +AsmReadPmc ( + IN UINT8 Index + ); + + +/** + Reads the current value of Performance Monitor Data Register (PMD). + + All processor implementations provide at least 4 performance counters + (PMC/PMD [4]...PMC/PMD [7] pairs), and 4 performance monitor counter + overflow status registers (PMC [0]... PMC [3]). Processor implementations may + provide additional implementation-dependent PMC and PMD to increase the number + of 'generic' performance counters (PMC/PMD pairs). The remainder of PMC and PMD + register set is implementation dependent. No parameter checking is performed + on Index. If the Index value is beyond the implemented PMD register range, + zero value will be returned. + This function is only available on IPF. + + @param Index The 8-bit Performance Monitor Data Register index to read. + + @return The current value of Performance Monitor Data Register specified by Index. **/ -VOID +UINT64 EFIAPI -LongJump ( - IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer, - IN UINTN Value +AsmReadPmd ( + IN UINT8 Index ); + /** - Enables CPU interrupts. + Writes the current value of 64-bit Instruction Breakpoint Register (IBR). - Enables CPU interrupts. + Writes current value of Instruction Breakpoint Register specified by Index. + The Instruction Breakpoint Registers are used in pairs. The even numbered + registers contain breakpoint addresses, and odd numbered registers contain + breakpoint mask conditions. At least 4 instruction registers pairs are implemented + on all processor models. Implemented registers are contiguous starting with + register 0. No parameter checking is performed on Index. If the Index value + is beyond the implemented IBR register range, a Reserved Register/Field fault may + occur. The caller must either guarantee that Index is valid, or the caller must + set up fault handlers to catch the faults. + This function is only available on IPF. + + @param Index The 8-bit Instruction Breakpoint Register index to write. + @param Value The 64-bit value to write to IBR. + + @return The 64-bit value written to the IBR. **/ -VOID +UINT64 EFIAPI -EnableInterrupts ( - VOID +AsmWriteIbr ( + IN UINT8 Index, + IN UINT64 Value ); + /** - Disables CPU interrupts. + Writes the current value of 64-bit Data Breakpoint Register (DBR). - Disables CPU interrupts. + Writes current value of Data Breakpoint Register specified by Index. + The Data Breakpoint Registers are used in pairs. The even numbered registers + contain breakpoint addresses, and odd numbered registers contain breakpoint + mask conditions. At least 4 data registers pairs are implemented on all processor + models. Implemented registers are contiguous starting with register 0. No parameter + checking is performed on Index. If the Index value is beyond the implemented + DBR register range, a Reserved Register/Field fault may occur. The caller must + either guarantee that Index is valid, or the caller must set up fault handlers to + catch the faults. + This function is only available on IPF. + + @param Index The 8-bit Data Breakpoint Register index to write. + @param Value The 64-bit value to write to DBR. + + @return The 64-bit value written to the DBR. **/ -VOID +UINT64 EFIAPI -DisableInterrupts ( - VOID +AsmWriteDbr ( + IN UINT8 Index, + IN UINT64 Value ); + /** - Disables CPU interrupts and returns the interrupt state prior to the disable - operation. + Writes the current value of 64-bit Performance Monitor Configuration Register (PMC). - Disables CPU interrupts and returns the interrupt state prior to the disable - operation. + Writes current value of Performance Monitor Configuration Register specified by Index. + All processor implementations provide at least 4 performance counters + (PMC/PMD [4]...PMC/PMD [7] pairs), and 4 performance monitor counter overflow status + registers (PMC [0]... PMC [3]). Processor implementations may provide additional + implementation-dependent PMC and PMD to increase the number of 'generic' performance + counters (PMC/PMD pairs). The remainder of PMC and PMD register set is implementation + dependent. No parameter checking is performed on Index. If the Index value is + beyond the implemented PMC register range, the write is ignored. + This function is only available on IPF. - @retval TRUE CPU interrupts were enabled on entry to this call. - @retval FALSE CPU interrupts were disabled on entry to this call. + @param Index The 8-bit Performance Monitor Configuration Register index to write. + @param Value The 64-bit value to write to PMC. + + @return The 64-bit value written to the PMC. **/ -BOOLEAN +UINT64 EFIAPI -SaveAndDisableInterrupts ( - VOID +AsmWritePmc ( + IN UINT8 Index, + IN UINT64 Value ); + /** - Enables CPU interrupts for the smallest window required to capture any - pending interrupts. + Writes the current value of 64-bit Performance Monitor Data Register (PMD). - Enables CPU interrupts for the smallest window required to capture any - pending interrupts. + Writes current value of Performance Monitor Data Register specified by Index. + All processor implementations provide at least 4 performance counters + (PMC/PMD [4]...PMC/PMD [7] pairs), and 4 performance monitor counter overflow + status registers (PMC [0]... PMC [3]). Processor implementations may provide + additional implementation-dependent PMC and PMD to increase the number of 'generic' + performance counters (PMC/PMD pairs). The remainder of PMC and PMD register set + is implementation dependent. No parameter checking is performed on Index. If the + Index value is beyond the implemented PMD register range, the write is ignored. + This function is only available on IPF. + + @param Index The 8-bit Performance Monitor Data Register index to write. + @param Value The 64-bit value to write to PMD. + + @return The 64-bit value written to the PMD. **/ -VOID +UINT64 EFIAPI -EnableDisableInterrupts ( - VOID +AsmWritePmd ( + IN UINT8 Index, + IN UINT64 Value ); + /** - Retrieves the current CPU interrupt state. + Reads the current value of 64-bit Global Pointer (GP). - Retrieves the current CPU interrupt state. Returns TRUE is interrupts are - currently enabled. Otherwise returns FALSE. + Reads and returns the current value of GP. + This function is only available on IPF. - @retval TRUE CPU interrupts are enabled. - @retval FALSE CPU interrupts are disabled. + @return The current value of GP. **/ -BOOLEAN +UINT64 EFIAPI -GetInterruptState ( +AsmReadGp ( VOID ); + /** - Set the current CPU interrupt state. + Write the current value of 64-bit Global Pointer (GP). - Sets the current CPU interrupt state to the state specified by - InterruptState. If InterruptState is TRUE, then interrupts are enabled. If - InterruptState is FALSE, then interrupts are disabled. InterruptState is - returned. + Writes the current value of GP. The 64-bit value written to the GP is returned. + No parameter checking is performed on Value. + This function is only available on IPF. - @param InterruptState TRUE if interrupts should enabled. FALSE if - interrupts should be disabled. + @param Value The 64-bit value to write to GP. - @return InterruptState + @return The 64-bit value written to the GP. **/ -BOOLEAN +UINT64 EFIAPI -SetInterruptState ( - IN BOOLEAN InterruptState +AsmWriteGp ( + IN UINT64 Value ); + /** - Places the CPU in a sleep state until an interrupt is received. + Reads the current value of 64-bit Stack Pointer (SP). - Places the CPU in a sleep state until an interrupt is received. If interrupts - are disabled prior to calling this function, then the CPU will be placed in a - sleep state indefinitely. + Reads and returns the current value of SP. + This function is only available on IPF. + + @return The current value of SP. **/ -VOID +UINT64 EFIAPI -CpuSleep ( +AsmReadSp ( VOID ); + /** - Requests CPU to pause for a short period of time. + Determines if the CPU is currently executing in virtual, physical, or mixed mode. - Requests CPU to pause for a short period of time. Typically used in MP - systems to prevent memory starvation while waiting for a spin lock. + Determines the current execution mode of the CPU. + If the CPU is in virtual mode(PSR.RT=1, PSR.DT=1, PSR.IT=1), then 1 is returned. + If the CPU is in physical mode(PSR.RT=0, PSR.DT=0, PSR.IT=0), then 0 is returned. + If the CPU is not in physical mode or virtual mode, then it is in mixed mode, + and -1 is returned. + This function is only available on IPF. + + @return 1 The CPU is in virtual mode. + @return 0 The CPU is in physical mode. + @return -1 The CPU is in mixed mode. **/ -VOID +INT64 EFIAPI -CpuPause ( +AsmCpuVirtual ( VOID ); + /** - Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU. + Makes a PAL procedure call. + + This is a wrapper function to make a PAL procedure call. Based on the Index + value this API will make static or stacked PAL call. The following table + describes the usage of PAL Procedure Index Assignment. Architected procedures + may be designated as required or optional. If a PAL procedure is specified + as optional, a unique return code of 0xFFFFFFFFFFFFFFFF is returned in the + Status field of the PAL_CALL_RETURN structure. + This indicates that the procedure is not present in this PAL implementation. + It is the caller's responsibility to check for this return code after calling + any optional PAL procedure. + No parameter checking is performed on the 5 input parameters, but there are + some common rules that the caller should follow when making a PAL call. Any + address passed to PAL as buffers for return parameters must be 8-byte aligned. + Unaligned addresses may cause undefined results. For those parameters defined + as reserved or some fields defined as reserved must be zero filled or the invalid + argument return value may be returned or undefined result may occur during the + execution of the procedure. If the PalEntryPoint does not point to a valid + PAL entry point then the system behavior is undefined. This function is only + available on IPF. + + @param PalEntryPoint The PAL procedure calls entry point. + @param Index The PAL procedure Index number. + @param Arg2 The 2nd parameter for PAL procedure calls. + @param Arg3 The 3rd parameter for PAL procedure calls. + @param Arg4 The 4th parameter for PAL procedure calls. - Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU. + @return structure returned from the PAL Call procedure, including the status and return value. **/ -VOID +PAL_CALL_RETURN EFIAPI -CpuFlushTlb ( - VOID +AsmPalCall ( + IN UINT64 PalEntryPoint, + IN UINT64 Index, + IN UINT64 Arg2, + IN UINT64 Arg3, + IN UINT64 Arg4 ); + /** Transfers control to a function starting with a new stack. @@ -2711,166 +4904,171 @@ CpuFlushTlb ( function. @param NewStack A pointer to the new stack to use for the EntryPoint function. + @param NewBsp A pointer to the new memory location for RSE backing + store. **/ VOID EFIAPI -SwitchStack ( +AsmSwitchStackAndBackingStore ( IN SWITCH_STACK_ENTRY_POINT EntryPoint, IN VOID *Context1, OPTIONAL IN VOID *Context2, OPTIONAL - IN VOID *NewStack + IN VOID *NewStack, + IN VOID *NewBsp ); /** - Generates a breakpoint on the CPU. + @todo This call should be removed after the PalCall + Instance issue has been fixed. - Generates a breakpoint on the CPU. The breakpoint must be implemented such - that code can resume normal execution after the breakpoint. + Performs a PAL call using static calling convention. -**/ -VOID -EFIAPI -CpuBreakpoint ( - VOID - ); + An internal function to perform a PAL call using static calling convention. -/** - Executes an infinite loop. + @param PalEntryPoint The entry point address of PAL. The address in ar.kr5 + would be used if this parameter were NULL on input. + @param Arg1 The first argument of a PAL call. + @param Arg2 The second argument of a PAL call. + @param Arg3 The third argument of a PAL call. + @param Arg4 The fourth argument of a PAL call. - Forces the CPU to execute an infinite loop. A debugger may be used to skip - past the loop and the code that follows the loop must execute properly. This - implies that the infinite loop must not cause the code that follow it to be - optimized away. + @return The values returned in r8, r9, r10 and r11. **/ -VOID -EFIAPI -CpuDeadLoop ( - VOID +PAL_CALL_RETURN +PalCallStatic ( + IN CONST VOID *PalEntryPoint, + IN UINT64 Arg1, + IN UINT64 Arg2, + IN UINT64 Arg3, + IN UINT64 Arg4 ); -// -// IA32 and X64 Specific Functions -// -// -// Byte packed structure for 16-bit Real Mode EFLAGS -// + +#elif defined (MDE_CPU_IA32) || defined (MDE_CPU_X64) +/// +/// IA32 and X64 Specific Functions +/// Byte packed structure for 16-bit Real Mode EFLAGS +/// typedef union { struct { - UINT32 CF:1; // Carry Flag - UINT32 Reserved_0:1; // Reserved - UINT32 PF:1; // Parity Flag - UINT32 Reserved_1:1; // Reserved - UINT32 AF:1; // Auxiliary Carry Flag - UINT32 Reserved_2:1; // Reserved - UINT32 ZF:1; // Zero Flag - UINT32 SF:1; // Sign Flag - UINT32 TF:1; // Trap Flag - UINT32 IF:1; // Interrupt Enable Flag - UINT32 DF:1; // Direction Flag - UINT32 OF:1; // Overflow Flag - UINT32 IOPL:2; // I/O Privilege Level - UINT32 NT:1; // Nested Task - UINT32 Reserved_3:1; // Reserved + UINT32 CF:1; /// Carry Flag + UINT32 Reserved_0:1; /// Reserved + UINT32 PF:1; /// Parity Flag + UINT32 Reserved_1:1; /// Reserved + UINT32 AF:1; /// Auxiliary Carry Flag + UINT32 Reserved_2:1; /// Reserved + UINT32 ZF:1; /// Zero Flag + UINT32 SF:1; /// Sign Flag + UINT32 TF:1; /// Trap Flag + UINT32 IF:1; /// Interrupt Enable Flag + UINT32 DF:1; /// Direction Flag + UINT32 OF:1; /// Overflow Flag + UINT32 IOPL:2; /// I/O Privilege Level + UINT32 NT:1; /// Nested Task + UINT32 Reserved_3:1; /// Reserved } Bits; UINT16 Uint16; } IA32_FLAGS16; -// -// Byte packed structure for EFLAGS/RFLAGS -// 32-bits on IA-32 -// 64-bits on X64. The upper 32-bits on X64 are reserved -// +/// +/// Byte packed structure for EFLAGS/RFLAGS +/// 32-bits on IA-32 +/// 64-bits on X64. The upper 32-bits on X64 are reserved +/// typedef union { struct { - UINT32 CF:1; // Carry Flag - UINT32 Reserved_0:1; // Reserved - UINT32 PF:1; // Parity Flag - UINT32 Reserved_1:1; // Reserved - UINT32 AF:1; // Auxiliary Carry Flag - UINT32 Reserved_2:1; // Reserved - UINT32 ZF:1; // Zero Flag - UINT32 SF:1; // Sign Flag - UINT32 TF:1; // Trap Flag - UINT32 IF:1; // Interrupt Enable Flag - UINT32 DF:1; // Direction Flag - UINT32 OF:1; // Overflow Flag - UINT32 IOPL:2; // I/O Privilege Level - UINT32 NT:1; // Nested Task - UINT32 Reserved_3:1; // Reserved - UINT32 RF:1; // Resume Flag - UINT32 VM:1; // Virtual 8086 Mode - UINT32 AC:1; // Alignment Check - UINT32 VIF:1; // Virtual Interrupt Flag - UINT32 VIP:1; // Virtual Interrupt Pending - UINT32 ID:1; // ID Flag - UINT32 Reserved_4:10; // Reserved + UINT32 CF:1; /// Carry Flag + UINT32 Reserved_0:1; /// Reserved + UINT32 PF:1; /// Parity Flag + UINT32 Reserved_1:1; /// Reserved + UINT32 AF:1; /// Auxiliary Carry Flag + UINT32 Reserved_2:1; /// Reserved + UINT32 ZF:1; /// Zero Flag + UINT32 SF:1; /// Sign Flag + UINT32 TF:1; /// Trap Flag + UINT32 IF:1; /// Interrupt Enable Flag + UINT32 DF:1; /// Direction Flag + UINT32 OF:1; /// Overflow Flag + UINT32 IOPL:2; /// I/O Privilege Level + UINT32 NT:1; /// Nested Task + UINT32 Reserved_3:1; /// Reserved + UINT32 RF:1; /// Resume Flag + UINT32 VM:1; /// Virtual 8086 Mode + UINT32 AC:1; /// Alignment Check + UINT32 VIF:1; /// Virtual Interrupt Flag + UINT32 VIP:1; /// Virtual Interrupt Pending + UINT32 ID:1; /// ID Flag + UINT32 Reserved_4:10; /// Reserved } Bits; UINTN UintN; } IA32_EFLAGS32; -// -// Byte packed structure for Control Register 0 (CR0) -// 32-bits on IA-32 -// 64-bits on X64. The upper 32-bits on X64 are reserved -// +/// +/// Byte packed structure for Control Register 0 (CR0) +/// 32-bits on IA-32 +/// 64-bits on X64. The upper 32-bits on X64 are reserved +/// typedef union { struct { - UINT32 PE:1; // Protection Enable - UINT32 MP:1; // Monitor Coprocessor - UINT32 EM:1; // Emulation - UINT32 TS:1; // Task Switched - UINT32 ET:1; // Extension Type - UINT32 NE:1; // Numeric Error - UINT32 Reserved_0:10; // Reserved - UINT32 WP:1; // Write Protect - UINT32 Reserved_1:1; // Reserved - UINT32 AM:1; // Alignment Mask - UINT32 Reserved_2:10; // Reserved - UINT32 NW:1; // Mot Write-through - UINT32 CD:1; // Cache Disable - UINT32 PG:1; // Paging + UINT32 PE:1; /// Protection Enable + UINT32 MP:1; /// Monitor Coprocessor + UINT32 EM:1; /// Emulation + UINT32 TS:1; /// Task Switched + UINT32 ET:1; /// Extension Type + UINT32 NE:1; /// Numeric Error + UINT32 Reserved_0:10; /// Reserved + UINT32 WP:1; /// Write Protect + UINT32 Reserved_1:1; /// Reserved + UINT32 AM:1; /// Alignment Mask + UINT32 Reserved_2:10; /// Reserved + UINT32 NW:1; /// Mot Write-through + UINT32 CD:1; /// Cache Disable + UINT32 PG:1; /// Paging } Bits; UINTN UintN; } IA32_CR0; -// -// Byte packed structure for Control Register 4 (CR4) -// 32-bits on IA-32 -// 64-bits on X64. The upper 32-bits on X64 are reserved -// +/// +/// Byte packed structure for Control Register 4 (CR4) +/// 32-bits on IA-32 +/// 64-bits on X64. The upper 32-bits on X64 are reserved +/// typedef union { struct { - UINT32 VME:1; // Virtual-8086 Mode Extensions - UINT32 PVI:1; // Protected-Mode Virtual Interrupts - UINT32 TSD:1; // Time Stamp Disable - UINT32 DE:1; // Debugging Extensions - UINT32 PSE:1; // Page Size Extensions - UINT32 PAE:1; // Physical Address Extension - UINT32 MCE:1; // Machine Check Enable - UINT32 PGE:1; // Page Global Enable - UINT32 PCE:1; // Performance Monitoring Counter - // Enable - UINT32 OSFXSR:1; // Operating System Support for - // FXSAVE and FXRSTOR instructions - UINT32 OSXMMEXCPT:1; // Operating System Support for - // Unmasked SIMD Floating Point - // Exceptions - UINT32 Reserved_0:2; // Reserved - UINT32 VMXE:1; // VMX Enable - UINT32 Reserved_1:18; // Reseved + UINT32 VME:1; /// Virtual-8086 Mode Extensions + UINT32 PVI:1; /// Protected-Mode Virtual Interrupts + UINT32 TSD:1; /// Time Stamp Disable + UINT32 DE:1; /// Debugging Extensions + UINT32 PSE:1; /// Page Size Extensions + UINT32 PAE:1; /// Physical Address Extension + UINT32 MCE:1; /// Machine Check Enable + UINT32 PGE:1; /// Page Global Enable + UINT32 PCE:1; /// Performance Monitoring Counter + /// Enable + UINT32 OSFXSR:1; /// Operating System Support for + /// FXSAVE and FXRSTOR instructions + UINT32 OSXMMEXCPT:1; /// Operating System Support for + /// Unmasked SIMD Floating Point + /// Exceptions + UINT32 Reserved_0:2; /// Reserved + UINT32 VMXE:1; /// VMX Enable + UINT32 Reserved_1:18; /// Reseved } Bits; UINTN UintN; } IA32_CR4; -// -// Byte packed structure for an IDTR, GDTR, LDTR descriptor -// +/// +/// Byte packed structure for an IDTR, GDTR, LDTR descriptor +/// @todo How to make this structure byte-packed in a compiler independent way? +/// +#pragma pack (1) typedef struct { UINT16 Limit; UINTN Base; } IA32_DESCRIPTOR; +#pragma pack () #define IA32_IDT_GATE_TYPE_TASK 0x85 #define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86 @@ -2878,30 +5076,30 @@ typedef struct { #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F -// -// Byte packed structure for an Interrupt Gate Descriptor -// +/// +/// Byte packed structure for an Interrupt Gate Descriptor +/// typedef union { struct { - UINT32 OffsetLow:16; // Offset bits 15..0 - UINT32 Selector:16; // Selector - UINT32 Reserved_0:8; // Reserved - UINT32 GateType:8; // Gate Type. See #defines above - UINT32 OffsetHigh:16; // Offset bits 31..16 + UINT32 OffsetLow:16; /// Offset bits 15..0 + UINT32 Selector:16; /// Selector + UINT32 Reserved_0:8; /// Reserved + UINT32 GateType:8; /// Gate Type. See #defines above + UINT32 OffsetHigh:16; /// Offset bits 31..16 } Bits; UINT64 Uint64; } IA32_IDT_GATE_DESCRIPTOR; -// -// Byte packed structure for an FP/SSE/SSE2 context -// +/// +/// Byte packed structure for an FP/SSE/SSE2 context +/// typedef struct { UINT8 Buffer[512]; } IA32_FX_BUFFER; -// -// Structures for the 16-bit real mode thunks -// +/// +/// Structures for the 16-bit real mode thunks +/// typedef struct { UINT32 Reserved1; UINT32 Reserved2; @@ -2965,19 +5163,20 @@ typedef union { IA32_BYTE_REGS H; } IA32_REGISTER_SET; -// -// Byte packed structure for an 16-bit real mode thunks -// +/// +/// Byte packed structure for an 16-bit real mode thunks +/// typedef struct { - IA32_REGISTER_SET RealModeState; + IA32_REGISTER_SET *RealModeState; VOID *RealModeBuffer; - UINTN RealModeBufferSize; - VOID *CallStack; - UINTN CallStackSize; - VOID *RealModeCode; - UINTN RealModeCodeSize; + UINT32 RealModeBufferSize; + UINT32 ThunkAttributes; } THUNK_CONTEXT; +#define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001 +#define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002 +#define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004 + /** Retrieves CPUID information. @@ -3013,6 +5212,51 @@ AsmCpuid ( OUT UINT32 *Edx OPTIONAL ); + +/** + Retrieves CPUID information using an extended leaf identifier. + + Executes the CPUID instruction with EAX set to the value specified by Index + and ECX set to the value specified by SubIndex. This function always returns + Index. This function is only available on IA-32 and x64. + + If Eax is not NULL, then the value of EAX after CPUID is returned in Eax. + If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx. + If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx. + If Edx is not NULL, then the value of EDX after CPUID is returned in Edx. + + @param Index The 32-bit value to load into EAX prior to invoking the + CPUID instruction. + @param SubIndex The 32-bit value to load into ECX prior to invoking the + CPUID instruction. + @param Eax Pointer to the 32-bit EAX value returned by the CPUID + instruction. This is an optional parameter that may be + NULL. + @param Ebx Pointer to the 32-bit EBX value returned by the CPUID + instruction. This is an optional parameter that may be + NULL. + @param Ecx Pointer to the 32-bit ECX value returned by the CPUID + instruction. This is an optional parameter that may be + NULL. + @param Edx Pointer to the 32-bit EDX value returned by the CPUID + instruction. This is an optional parameter that may be + NULL. + + @return Index + +**/ +UINT32 +EFIAPI +AsmCpuidEx ( + IN UINT32 Index, + IN UINT32 SubIndex, + OUT UINT32 *Eax, OPTIONAL + OUT UINT32 *Ebx, OPTIONAL + OUT UINT32 *Ecx, OPTIONAL + OUT UINT32 *Edx OPTIONAL + ); + + /** Returns the lower 32-bits of a Machine Specific Register(MSR). @@ -3033,6 +5277,7 @@ AsmReadMsr32 ( IN UINT32 Index ); + /** Zero-extend a 32-bit value and writes it to a Machine Specific Register(MSR). @@ -3056,6 +5301,7 @@ AsmWriteMsr32 ( IN UINT32 Value ); + /** Reads a 64-bit MSR, performs a bitwise inclusive OR on the lower 32-bits, and writes the result back to the 64-bit MSR. @@ -3082,6 +5328,7 @@ AsmMsrOr32 ( IN UINT32 OrData ); + /** Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes the result back to the 64-bit MSR. @@ -3108,6 +5355,7 @@ AsmMsrAnd32 ( IN UINT32 AndData ); + /** Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise inclusive OR on the lower 32-bits, and writes the result back to the 64-bit MSR. @@ -3138,6 +5386,7 @@ AsmMsrAndThenOr32 ( IN UINT32 OrData ); + /** Reads a bit field of an MSR. @@ -3149,7 +5398,7 @@ AsmMsrAndThenOr32 ( If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to read. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3168,6 +5417,7 @@ AsmMsrBitFieldRead32 ( IN UINTN EndBit ); + /** Writes a bit field to an MSR. @@ -3181,7 +5431,7 @@ AsmMsrBitFieldRead32 ( If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to write. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3202,6 +5452,7 @@ AsmMsrBitFieldWrite32 ( IN UINT32 Value ); + /** Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the result back to the bit field in the 64-bit MSR. @@ -3216,7 +5467,7 @@ AsmMsrBitFieldWrite32 ( If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to write. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3237,6 +5488,7 @@ AsmMsrBitFieldOr32 ( IN UINT32 OrData ); + /** Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the result back to the bit field in the 64-bit MSR. @@ -3251,7 +5503,7 @@ AsmMsrBitFieldOr32 ( If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to write. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3272,6 +5524,7 @@ AsmMsrBitFieldAnd32 ( IN UINT32 AndData ); + /** Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a bitwise inclusive OR, and writes the result back to the bit field in the @@ -3288,7 +5541,7 @@ AsmMsrBitFieldAnd32 ( If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to write. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3311,6 +5564,7 @@ AsmMsrBitFieldAndThenOr32 ( IN UINT32 OrData ); + /** Returns a 64-bit Machine Specific Register(MSR). @@ -3331,6 +5585,7 @@ AsmReadMsr64 ( IN UINT32 Index ); + /** Writes a 64-bit value to a Machine Specific Register(MSR), and returns the value. @@ -3355,6 +5610,7 @@ AsmWriteMsr64 ( IN UINT64 Value ); + /** Reads a 64-bit MSR, performs a bitwise inclusive OR, and writes the result back to the 64-bit MSR. @@ -3380,6 +5636,7 @@ AsmMsrOr64 ( IN UINT64 OrData ); + /** Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the 64-bit MSR. @@ -3405,6 +5662,7 @@ AsmMsrAnd64 ( IN UINT64 AndData ); + /** Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise inclusive OR, and writes the result back to the 64-bit MSR. @@ -3434,6 +5692,7 @@ AsmMsrAndThenOr64 ( IN UINT64 OrData ); + /** Reads a bit field of an MSR. @@ -3445,7 +5704,7 @@ AsmMsrAndThenOr64 ( If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to read. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3464,6 +5723,7 @@ AsmMsrBitFieldRead64 ( IN UINTN EndBit ); + /** Writes a bit field to an MSR. @@ -3476,7 +5736,7 @@ AsmMsrBitFieldRead64 ( If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to write. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3497,6 +5757,7 @@ AsmMsrBitFieldWrite64 ( IN UINT64 Value ); + /** Reads a bit field in a 64-bit MSR, performs a bitwise inclusive OR, and writes the result back to the bit field in the 64-bit MSR. @@ -3511,7 +5772,7 @@ AsmMsrBitFieldWrite64 ( If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to write. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3532,6 +5793,7 @@ AsmMsrBitFieldOr64 ( IN UINT64 OrData ); + /** Reads a bit field in a 64-bit MSR, performs a bitwise AND, and writes the result back to the bit field in the 64-bit MSR. @@ -3546,7 +5808,7 @@ AsmMsrBitFieldOr64 ( If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to write. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3567,6 +5829,7 @@ AsmMsrBitFieldAnd64 ( IN UINT64 AndData ); + /** Reads a bit field in a 64-bit MSR, performs a bitwise AND followed by a bitwise inclusive OR, and writes the result back to the bit field in the @@ -3582,7 +5845,7 @@ AsmMsrBitFieldAnd64 ( If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Index The 32-bit MSR index to write. @param StartBit The ordinal of the least significant bit in the bit field. @@ -3605,6 +5868,7 @@ AsmMsrBitFieldAndThenOr64 ( IN UINT64 OrData ); + /** Reads the current value of the EFLAGS register. @@ -3621,6 +5885,7 @@ AsmReadEflags ( VOID ); + /** Reads the current value of the Control Register 0 (CR0). @@ -3637,6 +5902,7 @@ AsmReadCr0 ( VOID ); + /** Reads the current value of the Control Register 2 (CR2). @@ -3653,6 +5919,7 @@ AsmReadCr2 ( VOID ); + /** Reads the current value of the Control Register 3 (CR3). @@ -3669,6 +5936,7 @@ AsmReadCr3 ( VOID ); + /** Reads the current value of the Control Register 4 (CR4). @@ -3685,6 +5953,7 @@ AsmReadCr4 ( VOID ); + /** Writes a value to Control Register 0 (CR0). @@ -3702,6 +5971,7 @@ AsmWriteCr0 ( UINTN Cr0 ); + /** Writes a value to Control Register 2 (CR2). @@ -3719,6 +5989,7 @@ AsmWriteCr2 ( UINTN Cr2 ); + /** Writes a value to Control Register 3 (CR3). @@ -3736,6 +6007,7 @@ AsmWriteCr3 ( UINTN Cr3 ); + /** Writes a value to Control Register 4 (CR4). @@ -3753,6 +6025,7 @@ AsmWriteCr4 ( UINTN Cr4 ); + /** Reads the current value of Debug Register 0 (DR0). @@ -3769,6 +6042,7 @@ AsmReadDr0 ( VOID ); + /** Reads the current value of Debug Register 1 (DR1). @@ -3785,6 +6059,7 @@ AsmReadDr1 ( VOID ); + /** Reads the current value of Debug Register 2 (DR2). @@ -3801,6 +6076,7 @@ AsmReadDr2 ( VOID ); + /** Reads the current value of Debug Register 3 (DR3). @@ -3817,6 +6093,7 @@ AsmReadDr3 ( VOID ); + /** Reads the current value of Debug Register 4 (DR4). @@ -3833,6 +6110,7 @@ AsmReadDr4 ( VOID ); + /** Reads the current value of Debug Register 5 (DR5). @@ -3849,6 +6127,7 @@ AsmReadDr5 ( VOID ); + /** Reads the current value of Debug Register 6 (DR6). @@ -3865,6 +6144,7 @@ AsmReadDr6 ( VOID ); + /** Reads the current value of Debug Register 7 (DR7). @@ -3881,6 +6161,7 @@ AsmReadDr7 ( VOID ); + /** Writes a value to Debug Register 0 (DR0). @@ -3898,6 +6179,7 @@ AsmWriteDr0 ( UINTN Dr0 ); + /** Writes a value to Debug Register 1 (DR1). @@ -3915,6 +6197,7 @@ AsmWriteDr1 ( UINTN Dr1 ); + /** Writes a value to Debug Register 2 (DR2). @@ -3932,6 +6215,7 @@ AsmWriteDr2 ( UINTN Dr2 ); + /** Writes a value to Debug Register 3 (DR3). @@ -3949,6 +6233,7 @@ AsmWriteDr3 ( UINTN Dr3 ); + /** Writes a value to Debug Register 4 (DR4). @@ -3966,6 +6251,7 @@ AsmWriteDr4 ( UINTN Dr4 ); + /** Writes a value to Debug Register 5 (DR5). @@ -3983,6 +6269,7 @@ AsmWriteDr5 ( UINTN Dr5 ); + /** Writes a value to Debug Register 6 (DR6). @@ -4000,6 +6287,7 @@ AsmWriteDr6 ( UINTN Dr6 ); + /** Writes a value to Debug Register 7 (DR7). @@ -4017,6 +6305,7 @@ AsmWriteDr7 ( UINTN Dr7 ); + /** Reads the current value of Code Segment Register (CS). @@ -4032,6 +6321,7 @@ AsmReadCs ( VOID ); + /** Reads the current value of Data Segment Register (DS). @@ -4047,6 +6337,7 @@ AsmReadDs ( VOID ); + /** Reads the current value of Extra Segment Register (ES). @@ -4062,6 +6353,7 @@ AsmReadEs ( VOID ); + /** Reads the current value of FS Data Segment Register (FS). @@ -4077,6 +6369,7 @@ AsmReadFs ( VOID ); + /** Reads the current value of GS Data Segment Register (GS). @@ -4092,6 +6385,7 @@ AsmReadGs ( VOID ); + /** Reads the current value of Stack Segment Register (SS). @@ -4107,6 +6401,7 @@ AsmReadSs ( VOID ); + /** Reads the current value of Task Register (TR). @@ -4122,6 +6417,7 @@ AsmReadTr ( VOID ); + /** Reads the current Global Descriptor Table Register(GDTR) descriptor. @@ -4139,6 +6435,7 @@ AsmReadGdtr ( OUT IA32_DESCRIPTOR *Gdtr ); + /** Writes the current Global Descriptor Table Register (GDTR) descriptor. @@ -4156,6 +6453,7 @@ AsmWriteGdtr ( IN CONST IA32_DESCRIPTOR *Gdtr ); + /** Reads the current Interrupt Descriptor Table Register(GDTR) descriptor. @@ -4173,6 +6471,7 @@ AsmReadIdtr ( OUT IA32_DESCRIPTOR *Idtr ); + /** Writes the current Interrupt Descriptor Table Register(GDTR) descriptor. @@ -4190,6 +6489,7 @@ AsmWriteIdtr ( IN CONST IA32_DESCRIPTOR *Idtr ); + /** Reads the current Local Descriptor Table Register(LDTR) selector. @@ -4205,6 +6505,7 @@ AsmReadLdtr ( VOID ); + /** Writes the current Local Descriptor Table Register (GDTR) selector. @@ -4220,6 +6521,7 @@ AsmWriteLdtr ( IN UINT16 Ldtr ); + /** Save the current floating point/SSE/SSE2 context to a buffer. @@ -4239,6 +6541,7 @@ AsmFxSave ( OUT IA32_FX_BUFFER *Buffer ); + /** Restores the current floating point/SSE/SSE2 context from a buffer. @@ -4259,6 +6562,7 @@ AsmFxRestore ( IN CONST IA32_FX_BUFFER *Buffer ); + /** Reads the current value of 64-bit MMX Register #0 (MM0). @@ -4274,6 +6578,7 @@ AsmReadMm0 ( VOID ); + /** Reads the current value of 64-bit MMX Register #1 (MM1). @@ -4289,6 +6594,7 @@ AsmReadMm1 ( VOID ); + /** Reads the current value of 64-bit MMX Register #2 (MM2). @@ -4304,6 +6610,7 @@ AsmReadMm2 ( VOID ); + /** Reads the current value of 64-bit MMX Register #3 (MM3). @@ -4319,6 +6626,7 @@ AsmReadMm3 ( VOID ); + /** Reads the current value of 64-bit MMX Register #4 (MM4). @@ -4334,6 +6642,7 @@ AsmReadMm4 ( VOID ); + /** Reads the current value of 64-bit MMX Register #5 (MM5). @@ -4349,6 +6658,7 @@ AsmReadMm5 ( VOID ); + /** Reads the current value of 64-bit MMX Register #6 (MM6). @@ -4364,6 +6674,7 @@ AsmReadMm6 ( VOID ); + /** Reads the current value of 64-bit MMX Register #7 (MM7). @@ -4379,6 +6690,7 @@ AsmReadMm7 ( VOID ); + /** Writes the current value of 64-bit MMX Register #0 (MM0). @@ -4394,6 +6706,7 @@ AsmWriteMm0 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #1 (MM1). @@ -4409,6 +6722,7 @@ AsmWriteMm1 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #2 (MM2). @@ -4424,6 +6738,7 @@ AsmWriteMm2 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #3 (MM3). @@ -4439,6 +6754,7 @@ AsmWriteMm3 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #4 (MM4). @@ -4454,6 +6770,7 @@ AsmWriteMm4 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #5 (MM5). @@ -4469,6 +6786,7 @@ AsmWriteMm5 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #6 (MM6). @@ -4484,6 +6802,7 @@ AsmWriteMm6 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #7 (MM7). @@ -4499,6 +6818,7 @@ AsmWriteMm7 ( IN UINT64 Value ); + /** Reads the current value of Time Stamp Counter (TSC). @@ -4514,6 +6834,7 @@ AsmReadTsc ( VOID ); + /** Reads the current value of a Performance Counter (PMC). @@ -4531,6 +6852,7 @@ AsmReadPmc ( IN UINT32 Index ); + /** Sets up a monitor buffer that is used by AsmMwait(). @@ -4555,6 +6877,7 @@ AsmMonitor ( IN UINTN Edx ); + /** Executes an MWAIT instruction. @@ -4576,6 +6899,7 @@ AsmMwait ( IN UINTN Ecx ); + /** Executes a WBINVD instruction. @@ -4589,6 +6913,7 @@ AsmWbinvd ( VOID ); + /** Executes a INVD instruction. @@ -4602,6 +6927,7 @@ AsmInvd ( VOID ); + /** Flushes a cache line from all the instruction and data caches within the coherency domain of the CPU. @@ -4623,6 +6949,7 @@ AsmFlushCacheLine ( IN VOID *LinearAddress ); + /** Enables the 32-bit paging mode on the CPU. @@ -4669,6 +6996,7 @@ AsmEnablePaging32 ( IN VOID *NewStack ); + /** Disables the 32-bit paging mode on the CPU. @@ -4712,6 +7040,7 @@ AsmDisablePaging32 ( IN VOID *NewStack ); + /** Enables the 64-bit paging mode on the CPU. @@ -4729,7 +7058,7 @@ AsmDisablePaging32 ( If EntryPoint is 0, then ASSERT(). If NewStack is 0, then ASSERT(). - @param Cs The 16-bit selector to load in the CS before EntryPoint + @param CodeSelector The 16-bit selector to load in the CS before EntryPoint is called. The descriptor in the GDT that this selector references must be setup for long mode. @param EntryPoint The 64-bit virtual address of the function to call with @@ -4754,6 +7083,7 @@ AsmEnablePaging64 ( IN UINT64 NewStack ); + /** Disables the 64-bit paging mode on the CPU. @@ -4769,7 +7099,7 @@ AsmEnablePaging64 ( If EntryPoint is 0, then ASSERT(). If NewStack is 0, then ASSERT(). - @param Cs The 16-bit selector to load in the CS before EntryPoint + @param CodeSelector The 16-bit selector to load in the CS before EntryPoint is called. The descriptor in the GDT that this selector references must be setup for 32-bit protected mode. @param EntryPoint The 64-bit virtual address of the function to call with @@ -4794,10 +7124,40 @@ AsmDisablePaging64 ( IN UINT32 NewStack ); + // // 16-bit thunking services // +/** + Retrieves the properties for 16-bit thunk functions. + + Computes the size of the buffer and stack below 1MB required to use the + AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This + buffer size is returned in RealModeBufferSize, and the stack size is returned + in ExtraStackSize. If parameters are passed to the 16-bit real mode code, + then the actual minimum stack size is ExtraStackSize plus the maximum number + of bytes that need to be passed to the 16-bit real mode code. + + If RealModeBufferSize is NULL, then ASSERT(). + If ExtraStackSize is NULL, then ASSERT(). + + @param RealModeBufferSize A pointer to the size of the buffer below 1MB + required to use the 16-bit thunk functions. + @param ExtraStackSize A pointer to the extra size of stack below 1MB + that the 16-bit thunk functions require for + temporary storage in the transition to and from + 16-bit real mode. + +**/ +VOID +EFIAPI +AsmGetThunk16Properties ( + OUT UINT32 *RealModeBufferSize, + OUT UINT32 *ExtraStackSize + ); + + /** Prepares all structures a code required to use AsmThunk16(). @@ -4815,6 +7175,7 @@ AsmPrepareThunk16 ( OUT THUNK_CONTEXT *ThunkContext ); + /** Transfers control to a 16-bit real mode entry point and returns the results. @@ -4835,6 +7196,7 @@ AsmThunk16 ( IN OUT THUNK_CONTEXT *ThunkContext ); + /** Prepares all structures and code for a 16-bit real mode thunk, transfers control to a 16-bit real mode entry point, and returns the results. @@ -4859,3 +7221,6 @@ AsmPrepareAndThunk16 ( ); #endif +#endif + +