X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdePkg%2FInclude%2FLibrary%2FBaseLib.h;h=6961c0a229a70f8cf70a27d52082d2bd9b7c608e;hb=ac644614683362804223844048c5be1a2adfa6b7;hp=ff663c91b7eff435f42063295b37022e5a93d6a8;hpb=878ddf1fc3540a715f63594ed22b6929e881afb4;p=mirror_edk2.git diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h index ff663c91b7..6961c0a229 100644 --- a/MdePkg/Include/Library/BaseLib.h +++ b/MdePkg/Include/Library/BaseLib.h @@ -1,16 +1,14 @@ /** @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 - 2007, 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. **/ @@ -25,7 +23,7 @@ // // SPIN_LOCK // -typedef UINTN SPIN_LOCK; +typedef volatile UINTN SPIN_LOCK; #if defined (MDE_CPU_IA32) // @@ -40,72 +38,56 @@ 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() // 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() @@ -123,6 +105,8 @@ 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() @@ -135,6 +119,8 @@ typedef struct { UINT64 IP; } BASE_LIBRARY_JUMP_BUFFER; +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 + #else #error Unknown Processor Type #endif @@ -152,10 +138,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 +159,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 +173,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 +197,7 @@ StrnCpy ( IN UINTN Length ); + /** Returns the length of a Null-terminated Unicode string. @@ -211,8 +205,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 +221,7 @@ StrLen ( IN CONST CHAR16 *String ); + /** Returns the size of a Null-terminated Unicode string in bytes, including the Null terminator. @@ -233,8 +230,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 +246,7 @@ StrSize ( IN CONST CHAR16 *String ); + /** Compares two Null-terminated Unicode strings, and returns the difference between the first mismatched Unicode characters. @@ -258,11 +258,15 @@ 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. @@ -278,6 +282,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,12 +294,16 @@ 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. @@ -312,6 +321,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 +333,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 +361,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 +376,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 +407,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. + @retval !NULL 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 UINTN + +**/ +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 UINT64 + +**/ +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 UINTN + +**/ +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 UINT64 + +**/ +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 binary Buffer Buf 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. + + @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 +783,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 +799,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 +816,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 +834,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 +858,7 @@ AsciiStrLen ( IN CONST CHAR8 *String ); + /** Returns the size of a Null-terminated ASCII string in bytes, including the Null terminator. @@ -476,7 +868,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 +882,7 @@ AsciiStrSize ( IN CONST CHAR8 *String ); + /** Compares two Null-terminated ASCII strings, and returns the difference between the first mismatched ASCII characters. @@ -502,9 +896,11 @@ 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. @@ -520,6 +916,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,9 +931,11 @@ 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. @@ -554,6 +953,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,16 +965,19 @@ 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. - + @param Length Maximum number of ASCII characters for compare. + @retval 0 FirstString is identical to SecondString. @retval !=0 FirstString is not identical to SecondString. @@ -587,6 +990,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 +1003,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 +1021,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 +1039,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,112 +1068,372 @@ 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. + @retval !NULL 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 UINTN **/ -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 UINT64 **/ -LIST_ENTRY * +UINT64 EFIAPI -InsertHeadList ( - IN LIST_ENTRY *ListHead, - IN LIST_ENTRY *Entry +AsciiStrDecimalToUint64 ( + IN CONST CHAR8 *String ); + /** - Adds a node to the end of a doubly linked list, and returns the pointer to - the head node of the doubly linked list. + Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN. - Adds the node Entry to the end of the doubly linked list denoted by ListHead, - and returns ListHead. + 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: - 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][zeros][x][hexadecimal 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 added at the end of the - doubly linked list. + 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. - @return ListHead + 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 UINTN **/ -LIST_ENTRY * +UINTN EFIAPI -InsertTailList ( - IN LIST_ENTRY *ListHead, - IN LIST_ENTRY *Entry +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 UINT64 + +**/ +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 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 LIST_ENTRY *ListHead, + IN 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. + + Adds the node Entry to the end 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 added at the end of the + doubly linked list. + + @return ListHead + +**/ +LIST_ENTRY * +EFIAPI +InsertTailList ( + IN LIST_ENTRY *ListHead, + IN LIST_ENTRY *Entry + ); + + /** Retrieves the first node of a doubly linked list. @@ -774,8 +1443,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 +1459,7 @@ GetFirstNode ( IN CONST LIST_ENTRY *List ); + /** Retrieves the next node of a doubly linked list. @@ -817,6 +1488,7 @@ GetNextNode ( IN CONST LIST_ENTRY *Node ); + /** Checks to see if a doubly linked list is empty or not. @@ -825,8 +1497,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,6 +1513,7 @@ IsListEmpty ( IN CONST LIST_ENTRY *ListHead ); + /** Determines if a node in a doubly linked list is null. @@ -850,12 +1524,13 @@ IsListEmpty ( 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,9 +1588,10 @@ 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. @@ -925,6 +1604,7 @@ SwapListEntries ( IN LIST_ENTRY *SecondEntry ); + /** Removes a node from a doubly linked list, and returns the node that follows the removed node. @@ -937,8 +1617,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 +1658,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 +1681,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 +1704,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 +1728,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 +1752,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 +1776,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 +1800,7 @@ RRotU64 ( IN UINTN Count ); + /** Returns the bit position of the lowest bit set in a 32-bit value. @@ -1132,6 +1820,7 @@ LowBitSet32 ( IN UINT32 Operand ); + /** Returns the bit position of the lowest bit set in a 64-bit value. @@ -1151,6 +1840,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 +1861,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 +1882,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 +1902,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 +1922,7 @@ GetPowerOfTwo64 ( IN UINT64 Operand ); + /** Switches the endianess of a 16-bit integer. @@ -1236,7 +1930,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 +1941,7 @@ SwapBytes16 ( IN UINT16 Value ); + /** Switches the endianess of a 32-bit integer. @@ -1254,7 +1949,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 +1960,7 @@ SwapBytes32 ( IN UINT32 Value ); + /** Switches the endianess of a 64-bit integer. @@ -1272,7 +1968,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 +1979,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 +2003,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 +2027,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 +2051,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 +2075,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 +2099,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 +2127,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 +2155,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 +2183,7 @@ DivS64x64Remainder ( OUT INT64 *Remainder OPTIONAL ); + /** Reads a 16-bit value from memory that may be unaligned. @@ -1487,7 +2192,7 @@ DivS64x64Remainder ( If the Buffer is NULL, then ASSERT(). - @param Buffer Pointer to a 16-bit value that may be unaligned. + @param Uint16 Pointer to a 16-bit value that may be unaligned. @return *Uint16 @@ -1498,6 +2203,7 @@ ReadUnaligned16 ( IN CONST UINT16 *Uint16 ); + /** Writes a 16-bit value to memory that may be unaligned. @@ -1507,7 +2213,7 @@ ReadUnaligned16 ( If the Buffer is NULL, then ASSERT(). - @param Buffer Pointer to a 16-bit value that may be unaligned. + @param Uint16 Pointer to a 16-bit value that may be unaligned. @param Value 16-bit value to write to Buffer. @return Value @@ -1520,6 +2226,7 @@ WriteUnaligned16 ( IN UINT16 Value ); + /** Reads a 24-bit value from memory that may be unaligned. @@ -1539,6 +2246,7 @@ ReadUnaligned24 ( IN CONST UINT32 *Buffer ); + /** Writes a 24-bit value to memory that may be unaligned. @@ -1561,6 +2269,7 @@ WriteUnaligned24 ( IN UINT32 Value ); + /** Reads a 32-bit value from memory that may be unaligned. @@ -1569,7 +2278,7 @@ WriteUnaligned24 ( If the Buffer is NULL, then ASSERT(). - @param Buffer Pointer to a 32-bit value that may be unaligned. + @param Uint32 Pointer to a 32-bit value that may be unaligned. @return *Uint32 @@ -1580,6 +2289,7 @@ ReadUnaligned32 ( IN CONST UINT32 *Uint32 ); + /** Writes a 32-bit value to memory that may be unaligned. @@ -1589,7 +2299,7 @@ ReadUnaligned32 ( If the Buffer is NULL, then ASSERT(). - @param Buffer Pointer to a 32-bit value that may be unaligned. + @param Uint32 Pointer to a 32-bit value that may be unaligned. @param Value 32-bit value to write to Buffer. @return Value @@ -1602,6 +2312,7 @@ WriteUnaligned32 ( IN UINT32 Value ); + /** Reads a 64-bit value from memory that may be unaligned. @@ -1610,7 +2321,7 @@ WriteUnaligned32 ( If the Buffer is NULL, then ASSERT(). - @param Buffer Pointer to a 64-bit value that may be unaligned. + @param Uint64 Pointer to a 64-bit value that may be unaligned. @return *Uint64 @@ -1621,6 +2332,7 @@ ReadUnaligned64 ( IN CONST UINT64 *Uint64 ); + /** Writes a 64-bit value to memory that may be unaligned. @@ -1630,7 +2342,7 @@ ReadUnaligned64 ( If the Buffer is NULL, then ASSERT(). - @param Buffer Pointer to a 64-bit value that may be unaligned. + @param Uint64 Pointer to a 64-bit value that may be unaligned. @param Value 64-bit value to write to Buffer. @return Value @@ -1643,6 +2355,7 @@ WriteUnaligned64 ( IN UINT64 Value ); + // // Bit Field Functions // @@ -1655,7 +2368,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 +2387,7 @@ BitFieldRead8 ( IN UINTN EndBit ); + /** Writes a bit field to an 8-bit value, and returns the result. @@ -1684,7 +2398,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 +2419,7 @@ BitFieldWrite8 ( IN UINT8 Value ); + /** Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the result. @@ -1716,7 +2431,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 +2452,7 @@ BitFieldOr8 ( IN UINT8 OrData ); + /** Reads a bit field from an 8-bit value, performs a bitwise AND, and returns the result. @@ -1748,7 +2464,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 +2485,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 +2498,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 +2521,7 @@ BitFieldAndThenOr8 ( IN UINT8 OrData ); + /** Returns a bit field from a 16-bit value. @@ -1812,7 +2530,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 +2549,7 @@ BitFieldRead16 ( IN UINTN EndBit ); + /** Writes a bit field to a 16-bit value, and returns the result. @@ -1841,7 +2560,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 +2581,7 @@ BitFieldWrite16 ( IN UINT16 Value ); + /** Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the result. @@ -1873,7 +2593,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 +2614,7 @@ BitFieldOr16 ( IN UINT16 OrData ); + /** Reads a bit field from a 16-bit value, performs a bitwise AND, and returns the result. @@ -1905,7 +2626,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 +2647,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 +2660,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 +2683,7 @@ BitFieldAndThenOr16 ( IN UINT16 OrData ); + /** Returns a bit field from a 32-bit value. @@ -1969,7 +2692,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 +2711,7 @@ BitFieldRead32 ( IN UINTN EndBit ); + /** Writes a bit field to a 32-bit value, and returns the result. @@ -1998,7 +2722,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 +2743,7 @@ BitFieldWrite32 ( IN UINT32 Value ); + /** Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the result. @@ -2030,7 +2755,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 +2776,7 @@ BitFieldOr32 ( IN UINT32 OrData ); + /** Reads a bit field from a 32-bit value, performs a bitwise AND, and returns the result. @@ -2062,7 +2788,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 +2809,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 +2822,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 +2845,7 @@ BitFieldAndThenOr32 ( IN UINT32 OrData ); + /** Returns a bit field from a 64-bit value. @@ -2126,7 +2854,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 +2873,7 @@ BitFieldRead64 ( IN UINTN EndBit ); + /** Writes a bit field to a 64-bit value, and returns the result. @@ -2155,7 +2884,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 +2905,7 @@ BitFieldWrite64 ( IN UINT64 Value ); + /** Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the result. @@ -2187,7 +2917,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 +2938,7 @@ BitFieldOr64 ( IN UINT64 OrData ); + /** Reads a bit field from a 64-bit value, performs a bitwise AND, and returns the result. @@ -2219,7 +2950,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 +2971,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 +2984,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 +3007,7 @@ BitFieldAndThenOr64 ( IN UINT64 OrData ); + // // Base Library Synchronization Functions // @@ -2301,6 +3034,7 @@ GetSpinLockProperties ( VOID ); + /** Initializes a spin lock to the released state and returns the spin lock. @@ -2323,6 +3057,7 @@ InitializeSpinLock ( IN SPIN_LOCK *SpinLock ); + /** Waits until a spin lock can be placed in the acquired state. @@ -2349,6 +3084,7 @@ AcquireSpinLock ( IN SPIN_LOCK *SpinLock ); + /** Attempts to place a spin lock in the acquired state. @@ -2372,6 +3108,7 @@ AcquireSpinLockOrFail ( IN SPIN_LOCK *SpinLock ); + /** Releases a spin lock. @@ -2392,6 +3129,7 @@ ReleaseSpinLock ( IN SPIN_LOCK *SpinLock ); + /** Performs an atomic increment of an 32-bit unsigned integer. @@ -2413,6 +3151,7 @@ InterlockedIncrement ( IN UINT32 *Value ); + /** Performs an atomic decrement of an 32-bit unsigned integer. @@ -2434,9 +3173,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 +3196,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 +3223,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. @@ -2492,34 +3249,259 @@ InterlockedCompareExchange64 ( 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 +3511,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. @@ -2537,162 +3520,1378 @@ MemoryFence ( **/ UINTN EFIAPI -SetJump ( - OUT BASE_LIBRARY_JUMP_BUFFER *JumpBuffer +SetJump ( + OUT BASE_LIBRARY_JUMP_BUFFER *JumpBuffer + ); + + +/** + Restores the CPU context that was saved with SetJump(). + + Restores the CPU context from the buffer specified by JumpBuffer. This + function never returns to the caller. Instead is resumes execution based on + 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. + +**/ +VOID +EFIAPI +LongJump ( + IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer, + IN UINTN Value + ); + + +/** + Enables CPU interrupts. + + Enables CPU interrupts. + +**/ +VOID +EFIAPI +EnableInterrupts ( + VOID + ); + + +/** + Disables CPU interrupts. + + Disables CPU interrupts. + +**/ +VOID +EFIAPI +DisableInterrupts ( + VOID + ); + + +/** + Disables CPU interrupts and returns the interrupt state prior to the disable + operation. + + 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. + + Enables CPU interrupts for the smallest window required to capture any + pending interrupts. + +**/ +VOID +EFIAPI +EnableDisableInterrupts ( + VOID + ); + + +/** + Retrieves the current CPU interrupt state. + + 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. + +**/ +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 ); + /** - Restores the CPU context that was saved with SetJump(). + Reads the current value of Performance Monitor Data Register (PMD). - Restores the CPU context from the buffer specified by JumpBuffer. This - function never returns to the caller. Instead is resumes execution based on - the state of JumpBuffer. + 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. - If JumpBuffer is NULL, then ASSERT(). - If Value is 0, then ASSERT(). + @param Index The 8-bit Performance Monitor Data Register index to read. - @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. + @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). + + Reads and returns the current value of SP. + This function is only available on IPF. - 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. + @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. - Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU. + @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. + + @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,45 +4910,51 @@ 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. - Generates a breakpoint on the CPU. The breakpoint must be implemented such - that code can resume normal execution after the breakpoint. +// +// Bugbug: This call should be removed after +// the PalCall Instance issue has been fixed. +// +/** + 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 Arg1 The second argument of a PAL call. + @param Arg1 The third argument of a PAL call. + @param Arg1 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 ); + +#elif defined (MDE_CPU_IA32) || defined (MDE_CPU_X64) // // IA32 and X64 Specific Functions // @@ -2866,11 +5071,14 @@ typedef union { // // Byte packed structure for an IDTR, GDTR, LDTR descriptor +/// @bug 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 @@ -2969,15 +5177,16 @@ typedef union { // 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 +5222,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 +5287,7 @@ AsmReadMsr32 ( IN UINT32 Index ); + /** Zero-extend a 32-bit value and writes it to a Machine Specific Register(MSR). @@ -3056,6 +5311,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 +5338,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 +5365,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 +5396,7 @@ AsmMsrAndThenOr32 ( IN UINT32 OrData ); + /** Reads a bit field of an MSR. @@ -3149,7 +5408,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 +5427,7 @@ AsmMsrBitFieldRead32 ( IN UINTN EndBit ); + /** Writes a bit field to an MSR. @@ -3181,7 +5441,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 +5462,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 +5477,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 +5498,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 +5513,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 +5534,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 +5551,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 +5574,7 @@ AsmMsrBitFieldAndThenOr32 ( IN UINT32 OrData ); + /** Returns a 64-bit Machine Specific Register(MSR). @@ -3331,6 +5595,7 @@ AsmReadMsr64 ( IN UINT32 Index ); + /** Writes a 64-bit value to a Machine Specific Register(MSR), and returns the value. @@ -3355,6 +5620,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 +5646,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 +5672,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 +5702,7 @@ AsmMsrAndThenOr64 ( IN UINT64 OrData ); + /** Reads a bit field of an MSR. @@ -3445,7 +5714,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 +5733,7 @@ AsmMsrBitFieldRead64 ( IN UINTN EndBit ); + /** Writes a bit field to an MSR. @@ -3476,7 +5746,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 +5767,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 +5782,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 +5803,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 +5818,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 +5839,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 +5855,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 +5878,7 @@ AsmMsrBitFieldAndThenOr64 ( IN UINT64 OrData ); + /** Reads the current value of the EFLAGS register. @@ -3621,6 +5895,7 @@ AsmReadEflags ( VOID ); + /** Reads the current value of the Control Register 0 (CR0). @@ -3637,6 +5912,7 @@ AsmReadCr0 ( VOID ); + /** Reads the current value of the Control Register 2 (CR2). @@ -3653,6 +5929,7 @@ AsmReadCr2 ( VOID ); + /** Reads the current value of the Control Register 3 (CR3). @@ -3669,6 +5946,7 @@ AsmReadCr3 ( VOID ); + /** Reads the current value of the Control Register 4 (CR4). @@ -3685,6 +5963,7 @@ AsmReadCr4 ( VOID ); + /** Writes a value to Control Register 0 (CR0). @@ -3702,6 +5981,7 @@ AsmWriteCr0 ( UINTN Cr0 ); + /** Writes a value to Control Register 2 (CR2). @@ -3719,6 +5999,7 @@ AsmWriteCr2 ( UINTN Cr2 ); + /** Writes a value to Control Register 3 (CR3). @@ -3736,6 +6017,7 @@ AsmWriteCr3 ( UINTN Cr3 ); + /** Writes a value to Control Register 4 (CR4). @@ -3753,6 +6035,7 @@ AsmWriteCr4 ( UINTN Cr4 ); + /** Reads the current value of Debug Register 0 (DR0). @@ -3769,6 +6052,7 @@ AsmReadDr0 ( VOID ); + /** Reads the current value of Debug Register 1 (DR1). @@ -3785,6 +6069,7 @@ AsmReadDr1 ( VOID ); + /** Reads the current value of Debug Register 2 (DR2). @@ -3801,6 +6086,7 @@ AsmReadDr2 ( VOID ); + /** Reads the current value of Debug Register 3 (DR3). @@ -3817,6 +6103,7 @@ AsmReadDr3 ( VOID ); + /** Reads the current value of Debug Register 4 (DR4). @@ -3833,6 +6120,7 @@ AsmReadDr4 ( VOID ); + /** Reads the current value of Debug Register 5 (DR5). @@ -3849,6 +6137,7 @@ AsmReadDr5 ( VOID ); + /** Reads the current value of Debug Register 6 (DR6). @@ -3865,6 +6154,7 @@ AsmReadDr6 ( VOID ); + /** Reads the current value of Debug Register 7 (DR7). @@ -3881,6 +6171,7 @@ AsmReadDr7 ( VOID ); + /** Writes a value to Debug Register 0 (DR0). @@ -3898,6 +6189,7 @@ AsmWriteDr0 ( UINTN Dr0 ); + /** Writes a value to Debug Register 1 (DR1). @@ -3915,6 +6207,7 @@ AsmWriteDr1 ( UINTN Dr1 ); + /** Writes a value to Debug Register 2 (DR2). @@ -3932,6 +6225,7 @@ AsmWriteDr2 ( UINTN Dr2 ); + /** Writes a value to Debug Register 3 (DR3). @@ -3949,6 +6243,7 @@ AsmWriteDr3 ( UINTN Dr3 ); + /** Writes a value to Debug Register 4 (DR4). @@ -3966,6 +6261,7 @@ AsmWriteDr4 ( UINTN Dr4 ); + /** Writes a value to Debug Register 5 (DR5). @@ -3983,6 +6279,7 @@ AsmWriteDr5 ( UINTN Dr5 ); + /** Writes a value to Debug Register 6 (DR6). @@ -4000,6 +6297,7 @@ AsmWriteDr6 ( UINTN Dr6 ); + /** Writes a value to Debug Register 7 (DR7). @@ -4017,6 +6315,7 @@ AsmWriteDr7 ( UINTN Dr7 ); + /** Reads the current value of Code Segment Register (CS). @@ -4032,6 +6331,7 @@ AsmReadCs ( VOID ); + /** Reads the current value of Data Segment Register (DS). @@ -4047,6 +6347,7 @@ AsmReadDs ( VOID ); + /** Reads the current value of Extra Segment Register (ES). @@ -4062,6 +6363,7 @@ AsmReadEs ( VOID ); + /** Reads the current value of FS Data Segment Register (FS). @@ -4077,6 +6379,7 @@ AsmReadFs ( VOID ); + /** Reads the current value of GS Data Segment Register (GS). @@ -4092,6 +6395,7 @@ AsmReadGs ( VOID ); + /** Reads the current value of Stack Segment Register (SS). @@ -4107,6 +6411,7 @@ AsmReadSs ( VOID ); + /** Reads the current value of Task Register (TR). @@ -4122,6 +6427,7 @@ AsmReadTr ( VOID ); + /** Reads the current Global Descriptor Table Register(GDTR) descriptor. @@ -4139,6 +6445,7 @@ AsmReadGdtr ( OUT IA32_DESCRIPTOR *Gdtr ); + /** Writes the current Global Descriptor Table Register (GDTR) descriptor. @@ -4156,6 +6463,7 @@ AsmWriteGdtr ( IN CONST IA32_DESCRIPTOR *Gdtr ); + /** Reads the current Interrupt Descriptor Table Register(GDTR) descriptor. @@ -4173,6 +6481,7 @@ AsmReadIdtr ( OUT IA32_DESCRIPTOR *Idtr ); + /** Writes the current Interrupt Descriptor Table Register(GDTR) descriptor. @@ -4190,6 +6499,7 @@ AsmWriteIdtr ( IN CONST IA32_DESCRIPTOR *Idtr ); + /** Reads the current Local Descriptor Table Register(LDTR) selector. @@ -4205,6 +6515,7 @@ AsmReadLdtr ( VOID ); + /** Writes the current Local Descriptor Table Register (GDTR) selector. @@ -4220,6 +6531,7 @@ AsmWriteLdtr ( IN UINT16 Ldtr ); + /** Save the current floating point/SSE/SSE2 context to a buffer. @@ -4239,6 +6551,7 @@ AsmFxSave ( OUT IA32_FX_BUFFER *Buffer ); + /** Restores the current floating point/SSE/SSE2 context from a buffer. @@ -4259,6 +6572,7 @@ AsmFxRestore ( IN CONST IA32_FX_BUFFER *Buffer ); + /** Reads the current value of 64-bit MMX Register #0 (MM0). @@ -4274,6 +6588,7 @@ AsmReadMm0 ( VOID ); + /** Reads the current value of 64-bit MMX Register #1 (MM1). @@ -4289,6 +6604,7 @@ AsmReadMm1 ( VOID ); + /** Reads the current value of 64-bit MMX Register #2 (MM2). @@ -4304,6 +6620,7 @@ AsmReadMm2 ( VOID ); + /** Reads the current value of 64-bit MMX Register #3 (MM3). @@ -4319,6 +6636,7 @@ AsmReadMm3 ( VOID ); + /** Reads the current value of 64-bit MMX Register #4 (MM4). @@ -4334,6 +6652,7 @@ AsmReadMm4 ( VOID ); + /** Reads the current value of 64-bit MMX Register #5 (MM5). @@ -4349,6 +6668,7 @@ AsmReadMm5 ( VOID ); + /** Reads the current value of 64-bit MMX Register #6 (MM6). @@ -4364,6 +6684,7 @@ AsmReadMm6 ( VOID ); + /** Reads the current value of 64-bit MMX Register #7 (MM7). @@ -4379,6 +6700,7 @@ AsmReadMm7 ( VOID ); + /** Writes the current value of 64-bit MMX Register #0 (MM0). @@ -4394,6 +6716,7 @@ AsmWriteMm0 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #1 (MM1). @@ -4409,6 +6732,7 @@ AsmWriteMm1 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #2 (MM2). @@ -4424,6 +6748,7 @@ AsmWriteMm2 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #3 (MM3). @@ -4439,6 +6764,7 @@ AsmWriteMm3 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #4 (MM4). @@ -4454,6 +6780,7 @@ AsmWriteMm4 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #5 (MM5). @@ -4469,6 +6796,7 @@ AsmWriteMm5 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #6 (MM6). @@ -4484,6 +6812,7 @@ AsmWriteMm6 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #7 (MM7). @@ -4499,6 +6828,7 @@ AsmWriteMm7 ( IN UINT64 Value ); + /** Reads the current value of Time Stamp Counter (TSC). @@ -4514,6 +6844,7 @@ AsmReadTsc ( VOID ); + /** Reads the current value of a Performance Counter (PMC). @@ -4531,6 +6862,7 @@ AsmReadPmc ( IN UINT32 Index ); + /** Sets up a monitor buffer that is used by AsmMwait(). @@ -4555,6 +6887,7 @@ AsmMonitor ( IN UINTN Edx ); + /** Executes an MWAIT instruction. @@ -4576,6 +6909,7 @@ AsmMwait ( IN UINTN Ecx ); + /** Executes a WBINVD instruction. @@ -4589,6 +6923,7 @@ AsmWbinvd ( VOID ); + /** Executes a INVD instruction. @@ -4602,6 +6937,7 @@ AsmInvd ( VOID ); + /** Flushes a cache line from all the instruction and data caches within the coherency domain of the CPU. @@ -4623,6 +6959,7 @@ AsmFlushCacheLine ( IN VOID *LinearAddress ); + /** Enables the 32-bit paging mode on the CPU. @@ -4669,6 +7006,7 @@ AsmEnablePaging32 ( IN VOID *NewStack ); + /** Disables the 32-bit paging mode on the CPU. @@ -4712,6 +7050,7 @@ AsmDisablePaging32 ( IN VOID *NewStack ); + /** Enables the 64-bit paging mode on the CPU. @@ -4754,6 +7093,7 @@ AsmEnablePaging64 ( IN UINT64 NewStack ); + /** Disables the 64-bit paging mode on the CPU. @@ -4794,10 +7134,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 +7185,7 @@ AsmPrepareThunk16 ( OUT THUNK_CONTEXT *ThunkContext ); + /** Transfers control to a 16-bit real mode entry point and returns the results. @@ -4835,6 +7206,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. @@ -4858,4 +7230,10 @@ AsmPrepareAndThunk16 ( IN OUT THUNK_CONTEXT *ThunkContext ); +#else + #endif + +#endif + +