X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdePkg%2FInclude%2FLibrary%2FBaseLib.h;h=0c16c4813058fb11e688e115ea0a97c27aa20c0f;hb=fc30687f39436f5b5e00396a5161b30b70db8277;hp=a63bc1bc3e893828505a1e841292dc413cbe0cde;hpb=dee4740abe5925ff25e452c1a705a36f8fb3b4b9;p=mirror_edk2.git diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h index a63bc1bc3e..0c16c48130 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. **/ @@ -22,15 +20,15 @@ // These include SPIN_LOCK and BASE_LIBRARY_JUMP_BUFFER // -// -// SPIN_LOCK -// -typedef UINTN SPIN_LOCK; +/// +/// SPIN_LOCK +/// +typedef volatile UINTN SPIN_LOCK; #if defined (MDE_CPU_IA32) -// -// IA32 context buffer used by SetJump() and LongJump() -// +/// +/// IA32 context buffer used by SetJump() and LongJump() +/// typedef struct { UINT32 Ebx; UINT32 Esi; @@ -40,10 +38,13 @@ typedef struct { UINT32 Eip; } BASE_LIBRARY_JUMP_BUFFER; +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4 + #elif defined (MDE_CPU_IPF) -// -// IPF context buffer used by SetJump() and LongJump() -// + +/// +/// IPF context buffer used by SetJump() and LongJump() +/// typedef struct { UINT64 F2[2]; UINT64 F3[2]; @@ -85,10 +86,12 @@ typedef struct { UINT64 FPSR; } BASE_LIBRARY_JUMP_BUFFER; +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10 + #elif defined (MDE_CPU_X64) -// -// X64 context buffer used by SetJump() and LongJump() -// +/// +/// X64 context buffer used by SetJump() and LongJump() +/// typedef struct { UINT64 Rbx; UINT64 Rsp; @@ -102,10 +105,12 @@ typedef struct { UINT64 Rip; } BASE_LIBRARY_JUMP_BUFFER; +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 + #elif defined (MDE_CPU_EBC) -// -// EBC context buffer used by SetJump() and LongJump() -// +/// +/// EBC context buffer used by SetJump() and LongJump() +/// typedef struct { UINT64 R0; UINT64 R1; @@ -114,6 +119,8 @@ typedef struct { UINT64 IP; } BASE_LIBRARY_JUMP_BUFFER; +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 + #else #error Unknown Processor Type #endif @@ -131,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. @@ -149,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 @@ -162,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. @@ -183,6 +197,7 @@ StrnCpy ( IN UINTN Length ); + /** Returns the length of a Null-terminated Unicode string. @@ -190,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. @@ -204,6 +221,7 @@ StrLen ( IN CONST CHAR16 *String ); + /** Returns the size of a Null-terminated Unicode string in bytes, including the Null terminator. @@ -212,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. @@ -226,6 +246,7 @@ StrSize ( IN CONST CHAR16 *String ); + /** Compares two Null-terminated Unicode strings, and returns the difference between the first mismatched Unicode characters. @@ -237,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. @@ -257,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. @@ -268,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. @@ -291,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. @@ -302,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. @@ -325,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 @@ -339,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. @@ -365,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 Value translated from String. + +**/ +UINTN +EFIAPI +StrDecimalToUintn ( + IN CONST CHAR16 *String + ); + +/** + Convert a Null-terminated Unicode decimal string to a value of + type UINT64. + + This function returns a value of type UINT64 by interpreting the contents + of the Unicode string specified by String as a decimal number. The format + of the input Unicode string String is: + + [spaces] [decimal digits]. + + The valid decimal digit character is in the range [0-9]. The + function will ignore the pad space, which includes spaces or + tab characters, before [decimal digits]. The running zero in the + beginning of [decimal digits] will be ignored. Then, the function + stops at the first character that is a not a valid decimal character + or a Null-terminator, whichever one comes first. + + If String is NULL, then ASSERT(). + If String is not aligned in a 16-bit boundary, then ASSERT(). + If String has only pad spaces, then 0 is returned. + If String has no pad spaces or valid decimal digits, + then 0 is returned. + If the number represented by String overflows according + to the range defined by UINT64, then ASSERT(). + + If PcdMaximumUnicodeStringLength is not zero, and String contains + more than PcdMaximumUnicodeStringLength Unicode characters not including + the Null-terminator, then ASSERT(). + + @param String Pointer to a Null-terminated Unicode string. + + @retval Value translated from String. + +**/ +UINT64 +EFIAPI +StrDecimalToUint64 ( + IN CONST CHAR16 *String + ); + + +/** + Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN. + + This function returns a value of type UINTN by interpreting the contents + of the Unicode string specified by String as a hexadecimal number. + The format of the input Unicode string String is: + + [spaces][zeros][x][hexadecimal digits]. + + The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. + The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. + If "x" appears in the input string, it must be prefixed with at least one 0. + The function will ignore the pad space, which includes spaces or tab characters, + before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or + [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the + first valid hexadecimal digit. Then, the function stops at the first character that is + a not a valid hexadecimal character or NULL, whichever one comes first. + + If String is NULL, then ASSERT(). + If String is not aligned in a 16-bit boundary, then ASSERT(). + If String has only pad spaces, then zero is returned. + If String has no leading pad spaces, leading zeros or valid hexadecimal digits, + then zero is returned. + If the number represented by String overflows according to the range defined by + UINTN, then ASSERT(). + + If PcdMaximumUnicodeStringLength is not zero, and String contains more than + PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, + then ASSERT(). + + @param String Pointer to a Null-terminated Unicode string. + + @retval Value translated from String. + +**/ +UINTN +EFIAPI +StrHexToUintn ( + IN CONST CHAR16 *String + ); + + +/** + Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64. + + This function returns a value of type UINT64 by interpreting the contents + of the Unicode string specified by String as a hexadecimal number. + The format of the input Unicode string String is + + [spaces][zeros][x][hexadecimal digits]. + + The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F]. + The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. + If "x" appears in the input string, it must be prefixed with at least one 0. + The function will ignore the pad space, which includes spaces or tab characters, + before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or + [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the + first valid hexadecimal digit. Then, the function stops at the first character that is + a not a valid hexadecimal character or NULL, whichever one comes first. + + If String is NULL, then ASSERT(). + If String is not aligned in a 16-bit boundary, then ASSERT(). + If String has only pad spaces, then zero is returned. + If String has no leading pad spaces, leading zeros or valid hexadecimal digits, + then zero is returned. + If the number represented by String overflows according to the range defined by + UINT64, then ASSERT(). + + If PcdMaximumUnicodeStringLength is not zero, and String contains more than + PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator, + then ASSERT(). + + @param String Pointer to a Null-terminated Unicode string. + + @retval Value translated from String. + +**/ +UINT64 +EFIAPI +StrHexToUint64 ( + IN CONST CHAR16 *String + ); + +/** + Convert a nibble in the low 4 bits of a byte to a Unicode hexadecimal character. + + This function converts a nibble in the low 4 bits of a byte to a Unicode hexadecimal + character For example, the nibble 0x01 and 0x0A will converted to L'1' and L'A' + respectively. + + The upper nibble in the input byte will be masked off. + + @param Nibble The nibble which is in the low 4 bits of the input byte. + + @retval CHAR16 The Unicode hexadecimal character. + +**/ +CHAR16 +EFIAPI +NibbleToHexChar ( + IN UINT8 Nibble + ) +; + +/** + Convert binary buffer to a Unicode String in a specified sequence. + + This function converts bytes in the 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. @@ -377,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. @@ -392,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 @@ -408,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. @@ -425,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. @@ -446,6 +858,7 @@ AsciiStrLen ( IN CONST CHAR8 *String ); + /** Returns the size of a Null-terminated ASCII string in bytes, including the Null terminator. @@ -455,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. @@ -468,6 +882,7 @@ AsciiStrSize ( IN CONST CHAR8 *String ); + /** Compares two Null-terminated ASCII strings, and returns the difference between the first mismatched ASCII characters. @@ -481,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. @@ -499,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. @@ -513,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. @@ -533,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. @@ -544,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. @@ -566,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. @@ -578,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(). @@ -594,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 @@ -611,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. @@ -638,124 +1068,343 @@ AsciiStrnCat ( IN UINTN Length ); + /** - Converts an 8-bit value to an 8-bit BCD value. + Returns the first occurance of a Null-terminated ASCII sub-string + in a Null-terminated ASCII string. - Converts the 8-bit value specified by Value to BCD. The BCD value is - returned. + 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. - If Value >= 100, then ASSERT(). + If String is NULL, then ASSERT(). + If SearchString is NULL, then ASSERT(). - @param Value The 8-bit value to convert to BCD. Range 0..99. + If PcdMaximumAsciiStringLength is not zero, and SearchString or + String contains more than PcdMaximumAsciiStringLength Unicode characters + not including the Null-terminator, then ASSERT(). - @return The BCD value + @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. **/ -UINT8 +CHAR8 * EFIAPI -DecimalToBcd8 ( - IN UINT8 Value +AsciiStrStr ( + IN CONST CHAR8 *String, + IN CONST CHAR8 *SearchString ); + /** - Converts an 8-bit BCD value to an 8-bit value. + Convert a Null-terminated ASCII decimal string to a value of type + UINTN. - Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit - value is returned. + 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 Value >= 0xA0, then ASSERT(). - If (Value & 0x0F) >= 0x0A, then ASSERT(). + [spaces] [decimal digits]. - @param Value The 8-bit BCD value to convert to an 8-bit value. + 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 The 8-bit value is returned. + If String has only pad spaces, then 0 is returned. + If String has no pad spaces or valid decimal digits, then 0 is returned. + If the number represented by String overflows according to the range defined by + UINTN, then ASSERT(). + If String is NULL, then ASSERT(). + If PcdMaximumAsciiStringLength is not zero, and String contains more than + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). + + @param String Pointer to a Null-terminated ASCII string. + + @retval Value translated from String. **/ -UINT8 +UINTN EFIAPI -BcdToDecimal8 ( - IN UINT8 Value +AsciiStrDecimalToUintn ( + IN CONST CHAR8 *String ); -// -// LIST_ENTRY definition -// -typedef struct _LIST_ENTRY LIST_ENTRY; -struct _LIST_ENTRY { - LIST_ENTRY *ForwardLink; - LIST_ENTRY *BackLink; -}; +/** + Convert a Null-terminated ASCII decimal string to a value of type + UINT64. -// -// Linked List Functions and Macros -// + 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: -/** - Initializes the head node of a doubly linked list that is declared as a - global variable in a module. + [spaces] [decimal digits]. - 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. + 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. - @param ListHead The head note of a list to initiailize. + If String has only pad spaces, then 0 is returned. + If String has no pad spaces or valid decimal digits, then 0 is returned. + If the number represented by String overflows according to the range defined by + UINT64, then ASSERT(). + If String is NULL, then ASSERT(). + If PcdMaximumAsciiStringLength is not zero, and String contains more than + PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator, + then ASSERT(). + + @param String Pointer to a Null-terminated ASCII string. + + @retval Value translated from String. **/ -#define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&ListHead, &ListHead} +UINT64 +EFIAPI +AsciiStrDecimalToUint64 ( + IN CONST CHAR8 *String + ); + /** - 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 hexadecimal 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 hexadecimal number. The format of the input ASCII + string String is: - If ListHead is NULL, then ASSERT(). + [spaces][zeros][x][hexadecimal digits]. - @param ListHead A pointer to the head node of a new 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 Value translated from String. **/ -LIST_ENTRY * +UINTN EFIAPI -InitializeListHead ( - IN LIST_ENTRY *ListHead +AsciiStrHexToUintn ( + 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 hexadecimal 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 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 inserted at the beginning - of a 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 UINT64, + then ASSERT(). + If String is NULL, then ASSERT(). + If PcdMaximumAsciiStringLength is not zero, + and String contains more than PcdMaximumAsciiStringLength ASCII characters not including + the Null-terminator, then ASSERT(). + + @param String Pointer to a Null-terminated ASCII string. + + @retval Value translated from String. **/ -LIST_ENTRY * +UINT64 +EFIAPI +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. @@ -766,8 +1415,9 @@ InsertHeadList ( If ListHead is NULL, then ASSERT(). If Entry is NULL, then ASSERT(). If ListHead was not initialized with InitializeListHead(), then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and ListHead contains more than - PcdMaximumLinkedListLenth nodes, then ASSERT(). + If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number + of nodes in ListHead, including the ListHead node, is greater than or + equal to PcdMaximumLinkedListLength, then ASSERT(). @param ListHead A pointer to the head node of a doubly linked list. @param Entry A pointer to a node that is to be added at the end of the @@ -783,6 +1433,7 @@ InsertTailList ( IN LIST_ENTRY *Entry ); + /** Retrieves the first node of a doubly linked list. @@ -792,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. @@ -807,6 +1459,7 @@ GetFirstNode ( IN CONST LIST_ENTRY *List ); + /** Retrieves the next node of a doubly linked list. @@ -835,6 +1488,7 @@ GetNextNode ( IN CONST LIST_ENTRY *Node ); + /** Checks to see if a doubly linked list is empty or not. @@ -843,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. @@ -858,6 +1513,7 @@ IsListEmpty ( IN CONST LIST_ENTRY *ListHead ); + /** Determines if a node in a doubly linked list is null. @@ -868,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. @@ -886,6 +1543,7 @@ IsNull ( IN CONST LIST_ENTRY *Node ); + /** Determines if a node the last node in a doubly linked list. @@ -896,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. @@ -914,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. @@ -928,12 +1588,15 @@ IsNodeAtEnd ( If FirstEntry is NULL, then ASSERT(). If SecondEntry is NULL, then ASSERT(). If SecondEntry and FirstEntry are not in the same linked list, then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and the linked list containing - FirstEntry and SecondEntry contains more than PcdMaximumLinkedListLenth - nodes, then ASSERT(). + If PcdMaximumLinkedListLength is not zero, and the number of nodes in the + linked list containing the FirstEntry and SecondEntry nodes, including + the FirstEntry and SecondEntry nodes, is greater than or equal to + PcdMaximumLinkedListLength, then ASSERT(). @param FirstEntry A pointer to a node in a linked list. @param SecondEntry A pointer to another node in the same linked list. + + @return SecondEntry **/ LIST_ENTRY * @@ -943,6 +1606,7 @@ SwapListEntries ( IN LIST_ENTRY *SecondEntry ); + /** Removes a node from a doubly linked list, and returns the node that follows the removed node. @@ -955,8 +1619,9 @@ SwapListEntries ( If Entry is NULL, then ASSERT(). If Entry is the head node of an empty list, then ASSERT(). - If PcdMaximumLinkedListLenth is not zero, and the linked list containing - Entry contains more than PcdMaximumLinkedListLenth nodes, then ASSERT(). + If PcdMaximumLinkedListLength is not zero, and the number of nodes in the + linked list containing Entry, including the Entry node, is greater than + or equal to PcdMaximumLinkedListLength, then ASSERT(). @param Entry A pointer to a node in a linked list @@ -995,6 +1660,7 @@ LShiftU64 ( IN UINTN Count ); + /** Shifts a 64-bit integer right between 0 and 63 bits. This high bits are filled with zeros. The shifted value is returned. @@ -1017,6 +1683,7 @@ RShiftU64 ( IN UINTN Count ); + /** Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled with original integer's bit 63. The shifted value is returned. @@ -1039,6 +1706,7 @@ ARShiftU64 ( IN UINTN Count ); + /** Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits with the high bits that were rotated. @@ -1062,6 +1730,7 @@ LRotU32 ( IN UINTN Count ); + /** Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits with the low bits that were rotated. @@ -1085,6 +1754,7 @@ RRotU32 ( IN UINTN Count ); + /** Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits with the high bits that were rotated. @@ -1108,6 +1778,7 @@ LRotU64 ( IN UINTN Count ); + /** Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits with the high low bits that were rotated. @@ -1131,6 +1802,7 @@ RRotU64 ( IN UINTN Count ); + /** Returns the bit position of the lowest bit set in a 32-bit value. @@ -1150,6 +1822,7 @@ LowBitSet32 ( IN UINT32 Operand ); + /** Returns the bit position of the lowest bit set in a 64-bit value. @@ -1169,6 +1842,7 @@ LowBitSet64 ( IN UINT64 Operand ); + /** Returns the bit position of the highest bit set in a 32-bit value. Equivalent to log2(x). @@ -1189,6 +1863,7 @@ HighBitSet32 ( IN UINT32 Operand ); + /** Returns the bit position of the highest bit set in a 64-bit value. Equivalent to log2(x). @@ -1209,6 +1884,7 @@ HighBitSet64 ( IN UINT64 Operand ); + /** Returns the value of the highest bit set in a 32-bit value. Equivalent to 1 << HighBitSet32(x). @@ -1228,6 +1904,7 @@ GetPowerOfTwo32 ( IN UINT32 Operand ); + /** Returns the value of the highest bit set in a 64-bit value. Equivalent to 1 << HighBitSet64(x). @@ -1247,6 +1924,7 @@ GetPowerOfTwo64 ( IN UINT64 Operand ); + /** Switches the endianess of a 16-bit integer. @@ -1254,7 +1932,7 @@ GetPowerOfTwo64 ( from little endian to big endian or vice versa. The byte swapped value is returned. - @param Operand A 16-bit unsigned value. + @param Value Operand A 16-bit unsigned value. @return The byte swaped Operand. @@ -1265,6 +1943,7 @@ SwapBytes16 ( IN UINT16 Value ); + /** Switches the endianess of a 32-bit integer. @@ -1272,7 +1951,7 @@ SwapBytes16 ( from little endian to big endian or vice versa. The byte swapped value is returned. - @param Operand A 32-bit unsigned value. + @param Value Operand A 32-bit unsigned value. @return The byte swaped Operand. @@ -1283,6 +1962,7 @@ SwapBytes32 ( IN UINT32 Value ); + /** Switches the endianess of a 64-bit integer. @@ -1290,7 +1970,7 @@ SwapBytes32 ( from little endian to big endian or vice versa. The byte swapped value is returned. - @param Operand A 64-bit unsigned value. + @param Value Operand A 64-bit unsigned value. @return The byte swaped Operand. @@ -1301,6 +1981,7 @@ SwapBytes64 ( IN UINT64 Value ); + /** Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 64-bit unsigned result. @@ -1324,6 +2005,7 @@ MultU64x32 ( IN UINT32 Multiplier ); + /** Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and generates a 64-bit unsigned result. @@ -1347,6 +2029,7 @@ MultU64x64 ( IN UINT64 Multiplier ); + /** Multiples a 64-bit signed integer by a 64-bit signed integer and generates a 64-bit signed result. @@ -1370,6 +2053,7 @@ MultS64x64 ( IN INT64 Multiplier ); + /** Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 64-bit unsigned result. @@ -1393,6 +2077,7 @@ DivU64x32 ( IN UINT32 Divisor ); + /** Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 32-bit unsigned remainder. @@ -1416,6 +2101,7 @@ ModU64x32 ( IN UINT32 Divisor ); + /** Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 64-bit unsigned result and an optional 32-bit unsigned remainder. @@ -1443,6 +2129,7 @@ DivU64x32Remainder ( OUT UINT32 *Remainder OPTIONAL ); + /** Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates a 64-bit unsigned result and an optional 64-bit unsigned remainder. @@ -1470,6 +2157,7 @@ DivU64x64Remainder ( OUT UINT64 *Remainder OPTIONAL ); + /** Divides a 64-bit signed integer by a 64-bit signed integer and generates a 64-bit signed result and a optional 64-bit signed remainder. @@ -1497,6 +2185,7 @@ DivS64x64Remainder ( OUT INT64 *Remainder OPTIONAL ); + /** Reads a 16-bit value from memory that may be unaligned. @@ -1505,7 +2194,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 @@ -1516,6 +2205,7 @@ ReadUnaligned16 ( IN CONST UINT16 *Uint16 ); + /** Writes a 16-bit value to memory that may be unaligned. @@ -1525,7 +2215,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 @@ -1538,6 +2228,7 @@ WriteUnaligned16 ( IN UINT16 Value ); + /** Reads a 24-bit value from memory that may be unaligned. @@ -1548,7 +2239,7 @@ WriteUnaligned16 ( @param Buffer Pointer to a 24-bit value that may be unaligned. - @return The value read. + @return The value read from Buffer. **/ UINT32 @@ -1557,6 +2248,7 @@ ReadUnaligned24 ( IN CONST UINT32 *Buffer ); + /** Writes a 24-bit value to memory that may be unaligned. @@ -1569,7 +2261,7 @@ ReadUnaligned24 ( @param Buffer Pointer to a 24-bit value that may be unaligned. @param Value 24-bit value to write to Buffer. - @return The value written. + @return The value written to Buffer. **/ UINT32 @@ -1579,6 +2271,7 @@ WriteUnaligned24 ( IN UINT32 Value ); + /** Reads a 32-bit value from memory that may be unaligned. @@ -1587,9 +2280,9 @@ 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 + @return Value read from Uint32 **/ UINT32 @@ -1598,6 +2291,7 @@ ReadUnaligned32 ( IN CONST UINT32 *Uint32 ); + /** Writes a 32-bit value to memory that may be unaligned. @@ -1607,10 +2301,10 @@ 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 + @return Value written to Uint32. **/ UINT32 @@ -1620,6 +2314,7 @@ WriteUnaligned32 ( IN UINT32 Value ); + /** Reads a 64-bit value from memory that may be unaligned. @@ -1628,9 +2323,9 @@ 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 + @return Value read from Uint64. **/ UINT64 @@ -1639,6 +2334,7 @@ ReadUnaligned64 ( IN CONST UINT64 *Uint64 ); + /** Writes a 64-bit value to memory that may be unaligned. @@ -1648,10 +2344,10 @@ 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 + @return Value written to Uint64. **/ UINT64 @@ -1661,6 +2357,7 @@ WriteUnaligned64 ( IN UINT64 Value ); + // // Bit Field Functions // @@ -1673,7 +2370,7 @@ WriteUnaligned64 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1692,6 +2389,7 @@ BitFieldRead8 ( IN UINTN EndBit ); + /** Writes a bit field to an 8-bit value, and returns the result. @@ -1702,7 +2400,7 @@ BitFieldRead8 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1723,6 +2421,7 @@ BitFieldWrite8 ( IN UINT8 Value ); + /** Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the result. @@ -1734,7 +2433,7 @@ BitFieldWrite8 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1755,6 +2454,7 @@ BitFieldOr8 ( IN UINT8 OrData ); + /** Reads a bit field from an 8-bit value, performs a bitwise AND, and returns the result. @@ -1766,7 +2466,7 @@ BitFieldOr8 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1787,6 +2487,7 @@ BitFieldAnd8 ( IN UINT8 AndData ); + /** Reads a bit field from an 8-bit value, performs a bitwise AND followed by a bitwise OR, and returns the result. @@ -1799,7 +2500,7 @@ BitFieldAnd8 ( If 8-bit operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). If EndBit is greater than 7, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1822,6 +2523,7 @@ BitFieldAndThenOr8 ( IN UINT8 OrData ); + /** Returns a bit field from a 16-bit value. @@ -1830,7 +2532,7 @@ BitFieldAndThenOr8 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1849,6 +2551,7 @@ BitFieldRead16 ( IN UINTN EndBit ); + /** Writes a bit field to a 16-bit value, and returns the result. @@ -1859,7 +2562,7 @@ BitFieldRead16 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1880,6 +2583,7 @@ BitFieldWrite16 ( IN UINT16 Value ); + /** Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the result. @@ -1891,7 +2595,7 @@ BitFieldWrite16 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1912,6 +2616,7 @@ BitFieldOr16 ( IN UINT16 OrData ); + /** Reads a bit field from a 16-bit value, performs a bitwise AND, and returns the result. @@ -1923,7 +2628,7 @@ BitFieldOr16 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1944,6 +2649,7 @@ BitFieldAnd16 ( IN UINT16 AndData ); + /** Reads a bit field from a 16-bit value, performs a bitwise AND followed by a bitwise OR, and returns the result. @@ -1956,7 +2662,7 @@ BitFieldAnd16 ( If 16-bit operations are not supported, then ASSERT(). If StartBit is greater than 15, then ASSERT(). If EndBit is greater than 15, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -1979,6 +2685,7 @@ BitFieldAndThenOr16 ( IN UINT16 OrData ); + /** Returns a bit field from a 32-bit value. @@ -1987,7 +2694,7 @@ BitFieldAndThenOr16 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2006,6 +2713,7 @@ BitFieldRead32 ( IN UINTN EndBit ); + /** Writes a bit field to a 32-bit value, and returns the result. @@ -2016,7 +2724,7 @@ BitFieldRead32 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2037,6 +2745,7 @@ BitFieldWrite32 ( IN UINT32 Value ); + /** Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the result. @@ -2048,7 +2757,7 @@ BitFieldWrite32 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2069,6 +2778,7 @@ BitFieldOr32 ( IN UINT32 OrData ); + /** Reads a bit field from a 32-bit value, performs a bitwise AND, and returns the result. @@ -2080,7 +2790,7 @@ BitFieldOr32 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2101,6 +2811,7 @@ BitFieldAnd32 ( IN UINT32 AndData ); + /** Reads a bit field from a 32-bit value, performs a bitwise AND followed by a bitwise OR, and returns the result. @@ -2113,7 +2824,7 @@ BitFieldAnd32 ( If 32-bit operations are not supported, then ASSERT(). If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2136,6 +2847,7 @@ BitFieldAndThenOr32 ( IN UINT32 OrData ); + /** Returns a bit field from a 64-bit value. @@ -2144,7 +2856,7 @@ BitFieldAndThenOr32 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2163,6 +2875,7 @@ BitFieldRead64 ( IN UINTN EndBit ); + /** Writes a bit field to a 64-bit value, and returns the result. @@ -2173,7 +2886,7 @@ BitFieldRead64 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2194,6 +2907,7 @@ BitFieldWrite64 ( IN UINT64 Value ); + /** Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the result. @@ -2205,7 +2919,7 @@ BitFieldWrite64 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2226,6 +2940,7 @@ BitFieldOr64 ( IN UINT64 OrData ); + /** Reads a bit field from a 64-bit value, performs a bitwise AND, and returns the result. @@ -2237,7 +2952,7 @@ BitFieldOr64 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2258,6 +2973,7 @@ BitFieldAnd64 ( IN UINT64 AndData ); + /** Reads a bit field from a 64-bit value, performs a bitwise AND followed by a bitwise OR, and returns the result. @@ -2270,7 +2986,7 @@ BitFieldAnd64 ( If 64-bit operations are not supported, then ASSERT(). If StartBit is greater than 63, then ASSERT(). If EndBit is greater than 63, then ASSERT(). - If EndBit is less than or equal to StartBit, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). @param Operand Operand on which to perform the bitfield operation. @param StartBit The ordinal of the least significant bit in the bit field. @@ -2293,6 +3009,7 @@ BitFieldAndThenOr64 ( IN UINT64 OrData ); + // // Base Library Synchronization Functions // @@ -2319,6 +3036,7 @@ GetSpinLockProperties ( VOID ); + /** Initializes a spin lock to the released state and returns the spin lock. @@ -2332,7 +3050,7 @@ GetSpinLockProperties ( @param SpinLock A pointer to the spin lock to initialize to the released state. - @return SpinLock + @return SpinLock in release state. **/ SPIN_LOCK * @@ -2341,6 +3059,7 @@ InitializeSpinLock ( IN SPIN_LOCK *SpinLock ); + /** Waits until a spin lock can be placed in the acquired state. @@ -2358,7 +3077,7 @@ InitializeSpinLock ( @param SpinLock A pointer to the spin lock to place in the acquired state. - @return SpinLock + @return SpinLock accquired lock. **/ SPIN_LOCK * @@ -2367,6 +3086,7 @@ AcquireSpinLock ( IN SPIN_LOCK *SpinLock ); + /** Attempts to place a spin lock in the acquired state. @@ -2390,6 +3110,7 @@ AcquireSpinLockOrFail ( IN SPIN_LOCK *SpinLock ); + /** Releases a spin lock. @@ -2401,7 +3122,7 @@ AcquireSpinLockOrFail ( @param SpinLock A pointer to the spin lock to release. - @return SpinLock + @return SpinLock released lock. **/ SPIN_LOCK * @@ -2410,6 +3131,7 @@ ReleaseSpinLock ( IN SPIN_LOCK *SpinLock ); + /** Performs an atomic increment of an 32-bit unsigned integer. @@ -2431,6 +3153,7 @@ InterlockedIncrement ( IN UINT32 *Value ); + /** Performs an atomic decrement of an 32-bit unsigned integer. @@ -2452,9 +3175,18 @@ InterlockedDecrement ( IN UINT32 *Value ); + /** Performs an atomic compare exchange operation on a 32-bit unsigned integer. + Performs an atomic compare exchange operation on the 32-bit unsigned integer + specified by Value. If Value is equal to CompareValue, then Value is set to + ExchangeValue and CompareValue is returned. If Value is not equal to CompareValue, + then Value is returned. The compare exchange operation must be performed using + MP safe mechanisms. + + If Value is NULL, then ASSERT(). + @param Value A pointer to the 32-bit value for the compare exchange operation. @param CompareValue 32-bit value used in compare operation. @@ -2466,14 +3198,22 @@ InterlockedDecrement ( UINT32 EFIAPI InterlockedCompareExchange32 ( - IN UINT32 *Value, + IN OUT UINT32 *Value, IN UINT32 CompareValue, IN UINT32 ExchangeValue ); + /** Performs an atomic compare exchange operation on a 64-bit unsigned integer. + Performs an atomic compare exchange operation on the 64-bit unsigned integer specified + by Value. If Value is equal to CompareValue, then Value is set to ExchangeValue and + CompareValue is returned. If Value is not equal to CompareValue, then Value is returned. + The compare exchange operation must be performed using MP safe mechanisms. + + If Value is NULL, then ASSERT(). + @param Value A pointer to the 64-bit value for the compare exchange operation. @param CompareValue 64-bit value used in compare operation. @@ -2485,11 +3225,12 @@ InterlockedCompareExchange32 ( UINT64 EFIAPI InterlockedCompareExchange64 ( - IN UINT64 *Value, + IN OUT UINT64 *Value, IN UINT64 CompareValue, IN UINT64 ExchangeValue ); + /** Performs an atomic compare exchange operation on a pointer value. @@ -2506,211 +3247,1646 @@ InterlockedCompareExchange64 ( @param CompareValue Pointer value used in compare operation. @param ExchangeValue Pointer value used in exchange operation. + @return The original *Value before exchange. +**/ +VOID * +EFIAPI +InterlockedCompareExchangePointer ( + IN OUT VOID **Value, + IN VOID *CompareValue, + IN VOID *ExchangeValue + ); + + +// +// Base Library Checksum Functions +// + +/** + Calculate the sum of all elements in a buffer in unit of UINT8. + During calculation, the carry bits are dropped. + + 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. + + 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. + + Saves the current CPU context in the buffer specified by JumpBuffer and + returns 0. The initial call to SetJump() must always return 0. Subsequent + 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. + + @retval 0 Indicates a return from SetJump(). + +**/ +UINTN +EFIAPI +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. + +**/ +VOID +EFIAPI +EnableInterrupts ( + VOID + ); + + +/** + Disables CPU interrupts. + +**/ +VOID +EFIAPI +DisableInterrupts ( + VOID + ); + + +/** + Disables CPU interrupts and returns the interrupt state prior to the disable + operation. + + @retval TRUE CPU interrupts were enabled on entry to this call. + @retval FALSE CPU interrupts were disabled on entry to this call. + +**/ +BOOLEAN +EFIAPI +SaveAndDisableInterrupts ( + VOID + ); + + +/** + Enables CPU interrupts for the smallest window required to capture any + pending interrupts. + +**/ +VOID +EFIAPI +EnableDisableInterrupts ( + VOID + ); + + +/** + Retrieves the current CPU interrupt state. + + Returns TRUE is interrupts are currently enabled. Otherwise + returns FALSE. + + @retval TRUE CPU interrupts are enabled. + @retval FALSE CPU interrupts are disabled. + +**/ +BOOLEAN +EFIAPI +GetInterruptState ( + VOID + ); + + +/** + Set the current CPU interrupt state. + + Sets the current CPU interrupt state to the state specified by + InterruptState. If InterruptState is TRUE, then interrupts are enabled. If + InterruptState is FALSE, then interrupts are disabled. InterruptState is + returned. + + @param InterruptState TRUE if interrupts should enabled. FALSE if + interrupts should be disabled. + + @return InterruptState + +**/ +BOOLEAN +EFIAPI +SetInterruptState ( + IN BOOLEAN InterruptState + ); + + +/** + Requests CPU to pause for a short period of time. + + Requests CPU to pause for a short period of time. Typically used in MP + systems to prevent memory starvation while waiting for a spin lock. + +**/ +VOID +EFIAPI +CpuPause ( + VOID + ); + + +/** + Transfers control to a function starting with a new stack. + + Transfers control to the function specified by EntryPoint using the + new stack specified by NewStack and passing in the parameters specified + by Context1 and Context2. Context1 and Context2 are optional and may + be NULL. The function EntryPoint must never return. This function + supports a variable number of arguments following the NewStack parameter. + These additional arguments are ignored on IA-32, x64, and EBC. + IPF CPUs expect one additional parameter of type VOID * that specifies + the new backing store pointer. + + If EntryPoint is NULL, then ASSERT(). + If NewStack is NULL, then ASSERT(). + + @param EntryPoint A pointer to function to call with the new stack. + @param Context1 A pointer to the context to pass into the EntryPoint + function. + @param Context2 A pointer to the context to pass into the EntryPoint + function. + @param NewStack A pointer to the new stack to use for the EntryPoint + function. + @param ... Extended parameters. + + +**/ +VOID +EFIAPI +SwitchStack ( + IN SWITCH_STACK_ENTRY_POINT EntryPoint, + IN VOID *Context1, OPTIONAL + IN VOID *Context2, OPTIONAL + IN VOID *NewStack, + ... + ); + + +/** + Generates a breakpoint on the CPU. + + Generates a breakpoint on the CPU. The breakpoint must be implemented such + that code can resume normal execution after the breakpoint. + +**/ +VOID +EFIAPI +CpuBreakpoint ( + VOID + ); + + +/** + Executes an infinite loop. + + Forces the CPU to execute an infinite loop. A debugger may be used to skip + past the loop and the code that follows the loop must execute properly. This + implies that the infinite loop must not cause the code that follow it to be + optimized away. + +**/ +VOID +EFIAPI +CpuDeadLoop ( + VOID + ); + + +#if defined (MDE_CPU_IPF) + +/** + Flush a range of cache lines in the cache coherency domain of the calling + CPU. + + Invalidates the cache lines specified by Address and Length. If Address is + not aligned on a cache line boundary, then entire cache line containing + Address is invalidated. If Address + Length is not aligned on a cache line + boundary, then the entire instruction cache line containing Address + Length + -1 is invalidated. This function may choose to invalidate the entire + instruction cache if that is more efficient than invalidating the specified + range. If Length is 0, the no instruction cache lines are invalidated. + Address is returned. + + If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT(). + + @param Address The base address of the instruction lines to invalidate. If + the CPU is in a physical addressing mode, then Address is a + physical address. If the CPU is in a virtual addressing mode, + then Address is a virtual address. + + @param Length The number of bytes to invalidate from the instruction cache. + + @return Address + +**/ +VOID * +EFIAPI +IpfFlushCacheRange ( + IN VOID *Address, + IN UINTN Length + ); + + +/** + Executes a FC instruction + Executes a FC instruction on the cache line specified by Address. + The cache line size affected is at least 32-bytes (aligned on a 32-byte boundary). + An implementation may flush a larger region. This function is only available on IPF. + + @param Address The Address of cache line to be flushed. + + @return The address of FC instruction executed. + +**/ +UINT64 +EFIAPI +AsmFc ( + IN UINT64 Address + ); + + +/** + Executes a FC.I instruction. + Executes a FC.I instruction on the cache line specified by Address. + The cache line size affected is at least 32-bytes (aligned on a 32-byte boundary). + An implementation may flush a larger region. This function is only available on IPF. + + @param Address The Address of cache line to be flushed. + + @return The address of FC.I instruction executed. + +**/ +UINT64 +EFIAPI +AsmFci ( + IN UINT64 Address + ); + + +/** + Reads the current value of a Processor Identifier Register (CPUID). + The Index of largest implemented CPUID (One less than the number of implemented CPUID + registers) is determined by CPUID [3] bits {7:0}. + No parameter checking is performed on Index. If the Index value is beyond the + implemented CPUID register range, a Reserved Register/Field fault may occur. The caller + must either guarantee that Index is valid, or the caller must set up fault handlers to + catch the faults. This function is only available on IPF. + + @param Index The 8-bit Processor Identifier Register index to read. + + @return The current value of Processor Identifier Register specified by Index. + +**/ +UINT64 +EFIAPI +AsmReadCpuid ( + IN UINT8 Index + ); + + +/** + Reads the current value of 64-bit Processor Status Register (PSR). + This function is only available on IPF. + + @return The current value of PSR. + +**/ +UINT64 +EFIAPI +AsmReadPsr ( + VOID + ); + + +/** + Writes the current value of 64-bit Processor Status Register (PSR). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of PSR must be 0 or a Reserved Register/Field fault may occur. The caller must either guarantee that Value is valid, or the caller must set up fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to PSR. + + @return The 64-bit value written to the PSR. + +**/ +UINT64 +EFIAPI +AsmWritePsr ( + IN UINT64 Value + ); + + +/** + Reads the current value of 64-bit Kernel Register #0 (KR0). + This function is only available on IPF. + + @return The current value of KR0. + +**/ +UINT64 +EFIAPI +AsmReadKr0 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #1 (KR1). + This function is only available on IPF. + + @return The current value of KR1. + +**/ +UINT64 +EFIAPI +AsmReadKr1 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #2 (KR2). + This function is only available on IPF. + + @return The current value of KR2. + +**/ +UINT64 +EFIAPI +AsmReadKr2 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #3 (KR3). + This function is only available on IPF. + + @return The current value of KR3. + +**/ +UINT64 +EFIAPI +AsmReadKr3 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #4 (KR4). + This function is only available on IPF. + + @return The current value of KR4. + +**/ +UINT64 +EFIAPI +AsmReadKr4 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #5 (KR5). + This function is only available on IPF. + + @return The current value of KR5. + +**/ +UINT64 +EFIAPI +AsmReadKr5 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #6 (KR6). + This function is only available on IPF. + + @return The current value of KR6. + +**/ +UINT64 +EFIAPI +AsmReadKr6 ( + VOID + ); + + +/** + Reads the current value of 64-bit Kernel Register #7 (KR7). + This function is only available on IPF. + + @return The current value of KR7. + +**/ +UINT64 +EFIAPI +AsmReadKr7 ( + VOID + ); + + +/** + Write the current value of 64-bit Kernel Register #0 (KR0). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR0. + + @return The 64-bit value written to the KR0. + +**/ +UINT64 +EFIAPI +AsmWriteKr0 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #1 (KR1). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR1. + + @return The 64-bit value written to the KR1. + +**/ +UINT64 +EFIAPI +AsmWriteKr1 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #2 (KR2). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR2. + + @return The 64-bit value written to the KR2. + +**/ +UINT64 +EFIAPI +AsmWriteKr2 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #3 (KR3). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR3. + + @return The 64-bit value written to the KR3. + +**/ +UINT64 +EFIAPI +AsmWriteKr3 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #4 (KR4). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR4. + + @return The 64-bit value written to the KR4. + +**/ +UINT64 +EFIAPI +AsmWriteKr4 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #5 (KR5). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR5. + + @return The 64-bit value written to the KR5. + +**/ +UINT64 +EFIAPI +AsmWriteKr5 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #6 (KR6). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR6. + + @return The 64-bit value written to the KR6. + +**/ +UINT64 +EFIAPI +AsmWriteKr6 ( + IN UINT64 Value + ); + + +/** + Write the current value of 64-bit Kernel Register #7 (KR7). + This function is only available on IPF. + + @param Value The 64-bit value to write to KR7. + + @return The 64-bit value written to the KR7. + +**/ +UINT64 +EFIAPI +AsmWriteKr7 ( + IN UINT64 Value + ); + + +/** + Reads the current value of Interval Timer Counter Register (ITC). + This function is only available on IPF. + + @return The current value of ITC. + +**/ +UINT64 +EFIAPI +AsmReadItc ( + VOID + ); + + +/** + Reads the current value of Interval Timer Vector Register (ITV). + This function is only available on IPF. + + @return The current value of ITV. + +**/ +UINT64 +EFIAPI +AsmReadItv ( + VOID + ); + + +/** + Reads the current value of Interval Timer Match Register (ITM). + This function is only available on IPF. + + @return The current value of ITM. +**/ +UINT64 +EFIAPI +AsmReadItm ( + VOID + ); + + +/** + Writes the current value of 64-bit Interval Timer Counter Register (ITC). + This function is only available on IPF. + + @param Value The 64-bit value to write to ITC. + + @return The 64-bit value written to the ITC. + +**/ +UINT64 +EFIAPI +AsmWriteItc ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Interval Timer Match Register (ITM). + This function is only available on IPF. + + @param Value The 64-bit value to write to ITM. + + @return The 64-bit value written to the ITM. + +**/ +UINT64 +EFIAPI +AsmWriteItm ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Interval Timer Vector Register (ITV). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of ITV must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to ITV. + + @return The 64-bit value written to the ITV. + +**/ +UINT64 +EFIAPI +AsmWriteItv ( + IN UINT64 Value + ); + + +/** + Reads the current value of Default Control Register (DCR). + This function is only available on IPF. + + @return The current value of DCR. + +**/ +UINT64 +EFIAPI +AsmReadDcr ( + VOID + ); + + +/** + Reads the current value of Interruption Vector Address Register (IVA). + This function is only available on IPF. + + @return The current value of IVA. +**/ +UINT64 +EFIAPI +AsmReadIva ( + VOID + ); + + +/** + Reads the current value of Page Table Address Register (PTA). + This function is only available on IPF. + + @return The current value of PTA. + +**/ +UINT64 +EFIAPI +AsmReadPta ( + VOID + ); + + +/** + Writes the current value of 64-bit Default Control Register (DCR). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of DCR must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to DCR. + + @return The 64-bit value written to the DCR. + +**/ +UINT64 +EFIAPI +AsmWriteDcr ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Interruption Vector Address Register (IVA). + The size of vector table is 32 K bytes and is 32 K bytes aligned + the low 15 bits of Value is ignored when written. + This function is only available on IPF. + + @param Value The 64-bit value to write to IVA. + + @return The 64-bit value written to the IVA. + +**/ +UINT64 +EFIAPI +AsmWriteIva ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Page Table Address Register (PTA). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of DCR must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to PTA. + + @return The 64-bit value written to the PTA. +**/ +UINT64 +EFIAPI +AsmWritePta ( + IN UINT64 Value + ); + + +/** + Reads the current value of Local Interrupt ID Register (LID). + This function is only available on IPF. + + @return The current value of LID. + +**/ +UINT64 +EFIAPI +AsmReadLid ( + VOID + ); + + +/** + Reads the current value of External Interrupt Vector Register (IVR). + This function is only available on IPF. + + @return The current value of IVR. + +**/ +UINT64 +EFIAPI +AsmReadIvr ( + VOID + ); + + +/** + Reads the current value of Task Priority Register (TPR). + This function is only available on IPF. + + @return The current value of TPR. + +**/ +UINT64 +EFIAPI +AsmReadTpr ( + VOID + ); + + +/** + Reads the current value of External Interrupt Request Register #0 (IRR0). + This function is only available on IPF. + + @return The current value of IRR0. + +**/ +UINT64 +EFIAPI +AsmReadIrr0 ( + VOID + ); + + +/** + Reads the current value of External Interrupt Request Register #1 (IRR1). + This function is only available on IPF. + + @return The current value of IRR1. + +**/ +UINT64 +EFIAPI +AsmReadIrr1 ( + VOID + ); + + +/** + Reads the current value of External Interrupt Request Register #2 (IRR2). + This function is only available on IPF. + + @return The current value of IRR2. + +**/ +UINT64 +EFIAPI +AsmReadIrr2 ( + VOID + ); + + +/** + Reads the current value of External Interrupt Request Register #3 (IRR3). + This function is only available on IPF. + + @return The current value of IRR3. + +**/ +UINT64 +EFIAPI +AsmReadIrr3 ( + VOID + ); + + +/** + Reads the current value of Performance Monitor Vector Register (PMV). + This function is only available on IPF. + + @return The current value of PMV. + +**/ +UINT64 +EFIAPI +AsmReadPmv ( + VOID + ); + + +/** + Reads the current value of Corrected Machine Check Vector Register (CMCV). + This function is only available on IPF. + + @return The current value of CMCV. + +**/ +UINT64 +EFIAPI +AsmReadCmcv ( + VOID + ); + + +/** + Reads the current value of Local Redirection Register #0 (LRR0). + This function is only available on IPF. + + @return The current value of LRR0. + +**/ +UINT64 +EFIAPI +AsmReadLrr0 ( + VOID + ); + + +/** + Reads the current value of Local Redirection Register #1 (LRR1). + This function is only available on IPF. + + @return The current value of LRR1. + +**/ +UINT64 +EFIAPI +AsmReadLrr1 ( + VOID + ); + + +/** + Writes the current value of 64-bit Page Local Interrupt ID Register (LID). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of LID must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to LID. + + @return The 64-bit value written to the LID. + +**/ +UINT64 +EFIAPI +AsmWriteLid ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Task Priority Register (TPR). + No parameter checking is performed on Value. All bits of Value corresponding to + reserved fields of TPR must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to TPR. + + @return The 64-bit value written to the TPR. + +**/ +UINT64 +EFIAPI +AsmWriteTpr ( + IN UINT64 Value + ); + + +/** + Performs a write operation on End OF External Interrupt Register (EOI). + Writes a value of 0 to the EOI Register. This function is only available on IPF. + +**/ +VOID +EFIAPI +AsmWriteEoi ( + VOID + ); + + +/** + Writes the current value of 64-bit Performance Monitor Vector Register (PMV). + No parameter checking is performed on Value. All bits of Value corresponding + to reserved fields of PMV must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to PMV. + + @return The 64-bit value written to the PMV. + +**/ +UINT64 +EFIAPI +AsmWritePmv ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Corrected Machine Check Vector Register (CMCV). + No parameter checking is performed on Value. All bits of Value corresponding + to reserved fields of CMCV must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to CMCV. + + @return The 64-bit value written to the CMCV. + +**/ +UINT64 +EFIAPI +AsmWriteCmcv ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Local Redirection Register #0 (LRR0). + No parameter checking is performed on Value. All bits of Value corresponding + to reserved fields of LRR0 must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must set up + fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to LRR0. + + @return The 64-bit value written to the LRR0. + +**/ +UINT64 +EFIAPI +AsmWriteLrr0 ( + IN UINT64 Value + ); + + +/** + Writes the current value of 64-bit Local Redirection Register #1 (LRR1). + No parameter checking is performed on Value. All bits of Value corresponding + to reserved fields of LRR1 must be 0 or a Reserved Register/Field fault may occur. + The caller must either guarantee that Value is valid, or the caller must + set up fault handlers to catch the faults. + This function is only available on IPF. + + @param Value The 64-bit value to write to LRR1. + + @return The 64-bit value written to the LRR1. + +**/ +UINT64 +EFIAPI +AsmWriteLrr1 ( + IN UINT64 Value + ); + + +/** + Reads the current value of Instruction Breakpoint Register (IBR). + + The Instruction Breakpoint Registers are used in pairs. The even numbered + registers contain breakpoint addresses, and the odd numbered registers contain + breakpoint mask conditions. At least 4 instruction registers pairs are implemented + on all processor models. Implemented registers are contiguous starting with + register 0. No parameter checking is performed on Index, and if the Index value + is beyond the implemented IBR register range, a Reserved Register/Field fault may + occur. The caller must either guarantee that Index is valid, or the caller must + set up fault handlers to catch the faults. + This function is only available on IPF. + + @param Index The 8-bit Instruction Breakpoint Register index to read. + + @return The current value of Instruction Breakpoint Register specified by Index. + **/ -VOID * +UINT64 EFIAPI -InterlockedCompareExchangePointer ( - IN VOID **Value, - IN VOID *CompareValue, - IN VOID *ExchangeValue +AsmReadIbr ( + IN UINT8 Index ); -// -// 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. + Reads the current value of Data Breakpoint Register (DBR). - All loads and stores that proceed calls to this function are guaranteed to be - globally visible when this function returns. + 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. **/ -VOID +UINT64 EFIAPI -MemoryFence ( - VOID +AsmReadDbr ( + IN UINT8 Index ); -/** - Saves the current CPU context that can be restored with a call to LongJump() - and returns 0. - Saves the current CPU context in the buffer specified by JumpBuffer and - returns 0. The initial call to SetJump() must always return 0. Subsequent - calls to LongJump() cause a non-zero value to be returned by SetJump(). +/** + Reads the current value of Performance Monitor Configuration Register (PMC). - If JumpBuffer is NULL, then ASSERT(). + 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 JumpBuffer A pointer to CPU context buffer. + @param Index The 8-bit Performance Monitor Configuration Register index to read. - @retval 0 Indicates a return from SetJump(). + @return The current value of Performance Monitor Configuration Register + specified by Index. **/ -UINTN +UINT64 EFIAPI -SetJump ( - OUT BASE_LIBRARY_JUMP_BUFFER *JumpBuffer +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. @@ -2729,45 +4905,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 Arg2 The second argument of a PAL call. + @param Arg3 The third argument of a PAL call. + @param Arg4 The fourth argument of a PAL call. - Forces the CPU to execute an infinite loop. A debugger may be used to skip - past the loop and the code that follows the loop must execute properly. This - implies that the infinite loop must not cause the code that follow it to be - optimized away. + @return The values returned in r8, r9, r10 and r11. **/ -VOID -EFIAPI -CpuDeadLoop ( - VOID +PAL_CALL_RETURN +PalCallStatic ( + IN CONST VOID *PalEntryPoint, + IN UINT64 Arg1, + IN UINT64 Arg2, + IN UINT64 Arg3, + IN UINT64 Arg4 ); + +#elif defined (MDE_CPU_IA32) || defined (MDE_CPU_X64) // // IA32 and X64 Specific Functions // @@ -2886,10 +5068,12 @@ 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 @@ -3033,6 +5217,7 @@ AsmCpuid ( OUT UINT32 *Edx OPTIONAL ); + /** Retrieves CPUID information using an extended leaf identifier. @@ -3076,6 +5261,7 @@ AsmCpuidEx ( OUT UINT32 *Edx OPTIONAL ); + /** Returns the lower 32-bits of a Machine Specific Register(MSR). @@ -3096,6 +5282,7 @@ AsmReadMsr32 ( IN UINT32 Index ); + /** Zero-extend a 32-bit value and writes it to a Machine Specific Register(MSR). @@ -3119,6 +5306,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. @@ -3145,6 +5333,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. @@ -3171,6 +5360,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. @@ -3201,6 +5391,7 @@ AsmMsrAndThenOr32 ( IN UINT32 OrData ); + /** Reads a bit field of an MSR. @@ -3212,7 +5403,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. @@ -3231,6 +5422,7 @@ AsmMsrBitFieldRead32 ( IN UINTN EndBit ); + /** Writes a bit field to an MSR. @@ -3244,7 +5436,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. @@ -3265,6 +5457,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. @@ -3279,7 +5472,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. @@ -3300,6 +5493,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. @@ -3314,7 +5508,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. @@ -3335,6 +5529,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 @@ -3351,7 +5546,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. @@ -3374,6 +5569,7 @@ AsmMsrBitFieldAndThenOr32 ( IN UINT32 OrData ); + /** Returns a 64-bit Machine Specific Register(MSR). @@ -3394,6 +5590,7 @@ AsmReadMsr64 ( IN UINT32 Index ); + /** Writes a 64-bit value to a Machine Specific Register(MSR), and returns the value. @@ -3418,6 +5615,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. @@ -3443,6 +5641,7 @@ AsmMsrOr64 ( IN UINT64 OrData ); + /** Reads a 64-bit MSR, performs a bitwise AND, and writes the result back to the 64-bit MSR. @@ -3468,6 +5667,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. @@ -3497,6 +5697,7 @@ AsmMsrAndThenOr64 ( IN UINT64 OrData ); + /** Reads a bit field of an MSR. @@ -3508,7 +5709,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. @@ -3527,6 +5728,7 @@ AsmMsrBitFieldRead64 ( IN UINTN EndBit ); + /** Writes a bit field to an MSR. @@ -3539,7 +5741,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. @@ -3560,6 +5762,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. @@ -3574,7 +5777,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. @@ -3595,6 +5798,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. @@ -3609,7 +5813,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. @@ -3630,6 +5834,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 @@ -3645,7 +5850,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. @@ -3668,6 +5873,7 @@ AsmMsrBitFieldAndThenOr64 ( IN UINT64 OrData ); + /** Reads the current value of the EFLAGS register. @@ -3684,6 +5890,7 @@ AsmReadEflags ( VOID ); + /** Reads the current value of the Control Register 0 (CR0). @@ -3700,6 +5907,7 @@ AsmReadCr0 ( VOID ); + /** Reads the current value of the Control Register 2 (CR2). @@ -3716,6 +5924,7 @@ AsmReadCr2 ( VOID ); + /** Reads the current value of the Control Register 3 (CR3). @@ -3732,6 +5941,7 @@ AsmReadCr3 ( VOID ); + /** Reads the current value of the Control Register 4 (CR4). @@ -3748,6 +5958,7 @@ AsmReadCr4 ( VOID ); + /** Writes a value to Control Register 0 (CR0). @@ -3765,6 +5976,7 @@ AsmWriteCr0 ( UINTN Cr0 ); + /** Writes a value to Control Register 2 (CR2). @@ -3782,6 +5994,7 @@ AsmWriteCr2 ( UINTN Cr2 ); + /** Writes a value to Control Register 3 (CR3). @@ -3799,6 +6012,7 @@ AsmWriteCr3 ( UINTN Cr3 ); + /** Writes a value to Control Register 4 (CR4). @@ -3816,6 +6030,7 @@ AsmWriteCr4 ( UINTN Cr4 ); + /** Reads the current value of Debug Register 0 (DR0). @@ -3832,6 +6047,7 @@ AsmReadDr0 ( VOID ); + /** Reads the current value of Debug Register 1 (DR1). @@ -3848,6 +6064,7 @@ AsmReadDr1 ( VOID ); + /** Reads the current value of Debug Register 2 (DR2). @@ -3864,6 +6081,7 @@ AsmReadDr2 ( VOID ); + /** Reads the current value of Debug Register 3 (DR3). @@ -3880,6 +6098,7 @@ AsmReadDr3 ( VOID ); + /** Reads the current value of Debug Register 4 (DR4). @@ -3896,6 +6115,7 @@ AsmReadDr4 ( VOID ); + /** Reads the current value of Debug Register 5 (DR5). @@ -3912,6 +6132,7 @@ AsmReadDr5 ( VOID ); + /** Reads the current value of Debug Register 6 (DR6). @@ -3928,6 +6149,7 @@ AsmReadDr6 ( VOID ); + /** Reads the current value of Debug Register 7 (DR7). @@ -3944,6 +6166,7 @@ AsmReadDr7 ( VOID ); + /** Writes a value to Debug Register 0 (DR0). @@ -3961,6 +6184,7 @@ AsmWriteDr0 ( UINTN Dr0 ); + /** Writes a value to Debug Register 1 (DR1). @@ -3978,6 +6202,7 @@ AsmWriteDr1 ( UINTN Dr1 ); + /** Writes a value to Debug Register 2 (DR2). @@ -3995,6 +6220,7 @@ AsmWriteDr2 ( UINTN Dr2 ); + /** Writes a value to Debug Register 3 (DR3). @@ -4012,6 +6238,7 @@ AsmWriteDr3 ( UINTN Dr3 ); + /** Writes a value to Debug Register 4 (DR4). @@ -4029,6 +6256,7 @@ AsmWriteDr4 ( UINTN Dr4 ); + /** Writes a value to Debug Register 5 (DR5). @@ -4046,6 +6274,7 @@ AsmWriteDr5 ( UINTN Dr5 ); + /** Writes a value to Debug Register 6 (DR6). @@ -4063,6 +6292,7 @@ AsmWriteDr6 ( UINTN Dr6 ); + /** Writes a value to Debug Register 7 (DR7). @@ -4080,6 +6310,7 @@ AsmWriteDr7 ( UINTN Dr7 ); + /** Reads the current value of Code Segment Register (CS). @@ -4095,6 +6326,7 @@ AsmReadCs ( VOID ); + /** Reads the current value of Data Segment Register (DS). @@ -4110,6 +6342,7 @@ AsmReadDs ( VOID ); + /** Reads the current value of Extra Segment Register (ES). @@ -4125,6 +6358,7 @@ AsmReadEs ( VOID ); + /** Reads the current value of FS Data Segment Register (FS). @@ -4140,6 +6374,7 @@ AsmReadFs ( VOID ); + /** Reads the current value of GS Data Segment Register (GS). @@ -4155,6 +6390,7 @@ AsmReadGs ( VOID ); + /** Reads the current value of Stack Segment Register (SS). @@ -4170,6 +6406,7 @@ AsmReadSs ( VOID ); + /** Reads the current value of Task Register (TR). @@ -4185,6 +6422,7 @@ AsmReadTr ( VOID ); + /** Reads the current Global Descriptor Table Register(GDTR) descriptor. @@ -4202,6 +6440,7 @@ AsmReadGdtr ( OUT IA32_DESCRIPTOR *Gdtr ); + /** Writes the current Global Descriptor Table Register (GDTR) descriptor. @@ -4219,6 +6458,7 @@ AsmWriteGdtr ( IN CONST IA32_DESCRIPTOR *Gdtr ); + /** Reads the current Interrupt Descriptor Table Register(GDTR) descriptor. @@ -4236,6 +6476,7 @@ AsmReadIdtr ( OUT IA32_DESCRIPTOR *Idtr ); + /** Writes the current Interrupt Descriptor Table Register(GDTR) descriptor. @@ -4253,6 +6494,7 @@ AsmWriteIdtr ( IN CONST IA32_DESCRIPTOR *Idtr ); + /** Reads the current Local Descriptor Table Register(LDTR) selector. @@ -4268,6 +6510,7 @@ AsmReadLdtr ( VOID ); + /** Writes the current Local Descriptor Table Register (GDTR) selector. @@ -4283,6 +6526,7 @@ AsmWriteLdtr ( IN UINT16 Ldtr ); + /** Save the current floating point/SSE/SSE2 context to a buffer. @@ -4302,6 +6546,7 @@ AsmFxSave ( OUT IA32_FX_BUFFER *Buffer ); + /** Restores the current floating point/SSE/SSE2 context from a buffer. @@ -4322,6 +6567,7 @@ AsmFxRestore ( IN CONST IA32_FX_BUFFER *Buffer ); + /** Reads the current value of 64-bit MMX Register #0 (MM0). @@ -4337,6 +6583,7 @@ AsmReadMm0 ( VOID ); + /** Reads the current value of 64-bit MMX Register #1 (MM1). @@ -4352,6 +6599,7 @@ AsmReadMm1 ( VOID ); + /** Reads the current value of 64-bit MMX Register #2 (MM2). @@ -4367,6 +6615,7 @@ AsmReadMm2 ( VOID ); + /** Reads the current value of 64-bit MMX Register #3 (MM3). @@ -4382,6 +6631,7 @@ AsmReadMm3 ( VOID ); + /** Reads the current value of 64-bit MMX Register #4 (MM4). @@ -4397,6 +6647,7 @@ AsmReadMm4 ( VOID ); + /** Reads the current value of 64-bit MMX Register #5 (MM5). @@ -4412,6 +6663,7 @@ AsmReadMm5 ( VOID ); + /** Reads the current value of 64-bit MMX Register #6 (MM6). @@ -4427,6 +6679,7 @@ AsmReadMm6 ( VOID ); + /** Reads the current value of 64-bit MMX Register #7 (MM7). @@ -4442,6 +6695,7 @@ AsmReadMm7 ( VOID ); + /** Writes the current value of 64-bit MMX Register #0 (MM0). @@ -4457,6 +6711,7 @@ AsmWriteMm0 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #1 (MM1). @@ -4472,6 +6727,7 @@ AsmWriteMm1 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #2 (MM2). @@ -4487,6 +6743,7 @@ AsmWriteMm2 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #3 (MM3). @@ -4502,6 +6759,7 @@ AsmWriteMm3 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #4 (MM4). @@ -4517,6 +6775,7 @@ AsmWriteMm4 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #5 (MM5). @@ -4532,6 +6791,7 @@ AsmWriteMm5 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #6 (MM6). @@ -4547,6 +6807,7 @@ AsmWriteMm6 ( IN UINT64 Value ); + /** Writes the current value of 64-bit MMX Register #7 (MM7). @@ -4562,6 +6823,7 @@ AsmWriteMm7 ( IN UINT64 Value ); + /** Reads the current value of Time Stamp Counter (TSC). @@ -4577,6 +6839,7 @@ AsmReadTsc ( VOID ); + /** Reads the current value of a Performance Counter (PMC). @@ -4594,6 +6857,7 @@ AsmReadPmc ( IN UINT32 Index ); + /** Sets up a monitor buffer that is used by AsmMwait(). @@ -4618,6 +6882,7 @@ AsmMonitor ( IN UINTN Edx ); + /** Executes an MWAIT instruction. @@ -4639,6 +6904,7 @@ AsmMwait ( IN UINTN Ecx ); + /** Executes a WBINVD instruction. @@ -4652,6 +6918,7 @@ AsmWbinvd ( VOID ); + /** Executes a INVD instruction. @@ -4665,6 +6932,7 @@ AsmInvd ( VOID ); + /** Flushes a cache line from all the instruction and data caches within the coherency domain of the CPU. @@ -4686,6 +6954,7 @@ AsmFlushCacheLine ( IN VOID *LinearAddress ); + /** Enables the 32-bit paging mode on the CPU. @@ -4732,6 +7001,7 @@ AsmEnablePaging32 ( IN VOID *NewStack ); + /** Disables the 32-bit paging mode on the CPU. @@ -4775,6 +7045,7 @@ AsmDisablePaging32 ( IN VOID *NewStack ); + /** Enables the 64-bit paging mode on the CPU. @@ -4792,7 +7063,7 @@ AsmDisablePaging32 ( If EntryPoint is 0, then ASSERT(). If NewStack is 0, then ASSERT(). - @param Cs The 16-bit selector to load in the CS before EntryPoint + @param CodeSelector The 16-bit selector to load in the CS before EntryPoint is called. The descriptor in the GDT that this selector references must be setup for long mode. @param EntryPoint The 64-bit virtual address of the function to call with @@ -4817,6 +7088,7 @@ AsmEnablePaging64 ( IN UINT64 NewStack ); + /** Disables the 64-bit paging mode on the CPU. @@ -4832,7 +7104,7 @@ AsmEnablePaging64 ( If EntryPoint is 0, then ASSERT(). If NewStack is 0, then ASSERT(). - @param Cs The 16-bit selector to load in the CS before EntryPoint + @param CodeSelector The 16-bit selector to load in the CS before EntryPoint is called. The descriptor in the GDT that this selector references must be setup for 32-bit protected mode. @param EntryPoint The 64-bit virtual address of the function to call with @@ -4857,6 +7129,7 @@ AsmDisablePaging64 ( IN UINT32 NewStack ); + // // 16-bit thunking services // @@ -4889,6 +7162,7 @@ AsmGetThunk16Properties ( OUT UINT32 *ExtraStackSize ); + /** Prepares all structures a code required to use AsmThunk16(). @@ -4906,6 +7180,7 @@ AsmPrepareThunk16 ( OUT THUNK_CONTEXT *ThunkContext ); + /** Transfers control to a 16-bit real mode entry point and returns the results. @@ -4926,6 +7201,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. @@ -4949,4 +7225,10 @@ AsmPrepareAndThunk16 ( IN OUT THUNK_CONTEXT *ThunkContext ); +#else + #endif + +#endif + +