/** @file\r
- Memory-only library functions with no library constructor/destructor\r
+ Provides string functions, linked list functions, math functions, synchronization\r
+ functions, and CPU architecture specific functions.\r
\r
- Copyright (c) 2006 - 2008, Intel Corporation\r
- All rights reserved. This program and the accompanying materials\r
- are licensed and made available under the terms and conditions of the BSD License\r
- which accompanies this distribution. The full text of the license may be found at\r
- http://opensource.org/licenses/bsd-license.php\r
+Copyright (c) 2006 - 2008, Intel Corporation\r
+All rights reserved. This program and the accompanying materials\r
+are licensed and made available under the terms and conditions of the BSD License\r
+which accompanies this distribution. The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php\r
\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
\r
\r
/**\r
- Copies one Null-terminated Unicode string with a maximum length to another\r
- Null-terminated Unicode string with a maximum length and returns the new\r
- Unicode string.\r
+ Copies up to a specified length from one Null-terminated Unicode string to \r
+ another Null-terminated Unicode string and returns the new Unicode string.\r
\r
This function copies the contents of the Unicode string Source to the Unicode\r
string Destination, and returns Destination. At most, Length Unicode\r
Returns the size of a Null-terminated Unicode string in bytes, including the\r
Null terminator.\r
\r
- This function returns the size, in bytes, of the Null-terminated Unicode\r
- string specified by String.\r
+ This function returns the size, in bytes, of the Null-terminated Unicode string \r
+ specified by String.\r
\r
If String is NULL, then ASSERT().\r
If String is not aligned on a 16-bit boundary, then ASSERT().\r
\r
\r
/**\r
- Compares two Null-terminated Unicode strings with maximum lengths, and\r
- returns the difference between the first mismatched Unicode characters.\r
-\r
+ Compares up to a specified length the contents of two Null-terminated Unicode strings,\r
+ and returns the difference between the first mismatched Unicode characters.\r
+ \r
This function compares the Null-terminated Unicode string FirstString to the\r
Null-terminated Unicode string SecondString. At most, Length Unicode\r
characters will be compared. If Length is 0, then 0 is returned. If\r
\r
\r
/**\r
- Concatenates one Null-terminated Unicode string with a maximum length to the\r
- end of another Null-terminated Unicode string, and returns the concatenated\r
+ Concatenates up to a specified length one Null-terminated Unicode to the end \r
+ of another Null-terminated Unicode string, and returns the concatenated \r
Unicode string.\r
\r
This function concatenates two Null-terminated Unicode strings. The contents\r
or String contains more than PcdMaximumUnicodeStringLength Unicode\r
characters not including the Null-terminator, then ASSERT().\r
\r
- @param String Pointer to a Null-terminated Unicode string.\r
- @param SearchString Pointer to a Null-terminated Unicode string to search for.\r
+ @param String Pointer to a Null-terminated Unicode string.\r
+ @param SearchString Pointer to a Null-terminated Unicode string to search for.\r
\r
@retval NULL If the SearchString does not appear in String.\r
@return others If there is a match.\r
CHAR16 *\r
EFIAPI\r
StrStr (\r
- IN CONST CHAR16 *String,\r
- IN CONST CHAR16 *SearchString\r
+ IN CONST CHAR16 *String,\r
+ IN CONST CHAR16 *SearchString\r
);\r
\r
/**\r
more than PcdMaximumUnicodeStringLength Unicode characters not including\r
the Null-terminator, then ASSERT().\r
\r
- @param String Pointer to a Null-terminated Unicode string.\r
+ @param String Pointer to a Null-terminated Unicode string.\r
\r
@retval Value translated from String.\r
\r
UINTN\r
EFIAPI\r
StrDecimalToUintn (\r
- IN CONST CHAR16 *String\r
+ IN CONST CHAR16 *String\r
);\r
\r
/**\r
more than PcdMaximumUnicodeStringLength Unicode characters not including\r
the Null-terminator, then ASSERT().\r
\r
- @param String Pointer to a Null-terminated Unicode string.\r
+ @param String Pointer to a Null-terminated Unicode string.\r
\r
@retval Value translated from String.\r
\r
UINT64\r
EFIAPI\r
StrDecimalToUint64 (\r
- IN CONST CHAR16 *String\r
+ IN CONST CHAR16 *String\r
);\r
\r
\r
PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,\r
then ASSERT().\r
\r
- @param String Pointer to a Null-terminated Unicode string.\r
+ @param String Pointer to a Null-terminated Unicode string.\r
\r
@retval Value translated from String.\r
\r
UINTN\r
EFIAPI\r
StrHexToUintn (\r
- IN CONST CHAR16 *String\r
+ IN CONST CHAR16 *String\r
);\r
\r
\r
PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,\r
then ASSERT().\r
\r
- @param String Pointer to a Null-terminated Unicode string.\r
+ @param String Pointer to a Null-terminated Unicode string.\r
\r
@retval Value translated from String.\r
\r
UINT64\r
EFIAPI\r
StrHexToUint64 (\r
- IN CONST CHAR16 *String\r
+ IN CONST CHAR16 *String\r
);\r
\r
/**\r
);\r
\r
/**\r
- Convert one Null-terminated Unicode string to a Null-terminated\r
+ Convert a Null-terminated Unicode string to a Null-terminated\r
ASCII string and returns the ASCII string.\r
\r
This function converts the content of the Unicode string Source\r
CHAR8 *\r
EFIAPI\r
UnicodeStrToAsciiStr (\r
- IN CONST CHAR16 *Source,\r
- OUT CHAR8 *Destination\r
+ IN CONST CHAR16 *Source,\r
+ OUT CHAR8 *Destination\r
);\r
\r
\r
\r
\r
/**\r
- Copies one Null-terminated ASCII string with a maximum length to another\r
- Null-terminated ASCII string with a maximum length and returns the new ASCII\r
- string.\r
+ Copies up to a specified length one Null-terminated ASCII string to another \r
+ Null-terminated ASCII string and returns the new ASCII string.\r
\r
This function copies the contents of the ASCII string Source to the ASCII\r
string Destination, and returns Destination. At most, Length ASCII characters\r
@param FirstString Pointer to a Null-terminated ASCII string.\r
@param SecondString Pointer to a Null-terminated ASCII string.\r
\r
- @retval 0 FirstString is identical to SecondString.\r
- @return others FirstString is not identical to SecondString.\r
+ @retval ==0 FirstString is identical to SecondString.\r
+ @retval !=0 FirstString is not identical to SecondString.\r
\r
**/\r
INTN\r
@param FirstString Pointer to a Null-terminated ASCII string.\r
@param SecondString Pointer to a Null-terminated ASCII string.\r
\r
- @retval 0 FirstString is identical to SecondString using case insensitive\r
+ @retval ==0 FirstString is identical to SecondString using case insensitive\r
comparisons.\r
- @return others FirstString is not identical to SecondString using case\r
+ @retval !=0 FirstString is not identical to SecondString using case\r
insensitive comparisons.\r
\r
**/\r
@param SecondString Pointer to a Null-terminated ASCII string.\r
@param Length Maximum number of ASCII characters for compare.\r
\r
- @retval 0 FirstString is identical to SecondString.\r
- @return others FirstString is not identical to SecondString.\r
+ @retval ==0 FirstString is identical to SecondString.\r
+ @retval !=0 FirstString is not identical to SecondString.\r
\r
**/\r
INTN\r
\r
\r
/**\r
- Concatenates one Null-terminated ASCII string with a maximum length to the\r
- end of another Null-terminated ASCII string, and returns the concatenated\r
- ASCII string.\r
+ Concatenates up to a specified length one Null-terminated ASCII string to \r
+ the end of another Null-terminated ASCII string, and returns the \r
+ concatenated ASCII string.\r
\r
This function concatenates two Null-terminated ASCII strings. The contents\r
of Null-terminated ASCII string Source are concatenated to the end of Null-\r
@param SearchString Pointer to a Null-terminated ASCII string to search for.\r
\r
@retval NULL If the SearchString does not appear in String.\r
- @return others If there is a match.\r
+ @retval others If there is a match return the first occurrence of SearchingString.\r
+ If the lenth of SearchString is zero,return String.\r
\r
**/\r
CHAR8 *\r
EFIAPI\r
AsciiStrStr (\r
- IN CONST CHAR8 *String,\r
- IN CONST CHAR8 *SearchString\r
+ IN CONST CHAR8 *String,\r
+ IN CONST CHAR8 *SearchString\r
);\r
\r
\r
PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
then ASSERT().\r
\r
- @param String Pointer to a Null-terminated ASCII string.\r
+ @param String Pointer to a Null-terminated ASCII string.\r
\r
@retval Value translated from String.\r
\r
PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
then ASSERT().\r
\r
- @param String Pointer to a Null-terminated ASCII string.\r
+ @param String Pointer to a Null-terminated ASCII string.\r
\r
@retval Value translated from String.\r
\r
UINT64\r
EFIAPI\r
AsciiStrDecimalToUint64 (\r
- IN CONST CHAR8 *String\r
+ IN CONST CHAR8 *String\r
);\r
\r
\r
and String contains more than PcdMaximumAsciiStringLength ASCII characters not including\r
the Null-terminator, then ASSERT().\r
\r
- @param String Pointer to a Null-terminated ASCII string.\r
+ @param String Pointer to a Null-terminated ASCII string.\r
\r
@retval Value translated from String.\r
\r
UINTN\r
EFIAPI\r
AsciiStrHexToUintn (\r
- IN CONST CHAR8 *String\r
+ IN CONST CHAR8 *String\r
);\r
\r
\r
and String contains more than PcdMaximumAsciiStringLength ASCII characters not including\r
the Null-terminator, then ASSERT().\r
\r
- @param String Pointer to a Null-terminated ASCII string.\r
+ @param String Pointer to a Null-terminated ASCII string.\r
\r
@retval Value translated from String.\r
\r
UINT64\r
EFIAPI\r
AsciiStrHexToUint64 (\r
- IN CONST CHAR8 *String\r
+ IN CONST CHAR8 *String\r
);\r
\r
\r
CHAR16 *\r
EFIAPI\r
AsciiStrToUnicodeStr (\r
- IN CONST CHAR8 *Source,\r
- OUT CHAR16 *Destination\r
+ IN CONST CHAR8 *Source,\r
+ OUT CHAR16 *Destination\r
);\r
\r
\r
@param ListHead The head note of a list to initiailize.\r
\r
**/\r
-#define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&ListHead, &ListHead}\r
+#define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}\r
\r
\r
/**\r
\r
If ListHead is NULL, then ASSERT().\r
If Entry is NULL, then ASSERT().\r
- If ListHead was not initialized with InitializeListHead(), then ASSERT().\r
+ If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
+ InitializeListHead(), then ASSERT().\r
If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number\r
of nodes in ListHead, including the ListHead node, is greater than or\r
equal to PcdMaximumLinkedListLength, then ASSERT().\r
\r
If ListHead is NULL, then ASSERT().\r
If Entry is NULL, then ASSERT().\r
- If ListHead was not initialized with InitializeListHead(), then ASSERT().\r
+ If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or \r
+ InitializeListHead(), then ASSERT().\r
If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number\r
of nodes in ListHead, including the ListHead node, is greater than or\r
equal to PcdMaximumLinkedListLength, then ASSERT().\r
/**\r
Retrieves the first node of a doubly linked list.\r
\r
- Returns the first node of a doubly linked list. List must have been\r
- initialized with InitializeListHead(). If List is empty, then NULL is\r
- returned.\r
+ Returns the first node of a doubly linked list. List must have been \r
+ initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
+ If List is empty, then List is returned.\r
\r
If List is NULL, then ASSERT().\r
- If List was not initialized with InitializeListHead(), then ASSERT().\r
+ If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or \r
+ InitializeListHead(), then ASSERT().\r
If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
in List, including the List node, is greater than or equal to\r
PcdMaximumLinkedListLength, then ASSERT().\r
/**\r
Retrieves the next node of a doubly linked list.\r
\r
- Returns the node of a doubly linked list that follows Node. List must have\r
- been initialized with InitializeListHead(). If List is empty, then List is\r
- returned.\r
+ Returns the node of a doubly linked list that follows Node. \r
+ List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()\r
+ or InitializeListHead(). If List is empty, then List is returned.\r
\r
If List is NULL, then ASSERT().\r
If Node is NULL, then ASSERT().\r
- If List was not initialized with InitializeListHead(), then ASSERT().\r
+ If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or \r
+ InitializeListHead(), then ASSERT().\r
If PcdMaximumLinkedListLenth is not zero, and List contains more than\r
PcdMaximumLinkedListLenth nodes, then ASSERT().\r
If Node is not a node in List, then ASSERT().\r
zero nodes, this function returns TRUE. Otherwise, it returns FALSE.\r
\r
If ListHead is NULL, then ASSERT().\r
- If ListHead was not initialized with InitializeListHead(), then ASSERT().\r
+ If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or \r
+ InitializeListHead(), then ASSERT().\r
If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
in List, including the List node, is greater than or equal to\r
PcdMaximumLinkedListLength, then ASSERT().\r
\r
Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the\r
nodes in the doubly linked list specified by List. List must have been\r
- initialized with InitializeListHead().\r
+ initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
\r
If List is NULL, then ASSERT().\r
If Node is NULL, then ASSERT().\r
- If List was not initialized with InitializeListHead(), then ASSERT().\r
+ If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), \r
+ then ASSERT().\r
If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
in List, including the List node, is greater than or equal to\r
PcdMaximumLinkedListLength, then ASSERT().\r
\r
Returns TRUE if Node is the last node in the doubly linked list specified by\r
List. Otherwise, FALSE is returned. List must have been initialized with\r
- InitializeListHead().\r
+ INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().\r
\r
If List is NULL, then ASSERT().\r
If Node is NULL, then ASSERT().\r
- If List was not initialized with InitializeListHead(), then ASSERT().\r
+ If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or\r
+ InitializeListHead(), then ASSERT().\r
If PcdMaximumLinkedListLenth is not zero, and the number of nodes\r
in List, including the List node, is greater than or equal to\r
PcdMaximumLinkedListLength, then ASSERT().\r
Otherwise, the location of the FirstEntry node is swapped with the location\r
of the SecondEntry node in a doubly linked list. SecondEntry must be in the\r
same double linked list as FirstEntry and that double linked list must have\r
- been initialized with InitializeListHead(). SecondEntry is returned after the\r
- nodes are swapped.\r
+ been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). \r
+ SecondEntry is returned after the nodes are swapped.\r
\r
If FirstEntry is NULL, then ASSERT().\r
If SecondEntry is NULL, then ASSERT().\r
@param Operand The 32-bit operand to rotate left.\r
@param Count The number of bits to rotate left.\r
\r
- @return Operand <<< Count\r
+ @return Operand << Count\r
\r
**/\r
UINT32\r
@param Operand The 64-bit operand to rotate left.\r
@param Count The number of bits to rotate left.\r
\r
- @return Operand <<< Count\r
+ @return Operand << Count\r
\r
**/\r
UINT64\r
@param Operand The 64-bit operand to rotate right.\r
@param Count The number of bits to rotate right.\r
\r
- @return Operand >>> Count\r
+ @return Operand >> Count\r
\r
**/\r
UINT64\r
\r
@param Operand The 32-bit operand to evaluate.\r
\r
- @return Position of the lowest bit set in Operand if found.\r
- @retval -1 Operand is zero.\r
+ @retval 0-31 The lowest bit set in Operand was found.\r
+ @retval -1 Operand is zero.\r
\r
**/\r
INTN\r
\r
@param Operand The 64-bit operand to evaluate.\r
\r
- @return Position of the lowest bit set in Operand if found.\r
- @retval -1 Operand is zero.\r
+ @retval 0-63 The lowest bit set in Operand was found.\r
+ @retval -1 Operand is zero.\r
+\r
\r
**/\r
INTN\r
\r
@param Operand The 32-bit operand to evaluate.\r
\r
- @return Position of the highest bit set in Operand if found.\r
- @retval -1 Operand is zero.\r
+ @retval 0-31 Position of the highest bit set in Operand if found.\r
+ @retval -1 Operand is zero.\r
\r
**/\r
INTN\r
\r
@param Operand The 64-bit operand to evaluate.\r
\r
- @return Position of the highest bit set in Operand if found.\r
- @retval -1 Operand is zero.\r
+ @retval 0-63 Position of the highest bit set in Operand if found.\r
+ @retval -1 Operand is zero.\r
\r
**/\r
INTN\r
\r
/**\r
Returns the value of the highest bit set in a 32-bit value. Equivalent to\r
- 1 << HighBitSet32(x).\r
+ 1 << log2(x).\r
\r
This function computes the value of the highest bit set in the 32-bit value\r
specified by Operand. If Operand is zero, then zero is returned.\r
\r
/**\r
Returns the value of the highest bit set in a 64-bit value. Equivalent to\r
- 1 << HighBitSet64(x).\r
+ 1 << log2(x).\r
\r
This function computes the value of the highest bit set in the 64-bit value\r
specified by Operand. If Operand is zero, then zero is returned.\r
\r
@param Value Operand A 16-bit unsigned value.\r
\r
- @return The byte swaped Operand.\r
+ @return The byte swapped Operand.\r
\r
**/\r
UINT16\r
\r
@param Value Operand A 32-bit unsigned value.\r
\r
- @return The byte swaped Operand.\r
+ @return The byte swapped Operand.\r
\r
**/\r
UINT32\r
\r
@param Value Operand A 64-bit unsigned value.\r
\r
- @return The byte swaped Operand.\r
+ @return The byte swapped Operand.\r
\r
**/\r
UINT64\r
NULL, then the 64-bit signed remainder is returned in Remainder. This\r
function returns the 64-bit signed quotient.\r
\r
+ It is the caller¡¯s responsibility to not call this function with a Divisor of 0.\r
+ If Divisor is 0, then the quotient and remainder should be assumed to be \r
+ the largest negative integer.\r
+\r
If Divisor is 0, then ASSERT().\r
\r
@param Dividend A 64-bit signed value.\r
SPIN_LOCK *\r
EFIAPI\r
InitializeSpinLock (\r
- IN SPIN_LOCK *SpinLock\r
+ OUT SPIN_LOCK *SpinLock\r
);\r
\r
\r
//\r
\r
/**\r
- Calculate the sum of all elements in a buffer in unit of UINT8.\r
+ Returns the sum of all elements in a buffer in unit of UINT8.\r
During calculation, the carry bits are dropped.\r
\r
This function calculates the sum of all elements in a buffer\r
If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().\r
\r
@param Buffer Pointer to the buffer to carry out the sum operation.\r
- @param Length The size, in bytes, of Buffer .\r
+ @param Length The size, in bytes, of Buffer.\r
\r
@return Sum The sum of Buffer with carry bits dropped during additions.\r
\r
UINT8\r
EFIAPI\r
CalculateSum8 (\r
- IN CONST UINT8 *Buffer,\r
- IN UINTN Length\r
+ IN CONST UINT8 *Buffer,\r
+ IN UINTN Length\r
);\r
\r
\r
@param Buffer Pointer to the buffer to carry out the checksum operation.\r
@param Length The size, in bytes, of Buffer.\r
\r
- @return Checksum The 2's complement checksum of Buffer.\r
+ @return Checksum The 2's complement checksum of Buffer.\r
\r
**/\r
UINT8\r
EFIAPI\r
CalculateCheckSum8 (\r
- IN CONST UINT8 *Buffer,\r
- IN UINTN Length\r
+ IN CONST UINT8 *Buffer,\r
+ IN UINTN Length\r
);\r
\r
\r
UINT16\r
EFIAPI\r
CalculateSum16 (\r
- IN CONST UINT16 *Buffer,\r
- IN UINTN Length\r
+ IN CONST UINT16 *Buffer,\r
+ IN UINTN Length\r
);\r
\r
\r
@param Buffer Pointer to the buffer to carry out the checksum operation.\r
@param Length The size, in bytes, of Buffer.\r
\r
- @return Checksum The 2's complement checksum of Buffer.\r
+ @return Checksum The 2's complement checksum of Buffer.\r
\r
**/\r
UINT16\r
EFIAPI\r
CalculateCheckSum16 (\r
- IN CONST UINT16 *Buffer,\r
- IN UINTN Length\r
+ IN CONST UINT16 *Buffer,\r
+ IN UINTN Length\r
);\r
\r
\r
/**\r
- Returns the sum of all elements in a buffer of 32-bit values. During\r
+ Returns the sum of all elements in a buffer of 32-bit values. During\r
calculation, the carry bits are dropped.\r
\r
This function calculates the sum of the 32-bit values in the buffer\r
specified by Buffer and Length. The carry bits in result of addition are dropped.\r
- The 32-bit result is returned. If Length is 0, then 0 is returned.\r
+ The 32-bit result is returned. If Length is 0, then 0 is returned.\r
\r
If Buffer is NULL, then ASSERT().\r
If Buffer is not aligned on a 32-bit boundary, then ASSERT().\r
UINT32\r
EFIAPI\r
CalculateSum32 (\r
- IN CONST UINT32 *Buffer,\r
- IN UINTN Length\r
+ IN CONST UINT32 *Buffer,\r
+ IN UINTN Length\r
);\r
\r
\r
@param Buffer Pointer to the buffer to carry out the checksum operation.\r
@param Length The size, in bytes, of Buffer.\r
\r
- @return Checksum The 2's complement checksum of Buffer.\r
+ @return Checksum The 2's complement checksum of Buffer.\r
\r
**/\r
UINT32\r
EFIAPI\r
CalculateCheckSum32 (\r
- IN CONST UINT32 *Buffer,\r
- IN UINTN Length\r
+ IN CONST UINT32 *Buffer,\r
+ IN UINTN Length\r
);\r
\r
\r
UINT64\r
EFIAPI\r
CalculateSum64 (\r
- IN CONST UINT64 *Buffer,\r
- IN UINTN Length\r
+ IN CONST UINT64 *Buffer,\r
+ IN UINTN Length\r
);\r
\r
\r
@param Buffer Pointer to the buffer to carry out the checksum operation.\r
@param Length The size, in bytes, of Buffer.\r
\r
- @return Checksum The 2's complement checksum of Buffer.\r
+ @return Checksum The 2's complement checksum of Buffer.\r
\r
**/\r
UINT64\r
EFIAPI\r
CalculateCheckSum64 (\r
- IN CONST UINT64 *Buffer,\r
- IN UINTN Length\r
+ IN CONST UINT64 *Buffer,\r
+ IN UINTN Length\r
);\r
\r
\r
\r
If JumpBuffer is NULL, then ASSERT().\r
For IPF CPUs, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().\r
+ \r
+ NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.\r
+ The same structure must never be used for more than one CPU architecture context.\r
+ For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module. \r
+ SetJump()/LongJump() is not currently supported for the EBC processor type. \r
\r
@param JumpBuffer A pointer to CPU context buffer.\r
\r
function.\r
@param NewStack A pointer to the new stack to use for the EntryPoint\r
function.\r
- @param ... Extended parameters.\r
+ @param ... This variable argument list is ignored for IA32, x64, and EBC. \r
+ For IPF, this variable argument list is expected to contain \r
+ a single parameter of type VOID * that specifies the new backing \r
+ store pointer.\r
\r
\r
**/\r
VOID\r
);\r
\r
-\r
#if defined (MDE_CPU_IPF)\r
\r
/**\r
The cache line size affected is at least 32-bytes (aligned on a 32-byte boundary).\r
An implementation may flush a larger region. This function is only available on IPF.\r
\r
- @param Address The Address of cache line to be flushed.\r
+ @param Address The Address of cache line to be flushed.\r
\r
@return The address of FC instruction executed.\r
\r
The cache line size affected is at least 32-bytes (aligned on a 32-byte boundary).\r
An implementation may flush a larger region. This function is only available on IPF.\r
\r
- @param Address The Address of cache line to be flushed.\r
+ @param Address The Address of cache line to be flushed.\r
\r
@return The address of FC.I instruction executed.\r
\r
\r
/**\r
Reads the current value of a Processor Identifier Register (CPUID).\r
+ \r
+ Reads and returns the current value of Processor Identifier Register specified by Index. \r
The Index of largest implemented CPUID (One less than the number of implemented CPUID\r
registers) is determined by CPUID [3] bits {7:0}.\r
No parameter checking is performed on Index. If the Index value is beyond the\r
must either guarantee that Index is valid, or the caller must set up fault handlers to\r
catch the faults. This function is only available on IPF.\r
\r
- @param Index The 8-bit Processor Identifier Register index to read.\r
+ @param Index The 8-bit Processor Identifier Register index to read.\r
\r
@return The current value of Processor Identifier Register specified by Index.\r
\r
\r
/**\r
Writes the current value of 64-bit Processor Status Register (PSR).\r
+\r
No parameter checking is performed on Value. All bits of Value corresponding to\r
- 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.\r
- This function is only available on IPF.\r
+ reserved fields of PSR must be 0 or a Reserved Register/Field fault may occur.\r
+ The caller must either guarantee that Value is valid, or the caller must set up\r
+ fault handlers to catch the faults. This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to PSR.\r
+ @param Value The 64-bit value to write to PSR.\r
\r
@return The 64-bit value written to the PSR.\r
\r
Write the current value of 64-bit Kernel Register #0 (KR0).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to KR0.\r
+ @param Value The 64-bit value to write to KR0.\r
\r
@return The 64-bit value written to the KR0.\r
\r
Write the current value of 64-bit Kernel Register #1 (KR1).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to KR1.\r
+ @param Value The 64-bit value to write to KR1.\r
\r
@return The 64-bit value written to the KR1.\r
\r
Write the current value of 64-bit Kernel Register #2 (KR2).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to KR2.\r
+ @param Value The 64-bit value to write to KR2.\r
\r
@return The 64-bit value written to the KR2.\r
\r
Write the current value of 64-bit Kernel Register #3 (KR3).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to KR3.\r
+ @param Value The 64-bit value to write to KR3.\r
\r
@return The 64-bit value written to the KR3.\r
\r
Write the current value of 64-bit Kernel Register #4 (KR4).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to KR4.\r
+ @param Value The 64-bit value to write to KR4.\r
\r
@return The 64-bit value written to the KR4.\r
\r
Write the current value of 64-bit Kernel Register #5 (KR5).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to KR5.\r
+ @param Value The 64-bit value to write to KR5.\r
\r
@return The 64-bit value written to the KR5.\r
\r
Write the current value of 64-bit Kernel Register #6 (KR6).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to KR6.\r
+ @param Value The 64-bit value to write to KR6.\r
\r
@return The 64-bit value written to the KR6.\r
\r
Write the current value of 64-bit Kernel Register #7 (KR7).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to KR7.\r
+ @param Value The 64-bit value to write to KR7.\r
\r
@return The 64-bit value written to the KR7.\r
\r
Writes the current value of 64-bit Interval Timer Counter Register (ITC).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to ITC.\r
+ @param Value The 64-bit value to write to ITC.\r
\r
@return The 64-bit value written to the ITC.\r
\r
Writes the current value of 64-bit Interval Timer Match Register (ITM).\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to ITM.\r
+ @param Value The 64-bit value to write to ITM.\r
\r
@return The 64-bit value written to the ITM.\r
\r
fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to ITV.\r
+ @param Value The 64-bit value to write to ITV.\r
\r
@return The 64-bit value written to the ITV.\r
\r
fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to DCR.\r
+ @param Value The 64-bit value to write to DCR.\r
\r
@return The 64-bit value written to the DCR.\r
\r
the low 15 bits of Value is ignored when written.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to IVA.\r
+ @param Value The 64-bit value to write to IVA.\r
\r
@return The 64-bit value written to the IVA.\r
\r
fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to PTA.\r
+ @param Value The 64-bit value to write to PTA.\r
\r
@return The 64-bit value written to the PTA.\r
**/\r
fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to LID.\r
+ @param Value The 64-bit value to write to LID.\r
\r
@return The 64-bit value written to the LID.\r
\r
fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to TPR.\r
+ @param Value The 64-bit value to write to TPR.\r
\r
@return The 64-bit value written to the TPR.\r
\r
fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to PMV.\r
+ @param Value The 64-bit value to write to PMV.\r
\r
@return The 64-bit value written to the PMV.\r
\r
fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to CMCV.\r
+ @param Value The 64-bit value to write to CMCV.\r
\r
@return The 64-bit value written to the CMCV.\r
\r
fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to LRR0.\r
+ @param Value The 64-bit value to write to LRR0.\r
\r
@return The 64-bit value written to the LRR0.\r
\r
set up fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Value The 64-bit value to write to LRR1.\r
+ @param Value The 64-bit value to write to LRR1.\r
\r
@return The 64-bit value written to the LRR1.\r
\r
set up fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Index The 8-bit Instruction Breakpoint Register index to read.\r
+ @param Index The 8-bit Instruction Breakpoint Register index to read.\r
\r
@return The current value of Instruction Breakpoint Register specified by Index.\r
\r
fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Index The 8-bit Data Breakpoint Register index to read.\r
+ @param Index The 8-bit Data Breakpoint Register index to read.\r
\r
@return The current value of Data Breakpoint Register specified by Index.\r
\r
zero value will be returned.\r
This function is only available on IPF.\r
\r
- @param Index The 8-bit Performance Monitor Configuration Register index to read.\r
+ @param Index The 8-bit Performance Monitor Configuration Register index to read.\r
\r
@return The current value of Performance Monitor Configuration Register\r
specified by Index.\r
zero value will be returned.\r
This function is only available on IPF.\r
\r
- @param Index The 8-bit Performance Monitor Data Register index to read.\r
+ @param Index The 8-bit Performance Monitor Data Register index to read.\r
\r
@return The current value of Performance Monitor Data Register specified by Index.\r
\r
set up fault handlers to catch the faults.\r
This function is only available on IPF.\r
\r
- @param Index The 8-bit Instruction Breakpoint Register index to write.\r
- @param Value The 64-bit value to write to IBR.\r
+ @param Index The 8-bit Instruction Breakpoint Register index to write.\r
+ @param Value The 64-bit value to write to IBR.\r
\r
@return The 64-bit value written to the IBR.\r
\r
catch the faults.\r
This function is only available on IPF.\r
\r
- @param Index The 8-bit Data Breakpoint Register index to write.\r
- @param Value The 64-bit value to write to DBR.\r
+ @param Index The 8-bit Data Breakpoint Register index to write.\r
+ @param Value The 64-bit value to write to DBR.\r
\r
@return The 64-bit value written to the DBR.\r
\r
beyond the implemented PMC register range, the write is ignored.\r
This function is only available on IPF.\r
\r
- @param Index The 8-bit Performance Monitor Configuration Register index to write.\r
- @param Value The 64-bit value to write to PMC.\r
+ @param Index The 8-bit Performance Monitor Configuration Register index to write.\r
+ @param Value The 64-bit value to write to PMC.\r
\r
@return The 64-bit value written to the PMC.\r
\r
Index value is beyond the implemented PMD register range, the write is ignored.\r
This function is only available on IPF.\r
\r
- @param Index The 8-bit Performance Monitor Data Register index to write.\r
- @param Value The 64-bit value to write to PMD.\r
+ @param Index The 8-bit Performance Monitor Data Register index to write.\r
+ @param Value The 64-bit value to write to PMD.\r
\r
@return The 64-bit value written to the PMD.\r
\r
and -1 is returned.\r
This function is only available on IPF.\r
\r
- @return 1 The CPU is in virtual mode.\r
- @return 0 The CPU is in physical mode.\r
- @return -1 The CPU is in mixed mode.\r
+ @retval 1 The CPU is in virtual mode.\r
+ @retval 0 The CPU is in physical mode.\r
+ @retval -1 The CPU is in mixed mode.\r
\r
**/\r
INT64\r
PAL entry point then the system behavior is undefined. This function is only\r
available on IPF.\r
\r
- @param PalEntryPoint The PAL procedure calls entry point.\r
- @param Index The PAL procedure Index number.\r
- @param Arg2 The 2nd parameter for PAL procedure calls.\r
- @param Arg3 The 3rd parameter for PAL procedure calls.\r
- @param Arg4 The 4th parameter for PAL procedure calls.\r
+ @param PalEntryPoint The PAL procedure calls entry point.\r
+ @param Index The PAL procedure Index number.\r
+ @param Arg2 The 2nd parameter for PAL procedure calls.\r
+ @param Arg3 The 3rd parameter for PAL procedure calls.\r
+ @param Arg4 The 4th parameter for PAL procedure calls.\r
\r
@return structure returned from the PAL Call procedure, including the status and return value.\r
\r
);\r
\r
\r
+\r
#elif defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)\r
///\r
/// IA32 and X64 Specific Functions\r
\r
\r
/**\r
- Zero-extend a 32-bit value and writes it to a Machine Specific Register(MSR).\r
+ Writes a 32-bit value to a Machine Specific Register(MSR), and returns the value.\r
+ The upper 32-bits of the MSR are set to zero.\r
\r
Writes the 32-bit value specified by Value to the MSR specified by Index. The\r
upper 32-bits of the MSR write are set to zero. The 32-bit value written to\r
\r
\r
/**\r
- Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.\r
+ Reads the current Interrupt Descriptor Table Register(IDTR) descriptor.\r
\r
Reads and returns the current IDTR descriptor and returns it in Idtr. This\r
function is only available on IA-32 and X64.\r
\r
\r
/**\r
- Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.\r
+ Writes the current Interrupt Descriptor Table Register(IDTR) descriptor.\r
\r
Writes the current IDTR descriptor and returns it in Idtr. This function is\r
only available on IA-32 and X64.\r
\r
\r
/**\r
- Writes the current Local Descriptor Table Register (GDTR) selector.\r
+ Writes the current Local Descriptor Table Register (LDTR) selector.\r
\r
Writes and the current LDTR descriptor specified by Ldtr. This function is\r
only available on IA-32 and X64.\r
If EntryPoint is 0, then ASSERT().\r
If NewStack is 0, then ASSERT().\r
\r
- @param CodeSelector The 16-bit selector to load in the CS before EntryPoint\r
+ @param Cs The 16-bit selector to load in the CS before EntryPoint\r
is called. The descriptor in the GDT that this selector\r
references must be setup for long mode.\r
@param EntryPoint The 64-bit virtual address of the function to call with\r
VOID\r
EFIAPI\r
AsmEnablePaging64 (\r
- IN UINT16 CodeSelector,\r
+ IN UINT16 Cs,\r
IN UINT64 EntryPoint,\r
IN UINT64 Context1, OPTIONAL\r
IN UINT64 Context2, OPTIONAL\r
If EntryPoint is 0, then ASSERT().\r
If NewStack is 0, then ASSERT().\r
\r
- @param CodeSelector The 16-bit selector to load in the CS before EntryPoint\r
+ @param Cs The 16-bit selector to load in the CS before EntryPoint\r
is called. The descriptor in the GDT that this selector\r
references must be setup for 32-bit protected mode.\r
@param EntryPoint The 64-bit virtual address of the function to call with\r
VOID\r
EFIAPI\r
AsmDisablePaging64 (\r
- IN UINT16 CodeSelector,\r
+ IN UINT16 Cs,\r
IN UINT32 EntryPoint,\r
IN UINT32 Context1, OPTIONAL\r
IN UINT32 Context2, OPTIONAL\r
Transfers control to a 16-bit real mode entry point and returns the results.\r
\r
Transfers control to a 16-bit real mode entry point and returns the results.\r
- AsmPrepareThunk16() must be called with ThunkContext before this function is\r
- used.\r
-\r
+ AsmPrepareThunk16() must be called with ThunkContext before this function is used.\r
+ This function must be called with interrupts disabled.\r
+\r
+ The register state from the RealModeState field of ThunkContext is restored just prior \r
+ to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState, \r
+ which is used to set the interrupt state when a 16-bit real mode entry point is called.\r
+ Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState.\r
+ The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to \r
+ the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function. \r
+ The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction,\r
+ so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment \r
+ and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry \r
+ point must exit with a RETF instruction. The register state is captured into RealModeState immediately \r
+ after the RETF instruction is executed.\r
+ \r
+ If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, \r
+ or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure \r
+ the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode. \r
+ \r
+ If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, \r
+ then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode. \r
+ This includes the base vectors, the interrupt masks, and the edge/level trigger mode.\r
+ \r
+ If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code \r
+ is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits.\r
+ \r
+ If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in \r
+ ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to \r
+ disable the A20 mask.\r
+ \r
+ If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in \r
+ ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails, \r
+ then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.\r
+ \r
+ If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in \r
+ ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports.\r
+ \r
If ThunkContext is NULL, then ASSERT().\r
If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT().\r
+ If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in \r
+ ThunkAttributes, then ASSERT().\r
\r
@param ThunkContext A pointer to the context structure that describes the\r
16-bit real mode code to call.\r
real mode thunk, then it is more efficient if AsmPrepareThunk16() is called\r
once and AsmThunk16() can be called for each 16-bit real mode thunk.\r
\r
- If ThunkContext is NULL, then ASSERT().\r
+ See AsmPrepareThunk16() and AsmThunk16() for the detailed description and ASSERT() conditions.\r
\r
@param ThunkContext A pointer to the context structure that describes the\r
16-bit real mode code to call.\r
projects / mirror_edk2.git / blobdiff