diff options
Diffstat (limited to 'MdePkg/Include/Library')
68 files changed, 8468 insertions, 4413 deletions
diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h index b41c10b1b661..762cb9ac3abb 100644 --- a/MdePkg/Include/Library/BaseLib.h +++ b/MdePkg/Include/Library/BaseLib.h @@ -2,15 +2,12 @@ Provides string functions, linked list functions, math functions, synchronization functions, file path functions, and CPU architecture-specific functions. -Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR> +Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR> Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR> -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) Microsoft Corporation.<BR> +Portions Copyright (c) 2020, Hewlett Packard Enterprise Development LP. All rights reserved.<BR> -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -31,62 +28,13 @@ typedef struct { UINT32 Ebp; UINT32 Esp; UINT32 Eip; + UINT32 Ssp; } BASE_LIBRARY_JUMP_BUFFER; #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4 #endif // defined (MDE_CPU_IA32) -#if defined (MDE_CPU_IPF) - -/// -/// The Itanium architecture context buffer used by SetJump() and LongJump(). -/// -typedef struct { - UINT64 F2[2]; - UINT64 F3[2]; - UINT64 F4[2]; - UINT64 F5[2]; - UINT64 F16[2]; - UINT64 F17[2]; - UINT64 F18[2]; - UINT64 F19[2]; - UINT64 F20[2]; - UINT64 F21[2]; - UINT64 F22[2]; - UINT64 F23[2]; - UINT64 F24[2]; - UINT64 F25[2]; - UINT64 F26[2]; - UINT64 F27[2]; - UINT64 F28[2]; - UINT64 F29[2]; - UINT64 F30[2]; - UINT64 F31[2]; - UINT64 R4; - UINT64 R5; - UINT64 R6; - UINT64 R7; - UINT64 SP; - UINT64 BR0; - UINT64 BR1; - UINT64 BR2; - UINT64 BR3; - UINT64 BR4; - UINT64 BR5; - UINT64 InitialUNAT; - UINT64 AfterSpillUNAT; - UINT64 PFS; - UINT64 BSP; - UINT64 Predicates; - UINT64 LoopCount; - UINT64 FPSR; -} BASE_LIBRARY_JUMP_BUFFER; - -#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10 - -#endif // defined (MDE_CPU_IPF) - #if defined (MDE_CPU_X64) /// /// The x64 architecture context buffer used by SetJump() and LongJump(). @@ -104,6 +52,7 @@ typedef struct { UINT64 Rip; UINT64 MxCsr; UINT8 XmmBuffer[160]; ///< XMM6-XMM15. + UINT64 Ssp; } BASE_LIBRARY_JUMP_BUFFER; #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 @@ -178,6 +127,30 @@ typedef struct { #endif // defined (MDE_CPU_AARCH64) +#if defined (MDE_CPU_RISCV64) +/// +/// The RISC-V architecture context buffer used by SetJump() and LongJump(). +/// +typedef struct { + UINT64 RA; + UINT64 S0; + UINT64 S1; + UINT64 S2; + UINT64 S3; + UINT64 S4; + UINT64 S5; + UINT64 S6; + UINT64 S7; + UINT64 S8; + UINT64 S9; + UINT64 S10; + UINT64 S11; + UINT64 SP; +} BASE_LIBRARY_JUMP_BUFFER; + +#define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8 + +#endif // defined (MDE_CPU_RISCV64) // // String Services @@ -243,7 +216,6 @@ StrnSizeS ( If Destination is not aligned on a 16-bit boundary, then ASSERT(). If Source is not aligned on a 16-bit boundary, then ASSERT(). - If an error would be returned, then the function will also ASSERT(). If an error is returned, then the Destination is unmodified. @@ -257,7 +229,7 @@ StrnSizeS ( @retval RETURN_INVALID_PARAMETER If Destination is NULL. If Source is NULL. If PcdMaximumUnicodeStringLength is not zero, - and DestMax is greater than + and DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0. @retval RETURN_ACCESS_DENIED If Source and Destination overlap. @@ -279,7 +251,6 @@ StrCpyS ( If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT(). If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT(). - If an error would be returned, then the function will also ASSERT(). If an error is returned, then the Destination is unmodified. @@ -290,12 +261,12 @@ StrCpyS ( @param Length The maximum number of Unicode characters to copy. @retval RETURN_SUCCESS String is copied. - @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than + @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than MIN(StrLen(Source), Length). @retval RETURN_INVALID_PARAMETER If Destination is NULL. If Source is NULL. If PcdMaximumUnicodeStringLength is not zero, - and DestMax is greater than + and DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0. @retval RETURN_ACCESS_DENIED If Source and Destination overlap. @@ -317,7 +288,6 @@ StrnCpyS ( If Destination is not aligned on a 16-bit boundary, then ASSERT(). If Source is not aligned on a 16-bit boundary, then ASSERT(). - If an error would be returned, then the function will also ASSERT(). If an error is returned, then the Destination is unmodified. @@ -327,14 +297,14 @@ StrnCpyS ( @param Source A pointer to a Null-terminated Unicode string. @retval RETURN_SUCCESS String is appended. - @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than + @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than StrLen(Destination). @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT greater than StrLen(Source). @retval RETURN_INVALID_PARAMETER If Destination is NULL. If Source is NULL. If PcdMaximumUnicodeStringLength is not zero, - and DestMax is greater than + and DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0. @retval RETURN_ACCESS_DENIED If Source and Destination overlap. @@ -357,7 +327,6 @@ StrCatS ( If Destination is not aligned on a 16-bit boundary, then ASSERT(). If Source is not aligned on a 16-bit boundary, then ASSERT(). - If an error would be returned, then the function will also ASSERT(). If an error is returned, then the Destination is unmodified. @@ -375,7 +344,7 @@ StrCatS ( @retval RETURN_INVALID_PARAMETER If Destination is NULL. If Source is NULL. If PcdMaximumUnicodeStringLength is not zero, - and DestMax is greater than + and DestMax is greater than PcdMaximumUnicodeStringLength. If DestMax is 0. @retval RETURN_ACCESS_DENIED If Source and Destination overlap. @@ -404,12 +373,7 @@ StrnCatS ( 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 Data is NULL, then ASSERT(). If String is not aligned in a 16-bit boundary, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and String contains more than - PcdMaximumUnicodeStringLength Unicode characters, not including the - Null-terminator, then ASSERT(). If String has no valid decimal digits in the above format, then 0 is stored at the location pointed to by Data. @@ -460,12 +424,7 @@ StrDecimalToUintnS ( 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 Data is NULL, then ASSERT(). If String is not aligned in a 16-bit boundary, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and String contains more than - PcdMaximumUnicodeStringLength Unicode characters, not including the - Null-terminator, then ASSERT(). If String has no valid decimal digits in the above format, then 0 is stored at the location pointed to by Data. @@ -521,12 +480,7 @@ StrDecimalToUint64S ( the first character that is a not a valid hexadecimal character or NULL, whichever one comes first. - If String is NULL, then ASSERT(). - If Data is NULL, then ASSERT(). If String is not aligned in a 16-bit boundary, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and String contains more than - PcdMaximumUnicodeStringLength Unicode characters, not including the - Null-terminator, then ASSERT(). If String has no valid hexadecimal digits in the above format, then 0 is stored at the location pointed to by Data. @@ -582,12 +536,7 @@ StrHexToUintnS ( the first character that is a not a valid hexadecimal character or NULL, whichever one comes first. - If String is NULL, then ASSERT(). - If Data is NULL, then ASSERT(). If String is not aligned in a 16-bit boundary, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and String contains more than - PcdMaximumUnicodeStringLength Unicode characters, not including the - Null-terminator, then ASSERT(). If String has no valid hexadecimal digits in the above format, then 0 is stored at the location pointed to by Data. @@ -676,8 +625,6 @@ AsciiStrnSizeS ( This function is similar as strcpy_s defined in C11. - If an error would be returned, then the function will also ASSERT(). - If an error is returned, then the Destination is unmodified. @param Destination A pointer to a Null-terminated Ascii string. @@ -690,7 +637,7 @@ AsciiStrnSizeS ( @retval RETURN_INVALID_PARAMETER If Destination is NULL. If Source is NULL. If PcdMaximumAsciiStringLength is not zero, - and DestMax is greater than + and DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0. @retval RETURN_ACCESS_DENIED If Source and Destination overlap. @@ -710,8 +657,6 @@ AsciiStrCpyS ( This function is similar as strncpy_s defined in C11. - If an error would be returned, then the function will also ASSERT(). - If an error is returned, then the Destination is unmodified. @param Destination A pointer to a Null-terminated Ascii string. @@ -721,12 +666,12 @@ AsciiStrCpyS ( @param Length The maximum number of Ascii characters to copy. @retval RETURN_SUCCESS String is copied. - @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than + @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than MIN(StrLen(Source), Length). @retval RETURN_INVALID_PARAMETER If Destination is NULL. If Source is NULL. If PcdMaximumAsciiStringLength is not zero, - and DestMax is greater than + and DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0. @retval RETURN_ACCESS_DENIED If Source and Destination overlap. @@ -746,8 +691,6 @@ AsciiStrnCpyS ( This function is similar as strcat_s defined in C11. - If an error would be returned, then the function will also ASSERT(). - If an error is returned, then the Destination is unmodified. @param Destination A pointer to a Null-terminated Ascii string. @@ -756,14 +699,14 @@ AsciiStrnCpyS ( @param Source A pointer to a Null-terminated Ascii string. @retval RETURN_SUCCESS String is appended. - @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than + @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than StrLen(Destination). @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT greater than StrLen(Source). @retval RETURN_INVALID_PARAMETER If Destination is NULL. If Source is NULL. If PcdMaximumAsciiStringLength is not zero, - and DestMax is greater than + and DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0. @retval RETURN_ACCESS_DENIED If Source and Destination overlap. @@ -784,8 +727,6 @@ AsciiStrCatS ( This function is similar as strncat_s defined in C11. - If an error would be returned, then the function will also ASSERT(). - If an error is returned, then the Destination is unmodified. @param Destination A pointer to a Null-terminated Ascii string. @@ -802,7 +743,7 @@ AsciiStrCatS ( @retval RETURN_INVALID_PARAMETER If Destination is NULL. If Source is NULL. If PcdMaximumAsciiStringLength is not zero, - and DestMax is greater than + and DestMax is greater than PcdMaximumAsciiStringLength. If DestMax is 0. @retval RETURN_ACCESS_DENIED If Source and Destination overlap. @@ -831,12 +772,6 @@ AsciiStrnCatS ( 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 Data is NULL, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and String contains more than - PcdMaximumAsciiStringLength Ascii characters, not including the - Null-terminator, then ASSERT(). - If String has no valid decimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINTN, then @@ -886,12 +821,6 @@ AsciiStrDecimalToUintnS ( 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 Data is NULL, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and String contains more than - PcdMaximumAsciiStringLength Ascii characters, not including the - Null-terminator, then ASSERT(). - If String has no valid decimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINT64, then @@ -945,12 +874,6 @@ AsciiStrDecimalToUint64S ( character that is a not a valid hexadecimal character or Null-terminator, whichever on comes first. - If String is NULL, then ASSERT(). - If Data is NULL, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and String contains more than - PcdMaximumAsciiStringLength Ascii characters, not including the - Null-terminator, then ASSERT(). - If String has no valid hexadecimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINTN, then @@ -1004,12 +927,6 @@ AsciiStrHexToUintnS ( character that is a not a valid hexadecimal character or Null-terminator, whichever on comes first. - If String is NULL, then ASSERT(). - If Data is NULL, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and String contains more than - PcdMaximumAsciiStringLength Ascii characters, not including the - Null-terminator, then ASSERT(). - If String has no valid hexadecimal digits in the above format, then 0 is stored at the location pointed to by Data. If the number represented by String exceeds the range defined by UINT64, then @@ -1083,7 +1000,7 @@ StrCpy ( /** [ATTENTION] This function is deprecated for security reason. - Copies up to a specified length from one Null-terminated Unicode string to + Copies up to a specified length from one Null-terminated Unicode string to another Null-terminated Unicode string and returns the new Unicode string. This function copies the contents of the Unicode string Source to the Unicode @@ -1099,7 +1016,7 @@ StrCpy ( 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 Length is greater than + If PcdMaximumUnicodeStringLength is not zero, and Length is greater than PcdMaximumUnicodeStringLength, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and Source contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator, @@ -1119,7 +1036,7 @@ StrnCpy ( IN CONST CHAR16 *Source, IN UINTN Length ); -#endif +#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES) /** Returns the length of a Null-terminated Unicode string. @@ -1149,7 +1066,7 @@ StrLen ( Returns the size of a Null-terminated Unicode string in bytes, including the Null terminator. - This function returns the size, in bytes, of the Null-terminated Unicode string + This function returns the size, in bytes, of the Null-terminated Unicode string specified by String. If String is NULL, then ASSERT(). @@ -1209,7 +1126,7 @@ StrCmp ( /** Compares up to a specified length the contents of two Null-terminated Unicode strings, and returns the difference between the first mismatched Unicode characters. - + This function compares the Null-terminated Unicode string FirstString to the Null-terminated Unicode string SecondString. At most, Length Unicode characters will be compared. If Length is 0, then 0 is returned. If @@ -1294,8 +1211,8 @@ StrCat ( /** [ATTENTION] This function is deprecated for security reason. - Concatenates up to a specified length one Null-terminated Unicode to the end - of another Null-terminated Unicode string, and returns the concatenated + Concatenates up to a specified length one Null-terminated Unicode to the end + of another Null-terminated Unicode string, and returns the concatenated Unicode string. This function concatenates two Null-terminated Unicode strings. The contents @@ -1311,7 +1228,7 @@ StrCat ( 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 Length is greater than + If PcdMaximumUnicodeStringLength is not zero, and Length is greater than PcdMaximumUnicodeStringLength, then ASSERT(). If PcdMaximumUnicodeStringLength is not zero, and Destination contains more than PcdMaximumUnicodeStringLength Unicode characters, not including the @@ -1338,7 +1255,7 @@ StrnCat ( IN CONST CHAR16 *Source, IN UINTN Length ); -#endif +#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES) /** Returns the first occurrence of a Null-terminated Unicode sub-string @@ -1451,7 +1368,7 @@ EFIAPI StrDecimalToUint64 ( IN CONST CHAR16 *String ); - + /** Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN. @@ -1468,7 +1385,7 @@ StrDecimalToUint64 ( 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 + 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(). @@ -1560,16 +1477,8 @@ StrHexToUint64 ( "::" can be used to compress one or more groups of X when X contains only 0. The "::" can only appear once in the String. - If String is NULL, then ASSERT(). - - If Address is NULL, then ASSERT(). - If String is not aligned in a 16-bit boundary, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and String contains more than - PcdMaximumUnicodeStringLength Unicode characters, not including the - Null-terminator, then ASSERT(). - If EndPointer is not NULL and Address is translated from String, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. @@ -1621,16 +1530,8 @@ StrToIpv6Address ( When /P is in the String, the function stops at the first character that is not a valid decimal digit character after P is converted. - If String is NULL, then ASSERT(). - - If Address is NULL, then ASSERT(). - If String is not aligned in a 16-bit boundary, then ASSERT(). - If PcdMaximumUnicodeStringLength is not zero, and String contains more than - PcdMaximumUnicodeStringLength Unicode characters, not including the - Null-terminator, then ASSERT(). - If EndPointer is not NULL and Address is translated from String, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. @@ -1694,8 +1595,6 @@ StrToIpv4Address ( oo Data4[48:55] pp Data4[56:63] - If String is NULL, then ASSERT(). - If Guid is NULL, then ASSERT(). If String is not aligned in a 16-bit boundary, then ASSERT(). @param String Pointer to a Null-terminated Unicode string. @@ -1730,17 +1629,6 @@ StrToGuid ( If String is not aligned in a 16-bit boundary, then ASSERT(). - If String is NULL, then ASSERT(). - - If Buffer is NULL, then ASSERT(). - - If Length is not multiple of 2, then ASSERT(). - - If PcdMaximumUnicodeStringLength is not zero and Length is greater than - PcdMaximumUnicodeStringLength, then ASSERT(). - - If MaxBufferSize is less than (Length / 2), then ASSERT(). - @param String Pointer to a Null-terminated Unicode string. @param Length The number of Unicode characters to decode. @param Buffer Pointer to the converted bytes array. @@ -1811,7 +1699,7 @@ UnicodeStrToAsciiStr ( OUT CHAR8 *Destination ); -#endif +#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES) /** Convert a Null-terminated Unicode string to a Null-terminated @@ -1831,7 +1719,6 @@ UnicodeStrToAsciiStr ( the upper 8 bits, then ASSERT(). If Source is not aligned on a 16-bit boundary, then ASSERT(). - If an error would be returned, then the function will also ASSERT(). If an error is returned, then the Destination is unmodified. @@ -1878,7 +1765,6 @@ UnicodeStrToAsciiStrS ( If any Unicode characters in Source contain non-zero value in the upper 8 bits, then ASSERT(). If Source is not aligned on a 16-bit boundary, then ASSERT(). - If an error would be returned, then the function will also ASSERT(). If an error is returned, then the Destination is unmodified. @@ -1952,7 +1838,7 @@ AsciiStrCpy ( /** [ATTENTION] This function is deprecated for security reason. - Copies up to a specified length one Null-terminated ASCII string to another + Copies up to a specified length one Null-terminated ASCII string to another Null-terminated ASCII string and returns the new ASCII string. This function copies the contents of the ASCII string Source to the ASCII @@ -1965,7 +1851,7 @@ AsciiStrCpy ( If Destination is NULL, then ASSERT(). If Source is NULL, then ASSERT(). If Source and Destination overlap, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and Length is greater than + If PcdMaximumAsciiStringLength is not zero, and Length is greater than PcdMaximumAsciiStringLength, then ASSERT(). If PcdMaximumAsciiStringLength is not zero, and Source contains more than PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, @@ -1985,7 +1871,7 @@ AsciiStrnCpy ( IN CONST CHAR8 *Source, IN UINTN Length ); -#endif +#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES) /** Returns the length of a Null-terminated ASCII string. @@ -2119,7 +2005,7 @@ AsciiStriCmp ( If Length > 0 and FirstString is NULL, then ASSERT(). If Length > 0 and SecondString is NULL, then ASSERT(). - If PcdMaximumAsciiStringLength is not zero, and Length is greater than + If PcdMaximumAsciiStringLength is not zero, and Length is greater than PcdMaximumAsciiStringLength, then ASSERT(). If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator, @@ -2131,7 +2017,7 @@ AsciiStriCmp ( @param FirstString The pointer to a Null-terminated ASCII string. @param SecondString The pointer to a Null-terminated ASCII string. @param Length The maximum number of ASCII characters for compare. - + @retval ==0 FirstString is identical to SecondString. @retval !=0 FirstString is not identical to SecondString. @@ -2187,8 +2073,8 @@ AsciiStrCat ( /** [ATTENTION] This function is deprecated for security reason. - Concatenates up to a specified length one Null-terminated ASCII string to - the end of another Null-terminated ASCII string, and returns the + Concatenates up to a specified length one Null-terminated ASCII string to + the end of another Null-terminated ASCII string, and returns the concatenated ASCII string. This function concatenates two Null-terminated ASCII strings. The contents @@ -2229,7 +2115,7 @@ AsciiStrnCat ( IN CONST CHAR8 *Source, IN UINTN Length ); -#endif +#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES) /** Returns the first occurrence of a Null-terminated ASCII sub-string @@ -2442,10 +2328,6 @@ AsciiStrHexToUint64 ( "::" can be used to compress one or more groups of X when X contains only 0. The "::" can only appear once in the String. - If String is NULL, then ASSERT(). - - If Address is NULL, then ASSERT(). - If EndPointer is not NULL and Address is translated from String, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. @@ -2497,10 +2379,6 @@ AsciiStrToIpv6Address ( When /P is in the String, the function stops at the first character that is not a valid decimal digit character after P is converted. - If String is NULL, then ASSERT(). - - If Address is NULL, then ASSERT(). - If EndPointer is not NULL and Address is translated from String, a pointer to the character that stopped the scan is stored at the location pointed to by EndPointer. @@ -2562,9 +2440,6 @@ AsciiStrToIpv4Address ( oo Data4[48:55] pp Data4[56:63] - If String is NULL, then ASSERT(). - If Guid is NULL, then ASSERT(). - @param String Pointer to a Null-terminated ASCII string. @param Guid Pointer to the converted GUID. @@ -2595,17 +2470,6 @@ AsciiStrToGuid ( decoding stops after Length of characters and outputs Buffer containing (Length / 2) bytes. - If String is NULL, then ASSERT(). - - If Buffer is NULL, then ASSERT(). - - If Length is not multiple of 2, then ASSERT(). - - If PcdMaximumAsciiStringLength is not zero and Length is greater than - PcdMaximumAsciiStringLength, then ASSERT(). - - If MaxBufferSize is less than (Length / 2), then ASSERT(). - @param String Pointer to a Null-terminated ASCII string. @param Length The number of ASCII characters to decode. @param Buffer Pointer to the converted bytes array. @@ -2670,7 +2534,7 @@ AsciiStrToUnicodeStr ( OUT CHAR16 *Destination ); -#endif +#endif // !defined (DISABLE_NEW_DEPRECATED_INTERFACES) /** Convert one Null-terminated ASCII string to a Null-terminated @@ -2686,7 +2550,6 @@ AsciiStrToUnicodeStr ( equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes. If Destination is not aligned on a 16-bit boundary, then ASSERT(). - If an error would be returned, then the function will also ASSERT(). If an error is returned, then the Destination is unmodified. @@ -2732,7 +2595,6 @@ AsciiStrToUnicodeStrS ( ((MIN(AsciiStrLen(Source), Length) + 1) * sizeof (CHAR8)) in bytes. If Destination is not aligned on a 16-bit boundary, then ASSERT(). - If an error would be returned, then the function will also ASSERT(). If an error is returned, then Destination and DestinationLength are unmodified. @@ -2771,6 +2633,165 @@ AsciiStrnToUnicodeStrS ( ); /** + Convert a Unicode character to upper case only if + it maps to a valid small-case ASCII character. + + This internal function only deal with Unicode character + which maps to a valid small-case ASCII character, i.e. + L'a' to L'z'. For other Unicode character, the input character + is returned directly. + + @param Char The character to convert. + + @retval LowerCharacter If the Char is with range L'a' to L'z'. + @retval Unchanged Otherwise. + +**/ +CHAR16 +EFIAPI +CharToUpper ( + IN CHAR16 Char + ); + +/** + Converts a lowercase Ascii character to upper one. + + If Chr is lowercase Ascii character, then converts it to upper one. + + If Value >= 0xA0, then ASSERT(). + If (Value & 0x0F) >= 0x0A, then ASSERT(). + + @param Chr one Ascii character + + @return The uppercase value of Ascii character + +**/ +CHAR8 +EFIAPI +AsciiCharToUpper ( + IN CHAR8 Chr + ); + +/** + Convert binary data to a Base64 encoded ascii string based on RFC4648. + + Produce a Null-terminated Ascii string in the output buffer specified by Destination and DestinationSize. + The Ascii string is produced by converting the data string specified by Source and SourceLength. + + @param Source Input UINT8 data + @param SourceLength Number of UINT8 bytes of data + @param Destination Pointer to output string buffer + @param DestinationSize Size of ascii buffer. Set to 0 to get the size needed. + Caller is responsible for passing in buffer of DestinationSize + + @retval RETURN_SUCCESS When ascii buffer is filled in. + @retval RETURN_INVALID_PARAMETER If Source is NULL or DestinationSize is NULL. + @retval RETURN_INVALID_PARAMETER If SourceLength or DestinationSize is bigger than (MAX_ADDRESS - (UINTN)Destination). + @retval RETURN_BUFFER_TOO_SMALL If SourceLength is 0 and DestinationSize is <1. + @retval RETURN_BUFFER_TOO_SMALL If Destination is NULL or DestinationSize is smaller than required buffersize. + +**/ +RETURN_STATUS +EFIAPI +Base64Encode ( + IN CONST UINT8 *Source, + IN UINTN SourceLength, + OUT CHAR8 *Destination OPTIONAL, + IN OUT UINTN *DestinationSize + ); + +/** + Decode Base64 ASCII encoded data to 8-bit binary representation, based on + RFC4648. + + Decoding occurs according to "Table 1: The Base 64 Alphabet" in RFC4648. + + Whitespace is ignored at all positions: + - 0x09 ('\t') horizontal tab + - 0x0A ('\n') new line + - 0x0B ('\v') vertical tab + - 0x0C ('\f') form feed + - 0x0D ('\r') carriage return + - 0x20 (' ') space + + The minimum amount of required padding (with ASCII 0x3D, '=') is tolerated + and enforced at the end of the Base64 ASCII encoded data, and only there. + + Other characters outside of the encoding alphabet cause the function to + reject the Base64 ASCII encoded data. + + @param[in] Source Array of CHAR8 elements containing the Base64 + ASCII encoding. May be NULL if SourceSize is + zero. + + @param[in] SourceSize Number of CHAR8 elements in Source. + + @param[out] Destination Array of UINT8 elements receiving the decoded + 8-bit binary representation. Allocated by the + caller. May be NULL if DestinationSize is + zero on input. If NULL, decoding is + performed, but the 8-bit binary + representation is not stored. If non-NULL and + the function returns an error, the contents + of Destination are indeterminate. + + @param[in,out] DestinationSize On input, the number of UINT8 elements that + the caller allocated for Destination. On + output, if the function returns + RETURN_SUCCESS or RETURN_BUFFER_TOO_SMALL, + the number of UINT8 elements that are + required for decoding the Base64 ASCII + representation. If the function returns a + value different from both RETURN_SUCCESS and + RETURN_BUFFER_TOO_SMALL, then DestinationSize + is indeterminate on output. + + @retval RETURN_SUCCESS SourceSize CHAR8 elements at Source have + been decoded to on-output DestinationSize + UINT8 elements at Destination. Note that + RETURN_SUCCESS covers the case when + DestinationSize is zero on input, and + Source decodes to zero bytes (due to + containing at most ignored whitespace). + + @retval RETURN_BUFFER_TOO_SMALL The input value of DestinationSize is not + large enough for decoding SourceSize CHAR8 + elements at Source. The required number of + UINT8 elements has been stored to + DestinationSize. + + @retval RETURN_INVALID_PARAMETER DestinationSize is NULL. + + @retval RETURN_INVALID_PARAMETER Source is NULL, but SourceSize is not zero. + + @retval RETURN_INVALID_PARAMETER Destination is NULL, but DestinationSize is + not zero on input. + + @retval RETURN_INVALID_PARAMETER Source is non-NULL, and (Source + + SourceSize) would wrap around MAX_ADDRESS. + + @retval RETURN_INVALID_PARAMETER Destination is non-NULL, and (Destination + + DestinationSize) would wrap around + MAX_ADDRESS, as specified on input. + + @retval RETURN_INVALID_PARAMETER None of Source and Destination are NULL, + and CHAR8[SourceSize] at Source overlaps + UINT8[DestinationSize] at Destination, as + specified on input. + + @retval RETURN_INVALID_PARAMETER Invalid CHAR8 element encountered in + Source. +**/ +RETURN_STATUS +EFIAPI +Base64Decode ( + IN CONST CHAR8 *Source OPTIONAL, + IN UINTN SourceSize, + OUT UINT8 *Destination OPTIONAL, + IN OUT UINTN *DestinationSize + ); + +/** 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 @@ -2867,6 +2888,59 @@ PathCleanUpDirectories( **/ #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)} +/** + Iterates over each node in a doubly linked list using each node's forward link. + + @param Entry A pointer to a list node used as a loop cursor during iteration + @param ListHead The head node of the doubly linked list + +**/ +#define BASE_LIST_FOR_EACH(Entry, ListHead) \ + for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink) + +/** + Iterates over each node in a doubly linked list using each node's forward link + with safety against node removal. + + This macro uses NextEntry to temporarily store the next list node so the node + pointed to by Entry may be deleted in the current loop iteration step and + iteration can continue from the node pointed to by NextEntry. + + @param Entry A pointer to a list node used as a loop cursor during iteration + @param NextEntry A pointer to a list node used to temporarily store the next node + @param ListHead The head node of the doubly linked list + +**/ +#define BASE_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \ + for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\ + Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink) + +/** + Checks whether FirstEntry and SecondEntry are part of the same doubly-linked + list. + + If FirstEntry is NULL, then ASSERT(). + If FirstEntry->ForwardLink is NULL, then ASSERT(). + If FirstEntry->BackLink is NULL, then ASSERT(). + If SecondEntry is NULL, then ASSERT(); + If PcdMaximumLinkedListLength is not zero, and List contains more than + PcdMaximumLinkedListLength nodes, then ASSERT(). + + @param FirstEntry A pointer to a node in a linked list. + @param SecondEntry A pointer to the node to locate. + + @retval TRUE SecondEntry is in the same doubly-linked list as FirstEntry. + @retval FALSE SecondEntry isn't in the same doubly-linked list as FirstEntry, + or FirstEntry is invalid. + +**/ +BOOLEAN +EFIAPI +IsNodeInList ( + IN CONST LIST_ENTRY *FirstEntry, + IN CONST LIST_ENTRY *SecondEntry + ); + /** Initializes the head node of a doubly linked list, and returns the pointer to @@ -2930,7 +3004,7 @@ InsertHeadList ( If ListHead is NULL, then ASSERT(). If Entry is NULL, then ASSERT(). - If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or + If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), then ASSERT(). If PcdMaximumLinkedListLength is not zero, and prior to insertion the number of nodes in ListHead, including the ListHead node, is greater than or @@ -2954,12 +3028,12 @@ InsertTailList ( /** Retrieves the first node of a doubly linked list. - Returns the first node of a doubly linked list. List must have been + Returns the first node of a doubly linked list. List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). If List is empty, then List is returned. If List is NULL, then ASSERT(). - If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or + If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), then ASSERT(). If PcdMaximumLinkedListLength is not zero, and the number of nodes in List, including the List node, is greater than or equal to @@ -2981,13 +3055,13 @@ GetFirstNode ( /** Retrieves the next node of a doubly linked list. - Returns the node of a doubly linked list that follows Node. + Returns the node of a doubly linked list that follows Node. List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). If List is empty, then List is returned. If List is NULL, then ASSERT(). If Node is NULL, then ASSERT(). - If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or + If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), then ASSERT(). If PcdMaximumLinkedListLength is not zero, and List contains more than PcdMaximumLinkedListLength nodes, then ASSERT(). @@ -3006,27 +3080,27 @@ GetNextNode ( IN CONST LIST_ENTRY *Node ); - + /** Retrieves the previous node of a doubly linked list. - - Returns the node of a doubly linked list that precedes Node. + + Returns the node of a doubly linked list that precedes Node. List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). If List is empty, then List is returned. - + If List is NULL, then ASSERT(). If Node is NULL, then ASSERT(). - If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or + If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), then ASSERT(). If PcdMaximumLinkedListLength is not zero, and List contains more than PcdMaximumLinkedListLength nodes, then ASSERT(). If PcdVerifyNodeInList is TRUE and 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. - + @return The pointer to the previous node if one exists. Otherwise List is returned. - + **/ LIST_ENTRY * EFIAPI @@ -3035,7 +3109,7 @@ GetPreviousNode ( IN CONST LIST_ENTRY *Node ); - + /** Checks to see if a doubly linked list is empty or not. @@ -3043,7 +3117,7 @@ GetPreviousNode ( zero nodes, this function returns TRUE. Otherwise, it returns FALSE. If ListHead is NULL, then ASSERT(). - If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or + If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), then ASSERT(). If PcdMaximumLinkedListLength is not zero, and the number of nodes in List, including the List node, is greater than or equal to @@ -3073,12 +3147,12 @@ IsListEmpty ( If List is NULL, then ASSERT(). If Node is NULL, then ASSERT(). - If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), + If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(), then ASSERT(). If PcdMaximumLinkedListLength is not zero, and the number of nodes in List, including the List node, is greater than or equal to PcdMaximumLinkedListLength, then ASSERT(). - If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal + If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal to List, then ASSERT(). @param List A pointer to the head node of a doubly linked list. @@ -3135,12 +3209,12 @@ IsNodeAtEnd ( Otherwise, the location of the FirstEntry node is swapped with the location of the SecondEntry node in a doubly linked list. SecondEntry must be in the same double linked list as FirstEntry and that double linked list must have - been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). + been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(). SecondEntry is returned after the nodes are swapped. If FirstEntry is NULL, then ASSERT(). If SecondEntry is NULL, then ASSERT(). - If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the + If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the same linked list, then ASSERT(). If PcdMaximumLinkedListLength is not zero, and the number of nodes in the linked list containing the FirstEntry and SecondEntry nodes, including @@ -3149,7 +3223,7 @@ IsNodeAtEnd ( @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. **/ @@ -3717,7 +3791,7 @@ DivU64x64Remainder ( function returns the 64-bit signed quotient. It is the caller's responsibility to not call this function with a Divisor of 0. - If Divisor is 0, then the quotient and remainder should be assumed to be + If Divisor is 0, then the quotient and remainder should be assumed to be the largest negative integer. If Divisor is 0, then ASSERT(). @@ -4049,7 +4123,7 @@ BitFieldAnd8 ( bitwise OR, and returns the result. Performs a bitwise AND between the bit field specified by StartBit and EndBit - in Operand and the value specified by AndData, followed by a bitwise + in Operand and the value specified by AndData, followed by a bitwise OR with value specified by OrData. All other bits in Operand are preserved. The new 8-bit value is returned. @@ -4216,7 +4290,7 @@ BitFieldAnd16 ( bitwise OR, and returns the result. Performs a bitwise AND between the bit field specified by StartBit and EndBit - in Operand and the value specified by AndData, followed by a bitwise + in Operand and the value specified by AndData, followed by a bitwise OR with value specified by OrData. All other bits in Operand are preserved. The new 16-bit value is returned. @@ -4383,7 +4457,7 @@ BitFieldAnd32 ( bitwise OR, and returns the result. Performs a bitwise AND between the bit field specified by StartBit and EndBit - in Operand and the value specified by AndData, followed by a bitwise + in Operand and the value specified by AndData, followed by a bitwise OR with value specified by OrData. All other bits in Operand are preserved. The new 32-bit value is returned. @@ -4550,7 +4624,7 @@ BitFieldAnd64 ( bitwise OR, and returns the result. Performs a bitwise AND between the bit field specified by StartBit and EndBit - in Operand and the value specified by AndData, followed by a bitwise + in Operand and the value specified by AndData, followed by a bitwise OR with value specified by OrData. All other bits in Operand are preserved. The new 64-bit value is returned. @@ -4582,6 +4656,62 @@ BitFieldAndThenOr64 ( IN UINT64 OrData ); +/** + Reads a bit field from a 32-bit value, counts and returns + the number of set bits. + + Counts the number of set bits in the bit field specified by + StartBit and EndBit in Operand. The count is returned. + + If StartBit is greater than 31, then ASSERT(). + If EndBit is greater than 31, 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. + Range 0..31. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..31. + + @return The number of bits set between StartBit and EndBit. + +**/ +UINT8 +EFIAPI +BitFieldCountOnes32 ( + IN UINT32 Operand, + IN UINTN StartBit, + IN UINTN EndBit + ); + +/** + Reads a bit field from a 64-bit value, counts and returns + the number of set bits. + + Counts the number of set bits in the bit field specified by + StartBit and EndBit in Operand. The count is returned. + + If StartBit is greater than 63, then ASSERT(). + If EndBit is greater than 63, 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. + Range 0..63. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..63. + + @return The number of bits set between StartBit and EndBit. + +**/ +UINT8 +EFIAPI +BitFieldCountOnes64 ( + IN UINT64 Operand, + IN UINTN StartBit, + IN UINTN EndBit + ); + // // Base Library Checksum Functions // @@ -4802,6 +4932,25 @@ CalculateCheckSum64 ( IN UINTN Length ); +/** + Computes and returns a 32-bit CRC for a data buffer. + CRC32 value bases on ITU-T V.42. + + If Buffer is NULL, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param[in] Buffer A pointer to the buffer on which the 32-bit CRC is to be computed. + @param[in] Length The number of bytes in the buffer Data. + + @retval Crc32 The 32-bit CRC was computed for the data buffer. + +**/ +UINT32 +EFIAPI +CalculateCrc32( + IN VOID *Buffer, + IN UINTN Length + ); // // Base Library CPU Functions @@ -4846,17 +4995,18 @@ MemoryFence ( If JumpBuffer is NULL, then ASSERT(). For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT(). - + NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific. The same structure must never be used for more than one CPU architecture context. - For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module. - SetJump()/LongJump() is not currently supported for the EBC processor type. + For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module. + SetJump()/LongJump() is not currently supported for the EBC processor type. @param JumpBuffer A pointer to CPU context buffer. @retval 0 Indicates a return from SetJump(). **/ +RETURNS_TWICE UINTN EFIAPI SetJump ( @@ -5011,9 +5161,9 @@ CpuPause ( function. @param NewStack A pointer to the new stack to use for the EntryPoint function. - @param ... This variable argument list is ignored for IA-32, x64, and - EBC architectures. For Itanium processors, this variable - argument list is expected to contain a single parameter of + @param ... This variable argument list is ignored for IA-32, x64, and + EBC architectures. For Itanium processors, this variable + argument list is expected to contain a single parameter of type VOID * that specifies the new backing store pointer. @@ -5057,1399 +5207,22 @@ EFIAPI CpuDeadLoop ( VOID ); - -#if defined (MDE_CPU_IPF) - -/** - Flush a range of cache lines in the cache coherency domain of the calling - CPU. - - Flushes 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 flushed. - If Address + Length is not aligned on a cache line boundary, then the entire cache - line containing Address + Length - 1 is flushed. This function may choose to flush - the entire cache if that is more efficient than flushing the specified range. If - Length is 0, the no cache lines are flushed. Address is returned. - This function is only available on Itanium processors. - - 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 -AsmFlushCacheRange ( - IN VOID *Address, - IN UINTN Length - ); - - -/** - Executes an FC instruction. - Executes an 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 Itanium processors. - - @param Address The Address of cache line to be flushed. - - @return The address of FC instruction executed. - -**/ -UINT64 -EFIAPI -AsmFc ( - IN UINT64 Address - ); - - -/** - Executes an FC.I instruction. - Executes an 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 Itanium processors. - - @param Address The Address of cache line to be flushed. - - @return The address of the FC.I instruction executed. - -**/ -UINT64 -EFIAPI -AsmFci ( - IN UINT64 Address - ); - - -/** - Reads the current value of a Processor Identifier Register (CPUID). - - Reads and returns the current value of Processor Identifier Register specified by Index. - 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 Itanium processors. - - @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 Itanium processors. - - @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 Itanium processors. - - @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). - - Reads and returns the current value of KR0. - This function is only available on Itanium processors. - - @return The current value of KR0. - -**/ -UINT64 -EFIAPI -AsmReadKr0 ( - VOID - ); - - -/** - Reads the current value of 64-bit Kernel Register #1 (KR1). - - Reads and returns the current value of KR1. - This function is only available on Itanium processors. - - @return The current value of KR1. - -**/ -UINT64 -EFIAPI -AsmReadKr1 ( - VOID - ); - - -/** - Reads the current value of 64-bit Kernel Register #2 (KR2). - - Reads and returns the current value of KR2. - This function is only available on Itanium processors. - - @return The current value of KR2. - -**/ -UINT64 -EFIAPI -AsmReadKr2 ( - VOID - ); - - -/** - Reads the current value of 64-bit Kernel Register #3 (KR3). - - Reads and returns the current value of KR3. - This function is only available on Itanium processors. - - @return The current value of KR3. - -**/ -UINT64 -EFIAPI -AsmReadKr3 ( - VOID - ); - - -/** - Reads the current value of 64-bit Kernel Register #4 (KR4). - - Reads and returns the current value of KR4. - This function is only available on Itanium processors. - - @return The current value of KR4. - -**/ -UINT64 -EFIAPI -AsmReadKr4 ( - VOID - ); - - -/** - Reads the current value of 64-bit Kernel Register #5 (KR5). - - Reads and returns the current value of KR5. - This function is only available on Itanium processors. - - @return The current value of KR5. - -**/ -UINT64 -EFIAPI -AsmReadKr5 ( - VOID - ); - - -/** - Reads the current value of 64-bit Kernel Register #6 (KR6). - - Reads and returns the current value of KR6. - This function is only available on Itanium processors. - - @return The current value of KR6. - -**/ -UINT64 -EFIAPI -AsmReadKr6 ( - VOID - ); /** - Reads the current value of 64-bit Kernel Register #7 (KR7). + Uses as a barrier to stop speculative execution. - Reads and returns the current value of KR7. - This function is only available on Itanium processors. - - @return The current value of KR7. - -**/ -UINT64 -EFIAPI -AsmReadKr7 ( - VOID - ); - - -/** - Write the current value of 64-bit Kernel Register #0 (KR0). - - Writes the current value of KR0. The 64-bit value written to - the KR0 is returned. This function is only available on Itanium processors. - - @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). - - Writes the current value of KR1. The 64-bit value written to - the KR1 is returned. This function is only available on Itanium processors. - - @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). - - Writes the current value of KR2. The 64-bit value written to - the KR2 is returned. This function is only available on Itanium processors. - - @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). - - Writes the current value of KR3. The 64-bit value written to - the KR3 is returned. This function is only available on Itanium processors. - - @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). - - Writes the current value of KR4. The 64-bit value written to - the KR4 is returned. This function is only available on Itanium processors. - - @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). - - Writes the current value of KR5. The 64-bit value written to - the KR5 is returned. This function is only available on Itanium processors. - - @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). - - Writes the current value of KR6. The 64-bit value written to - the KR6 is returned. This function is only available on Itanium processors. - - @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). - - Writes the current value of KR7. The 64-bit value written to - the KR7 is returned. This function is only available on Itanium processors. - - @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). - - Reads and returns the current value of ITC. - This function is only available on Itanium processors. - - @return The current value of ITC. - -**/ -UINT64 -EFIAPI -AsmReadItc ( - VOID - ); - - -/** - Reads the current value of Interval Timer Vector Register (ITV). - - Reads and returns the current value of ITV. - This function is only available on Itanium processors. - - @return The current value of ITV. - -**/ -UINT64 -EFIAPI -AsmReadItv ( - VOID - ); - - -/** - Reads the current value of Interval Timer Match Register (ITM). - - Reads and returns the current value of ITM. - This function is only available on Itanium processors. - - @return The current value of ITM. -**/ -UINT64 -EFIAPI -AsmReadItm ( - VOID - ); - - -/** - Writes the current value of 64-bit Interval Timer Counter Register (ITC). - - Writes the current value of ITC. The 64-bit value written to the ITC is returned. - This function is only available on Itanium processors. - - @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). - - Writes the current value of ITM. The 64-bit value written to the ITM is returned. - This function is only available on Itanium processors. - - @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). - - Writes the current value of ITV. The 64-bit value written to the ITV is returned. - 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 Itanium processors. - - @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). - - Reads and returns the current value of DCR. This function is only available on Itanium processors. - - @return The current value of DCR. - -**/ -UINT64 -EFIAPI -AsmReadDcr ( - VOID - ); - - -/** - Reads the current value of Interruption Vector Address Register (IVA). - - Reads and returns the current value of IVA. This function is only available on Itanium processors. - - @return The current value of IVA. -**/ -UINT64 -EFIAPI -AsmReadIva ( - VOID - ); - - -/** - Reads the current value of Page Table Address Register (PTA). - - Reads and returns the current value of PTA. This function is only available on Itanium processors. - - @return The current value of PTA. - -**/ -UINT64 -EFIAPI -AsmReadPta ( - VOID - ); - - -/** - Writes the current value of 64-bit Default Control Register (DCR). - - Writes the current value of DCR. The 64-bit value written to the DCR is returned. - 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 Itanium processors. - - @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). - - Writes the current value of IVA. The 64-bit value written to the IVA is returned. - 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 Itanium processors. - - @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). - - Writes the current value of PTA. The 64-bit value written to the PTA is returned. - 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 Itanium processors. - - @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). - - Reads and returns the current value of LID. This function is only available on Itanium processors. - - @return The current value of LID. - -**/ -UINT64 -EFIAPI -AsmReadLid ( - VOID - ); - - -/** - Reads the current value of External Interrupt Vector Register (IVR). - - Reads and returns the current value of IVR. This function is only available on Itanium processors. - - @return The current value of IVR. - -**/ -UINT64 -EFIAPI -AsmReadIvr ( - VOID - ); - - -/** - Reads the current value of Task Priority Register (TPR). - - Reads and returns the current value of TPR. This function is only available on Itanium processors. - - @return The current value of TPR. - -**/ -UINT64 -EFIAPI -AsmReadTpr ( - VOID - ); - - -/** - Reads the current value of External Interrupt Request Register #0 (IRR0). - - Reads and returns the current value of IRR0. This function is only available on Itanium processors. - - @return The current value of IRR0. - -**/ -UINT64 -EFIAPI -AsmReadIrr0 ( - VOID - ); - - -/** - Reads the current value of External Interrupt Request Register #1 (IRR1). - - Reads and returns the current value of IRR1. This function is only available on Itanium processors. - - @return The current value of IRR1. - -**/ -UINT64 -EFIAPI -AsmReadIrr1 ( - VOID - ); - - -/** - Reads the current value of External Interrupt Request Register #2 (IRR2). - - Reads and returns the current value of IRR2. This function is only available on Itanium processors. - - @return The current value of IRR2. - -**/ -UINT64 -EFIAPI -AsmReadIrr2 ( - VOID - ); - - -/** - Reads the current value of External Interrupt Request Register #3 (IRR3). - - Reads and returns the current value of IRR3. This function is only available on Itanium processors. - - @return The current value of IRR3. - -**/ -UINT64 -EFIAPI -AsmReadIrr3 ( - VOID - ); - - -/** - Reads the current value of Performance Monitor Vector Register (PMV). - - Reads and returns the current value of PMV. This function is only available on Itanium processors. - - @return The current value of PMV. - -**/ -UINT64 -EFIAPI -AsmReadPmv ( - VOID - ); - - -/** - Reads the current value of Corrected Machine Check Vector Register (CMCV). - - Reads and returns the current value of CMCV. This function is only available on Itanium processors. - - @return The current value of CMCV. - -**/ -UINT64 -EFIAPI -AsmReadCmcv ( - VOID - ); - - -/** - Reads the current value of Local Redirection Register #0 (LRR0). - - Reads and returns the current value of LRR0. This function is only available on Itanium processors. - - @return The current value of LRR0. - -**/ -UINT64 -EFIAPI -AsmReadLrr0 ( - VOID - ); - - -/** - Reads the current value of Local Redirection Register #1 (LRR1). - - Reads and returns the current value of LRR1. This function is only available on Itanium processors. - - @return The current value of LRR1. - -**/ -UINT64 -EFIAPI -AsmReadLrr1 ( - VOID - ); - - -/** - Writes the current value of 64-bit Page Local Interrupt ID Register (LID). - - Writes the current value of LID. The 64-bit value written to the LID is returned. - 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 Itanium processors. - - @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). - - Writes the current value of TPR. The 64-bit value written to the TPR is returned. - 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 Itanium processors. - - @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 Itanium processors. + Ensures that no later instruction will execute speculatively, until all prior + instructions have completed. **/ VOID EFIAPI -AsmWriteEoi ( +SpeculationBarrier ( VOID ); -/** - Writes the current value of 64-bit Performance Monitor Vector Register (PMV). - - Writes the current value of PMV. The 64-bit value written to the PMV is returned. - 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 Itanium processors. - - @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). - - Writes the current value of CMCV. The 64-bit value written to the CMCV is returned. - 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 Itanium processors. - - @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). - - Writes the current value of LRR0. The 64-bit value written to the LRR0 is returned. - 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 Itanium processors. - - @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). - - Writes the current value of LRR1. The 64-bit value written to the LRR1 is returned. - 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 Itanium processors. - - @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 four 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 Itanium processors. - - @param Index The 8-bit Instruction Breakpoint Register index to read. - - @return The current value of Instruction Breakpoint Register specified by Index. - -**/ -UINT64 -EFIAPI -AsmReadIbr ( - IN UINT8 Index - ); - - -/** - Reads the current value of Data Breakpoint Register (DBR). - - The Data Breakpoint Registers are used in pairs. The even numbered registers - contain breakpoint addresses, and odd numbered registers contain breakpoint - mask conditions. At least four 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 Itanium processors. - - @param Index The 8-bit Data Breakpoint Register index to read. - - @return The current value of Data Breakpoint Register specified by Index. - -**/ -UINT64 -EFIAPI -AsmReadDbr ( - IN UINT8 Index - ); - - -/** - Reads the current value of Performance Monitor Configuration Register (PMC). - - All processor implementations provide at least four performance counters - (PMC/PMD [4]...PMC/PMD [7] pairs), and four 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 Itanium processors. - - @param Index The 8-bit Performance Monitor Configuration Register index to read. - - @return The current value of Performance Monitor Configuration Register - specified by Index. - -**/ -UINT64 -EFIAPI -AsmReadPmc ( - IN UINT8 Index - ); - - -/** - Reads the current value of Performance Monitor Data Register (PMD). - - All processor implementations provide at least 4 performance counters - (PMC/PMD [4]...PMC/PMD [7] pairs), and 4 performance monitor counter - overflow status registers (PMC [0]... PMC [3]). Processor implementations may - provide additional implementation-dependent PMC and PMD to increase the number - of 'generic' performance counters (PMC/PMD pairs). The remainder of PMC and PMD - register set is implementation dependent. No parameter checking is performed - on Index. If the Index value is beyond the implemented PMD register range, - zero value will be returned. - This function is only available on Itanium processors. - - @param Index The 8-bit Performance Monitor Data Register index to read. - - @return The current value of Performance Monitor Data Register specified by Index. - -**/ -UINT64 -EFIAPI -AsmReadPmd ( - IN UINT8 Index - ); - - -/** - Writes the current value of 64-bit Instruction Breakpoint Register (IBR). - - 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 four 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 Itanium processors. - - @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. - -**/ -UINT64 -EFIAPI -AsmWriteIbr ( - IN UINT8 Index, - IN UINT64 Value - ); - - -/** - Writes the current value of 64-bit Data Breakpoint Register (DBR). - - 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 four 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 Itanium processors. - - @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. - -**/ -UINT64 -EFIAPI -AsmWriteDbr ( - IN UINT8 Index, - IN UINT64 Value - ); - - -/** - Writes the current value of 64-bit Performance Monitor Configuration Register (PMC). - - Writes current value of Performance Monitor Configuration Register specified by Index. - All processor implementations provide at least four performance counters - (PMC/PMD [4]...PMC/PMD [7] pairs), and four 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 Itanium processors. - - @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. - -**/ -UINT64 -EFIAPI -AsmWritePmc ( - IN UINT8 Index, - IN UINT64 Value - ); - - -/** - Writes the current value of 64-bit Performance Monitor Data Register (PMD). - - Writes current value of Performance Monitor Data Register specified by Index. - All processor implementations provide at least four performance counters - (PMC/PMD [4]...PMC/PMD [7] pairs), and four 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 Itanium processors. - - @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. - -**/ -UINT64 -EFIAPI -AsmWritePmd ( - IN UINT8 Index, - IN UINT64 Value - ); - - -/** - Reads the current value of 64-bit Global Pointer (GP). - - Reads and returns the current value of GP. - This function is only available on Itanium processors. - - @return The current value of GP. - -**/ -UINT64 -EFIAPI -AsmReadGp ( - VOID - ); - - -/** - Write the current value of 64-bit Global Pointer (GP). - - 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 Itanium processors. - - @param Value The 64-bit value to write to GP. - - @return The 64-bit value written to the GP. - -**/ -UINT64 -EFIAPI -AsmWriteGp ( - IN UINT64 Value - ); - - -/** - Reads the current value of 64-bit Stack Pointer (SP). - - Reads and returns the current value of SP. - This function is only available on Itanium processors. - - @return The current value of SP. - -**/ -UINT64 -EFIAPI -AsmReadSp ( - VOID - ); - - -/// -/// Valid Index value for AsmReadControlRegister(). -/// -#define IPF_CONTROL_REGISTER_DCR 0 -#define IPF_CONTROL_REGISTER_ITM 1 -#define IPF_CONTROL_REGISTER_IVA 2 -#define IPF_CONTROL_REGISTER_PTA 8 -#define IPF_CONTROL_REGISTER_IPSR 16 -#define IPF_CONTROL_REGISTER_ISR 17 -#define IPF_CONTROL_REGISTER_IIP 19 -#define IPF_CONTROL_REGISTER_IFA 20 -#define IPF_CONTROL_REGISTER_ITIR 21 -#define IPF_CONTROL_REGISTER_IIPA 22 -#define IPF_CONTROL_REGISTER_IFS 23 -#define IPF_CONTROL_REGISTER_IIM 24 -#define IPF_CONTROL_REGISTER_IHA 25 -#define IPF_CONTROL_REGISTER_LID 64 -#define IPF_CONTROL_REGISTER_IVR 65 -#define IPF_CONTROL_REGISTER_TPR 66 -#define IPF_CONTROL_REGISTER_EOI 67 -#define IPF_CONTROL_REGISTER_IRR0 68 -#define IPF_CONTROL_REGISTER_IRR1 69 -#define IPF_CONTROL_REGISTER_IRR2 70 -#define IPF_CONTROL_REGISTER_IRR3 71 -#define IPF_CONTROL_REGISTER_ITV 72 -#define IPF_CONTROL_REGISTER_PMV 73 -#define IPF_CONTROL_REGISTER_CMCV 74 -#define IPF_CONTROL_REGISTER_LRR0 80 -#define IPF_CONTROL_REGISTER_LRR1 81 - -/** - Reads a 64-bit control register. - - Reads and returns the control register specified by Index. The valid Index valued - are defined above in "Related Definitions". - If Index is invalid then 0xFFFFFFFFFFFFFFFF is returned. This function is only - available on Itanium processors. - - @param Index The index of the control register to read. - - @return The control register specified by Index. - -**/ -UINT64 -EFIAPI -AsmReadControlRegister ( - IN UINT64 Index - ); - - -/// -/// Valid Index value for AsmReadApplicationRegister(). -/// -#define IPF_APPLICATION_REGISTER_K0 0 -#define IPF_APPLICATION_REGISTER_K1 1 -#define IPF_APPLICATION_REGISTER_K2 2 -#define IPF_APPLICATION_REGISTER_K3 3 -#define IPF_APPLICATION_REGISTER_K4 4 -#define IPF_APPLICATION_REGISTER_K5 5 -#define IPF_APPLICATION_REGISTER_K6 6 -#define IPF_APPLICATION_REGISTER_K7 7 -#define IPF_APPLICATION_REGISTER_RSC 16 -#define IPF_APPLICATION_REGISTER_BSP 17 -#define IPF_APPLICATION_REGISTER_BSPSTORE 18 -#define IPF_APPLICATION_REGISTER_RNAT 19 -#define IPF_APPLICATION_REGISTER_FCR 21 -#define IPF_APPLICATION_REGISTER_EFLAG 24 -#define IPF_APPLICATION_REGISTER_CSD 25 -#define IPF_APPLICATION_REGISTER_SSD 26 -#define IPF_APPLICATION_REGISTER_CFLG 27 -#define IPF_APPLICATION_REGISTER_FSR 28 -#define IPF_APPLICATION_REGISTER_FIR 29 -#define IPF_APPLICATION_REGISTER_FDR 30 -#define IPF_APPLICATION_REGISTER_CCV 32 -#define IPF_APPLICATION_REGISTER_UNAT 36 -#define IPF_APPLICATION_REGISTER_FPSR 40 -#define IPF_APPLICATION_REGISTER_ITC 44 -#define IPF_APPLICATION_REGISTER_PFS 64 -#define IPF_APPLICATION_REGISTER_LC 65 -#define IPF_APPLICATION_REGISTER_EC 66 - -/** - Reads a 64-bit application register. - - Reads and returns the application register specified by Index. The valid Index - valued are defined above in "Related Definitions". - If Index is invalid then 0xFFFFFFFFFFFFFFFF is returned. This function is only - available on Itanium processors. - - @param Index The index of the application register to read. - - @return The application register specified by Index. - -**/ -UINT64 -EFIAPI -AsmReadApplicationRegister ( - IN UINT64 Index - ); - - -/** - Reads the current value of a Machine Specific Register (MSR). - - Reads and returns the current value of the Machine Specific Register specified by Index. No - parameter checking is performed on Index, and if the Index value is beyond the implemented MSR - 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 Itanium processors. - - @param Index The 8-bit Machine Specific Register index to read. - - @return The current value of the Machine Specific Register specified by Index. - -**/ -UINT64 -EFIAPI -AsmReadMsr ( - IN UINT8 Index - ); - - -/** - Writes the current value of a Machine Specific Register (MSR). - - Writes Value to the Machine Specific Register specified by Index. Value is returned. No - parameter checking is performed on Index, and if the Index value is beyond the implemented MSR - 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 Itanium processors. - - @param Index The 8-bit Machine Specific Register index to write. - @param Value The 64-bit value to write to the Machine Specific Register. - - @return The 64-bit value to write to the Machine Specific Register. - -**/ -UINT64 -EFIAPI -AsmWriteMsr ( - IN UINT8 Index, - IN UINT64 Value - ); - - -/** - Determines if the CPU is currently executing in virtual, physical, or mixed mode. - - 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 Itanium processors. - - @retval 1 The CPU is in virtual mode. - @retval 0 The CPU is in physical mode. - @retval -1 The CPU is in mixed mode. - -**/ -INT64 -EFIAPI -AsmCpuVirtual ( - VOID - ); - - -/** - 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 Itanium processors. - - @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. - -**/ -PAL_CALL_RETURN -EFIAPI -AsmPalCall ( - IN UINT64 PalEntryPoint, - IN UINT64 Index, - IN UINT64 Arg2, - IN UINT64 Arg3, - IN UINT64 Arg4 - ); -#endif - #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64) /// /// IA32 and x64 Specific Functions. @@ -6556,9 +5329,19 @@ typedef union { UINT32 OSXMMEXCPT:1; ///< Operating System Support for ///< Unmasked SIMD Floating Point ///< Exceptions. - UINT32 Reserved_0:2; ///< Reserved. - UINT32 VMXE:1; ///< VMX Enable - UINT32 Reserved_1:18; ///< Reserved. + UINT32 UMIP:1; ///< User-Mode Instruction Prevention. + UINT32 LA57:1; ///< Linear Address 57bit. + UINT32 VMXE:1; ///< VMX Enable. + UINT32 SMXE:1; ///< SMX Enable. + UINT32 Reserved_3:1; ///< Reserved. + UINT32 FSGSBASE:1; ///< FSGSBASE Enable. + UINT32 PCIDE:1; ///< PCID Enable. + UINT32 OSXSAVE:1; ///< XSAVE and Processor Extended States Enable. + UINT32 Reserved_4:1; ///< Reserved. + UINT32 SMEP:1; ///< SMEP Enable. + UINT32 SMAP:1; ///< SMAP Enable. + UINT32 PKE:1; ///< Protection-Key Enable. + UINT32 Reserved_5:9; ///< Reserved. } Bits; UINTN UintN; } IA32_CR4; @@ -6601,6 +5384,8 @@ typedef struct { #define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E #define IA32_IDT_GATE_TYPE_TRAP_32 0x8F +#define IA32_GDT_TYPE_TSS 0x9 +#define IA32_GDT_ALIGNMENT 8 #if defined (MDE_CPU_IA32) /// @@ -6617,7 +5402,71 @@ typedef union { UINT64 Uint64; } IA32_IDT_GATE_DESCRIPTOR; -#endif +#pragma pack (1) +// +// IA32 Task-State Segment Definition +// +typedef struct { + UINT16 PreviousTaskLink; + UINT16 Reserved_2; + UINT32 ESP0; + UINT16 SS0; + UINT16 Reserved_10; + UINT32 ESP1; + UINT16 SS1; + UINT16 Reserved_18; + UINT32 ESP2; + UINT16 SS2; + UINT16 Reserved_26; + UINT32 CR3; + UINT32 EIP; + UINT32 EFLAGS; + UINT32 EAX; + UINT32 ECX; + UINT32 EDX; + UINT32 EBX; + UINT32 ESP; + UINT32 EBP; + UINT32 ESI; + UINT32 EDI; + UINT16 ES; + UINT16 Reserved_74; + UINT16 CS; + UINT16 Reserved_78; + UINT16 SS; + UINT16 Reserved_82; + UINT16 DS; + UINT16 Reserved_86; + UINT16 FS; + UINT16 Reserved_90; + UINT16 GS; + UINT16 Reserved_94; + UINT16 LDTSegmentSelector; + UINT16 Reserved_98; + UINT16 T; + UINT16 IOMapBaseAddress; +} IA32_TASK_STATE_SEGMENT; + +typedef union { + struct { + UINT32 LimitLow:16; ///< Segment Limit 15..00 + UINT32 BaseLow:16; ///< Base Address 15..00 + UINT32 BaseMid:8; ///< Base Address 23..16 + UINT32 Type:4; ///< Type (1 0 B 1) + UINT32 Reserved_43:1; ///< 0 + UINT32 DPL:2; ///< Descriptor Privilege Level + UINT32 P:1; ///< Segment Present + UINT32 LimitHigh:4; ///< Segment Limit 19..16 + UINT32 AVL:1; ///< Available for use by system software + UINT32 Reserved_52:2; ///< 0 0 + UINT32 G:1; ///< Granularity + UINT32 BaseHigh:8; ///< Base Address 31..24 + } Bits; + UINT64 Uint64; +} IA32_TSS_DESCRIPTOR; +#pragma pack () + +#endif // defined (MDE_CPU_IA32) #if defined (MDE_CPU_X64) /// @@ -6636,10 +5485,50 @@ typedef union { struct { UINT64 Uint64; UINT64 Uint64_1; - } Uint128; + } Uint128; } IA32_IDT_GATE_DESCRIPTOR; -#endif +#pragma pack (1) +// +// IA32 Task-State Segment Definition +// +typedef struct { + UINT32 Reserved_0; + UINT64 RSP0; + UINT64 RSP1; + UINT64 RSP2; + UINT64 Reserved_28; + UINT64 IST[7]; + UINT64 Reserved_92; + UINT16 Reserved_100; + UINT16 IOMapBaseAddress; +} IA32_TASK_STATE_SEGMENT; + +typedef union { + struct { + UINT32 LimitLow:16; ///< Segment Limit 15..00 + UINT32 BaseLow:16; ///< Base Address 15..00 + UINT32 BaseMidl:8; ///< Base Address 23..16 + UINT32 Type:4; ///< Type (1 0 B 1) + UINT32 Reserved_43:1; ///< 0 + UINT32 DPL:2; ///< Descriptor Privilege Level + UINT32 P:1; ///< Segment Present + UINT32 LimitHigh:4; ///< Segment Limit 19..16 + UINT32 AVL:1; ///< Available for use by system software + UINT32 Reserved_52:2; ///< 0 0 + UINT32 G:1; ///< Granularity + UINT32 BaseMidh:8; ///< Base Address 31..24 + UINT32 BaseHigh:32; ///< Base Address 63..32 + UINT32 Reserved_96:32; ///< Reserved + } Bits; + struct { + UINT64 Uint64; + UINT64 Uint64_1; + } Uint128; +} IA32_TSS_DESCRIPTOR; +#pragma pack () + +#endif // defined (MDE_CPU_X64) /// /// Byte packed structure for an FP/SSE/SSE2 context. @@ -6728,6 +5617,20 @@ typedef struct { #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002 #define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004 +/// +/// Type definition for representing labels in NASM source code that allow for +/// the patching of immediate operands of IA32 and X64 instructions. +/// +/// While the type is technically defined as a function type (note: not a +/// pointer-to-function type), such labels in NASM source code never stand for +/// actual functions, and identifiers declared with this function type should +/// never be called. This is also why the EFIAPI calling convention specifier +/// is missing from the typedef, and why the typedef does not follow the usual +/// edk2 coding style for function (or pointer-to-function) typedefs. The VOID +/// return type and the VOID argument list are merely artifacts. +/// +typedef VOID (X86_ASSEMBLY_PATCH_LABEL) (VOID); + /** Retrieves CPUID information. @@ -7004,8 +5907,8 @@ AsmMsrBitFieldRead32 ( Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit field is specified by the StartBit and the EndBit. All other bits in the destination MSR are preserved. The lower 32-bits of the MSR written is - returned. The caller must either guarantee that Index and the data written - is valid, or the caller must set up exception handlers to catch the exceptions. + returned. The caller must either guarantee that Index and the data written + is valid, or the caller must set up exception handlers to catch the exceptions. This function is only available on IA-32 and x64. If StartBit is greater than 31, then ASSERT(). @@ -7248,7 +6151,7 @@ AsmMsrAnd64 ( /** - Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise + Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise OR, and writes the result back to the 64-bit MSR. Reads the 64-bit MSR specified by Index, performs a bitwise AND between read @@ -7313,8 +6216,8 @@ AsmMsrBitFieldRead64 ( Writes Value to a bit field in a 64-bit MSR. The bit field is specified by the StartBit and the EndBit. All other bits in the destination MSR are - preserved. The MSR written is returned. The caller must either guarantee - that Index and the data written is valid, or the caller must set up exception + preserved. The MSR written is returned. The caller must either guarantee + that Index and the data written is valid, or the caller must set up exception handlers to catch the exceptions. This function is only available on IA-32 and x64. If StartBit is greater than 63, then ASSERT(). @@ -8726,7 +7629,7 @@ AsmDisablePaging64 ( in ExtraStackSize. If parameters are passed to the 16-bit real mode code, then the actual minimum stack size is ExtraStackSize plus the maximum number of bytes that need to be passed to the 16-bit real mode code. - + If RealModeBufferSize is NULL, then ASSERT(). If ExtraStackSize is NULL, then ASSERT(). @@ -8750,7 +7653,7 @@ AsmGetThunk16Properties ( Prepares all structures a code required to use AsmThunk16(). Prepares all structures and code required to use AsmThunk16(). - + This interface is limited to be used in either physical mode or virtual modes with paging enabled where the virtual to physical mappings for ThunkContext.RealModeBuffer is mapped 1:1. @@ -8774,43 +7677,43 @@ AsmPrepareThunk16 ( AsmPrepareThunk16() must be called with ThunkContext before this function is used. This function must be called with interrupts disabled. - The register state from the RealModeState field of ThunkContext is restored just prior - to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState, + The register state from the RealModeState field of ThunkContext is restored just prior + to calling the 16-bit real mode entry point. This includes the EFLAGS field of RealModeState, which is used to set the interrupt state when a 16-bit real mode entry point is called. Control is transferred to the 16-bit real mode entry point specified by the CS and Eip fields of RealModeState. - The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to - the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function. + The stack is initialized to the SS and ESP fields of RealModeState. Any parameters passed to + the 16-bit real mode code must be populated by the caller at SS:ESP prior to calling this function. The 16-bit real mode entry point is invoked with a 16-bit CALL FAR instruction, - so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment - and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry - point must exit with a RETF instruction. The register state is captured into RealModeState immediately + so when accessing stack contents, the 16-bit real mode code must account for the 16-bit segment + and 16-bit offset of the return address that were pushed onto the stack. The 16-bit real mode entry + point must exit with a RETF instruction. The register state is captured into RealModeState immediately after the RETF instruction is executed. - - If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, - or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure - the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode. - - If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, - then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode. + + If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, + or any of the 16-bit real mode code makes a SW interrupt, then the caller is responsible for making sure + the IDT at address 0 is initialized to handle any HW or SW interrupts that may occur while in 16-bit real mode. + + If EFLAGS specifies interrupts enabled, or any of the 16-bit real mode code enables interrupts, + then the caller is responsible for making sure the 8259 PIC is in a state compatible with 16-bit real mode. This includes the base vectors, the interrupt masks, and the edge/level trigger mode. - - If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code + + If THUNK_ATTRIBUTE_BIG_REAL_MODE is set in the ThunkAttributes field of ThunkContext, then the user code is invoked in big real mode. Otherwise, the user code is invoked in 16-bit real mode with 64KB segment limits. - - If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in - ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to + + If neither THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 nor THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in + ThunkAttributes, then it is assumed that the user code did not enable the A20 mask, and no attempt is made to disable the A20 mask. - - If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in - ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails, + + If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is set and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is clear in + ThunkAttributes, then attempt to use the INT 15 service to disable the A20 mask. If this INT 15 call fails, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports. - - If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in + + If THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 is clear and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL is set in ThunkAttributes, then attempt to disable the A20 mask by directly accessing the 8042 keyboard controller I/O ports. - + If ThunkContext is NULL, then ASSERT(). If AsmPrepareThunk16() was not previously called with ThunkContext, then ASSERT(). - If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in + If both THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 and THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL are set in ThunkAttributes, then ASSERT(). This interface is limited to be used in either physical mode or virtual modes with paging enabled where the @@ -8904,7 +7807,71 @@ AsmRdRand64 ( OUT UINT64 *Rand ); -#endif -#endif +/** + Load given selector into TR register. + + @param[in] Selector Task segment selector +**/ +VOID +EFIAPI +AsmWriteTr ( + IN UINT16 Selector + ); + +/** + Performs a serializing operation on all load-from-memory instructions that + were issued prior the AsmLfence function. + + Executes a LFENCE instruction. This function is only available on IA-32 and x64. +**/ +VOID +EFIAPI +AsmLfence ( + VOID + ); + +/** + Patch the immediate operand of an IA32 or X64 instruction such that the byte, + word, dword or qword operand is encoded at the end of the instruction's + binary representation. + + This function should be used to update object code that was compiled with + NASM from assembly source code. Example: + + NASM source code: + + mov eax, strict dword 0 ; the imm32 zero operand will be patched + ASM_PFX(gPatchCr3): + mov cr3, eax + + C source code: + + X86_ASSEMBLY_PATCH_LABEL gPatchCr3; + PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4); + + @param[out] InstructionEnd Pointer right past the instruction to patch. The + immediate operand to patch is expected to + comprise the trailing bytes of the instruction. + If InstructionEnd is closer to address 0 than + ValueSize permits, then ASSERT(). + + @param[in] PatchValue The constant to write to the immediate operand. + The caller is responsible for ensuring that + PatchValue can be represented in the byte, word, + dword or qword operand (as indicated through + ValueSize); otherwise ASSERT(). + + @param[in] ValueSize The size of the operand in bytes; must be 1, 2, + 4, or 8. ASSERT() otherwise. +**/ +VOID +EFIAPI +PatchInstructionX86 ( + OUT X86_ASSEMBLY_PATCH_LABEL *InstructionEnd, + IN UINT64 PatchValue, + IN UINTN ValueSize + ); +#endif // defined (MDE_CPU_IA32) || defined (MDE_CPU_X64) +#endif // !defined (__BASE_LIB__) diff --git a/MdePkg/Include/Library/BaseMemoryLib.h b/MdePkg/Include/Library/BaseMemoryLib.h index 31a403c56ab9..3c764aebc517 100644 --- a/MdePkg/Include/Library/BaseMemoryLib.h +++ b/MdePkg/Include/Library/BaseMemoryLib.h @@ -1,18 +1,12 @@ /** @file Provides copy memory, fill memory, zero memory, and GUID functions. - - The Base Memory Library provides optimized implementations for common memory-based operations. - These functions should be used in place of coding your own loops to do equivalent common functions. - This allows optimized library implementations to help increase performance. -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that accompanies this distribution. -The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php. + The Base Memory Library provides optimized implementations for common memory-based operations. + These functions should be used in place of coding your own loops to do equivalent common functions. + This allows optimized library implementations to help increase performance. -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -25,7 +19,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. This function copies Length bytes from SourceBuffer to DestinationBuffer, and returns DestinationBuffer. The implementation must be reentrant, and it must handle the case where SourceBuffer overlaps DestinationBuffer. - + If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT(). @@ -48,7 +42,7 @@ CopyMem ( Fills a target buffer with a byte value, and returns the target buffer. This function fills Length bytes of Buffer with Value, and returns Buffer. - + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). @param Buffer The memory to set. @@ -178,7 +172,7 @@ SetMemN ( Fills a target buffer with zeros, and returns the target buffer. This function fills Length bytes of Buffer with zeros, and returns Buffer. - + If Length > 0 and Buffer is NULL, then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). @@ -202,7 +196,7 @@ ZeroMem ( If all Length bytes of the two buffers are identical, then 0 is returned. Otherwise, the value returned is the first mismatched byte in SourceBuffer subtracted from the first mismatched byte in DestinationBuffer. - + If Length > 0 and DestinationBuffer is NULL, then ASSERT(). If Length > 0 and SourceBuffer is NULL, then ASSERT(). If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT(). @@ -215,7 +209,7 @@ ZeroMem ( @return 0 All Length bytes of the two buffers are identical. @retval Non-zero The first mismatched byte in SourceBuffer subtracted from the first mismatched byte in DestinationBuffer. - + **/ INTN EFIAPI @@ -233,7 +227,7 @@ CompareMem ( address to the highest address for an 8-bit value that matches Value. If a match is found, then a pointer to the matching byte in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. - + If Length > 0 and Buffer is NULL, then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). @@ -260,7 +254,7 @@ ScanMem8 ( address to the highest address for a 16-bit value that matches Value. If a match is found, then a pointer to the matching byte in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. - + If Length > 0 and 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(). @@ -289,7 +283,7 @@ ScanMem16 ( address to the highest address for a 32-bit value that matches Value. If a match is found, then a pointer to the matching byte in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. - + If Length > 0 and 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(). @@ -318,7 +312,7 @@ ScanMem32 ( address to the highest address for a 64-bit value that matches Value. If a match is found, then a pointer to the matching byte in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. - + If Length > 0 and 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(). @@ -340,14 +334,14 @@ ScanMem64 ( ); /** - Scans a target buffer for a UINTN sized value, and returns a pointer to the matching + Scans a target buffer for a UINTN sized value, and returns a pointer to the matching UINTN sized value in the target buffer. This function searches target the buffer specified by Buffer and Length from the lowest address to the highest address for a UINTN sized value that matches Value. If a match is found, then a pointer to the matching byte in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. - + If Length > 0 and Buffer is NULL, then ASSERT(). If Buffer is not aligned on a UINTN boundary, then ASSERT(). If Length is not aligned on a UINTN boundary, then ASSERT(). @@ -367,13 +361,13 @@ ScanMemN ( IN UINTN Length, IN UINTN Value ); - + /** Copies a source GUID to a destination GUID. This function copies the contents of the 128-bit GUID specified by SourceGuid to DestinationGuid, and returns DestinationGuid. - + If DestinationGuid is NULL, then ASSERT(). If SourceGuid is NULL, then ASSERT(). @@ -395,7 +389,7 @@ CopyGuid ( This function compares Guid1 to Guid2. If the GUIDs are identical then TRUE is returned. If there are any bit differences in the two GUIDs, then FALSE is returned. - + If Guid1 is NULL, then ASSERT(). If Guid2 is NULL, then ASSERT(). @@ -422,7 +416,7 @@ CompareGuid ( GUID value that matches Guid. If a match is found, then a pointer to the matching GUID in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. - + If Length > 0 and Buffer is NULL, then ASSERT(). If Buffer is not aligned on a 32-bit boundary, then ASSERT(). If Length is not aligned on a 128-bit boundary, then ASSERT(). diff --git a/MdePkg/Include/Library/CacheMaintenanceLib.h b/MdePkg/Include/Library/CacheMaintenanceLib.h index b2c6258a32a4..18bd6050f41d 100644 --- a/MdePkg/Include/Library/CacheMaintenanceLib.h +++ b/MdePkg/Include/Library/CacheMaintenanceLib.h @@ -1,17 +1,11 @@ /** @file Provides services to maintain instruction and data caches. - + The Cache Maintenance Library provides abstractions for basic processor cache operations. It removes the need to use assembly in C code. - -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/CpuLib.h b/MdePkg/Include/Library/CpuLib.h index 662e4d9ce69c..76e4fd1708d3 100644 --- a/MdePkg/Include/Library/CpuLib.h +++ b/MdePkg/Include/Library/CpuLib.h @@ -1,20 +1,14 @@ /** @file Provides CPU architecture specific functions that can not be defined in the Base Library due to dependencies on the PAL Library - + The CPU Library provides services to flush CPU TLBs and place the CPU in a sleep state. The implementation of these services on Itanium processors requires the use of PAL Calls. PAL Calls require PEI and DXE specific mechanisms to look up PAL Entry Point. As a result, these services could not be defined in the Base Library. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/DebugLib.h b/MdePkg/Include/Library/DebugLib.h index a26b635a22f1..d71dacd79d4a 100644 --- a/MdePkg/Include/Library/DebugLib.h +++ b/MdePkg/Include/Library/DebugLib.h @@ -1,6 +1,6 @@ /** @file Provides services to print debug and assert messages to a debug output device. - + The Debug library supports debug print and asserts based on a combination of macros and code. The debug library can be turned on and off so that the debug code does not increase the size of an image. @@ -8,14 +8,8 @@ of size reduction when compiler optimization is disabled. If MDEPKG_NDEBUG is defined, then debug and assert related macros wrapped by it are the NULL implementations. -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that 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. +Copyright (c) 2006 - 2020, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -80,15 +74,15 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Prints a debug message to the debug output device if the specified error level is enabled. - If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function - GetDebugPrintErrorLevel (), then print the message specified by Format and the + If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function + GetDebugPrintErrorLevel (), then print the message specified by Format and the associated variable argument list to the debug output device. If Format is NULL, then ASSERT(). @param ErrorLevel The error level of the debug message. @param Format The format string for the debug message to print. - @param ... The variable argument list whose contents are accessed + @param ... The variable argument list whose contents are accessed based on the format string specified by Format. **/ @@ -102,14 +96,64 @@ DebugPrint ( /** - Prints an assert message containing a filename, line number, and description. + Prints a debug message to the debug output device if the specified + error level is enabled. + + If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function + GetDebugPrintErrorLevel (), then print the message specified by Format and + the associated variable argument list to the debug output device. + + If Format is NULL, then ASSERT(). + + @param ErrorLevel The error level of the debug message. + @param Format Format string for the debug message to print. + @param VaListMarker VA_LIST marker for the variable argument list. + +**/ +VOID +EFIAPI +DebugVPrint ( + IN UINTN ErrorLevel, + IN CONST CHAR8 *Format, + IN VA_LIST VaListMarker + ); + + +/** + Prints a debug message to the debug output device if the specified + error level is enabled. + This function use BASE_LIST which would provide a more compatible + service than VA_LIST. + + If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function + GetDebugPrintErrorLevel (), then print the message specified by Format and + the associated variable argument list to the debug output device. + + If Format is NULL, then ASSERT(). + + @param ErrorLevel The error level of the debug message. + @param Format Format string for the debug message to print. + @param BaseListMarker BASE_LIST marker for the variable argument list. + +**/ +VOID +EFIAPI +DebugBPrint ( + IN UINTN ErrorLevel, + IN CONST CHAR8 *Format, + IN BASE_LIST BaseListMarker + ); + + +/** + Prints an assert message containing a filename, line number, and description. This may be followed by a breakpoint or a dead loop. Print a message of the form "ASSERT <FileName>(<LineNumber>): <Description>\n" - to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of - PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if - DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then - CpuDeadLoop() is called. If neither of these bits are set, then this function + to the debug output device. If DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED bit of + PcdDebugProperyMask is set then CpuBreakpoint() is called. Otherwise, if + DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED bit of PcdDebugProperyMask is set then + CpuDeadLoop() is called. If neither of these bits are set, then this function returns immediately after the message is printed to the debug output device. DebugAssert() must actively prevent recursion. If DebugAssert() is called while processing another DebugAssert(), then DebugAssert() must return immediately. @@ -134,14 +178,14 @@ DebugAssert ( /** Fills a target buffer with PcdDebugClearMemoryValue, and returns the target buffer. - This function fills Length bytes of Buffer with the value specified by + This function fills Length bytes of Buffer with the value specified by PcdDebugClearMemoryValue, and returns Buffer. If Buffer is NULL, then ASSERT(). - If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). @param Buffer The pointer to the target buffer to be filled with PcdDebugClearMemoryValue. - @param Length The number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. + @param Length The number of bytes in Buffer to fill with zeros PcdDebugClearMemoryValue. @return Buffer The pointer to the target buffer filled with PcdDebugClearMemoryValue. @@ -157,7 +201,7 @@ DebugClearMemory ( /** Returns TRUE if ASSERT() macros are enabled. - This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of + This function returns TRUE if the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set. Otherwise, FALSE is returned. @retval TRUE The DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set. @@ -171,10 +215,10 @@ DebugAssertEnabled ( ); -/** +/** Returns TRUE if DEBUG() macros are enabled. - This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of + This function returns TRUE if the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set. Otherwise, FALSE is returned. @retval TRUE The DEBUG_PROPERTY_DEBUG_PRINT_ENABLED bit of PcdDebugProperyMask is set. @@ -188,10 +232,10 @@ DebugPrintEnabled ( ); -/** +/** Returns TRUE if DEBUG_CODE() macros are enabled. - This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of + This function returns TRUE if the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set. Otherwise, FALSE is returned. @retval TRUE The DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set. @@ -205,10 +249,10 @@ DebugCodeEnabled ( ); -/** +/** Returns TRUE if DEBUG_CLEAR_MEMORY() macro is enabled. - This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of + This function returns TRUE if the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set. Otherwise, FALSE is returned. @retval TRUE The DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set. @@ -236,7 +280,7 @@ DebugPrintLevelEnabled ( IN CONST UINTN ErrorLevel ); -/** +/** Internal worker macro that calls DebugAssert(). This macro calls DebugAssert(), passing in the filename, line number, and an @@ -245,18 +289,22 @@ DebugPrintLevelEnabled ( @param Expression Boolean expression that evaluated to FALSE **/ +#if defined(__clang__) && defined(__FILE_NAME__) +#define _ASSERT(Expression) DebugAssert (__FILE_NAME__, __LINE__, #Expression) +#else #define _ASSERT(Expression) DebugAssert (__FILE__, __LINE__, #Expression) +#endif -/** +/** Internal worker macro that calls DebugPrint(). - This macro calls DebugPrint() passing in the debug error level, a format + This macro calls DebugPrint() passing in the debug error level, a format string, and a variable argument list. __VA_ARGS__ is not supported by EBC compiler, Microsoft Visual Studio .NET 2003 and Microsoft Windows Server 2003 Driver Development Kit (Microsoft WINDDK) version 3790.1830. - @param Expression Expression containing an error level, a format string, + @param Expression Expression containing an error level, a format string, and a variable argument list based on the format string. **/ @@ -273,19 +321,19 @@ DebugPrintLevelEnabled ( #define _DEBUG(Expression) DebugPrint Expression #endif -/** +/** Macro that calls DebugAssert() if an expression evaluates to FALSE. - If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED - bit of PcdDebugProperyMask is set, then this macro evaluates the Boolean - expression specified by Expression. If Expression evaluates to FALSE, then - DebugAssert() is called passing in the source filename, source line number, + If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED + bit of PcdDebugProperyMask is set, then this macro evaluates the Boolean + expression specified by Expression. If Expression evaluates to FALSE, then + DebugAssert() is called passing in the source filename, source line number, and Expression. @param Expression Boolean expression. **/ -#if !defined(MDEPKG_NDEBUG) +#if !defined(MDEPKG_NDEBUG) #define ASSERT(Expression) \ do { \ if (DebugAssertEnabled ()) { \ @@ -299,19 +347,19 @@ DebugPrintLevelEnabled ( #define ASSERT(Expression) #endif -/** +/** Macro that calls DebugPrint(). - If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED - bit of PcdDebugProperyMask is set, then this macro passes Expression to + If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED + bit of PcdDebugProperyMask is set, then this macro passes Expression to DebugPrint(). - @param Expression Expression containing an error level, a format string, + @param Expression Expression containing an error level, a format string, and a variable argument list based on the format string. - + **/ -#if !defined(MDEPKG_NDEBUG) +#if !defined(MDEPKG_NDEBUG) #define DEBUG(Expression) \ do { \ if (DebugPrintEnabled ()) { \ @@ -322,13 +370,13 @@ DebugPrintLevelEnabled ( #define DEBUG(Expression) #endif -/** +/** Macro that calls DebugAssert() if an EFI_STATUS evaluates to an error code. - If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED - bit of PcdDebugProperyMask is set, then this macro evaluates the EFI_STATUS - value specified by StatusParameter. If StatusParameter is an error code, - then DebugAssert() is called passing in the source filename, source line + If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED + bit of PcdDebugProperyMask is set, then this macro evaluates the EFI_STATUS + value specified by StatusParameter. If StatusParameter is an error code, + then DebugAssert() is called passing in the source filename, source line number, and StatusParameter. @param StatusParameter EFI_STATUS value to evaluate. @@ -375,23 +423,23 @@ DebugPrintLevelEnabled ( #define ASSERT_RETURN_ERROR(StatusParameter) #endif -/** - Macro that calls DebugAssert() if a protocol is already installed in the +/** + Macro that calls DebugAssert() if a protocol is already installed in the handle database. - If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit + If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear, then return. - If Handle is NULL, then a check is made to see if the protocol specified by Guid - is present on any handle in the handle database. If Handle is not NULL, then - a check is made to see if the protocol specified by Guid is present on the - handle specified by Handle. If the check finds the protocol, then DebugAssert() + If Handle is NULL, then a check is made to see if the protocol specified by Guid + is present on any handle in the handle database. If Handle is not NULL, then + a check is made to see if the protocol specified by Guid is present on the + handle specified by Handle. If the check finds the protocol, then DebugAssert() is called passing in the source filename, source line number, and Guid. If Guid is NULL, then ASSERT(). - @param Handle The handle to check for the protocol. This is an optional - parameter that may be NULL. If it is NULL, then the entire + @param Handle The handle to check for the protocol. This is an optional + parameter that may be NULL. If it is NULL, then the entire handle database is searched. @param Guid The pointer to a protocol GUID. @@ -421,32 +469,32 @@ DebugPrintLevelEnabled ( /** Macro that marks the beginning of debug source code. - If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, + If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, then this macro marks the beginning of source code that is included in a module. - Otherwise, the source lines between DEBUG_CODE_BEGIN() and DEBUG_CODE_END() + Otherwise, the source lines between DEBUG_CODE_BEGIN() and DEBUG_CODE_END() are not included in a module. **/ #define DEBUG_CODE_BEGIN() do { if (DebugCodeEnabled ()) { UINT8 __DebugCodeLocal -/** +/** The macro that marks the end of debug source code. - If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, - then this macro marks the end of source code that is included in a module. - Otherwise, the source lines between DEBUG_CODE_BEGIN() and DEBUG_CODE_END() + If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, + then this macro marks the end of source code that is included in a module. + Otherwise, the source lines between DEBUG_CODE_BEGIN() and DEBUG_CODE_END() are not included in a module. **/ #define DEBUG_CODE_END() __DebugCodeLocal = 0; __DebugCodeLocal++; } } while (FALSE) -/** +/** The macro that declares a section of debug source code. - If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, - then the source code specified by Expression is included in a module. + If the DEBUG_PROPERTY_DEBUG_CODE_ENABLED bit of PcdDebugProperyMask is set, + then the source code specified by Expression is included in a module. Otherwise, the source specified by Expression is not included in a module. **/ @@ -456,10 +504,10 @@ DebugPrintLevelEnabled ( DEBUG_CODE_END () -/** +/** The macro that calls DebugClearMemory() to clear a buffer to a default value. - If the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set, + If the DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED bit of PcdDebugProperyMask is set, then this macro calls DebugClearMemory() passing in Address and Length. @param Address The pointer to a buffer. @@ -475,42 +523,42 @@ DebugPrintLevelEnabled ( /** - Macro that calls DebugAssert() if the containing record does not have a - matching signature. If the signatures matches, then a pointer to the data - structure that contains a specified field of that data structure is returned. - This is a lightweight method hide information by placing a public data - structure inside a larger private data structure and using a pointer to the + Macro that calls DebugAssert() if the containing record does not have a + matching signature. If the signatures matches, then a pointer to the data + structure that contains a specified field of that data structure is returned. + This is a lightweight method hide information by placing a public data + structure inside a larger private data structure and using a pointer to the public data structure to retrieve a pointer to the private data structure. - If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit + If MDEPKG_NDEBUG is defined or the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is clear, then this macro computes the offset, in bytes, - of the field specified by Field from the beginning of the data structure specified - by TYPE. This offset is subtracted from Record, and is used to return a pointer + of the field specified by Field from the beginning of the data structure specified + by TYPE. This offset is subtracted from Record, and is used to return a pointer to a data structure of the type specified by TYPE. If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit - of PcdDebugProperyMask is set, then this macro computes the offset, in bytes, - of field specified by Field from the beginning of the data structure specified + of PcdDebugProperyMask is set, then this macro computes the offset, in bytes, + of field specified by Field from the beginning of the data structure specified by TYPE. This offset is subtracted from Record, and is used to compute a pointer - to a data structure of the type specified by TYPE. The Signature field of the - data structure specified by TYPE is compared to TestSignature. If the signatures - match, then a pointer to the pointer to a data structure of the type specified by - TYPE is returned. If the signatures do not match, then DebugAssert() is called - with a description of "CR has a bad signature" and Record is returned. + to a data structure of the type specified by TYPE. The Signature field of the + data structure specified by TYPE is compared to TestSignature. If the signatures + match, then a pointer to the pointer to a data structure of the type specified by + TYPE is returned. If the signatures do not match, then DebugAssert() is called + with a description of "CR has a bad signature" and Record is returned. - If the data type specified by TYPE does not contain the field specified by Field, + If the data type specified by TYPE does not contain the field specified by Field, then the module will not compile. - If TYPE does not contain a field called Signature, then the module will not + If TYPE does not contain a field called Signature, then the module will not compile. - @param Record The pointer to the field specified by Field within a data + @param Record The pointer to the field specified by Field within a data structure of type TYPE. - @param TYPE The name of the data structure type to return This - data structure must contain the field specified by Field. + @param TYPE The name of the data structure type to return This + data structure must contain the field specified by Field. - @param Field The name of the field in the data structure specified + @param Field The name of the field in the data structure specified by TYPE to which Record points. @param TestSignature The 32-bit signature value to match. @@ -525,5 +573,5 @@ DebugPrintLevelEnabled ( #define CR(Record, TYPE, Field, TestSignature) \ BASE_CR (Record, TYPE, Field) #endif - + #endif diff --git a/MdePkg/Include/Library/DebugPrintErrorLevelLib.h b/MdePkg/Include/Library/DebugPrintErrorLevelLib.h index 496f07b54d17..f57097f815b4 100644 --- a/MdePkg/Include/Library/DebugPrintErrorLevelLib.h +++ b/MdePkg/Include/Library/DebugPrintErrorLevelLib.h @@ -1,14 +1,8 @@ /** @file Debug Print Error Level Library class - Copyright (c) 2011, Intel Corporation. All rights reserved.<BR> - 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. + Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef _DEBUG_PRINT_ERROR_LEVEL_LIB_H_ @@ -28,9 +22,9 @@ GetDebugPrintErrorLevel ( /** Sets the global debug print error level mask fpr the entire platform. - + @param ErrorLevel Global debug print error level - + @retval TRUE The debug print error level mask was successfully set. @retval FALSE The debug print error level mask could not be set. diff --git a/MdePkg/Include/Library/DevicePathLib.h b/MdePkg/Include/Library/DevicePathLib.h index 61fa19ce690d..687b5b30dda0 100644 --- a/MdePkg/Include/Library/DevicePathLib.h +++ b/MdePkg/Include/Library/DevicePathLib.h @@ -1,17 +1,11 @@ /** @file Provides library functions to construct and parse UEFI Device Paths. - This library provides defines, macros, and functions to help create and parse + This library provides defines, macros, and functions to help create and parse EFI_DEVICE_PATH_PROTOCOL structures. -Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that 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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -22,12 +16,13 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Determine whether a given device path is valid. - If DevicePath is NULL, then ASSERT(). @param DevicePath A pointer to a device path data structure. @param MaxSize The maximum size of the device path data structure. @retval TRUE DevicePath is valid. + @retval FALSE DevicePath is NULL. + @retval FALSE Maxsize is less than sizeof(EFI_DEVICE_PATH_PROTOCOL). @retval FALSE The length of any node node in the DevicePath is less than sizeof (EFI_DEVICE_PATH_PROTOCOL). @retval FALSE If MaxSize is not zero, the size of the DevicePath @@ -81,9 +76,9 @@ DevicePathSubType ( /** Returns the 16-bit Length field of a device path node. - Returns the 16-bit Length field of the device path node specified by Node. + Returns the 16-bit Length field of the device path node specified by Node. Node is not required to be aligned on a 16-bit boundary, so it is recommended - that a function such as ReadUnaligned16() be used to extract the contents of + that a function such as ReadUnaligned16() be used to extract the contents of the Length field. If Node is NULL, then ASSERT(). @@ -119,12 +114,12 @@ NextDevicePathNode ( /** Determines if a device path node is an end node of a device path. - This includes nodes that are the end of a device path instance and nodes that + This includes nodes that are the end of a device path instance and nodes that are the end of an entire device path. - Determines if the device path node specified by Node is an end node of a device path. - This includes nodes that are the end of a device path instance and nodes that are the - end of an entire device path. If Node represents an end node of a device path, + Determines if the device path node specified by Node is an end node of a device path. + This includes nodes that are the end of a device path instance and nodes that are the + end of an entire device path. If Node represents an end node of a device path, then TRUE is returned. Otherwise, FALSE is returned. If Node is NULL, then ASSERT(). @@ -133,7 +128,7 @@ NextDevicePathNode ( @retval TRUE The device path node specified by Node is an end node of a device path. @retval FALSE The device path node specified by Node is not an end node of a device path. - + **/ BOOLEAN EFIAPI @@ -186,8 +181,8 @@ IsDevicePathEndInstance ( /** Sets the length, in bytes, of a device path node. - Sets the length of the device path node specified by Node to the value specified - by NodeLength. NodeLength is returned. Node is not required to be aligned on + Sets the length of the device path node specified by Node to the value specified + by NodeLength. NodeLength is returned. Node is not required to be aligned on a 16-bit boundary, so it is recommended that a function such as WriteUnaligned16() be used to set the contents of the Length field. @@ -211,15 +206,15 @@ SetDevicePathNodeLength ( /** Fills in all the fields of a device path node that is the end of an entire device path. - Fills in all the fields of a device path node specified by Node so Node represents - the end of an entire device path. The Type field of Node is set to - END_DEVICE_PATH_TYPE, the SubType field of Node is set to - END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to - END_DEVICE_PATH_LENGTH. Node is not required to be aligned on a 16-bit boundary, - so it is recommended that a function such as WriteUnaligned16() be used to set - the contents of the Length field. + Fills in all the fields of a device path node specified by Node so Node represents + the end of an entire device path. The Type field of Node is set to + END_DEVICE_PATH_TYPE, the SubType field of Node is set to + END_ENTIRE_DEVICE_PATH_SUBTYPE, and the Length field of Node is set to + END_DEVICE_PATH_LENGTH. Node is not required to be aligned on a 16-bit boundary, + so it is recommended that a function such as WriteUnaligned16() be used to set + the contents of the Length field. - If Node is NULL, then ASSERT(). + If Node is NULL, then ASSERT(). @param Node A pointer to a device path node data structure. @@ -233,7 +228,7 @@ SetDevicePathEndNode ( /** Returns the size of a device path in bytes. - This function returns the size, in bytes, of the device path data structure + This function returns the size, in bytes, of the device path data structure specified by DevicePath including the end of device path node. If DevicePath is NULL or invalid, then 0 is returned. @@ -255,15 +250,15 @@ GetDevicePathSize ( This function allocates space for a new copy of the device path specified by DevicePath. If DevicePath is NULL, then NULL is returned. If the memory is successfully allocated, then the contents of DevicePath are copied to the newly allocated buffer, and a pointer to that buffer - is returned. Otherwise, NULL is returned. - The memory for the new device path is allocated from EFI boot services memory. - It is the responsibility of the caller to free the memory allocated. - + is returned. Otherwise, NULL is returned. + The memory for the new device path is allocated from EFI boot services memory. + It is the responsibility of the caller to free the memory allocated. + @param DevicePath A pointer to a device path data structure. @retval NULL DevicePath is NULL or invalid. @retval Others A pointer to the duplicated device path. - + **/ EFI_DEVICE_PATH_PROTOCOL * EFIAPI @@ -276,18 +271,18 @@ DuplicateDevicePath ( This function creates a new device path by appending a copy of SecondDevicePath to a copy of FirstDevicePath in a newly allocated buffer. Only the end-of-device-path device node from - SecondDevicePath is retained. The newly created device path is returned. - If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned. - If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned. + SecondDevicePath is retained. The newly created device path is returned. + If FirstDevicePath is NULL, then it is ignored, and a duplicate of SecondDevicePath is returned. + If SecondDevicePath is NULL, then it is ignored, and a duplicate of FirstDevicePath is returned. If both FirstDevicePath and SecondDevicePath are NULL, then a copy of an end-of-device-path is - returned. + returned. If there is not enough memory for the newly allocated buffer, then NULL is returned. The memory for the new device path is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated. @param FirstDevicePath A pointer to a device path data structure. @param SecondDevicePath A pointer to a device path data structure. - + @retval NULL If there is not enough memory for the newly allocated buffer. @retval NULL If FirstDevicePath or SecondDevicePath is invalid. @retval Others A pointer to the new device path if success. @@ -312,7 +307,7 @@ AppendDevicePath ( node is returned. If both DevicePathNode and DevicePath are NULL then a copy of an end-of-device-path device node is returned. - If there is not enough memory to allocate space for the new device path, then NULL is returned. + If there is not enough memory to allocate space for the new device path, then NULL is returned. The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated. @@ -321,7 +316,7 @@ AppendDevicePath ( @retval NULL There is not enough memory for the new device path. @retval Others A pointer to the new device path if success. - A copy of DevicePathNode followed by an end-of-device-path node + A copy of DevicePathNode followed by an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL. A copy of an end-of-device-path node if both FirstDevicePath and SecondDevicePath are NULL. @@ -336,18 +331,18 @@ AppendDevicePathNode ( /** Creates a new device path by appending the specified device path instance to the specified device path. - + This function creates a new device path by appending a copy of the device path instance specified by DevicePathInstance to a copy of the device path secified by DevicePath in a allocated buffer. The end-of-device-path device node is moved after the end of the appended device path instance - and a new end-of-device-path-instance node is inserted between. + and a new end-of-device-path-instance node is inserted between. If DevicePath is NULL, then a copy if DevicePathInstance is returned. If DevicePathInstance is NULL, then NULL is returned. If DevicePath or DevicePathInstance is invalid, then NULL is returned. - If there is not enough memory to allocate space for the new device path, then NULL is returned. + If there is not enough memory to allocate space for the new device path, then NULL is returned. The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated. - + @param DevicePath A pointer to a device path data structure. @param DevicePathInstance A pointer to a device path instance. @@ -370,11 +365,11 @@ AppendDevicePathInstance ( to hold the size of the device path instance copy. If DevicePath is NULL, then NULL is returned. If DevicePath points to a invalid device path, then NULL is returned. - If there is not enough memory to allocate space for the new device path, then NULL is returned. + If there is not enough memory to allocate space for the new device path, then NULL is returned. The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated. If Size is NULL, then ASSERT(). - + @param DevicePath On input, this holds the pointer to the current device path instance. On output, this holds the pointer to the next device path instance or NULL if there are no more device path @@ -399,8 +394,8 @@ GetNextDevicePathInstance ( This function creates a new device node in a newly allocated buffer of size NodeLength and initializes the device path node header with NodeType and NodeSubType. The new device path node is returned. - If NodeLength is smaller than a device path header, then NULL is returned. - If there is not enough memory to allocate space for the new device path, then NULL is returned. + If NodeLength is smaller than a device path header, then NULL is returned. + If there is not enough memory to allocate space for the new device path, then NULL is returned. The memory is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated. @@ -443,7 +438,7 @@ IsDevicePathMultiInstance ( This function returns the device path protocol from the handle specified by Handle. If Handle is NULL or Handle does not contain a device path protocol, then NULL is returned. - + @param Handle The handle from which to retrieve the device path protocol. @return The device path protocol from the handle specified by Handle. @@ -465,7 +460,7 @@ DevicePathFromHandle ( path node for the file specified by FileName is allocated and returned. The memory for the new device path is allocated from EFI boot services memory. It is the responsibility of the caller to free the memory allocated. - + If FileName is NULL, then ASSERT(). If FileName is not aligned on a 16-bit boundary, then ASSERT(). diff --git a/MdePkg/Include/Library/DxeCoreEntryPoint.h b/MdePkg/Include/Library/DxeCoreEntryPoint.h index b0de4ee9ff3e..0a18966e03ea 100644 --- a/MdePkg/Include/Library/DxeCoreEntryPoint.h +++ b/MdePkg/Include/Library/DxeCoreEntryPoint.h @@ -1,14 +1,8 @@ /** @file Module entry point library for DXE core. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -16,13 +10,13 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define __MODULE_ENTRY_POINT_H__ /// -/// Global variable that contains a pointer to the Hob List passed into the DXE Core entry point. -/// +/// Global variable that contains a pointer to the Hob List passed into the DXE Core entry point. +/// extern VOID *gHobList; /** - The entry point of PE/COFF Image for the DXE Core. + The entry point of PE/COFF Image for the DXE Core. This function is the entry point for the DXE Core. This function is required to call ProcessModuleEntryPointList() and ProcessModuleEntryPointList() is never expected to return. @@ -30,7 +24,7 @@ extern VOID *gHobList; System Table and the image handle for the DXE Core itself have been established. If ProcessModuleEntryPointList() returns, then ASSERT() and halt the system. - @param HobStart Pointer to the beginning of the HOB List passed in from the PEI Phase. + @param HobStart Pointer to the beginning of the HOB List passed in from the PEI Phase. **/ VOID @@ -45,7 +39,7 @@ _ModuleEntryPoint ( This function is required to call _ModuleEntryPoint() passing in HobStart. - @param HobStart Pointer to the beginning of the HOB List passed in from the PEI Phase. + @param HobStart Pointer to the beginning of the HOB List passed in from the PEI Phase. **/ VOID @@ -83,12 +77,12 @@ ProcessLibraryConstructorList ( Autogenerated function that calls a set of module entry points. This function must be called by _ModuleEntryPoint(). - This function calls the set of module entry points. + This function calls the set of module entry points. This function is autogenerated by build tools and those build tools are responsible for collecting the module entry points and calling them in a specified order. - @param HobStart Pointer to the beginning of the HOB List passed in from the PEI Phase. - + @param HobStart Pointer to the beginning of the HOB List passed in from the PEI Phase. + **/ VOID EFIAPI diff --git a/MdePkg/Include/Library/DxeServicesLib.h b/MdePkg/Include/Library/DxeServicesLib.h index 48cb70339850..54040e8289eb 100644 --- a/MdePkg/Include/Library/DxeServicesLib.h +++ b/MdePkg/Include/Library/DxeServicesLib.h @@ -1,16 +1,10 @@ /** @file - MDE DXE Services Library provides functions that simplify the development of DXE Drivers. + MDE DXE Services Library provides functions that simplify the development of DXE Drivers. These functions help access data from sections of FFS files or from file path. -Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> (C) Copyright 2015 Hewlett Packard Enterprise Development LP<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that 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. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -18,20 +12,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define __DXE_SERVICES_LIB_H__ /** - Searches all the available firmware volumes and returns the first matching FFS section. + Searches all the available firmware volumes and returns the first matching FFS section. This function searches all the firmware volumes for FFS files with FV file type specified by FileType - The order that the firmware volumes is searched is not deterministic. For each available FV a search - is made for FFS file of type FileType. If the FV contains more than one FFS file with the same FileType, - the FileInstance instance will be the matched FFS file. For each FFS file found a search - is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances - of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer. - Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. - It is the caller's responsibility to use FreePool() to free the allocated buffer. - See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections + The order that the firmware volumes is searched is not deterministic. For each available FV a search + is made for FFS file of type FileType. If the FV contains more than one FFS file with the same FileType, + the FileInstance instance will be the matched FFS file. For each FFS file found a search + is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances + of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer. + Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. + It is the caller's responsibility to use FreePool() to free the allocated buffer. + See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections are retrieved from an FFS file based on SectionType and SectionInstance. - If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, + If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, the search will be retried with a section type of EFI_SECTION_PE32. This function must be called with a TPL <= TPL_NOTIFY. @@ -41,9 +35,9 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @param FileType Indicates the FV file type to search for within all available FVs. @param FileInstance Indicates which file instance within all available FVs specified by FileType. FileInstance starts from zero. - @param SectionType Indicates the FFS section type to search for within the FFS file + @param SectionType Indicates the FFS section type to search for within the FFS file specified by FileType with FileInstance. - @param SectionInstance Indicates which section instance within the FFS file + @param SectionInstance Indicates which section instance within the FFS file specified by FileType with FileInstance to retrieve. SectionInstance starts from zero. @param Buffer On output, a pointer to a callee allocated buffer containing the FFS file section that was found. Is it the caller's responsibility to free this buffer using FreePool(). @@ -53,7 +47,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @retval EFI_NOT_FOUND The specified FFS section could not be found. @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve the matching FFS section. @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a device error. - @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the firmware volume that + @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the firmware volume that contains the matching FFS section does not allow reads. **/ EFI_STATUS @@ -68,18 +62,18 @@ GetSectionFromAnyFvByFileType ( ); /** - Searches all the available firmware volumes and returns the first matching FFS section. - - This function searches all the firmware volumes for FFS files with an FFS filename specified by NameGuid. - The order in which the firmware volumes are searched is not deterministic. For each FFS file found, a search - is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances - of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer. - Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. - It is the caller's responsibility to use FreePool() to free the allocated buffer. - See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections + Searches all the available firmware volumes and returns the first matching FFS section. + + This function searches all the firmware volumes for FFS files with an FFS filename specified by NameGuid. + The order in which the firmware volumes are searched is not deterministic. For each FFS file found, a search + is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances + of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer. + Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. + It is the caller's responsibility to use FreePool() to free the allocated buffer. + See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections are retrieved from an FFS file based on SectionType and SectionInstance. - If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, + If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, the search will be retried with a section type of EFI_SECTION_PE32. This function must be called with a TPL <= TPL_NOTIFY. @@ -88,26 +82,26 @@ GetSectionFromAnyFvByFileType ( If Size is NULL, then ASSERT(). - @param NameGuid A pointer to to the FFS filename GUID to search for - within any of the firmware volumes in the platform. - @param SectionType Indicates the FFS section type to search for within + @param NameGuid A pointer to to the FFS filename GUID to search for + within any of the firmware volumes in the platform. + @param SectionType Indicates the FFS section type to search for within the FFS file specified by NameGuid. - @param SectionInstance Indicates which section instance within the FFS file + @param SectionInstance Indicates which section instance within the FFS file specified by NameGuid to retrieve. - @param Buffer On output, a pointer to a callee-allocated buffer - containing the FFS file section that was found. - It is the caller's responsibility to free this + @param Buffer On output, a pointer to a callee-allocated buffer + containing the FFS file section that was found. + It is the caller's responsibility to free this buffer using FreePool(). @param Size On output, a pointer to the size, in bytes, of Buffer. @retval EFI_SUCCESS The specified FFS section was returned. @retval EFI_NOT_FOUND The specified FFS section could not be found. - @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve the matching FFS section. - @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a + @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a device error. - @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the - firmware volume that contains the matching FFS + @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the + firmware volume that contains the matching FFS section does not allow reads. **/ EFI_STATUS @@ -121,49 +115,49 @@ GetSectionFromAnyFv ( ); /** - Searches the firmware volume that the currently executing module was loaded from and returns the first matching FFS section. + Searches the firmware volume that the currently executing module was loaded from and returns the first matching FFS section. - This function searches the firmware volume that the currently executing module was loaded - from for an FFS file with an FFS filename specified by NameGuid. If the FFS file is found, a search - is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance + This function searches the firmware volume that the currently executing module was loaded + from for an FFS file with an FFS filename specified by NameGuid. If the FFS file is found, a search + is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer. - Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. - It is the caller's responsibility to use FreePool() to free the allocated buffer. - See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections are retrieved from + Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. + It is the caller's responsibility to use FreePool() to free the allocated buffer. + See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections are retrieved from an FFS file based on SectionType and SectionInstance. If the currently executing module was not loaded from a firmware volume, then EFI_NOT_FOUND is returned. - If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, + If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, the search will be retried with a section type of EFI_SECTION_PE32. - + This function must be called with a TPL <= TPL_NOTIFY. If NameGuid is NULL, then ASSERT(). If Buffer is NULL, then ASSERT(). If Size is NULL, then ASSERT(). - @param NameGuid A pointer to to the FFS filename GUID to search for - within the firmware volumes that the currently + @param NameGuid A pointer to to the FFS filename GUID to search for + within the firmware volumes that the currently executing module was loaded from. - @param SectionType Indicates the FFS section type to search for within + @param SectionType Indicates the FFS section type to search for within the FFS file specified by NameGuid. - @param SectionInstance Indicates which section instance within the FFS + @param SectionInstance Indicates which section instance within the FFS file specified by NameGuid to retrieve. - @param Buffer On output, a pointer to a callee allocated buffer - containing the FFS file section that was found. - It is the caller's responsibility to free this buffer + @param Buffer On output, a pointer to a callee allocated buffer + containing the FFS file section that was found. + It is the caller's responsibility to free this buffer using FreePool(). @param Size On output, a pointer to the size, in bytes, of Buffer. @retval EFI_SUCCESS The specified FFS section was returned. @retval EFI_NOT_FOUND The specified FFS section could not be found. - @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve the matching FFS section. - @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a + @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a device error. - @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the - firmware volume that contains the matching FFS - section does not allow reads. + @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the + firmware volume that contains the matching FFS + section does not allow reads. **/ EFI_STATUS EFIAPI @@ -177,46 +171,46 @@ GetSectionFromFv ( /** - Searches the FFS file the the currently executing module was loaded from and returns the first matching FFS section. + Searches the FFS file the currently executing module was loaded from and returns the first matching FFS section. This function searches the FFS file that the currently executing module was loaded from for a FFS sections of type SectionType. - If the FFS file contains at least SectionInstance instances of the FFS section specified by SectionType, - then the SectionInstance instance is returned in Buffer. Buffer is allocated using AllocatePool(), - and the size of the allocated buffer is returned in Size. It is the caller's responsibility - to use FreePool() to free the allocated buffer. See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for + If the FFS file contains at least SectionInstance instances of the FFS section specified by SectionType, + then the SectionInstance instance is returned in Buffer. Buffer is allocated using AllocatePool(), + and the size of the allocated buffer is returned in Size. It is the caller's responsibility + to use FreePool() to free the allocated buffer. See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections are retrieved from an FFS file based on SectionType and SectionInstance. If the currently executing module was not loaded from an FFS file, then EFI_NOT_FOUND is returned. - If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, + If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, the search will be retried with a section type of EFI_SECTION_PE32. This function must be called with a TPL <= TPL_NOTIFY. - + If Buffer is NULL, then ASSERT(). If Size is NULL, then ASSERT(). - @param SectionType Indicates the FFS section type to search for within - the FFS file that the currently executing module + @param SectionType Indicates the FFS section type to search for within + the FFS file that the currently executing module was loaded from. - @param SectionInstance Indicates which section instance to retrieve within - the FFS file that the currently executing module + @param SectionInstance Indicates which section instance to retrieve within + the FFS file that the currently executing module was loaded from. - @param Buffer On output, a pointer to a callee allocated buffer - containing the FFS file section that was found. - It is the caller's responsibility to free this buffer + @param Buffer On output, a pointer to a callee allocated buffer + containing the FFS file section that was found. + It is the caller's responsibility to free this buffer using FreePool(). @param Size On output, a pointer to the size, in bytes, of Buffer. @retval EFI_SUCCESS The specified FFS section was returned. @retval EFI_NOT_FOUND The specified FFS section could not be found. - @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve the matching FFS section. - @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a + @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a device error. - @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the - firmware volume that contains the matching FFS - section does not allow reads. - + @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the + firmware volume that contains the matching FFS + section does not allow reads. + **/ EFI_STATUS EFIAPI @@ -229,22 +223,22 @@ GetSectionFromFfs ( /** - Get the image file buffer data and buffer size by its device path. - - Access the file either from a firmware volume, from a file system interface, + Get the image file buffer data and buffer size by its device path. + + Access the file either from a firmware volume, from a file system interface, or from the load file interface. - + Allocate memory to store the found image. The caller is responsible to free memory. If FilePath is NULL, then NULL is returned. If FileSize is NULL, then NULL is returned. If AuthenticationStatus is NULL, then NULL is returned. - @param[in] BootPolicy The policy for Open Image File.If TRUE, - indicates that the request originates from + @param[in] BootPolicy The policy for Open Image File.If TRUE, + indicates that the request originates from the boot manager, and that the boot manager is - attempting to load FilePath as a boot selection. - If FALSE, then FilePath must match an exact + attempting to load FilePath as a boot selection. + If FALSE, then FilePath must match an exact file to be loaded. @param[in] FilePath Pointer to the device path of the file that is abstracted to the file buffer. @@ -305,5 +299,26 @@ GetFileDevicePathFromAnyFv ( OUT EFI_DEVICE_PATH_PROTOCOL **FvFileDevicePath ); -#endif +/** + Allocates one or more 4KB pages of a given type from a memory region that is + accessible to PEI. + + Allocates the number of 4KB pages of type 'MemoryType' and returns a + pointer to the allocated buffer. The buffer returned is aligned on a 4KB + boundary. If Pages is 0, then NULL is returned. If there is not enough + memory remaining to satisfy the request, then NULL is returned. + + @param[in] MemoryType The memory type to allocate + @param[in] Pages The number of 4 KB pages to allocate. + + @return A pointer to the allocated buffer or NULL if allocation fails. +**/ +VOID * +EFIAPI +AllocatePeiAccessiblePages ( + IN EFI_MEMORY_TYPE MemoryType, + IN UINTN Pages + ); + +#endif diff --git a/MdePkg/Include/Library/DxeServicesTableLib.h b/MdePkg/Include/Library/DxeServicesTableLib.h index 0038715530fb..d604f4174747 100644 --- a/MdePkg/Include/Library/DxeServicesTableLib.h +++ b/MdePkg/Include/Library/DxeServicesTableLib.h @@ -1,24 +1,18 @@ /** @file Provides a service to retrieve a pointer to the DXE Services Table. Only available to DXE module types. - - This library does not contain any functions or macros. It simply exports a global - pointer to the DXE Services Table as defined in the Platform Initialization Driver - Execution Environment Core Interface Specification. The library constructor must + + This library does not contain any functions or macros. It simply exports a global + pointer to the DXE Services Table as defined in the Platform Initialization Driver + Execution Environment Core Interface Specification. The library constructor must initialize this global pointer to the DX Services Table, so it is available at the - module's entry point. Since there is overhead in looking up the pointer to the DXE - Services Table, only those modules that actually require access to the DXE Services - Table should use this library. This will typically be DXE Drivers that require GCD + module's entry point. Since there is overhead in looking up the pointer to the DXE + Services Table, only those modules that actually require access to the DXE Services + Table should use this library. This will typically be DXE Drivers that require GCD or Dispatcher services. - -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/ExtendedSalLib.h b/MdePkg/Include/Library/ExtendedSalLib.h deleted file mode 100644 index 710675ff8eeb..000000000000 --- a/MdePkg/Include/Library/ExtendedSalLib.h +++ /dev/null @@ -1,494 +0,0 @@ -/** @file - Library class definition of Extended SAL Library. - -Copyright (c) 2007 - 2011, Intel Corporation. All rights reserved.<BR> -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. - -**/ - -#ifndef _EXTENDED_SAL_LIB_H__ -#define _EXTENDED_SAL_LIB_H__ - -#include <IndustryStandard/Sal.h> - -/** - Register ESAL Class and its associated global. - - This function Registers one or more Extended SAL services in a given - class along with the associated global context. - This function is only available prior to ExitBootServices(). - - @param ClassGuidLo GUID of function class, lower 64-bits - @param ClassGuidHi GUID of function class, upper 64-bits - @param ModuleGlobal Module global for Function. - @param ... List of Function/FunctionId pairs, ended by NULL - - @retval EFI_SUCCESS The Extended SAL services were registered. - @retval EFI_UNSUPPORTED This function was called after ExitBootServices(). - @retval EFI_OUT_OF_RESOURCES There are not enough resources available to register one or more of the specified services. - @retval Other ClassGuid could not be installed onto a new handle. - -**/ -EFI_STATUS -EFIAPI -RegisterEsalClass ( - IN CONST UINT64 ClassGuidLo, - IN CONST UINT64 ClassGuidHi, - IN VOID *ModuleGlobal, OPTIONAL - ... - ); - -/** - Calls an Extended SAL Class service that was previously registered with RegisterEsalClass(). - - This function calls an Extended SAL Class service that was previously registered with RegisterEsalClass(). - - @param ClassGuidLo GUID of function, lower 64-bits - @param ClassGuidHi GUID of function, upper 64-bits - @param FunctionId Function in ClassGuid to call - @param Arg2 Argument 2 ClassGuid/FunctionId defined - @param Arg3 Argument 3 ClassGuid/FunctionId defined - @param Arg4 Argument 4 ClassGuid/FunctionId defined - @param Arg5 Argument 5 ClassGuid/FunctionId defined - @param Arg6 Argument 6 ClassGuid/FunctionId defined - @param Arg7 Argument 7 ClassGuid/FunctionId defined - @param Arg8 Argument 8 ClassGuid/FunctionId defined - - @retval EFI_SAL_ERROR The address of ExtendedSalProc() can not be determined - for the current CPU execution mode. - @retval Other See the return status from ExtendedSalProc() in the - EXTENDED_SAL_BOOT_SERVICE_PROTOCOL. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalCall ( - IN UINT64 ClassGuidLo, - IN UINT64 ClassGuidHi, - IN UINT64 FunctionId, - IN UINT64 Arg2, - IN UINT64 Arg3, - IN UINT64 Arg4, - IN UINT64 Arg5, - IN UINT64 Arg6, - IN UINT64 Arg7, - IN UINT64 Arg8 - ); - -/** - Wrapper for the EsalStallFunctionId service of Extended SAL Stall Services Class. - - This function is a wrapper for the EsalStallFunctionId service of Extended SAL - Stall Services Class. See EsalStallFunctionId of Extended SAL Specification. - - @param Microseconds The number of microseconds to delay. - - @retval EFI_SAL_SUCCESS Call completed without error. - @retval EFI_SAL_INVALID_ARGUMENT Invalid argument. - @retval EFI_SAL_VIRTUAL_ADDRESS_ERROR Virtual address not registered - -**/ -SAL_RETURN_REGS -EFIAPI -EsalStall ( - IN UINTN Microseconds - ); - -/** - Wrapper for the EsalSetNewPalEntryFunctionId service of Extended SAL PAL Services Services Class. - - This function is a wrapper for the EsalSetNewPalEntryFunctionId service of Extended SAL - PAL Services Services Class. See EsalSetNewPalEntryFunctionId of Extended SAL Specification. - - @param PhysicalAddress If TRUE, then PalEntryPoint is a physical address. - If FALSE, then PalEntryPoint is a virtual address. - @param PalEntryPoint The PAL Entry Point being set. - - @retval EFI_SAL_SUCCESS The PAL Entry Point was set. - @retval EFI_SAL_VIRTUAL_ADDRESS_ERROR This function was called in virtual mode before - virtual mappings for the specified Extended SAL - Procedure are available. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalSetNewPalEntry ( - IN BOOLEAN PhysicalAddress, - IN UINT64 PalEntryPoint - ); - -/** - Wrapper for the EsalGetNewPalEntryFunctionId service of Extended SAL PAL Services Services Class. - - This function is a wrapper for the EsalGetNewPalEntryFunctionId service of Extended SAL - PAL Services Services Class. See EsalGetNewPalEntryFunctionId of Extended SAL Specification. - - @param PhysicalAddress If TRUE, then PalEntryPoint is a physical address. - If FALSE, then PalEntryPoint is a virtual address. - - @retval EFI_SAL_SUCCESS The PAL Entry Point was retrieved and returned in - SAL_RETURN_REGS.r9. - @retval EFI_SAL_VIRTUAL_ADDRESS_ERROR This function was called in virtual mode before - virtual mappings for the specified Extended SAL - Procedure are available. - @return r9 PAL entry point retrieved. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalGetNewPalEntry ( - IN BOOLEAN PhysicalAddress - ); - -/** - Wrapper for the EsalGetStateBufferFunctionId service of Extended SAL MCA Log Services Class. - - This function is a wrapper for the EsalGetStateBufferFunctionId service of Extended SAL - MCA Log Services Class. See EsalGetStateBufferFunctionId of Extended SAL Specification. - - @param McaType See type parameter of SAL Procedure SAL_GET_STATE_INFO. - @param McaBuffer A pointer to the base address of the returned buffer. - Copied from SAL_RETURN_REGS.r9. - @param BufferSize A pointer to the size, in bytes, of the returned buffer. - Copied from SAL_RETURN_REGS.r10. - - @retval EFI_SAL_SUCCESS The memory buffer to store error records was returned in r9 and r10. - @retval EFI_OUT_OF_RESOURCES A memory buffer for string error records in not available - @return r9 Base address of the returned buffer - @return r10 Size of the returned buffer in bytes - -**/ -SAL_RETURN_REGS -EFIAPI -EsalGetStateBuffer ( - IN UINT64 McaType, - OUT UINT8 **McaBuffer, - OUT UINTN *BufferSize - ); - -/** - Wrapper for the EsalSaveStateBufferFunctionId service of Extended SAL MCA Log Services Class. - - This function is a wrapper for the EsalSaveStateBufferFunctionId service of Extended SAL - MCA Log Services Class. See EsalSaveStateBufferFunctionId of Extended SAL Specification. - - @param McaType See type parameter of SAL Procedure SAL_GET_STATE_INFO. - - @retval EFI_SUCCESS The memory buffer containing the error record was written to nonvolatile storage. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalSaveStateBuffer ( - IN UINT64 McaType - ); - -/** - Wrapper for the EsalGetVectorsFunctionId service of Extended SAL Base Services Class. - - This function is a wrapper for the EsalGetVectorsFunctionId service of Extended SAL - Base Services Class. See EsalGetVectorsFunctionId of Extended SAL Specification. - - @param VectorType The vector type to retrieve. - 0 - MCA, 1 - BSP INIT, 2 - BOOT_RENDEZ, 3 - AP INIT. - - @retval EFI_SAL_SUCCESS Call completed without error. - @retval EFI_SAL_INVALID_ARGUMENT Invalid argument. - @retval EFI_SAL_NO_INFORMATION The requested vector has not been registered - with the SAL Procedure SAL_SET_VECTORS. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalGetVectors ( - IN UINT64 VectorType - ); - -/** - Wrapper for the EsalMcGetParamsFunctionId service of Extended SAL Base Services Class. - - This function is a wrapper for the EsalMcGetParamsFunctionId service of Extended SAL - Base Services Class. See EsalMcGetParamsFunctionId of Extended SAL Specification. - - @param ParamInfoType The parameter type to retrieve. - 1 - rendezvous interrupt - 2 - wake up - 3 - Corrected Platform Error Vector. - - @retval EFI_SAL_SUCCESS Call completed without error. - @retval EFI_SAL_INVALID_ARGUMENT Invalid argument. - @retval EFI_SAL_NO_INFORMATION The requested vector has not been registered - with the SAL Procedure SAL_MC_SET_PARAMS. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalMcGetParams ( - IN UINT64 ParamInfoType - ); - -/** - Wrapper for the EsalMcGetParamsFunctionId service of Extended SAL Base Services Class. - - This function is a wrapper for the EsalMcGetParamsFunctionId service of Extended SAL - Base Services Class. See EsalMcGetParamsFunctionId of Extended SAL Specification. - - @retval EFI_SAL_SUCCESS Call completed without error. - @retval EFI_SAL_NO_INFORMATION The requested vector has not been registered - with the SAL Procedure SAL_MC_SET_PARAMS. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalMcGetMcParams ( - VOID - ); - -/** - Wrapper for the EsalGetMcCheckinFlagsFunctionId service of Extended SAL Base Services Class. - - This function is a wrapper for the EsalGetMcCheckinFlagsFunctionId service of Extended SAL - Base Services Class. See EsalGetMcCheckinFlagsFunctionId of Extended SAL Specification. - - @param CpuIndex The index of the CPU of set of enabled CPUs to check. - - @retval EFI_SAL_SUCCESS The checkin status of the requested CPU was returned. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalGetMcCheckinFlags ( - IN UINT64 CpuIndex - ); - -/** - Wrapper for the EsalAddCpuDataFunctionId service of Extended SAL MP Services Class. - - This function is a wrapper for the EsalAddCpuDataFunctionId service of Extended SAL - MP Services Class. See EsalAddCpuDataFunctionId of Extended SAL Specification. - - @param CpuGlobalId The Global ID for the CPU being added. - @param Enabled The enable flag for the CPU being added. - TRUE means the CPU is enabled. - FALSE means the CPU is disabled. - @param PalCompatibility The PAL Compatibility value for the CPU being added. - - @retval EFI_SAL_SUCCESS The CPU was added to the database. - @retval EFI_SAL_NOT_ENOUGH_SCRATCH There are not enough resource available to add the CPU. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalAddCpuData ( - IN UINT64 CpuGlobalId, - IN BOOLEAN Enabled, - IN UINT64 PalCompatibility - ); - -/** - Wrapper for the EsalRemoveCpuDataFunctionId service of Extended SAL MP Services Class. - - This function is a wrapper for the EsalRemoveCpuDataFunctionId service of Extended SAL - MP Services Class. See EsalRemoveCpuDataFunctionId of Extended SAL Specification. - - @param CpuGlobalId The Global ID for the CPU being removed. - - @retval EFI_SAL_SUCCESS The CPU was removed from the database. - @retval EFI_SAL_NO_INFORMATION The specified CPU is not in the database. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalRemoveCpuData ( - IN UINT64 CpuGlobalId - ); - -/** - Wrapper for the EsalModifyCpuDataFunctionId service of Extended SAL MP Services Class. - - This function is a wrapper for the EsalModifyCpuDataFunctionId service of Extended SAL - MP Services Class. See EsalModifyCpuDataFunctionId of Extended SAL Specification. - - @param CpuGlobalId The Global ID for the CPU being modified. - @param Enabled The enable flag for the CPU being modified. - TRUE means the CPU is enabled. - FALSE means the CPU is disabled. - @param PalCompatibility The PAL Compatibility value for the CPU being modified. - - @retval EFI_SAL_SUCCESS The CPU database was updated. - @retval EFI_SAL_NO_INFORMATION The specified CPU is not in the database. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalModifyCpuData ( - IN UINT64 CpuGlobalId, - IN BOOLEAN Enabled, - IN UINT64 PalCompatibility - ); - -/** - Wrapper for the EsalGetCpuDataByIdFunctionId service of Extended SAL MP Services Class. - - This function is a wrapper for the EsalGetCpuDataByIdFunctionId service of Extended SAL - MP Services Class. See EsalGetCpuDataByIdFunctionId of Extended SAL Specification. - - @param CpuGlobalId The Global ID for the CPU being looked up. - @param IndexByEnabledCpu If TRUE, then the index of set of enabled CPUs of database is returned. - If FALSE, then the index of set of all CPUs of database is returned. - - @retval EFI_SAL_SUCCESS The information on the specified CPU was returned. - @retval EFI_SAL_NO_INFORMATION The specified CPU is not in the database. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalGetCpuDataById ( - IN UINT64 CpuGlobalId, - IN BOOLEAN IndexByEnabledCpu - ); - -/** - Wrapper for the EsalGetCpuDataByIndexFunctionId service of Extended SAL MP Services Class. - - This function is a wrapper for the EsalGetCpuDataByIndexFunctionId service of Extended SAL - MP Services Class. See EsalGetCpuDataByIndexFunctionId of Extended SAL Specification. - - @param Index The Global ID for the CPU being modified. - @param IndexByEnabledCpu If TRUE, then the index of set of enabled CPUs of database is returned. - If FALSE, then the index of set of all CPUs of database is returned. - - @retval EFI_SAL_SUCCESS The information on the specified CPU was returned. - @retval EFI_SAL_NO_INFORMATION The specified CPU is not in the database. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalGetCpuDataByIndex ( - IN UINT64 Index, - IN BOOLEAN IndexByEnabledCpu - ); - -/** - Wrapper for the EsalWhoAmIFunctionId service of Extended SAL MP Services Class. - - This function is a wrapper for the EsalWhoAmIFunctionId service of Extended SAL - MP Services Class. See EsalWhoAmIFunctionId of Extended SAL Specification. - - @param IndexByEnabledCpu If TRUE, then the index of set of enabled CPUs of database is returned. - If FALSE, then the index of set of all CPUs of database is returned. - - @retval EFI_SAL_SUCCESS The Global ID for the calling CPU was returned. - @retval EFI_SAL_NO_INFORMATION The calling CPU is not in the database. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalWhoAmI ( - IN BOOLEAN IndexByEnabledCpu - ); - -/** - Wrapper for the EsalNumProcessors service of Extended SAL MP Services Class. - - This function is a wrapper for the EsalNumProcessors service of Extended SAL - MP Services Class. See EsalNumProcessors of Extended SAL Specification. - - @retval EFI_SAL_SUCCESS The information on the number of CPUs in the platform - was returned. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalNumProcessors ( - VOID - ); - -/** - Wrapper for the EsalSetMinStateFnctionId service of Extended SAL MP Services Class. - - This function is a wrapper for the EsalSetMinStateFnctionId service of Extended SAL - MP Services Class. See EsalSetMinStateFnctionId of Extended SAL Specification. - - @param CpuGlobalId The Global ID for the CPU whose MINSTATE pointer is being set. - @param MinStatePointer The physical address of the MINSTATE buffer for the CPU - specified by CpuGlobalId. - - @retval EFI_SAL_SUCCESS The MINSTATE pointer was set for the specified CPU. - @retval EFI_SAL_NO_INFORMATION The specified CPU is not in the database. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalSetMinState ( - IN UINT64 CpuGlobalId, - IN EFI_PHYSICAL_ADDRESS MinStatePointer - ); - -/** - Wrapper for the EsalGetMinStateFunctionId service of Extended SAL MP Services Class. - - This function is a wrapper for the EsalGetMinStateFunctionId service of Extended SAL - MP Services Class. See EsalGetMinStateFunctionId of Extended SAL Specification. - - @param CpuGlobalId The Global ID for the CPU whose MINSTATE pointer is being retrieved. - - @retval EFI_SAL_SUCCESS The MINSTATE pointer for the specified CPU was retrieved. - @retval EFI_SAL_NO_INFORMATION The specified CPU is not in the database. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalGetMinState ( - IN UINT64 CpuGlobalId - ); - -/** - Wrapper for the EsalMcsGetStateInfoFunctionId service of Extended SAL MCA Services Class. - - This function is a wrapper for the EsalMcsGetStateInfoFunctionId service of Extended SAL - MCA Services Class. See EsalMcsGetStateInfoFunctionId of Extended SAL Specification. - - @param CpuGlobalId The Global ID for the CPU whose MCA state buffer is being retrieved. - @param StateBufferPointer A pointer to the returned MCA state buffer. - @param RequiredStateBufferSize A pointer to the size, in bytes, of the returned MCA state buffer. - - @retval EFI_SUCCESS MINSTATE successfully got and size calculated. - @retval EFI_SAL_NO_INFORMATION Fail to get MINSTATE. - -**/ -SAL_RETURN_REGS -EFIAPI -EsalMcaGetStateInfo ( - IN UINT64 CpuGlobalId, - OUT EFI_PHYSICAL_ADDRESS *StateBufferPointer, - OUT UINT64 *RequiredStateBufferSize - ); - -/** - Wrapper for the EsalMcaRegisterCpuFunctionId service of Extended SAL MCA Services Class. - - This function is a wrapper for the EsalMcaRegisterCpuFunctionId service of Extended SAL - MCA Services Class. See EsalMcaRegisterCpuFunctionId of Extended SAL Specification. - - @param CpuGlobalId The Global ID for the CPU whose MCA state buffer is being set. - @param StateBufferPointer A pointer to the MCA state buffer. - - @retval EFI_SAL_NO_INFORMATION Cannot get the processor info with the CpuId - @retval EFI_SUCCESS Save the processor's state info successfully - -**/ -SAL_RETURN_REGS -EFIAPI -EsalMcaRegisterCpu ( - IN UINT64 CpuGlobalId, - IN EFI_PHYSICAL_ADDRESS StateBufferPointer - ); - -#endif diff --git a/MdePkg/Include/Library/ExtractGuidedSectionLib.h b/MdePkg/Include/Library/ExtractGuidedSectionLib.h index 73dfed2e292f..95c7670ada66 100644 --- a/MdePkg/Include/Library/ExtractGuidedSectionLib.h +++ b/MdePkg/Include/Library/ExtractGuidedSectionLib.h @@ -1,23 +1,17 @@ /** @file - This library provides common functions to process the different guided section data. - - This library provides functions to process GUIDed sections of FFS files. Handlers may - be registered to decode GUIDed sections of FFS files. Services are provided to determine - the set of supported section GUIDs, collection information about a specific GUIDed section, - and decode a specific GUIDed section. - - A library instance that produces this library class may be used to produce a - EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI or a EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL - providing a simple method to extend the number of GUIDed sections types a platform supports. + This library provides common functions to process the different guided section data. + + This library provides functions to process GUIDed sections of FFS files. Handlers may + be registered to decode GUIDed sections of FFS files. Services are provided to determine + the set of supported section GUIDs, collection information about a specific GUIDed section, + and decode a specific GUIDed section. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -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 + A library instance that produces this library class may be used to produce a + EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI or a EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL + providing a simple method to extend the number of GUIDed sections types a platform supports. -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef __EXTRACT_GUIDED_SECTION_H__ @@ -27,16 +21,16 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Examines a GUIDed section and returns the size of the decoded buffer and the size of an optional scratch buffer required to actually decode the data in a GUIDed section. - Examines a GUIDed section specified by InputSection. + Examines a GUIDed section specified by InputSection. If GUID for InputSection does not match the GUID that this handler supports, - then RETURN_UNSUPPORTED is returned. + then RETURN_UNSUPPORTED is returned. If the required information can not be retrieved from InputSection, then RETURN_INVALID_PARAMETER is returned. If the GUID of InputSection does match the GUID that this handler supports, then the size required to hold the decoded buffer is returned in OututBufferSize, the size of an optional scratch buffer is returned in ScratchSize, and the Attributes field from EFI_GUID_DEFINED_SECTION header of InputSection is returned in SectionAttribute. - + If InputSection is NULL, then ASSERT(). If OutputBufferSize is NULL, then ASSERT(). If ScratchBufferSize is NULL, then ASSERT(). @@ -67,16 +61,16 @@ RETURN_STATUS /** Decodes a GUIDed section into a caller allocated output buffer. - - Decodes the GUIDed section specified by InputSection. - If GUID for InputSection does not match the GUID that this handler supports, then RETURN_UNSUPPORTED is returned. + + Decodes the GUIDed section specified by InputSection. + If GUID for InputSection does not match the GUID that this handler supports, then RETURN_UNSUPPORTED is returned. If the data in InputSection can not be decoded, then RETURN_INVALID_PARAMETER is returned. If the GUID of InputSection does match the GUID that this handler supports, then InputSection is decoded into the buffer specified by OutputBuffer and the authentication status of this decode operation is returned in AuthenticationStatus. If the decoded buffer is identical to the data in InputSection, then OutputBuffer is set to point at the data in InputSection. Otherwise, the decoded data will be placed in caller allocated buffer specified by OutputBuffer. - + If InputSection is NULL, then ASSERT(). If OutputBuffer is NULL, then ASSERT(). If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT(). @@ -84,10 +78,10 @@ RETURN_STATUS @param[in] InputSection A pointer to a GUIDed section of an FFS formatted file. - @param[out] OutputBuffer A pointer to a buffer that contains the result of a decode operation. + @param[out] OutputBuffer A pointer to a buffer that contains the result of a decode operation. @param[out] ScratchBuffer A caller allocated buffer that may be required by this function - as a scratch buffer to perform the decode operation. - @param[out] AuthenticationStatus + as a scratch buffer to perform the decode operation. + @param[out] AuthenticationStatus A pointer to the authentication status of the decoded output buffer. See the definition of authentication status in the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI section of the PI Specification. EFI_AUTH_STATUS_PLATFORM_OVERRIDE must @@ -114,7 +108,7 @@ RETURN_STATUS Registers the handlers specified by GetInfoHandler and DecodeHandler with the GUID specified by SectionGuid. If the GUID value specified by SectionGuid has already been registered, then return RETURN_ALREADY_STARTED. If there are not enough resources available to register the handlers then RETURN_OUT_OF_RESOURCES is returned. - + If SectionGuid is NULL, then ASSERT(). If GetInfoHandler is NULL, then ASSERT(). If DecodeHandler is NULL, then ASSERT(). @@ -125,7 +119,7 @@ RETURN_STATUS size of the decoded buffer and the size of an optional scratch buffer required to actually decode the data in a GUIDed section. @param[in] DecodeHandler Pointer to a function that decodes a GUIDed section into a caller - allocated output buffer. + allocated output buffer. @retval RETURN_SUCCESS The handlers were registered. @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to register the handlers. @@ -144,7 +138,7 @@ ExtractGuidedSectionRegisterHandlers ( Sets ExtractHandlerGuidTable so it points at a callee allocated array of registered GUIDs. The total number of GUIDs in the array are returned. Since the array of GUIDs is callee allocated - and caller must treat this array of GUIDs as read-only data. + and caller must treat this array of GUIDs as read-only data. If ExtractHandlerGuidTable is NULL, then ASSERT(). @param[out] ExtractHandlerGuidTable A pointer to the array of GUIDs that have been registered through @@ -165,14 +159,14 @@ ExtractGuidedSectionGetGuidList ( The selected handler is used to retrieve and return the size of the decoded buffer and the size of an optional scratch buffer required to actually decode the data in a GUIDed section. - Examines a GUIDed section specified by InputSection. + Examines a GUIDed section specified by InputSection. If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(), - then RETURN_UNSUPPORTED is returned. - If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler + then RETURN_UNSUPPORTED is returned. + If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers() is used to retrieve the OututBufferSize, ScratchSize, and Attributes values. The return status from the handler of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER is returned. - + If InputSection is NULL, then ASSERT(). If OutputBufferSize is NULL, then ASSERT(). If ScratchBufferSize is NULL, then ASSERT(). @@ -199,7 +193,7 @@ ExtractGuidedSectionGetInfo ( IN CONST VOID *InputSection, OUT UINT32 *OutputBufferSize, OUT UINT32 *ScratchBufferSize, - OUT UINT16 *SectionAttribute + OUT UINT16 *SectionAttribute ); /** @@ -208,26 +202,26 @@ ExtractGuidedSectionGetInfo ( The selected handler is used to decode the data in a GUIDed section and return the result in a caller allocated output buffer. - Decodes the GUIDed section specified by InputSection. + Decodes the GUIDed section specified by InputSection. If GUID for InputSection does not match any of the GUIDs registered through ExtractGuidedSectionRegisterHandlers(), - then RETURN_UNSUPPORTED is returned. + then RETURN_UNSUPPORTED is returned. If the GUID of InputSection does match the GUID that this handler supports, then the the associated handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER that was registered with ExtractGuidedSectionRegisterHandlers() is used to decode InputSection into the buffer specified by OutputBuffer and the authentication status of this decode operation is returned in AuthenticationStatus. If the decoded buffer is identical to the data in InputSection, then OutputBuffer is set to point at the data in InputSection. Otherwise, the decoded data will be placed in caller allocated buffer specified by OutputBuffer. This function is responsible for computing the EFI_AUTH_STATUS_PLATFORM_OVERRIDE - bit of in AuthenticationStatus. The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned. - + bit of in AuthenticationStatus. The return status from the handler of type EXTRACT_GUIDED_SECTION_DECODE_HANDLER is returned. + If InputSection is NULL, then ASSERT(). If OutputBuffer is NULL, then ASSERT(). If ScratchBuffer is NULL and this decode operation requires a scratch buffer, then ASSERT(). - If AuthenticationStatus is NULL, then ASSERT(). + If AuthenticationStatus is NULL, then ASSERT(). @param[in] InputSection A pointer to a GUIDed section of an FFS formatted file. - @param[out] OutputBuffer A pointer to a buffer that contains the result of a decode operation. - @param[in] ScratchBuffer A caller allocated buffer that may be required by this function as a scratch buffer to perform the decode operation. - @param[out] AuthenticationStatus + @param[out] OutputBuffer A pointer to a buffer that contains the result of a decode operation. + @param[in] ScratchBuffer A caller allocated buffer that may be required by this function as a scratch buffer to perform the decode operation. + @param[out] AuthenticationStatus A pointer to the authentication status of the decoded output buffer. See the definition of authentication status in the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI section of the PI Specification. @@ -243,27 +237,27 @@ ExtractGuidedSectionDecode ( IN CONST VOID *InputSection, OUT VOID **OutputBuffer, IN VOID *ScratchBuffer, OPTIONAL - OUT UINT32 *AuthenticationStatus + OUT UINT32 *AuthenticationStatus ); /** - Retrieves handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and + Retrieves handlers of type EXTRACT_GUIDED_SECTION_GET_INFO_HANDLER and EXTRACT_GUIDED_SECTION_DECODE_HANDLER for a specific GUID section type. - - Retrieves the handlers associated with SectionGuid and returns them in + + Retrieves the handlers associated with SectionGuid and returns them in GetInfoHandler and DecodeHandler. - If the GUID value specified by SectionGuid has not been registered, then + If the GUID value specified by SectionGuid has not been registered, then return RETURN_NOT_FOUND. - + If SectionGuid is NULL, then ASSERT(). - @param[in] SectionGuid A pointer to the GUID associated with the handlersof the GUIDed + @param[in] SectionGuid A pointer to the GUID associated with the handlersof the GUIDed section type being retrieved. - @param[out] GetInfoHandler Pointer to a function that examines a GUIDed section and returns - the size of the decoded buffer and the size of an optional scratch - buffer required to actually decode the data in a GUIDed section. - This is an optional parameter that may be NULL. If it is NULL, then + @param[out] GetInfoHandler Pointer to a function that examines a GUIDed section and returns + the size of the decoded buffer and the size of an optional scratch + buffer required to actually decode the data in a GUIDed section. + This is an optional parameter that may be NULL. If it is NULL, then the previously registered handler is not returned. @param[out] DecodeHandler Pointer to a function that decodes a GUIDed section into a caller allocated output buffer. This is an optional parameter that may be NULL. diff --git a/MdePkg/Include/Library/FileHandleLib.h b/MdePkg/Include/Library/FileHandleLib.h index cbafa4aca82c..c473c668ba94 100644 --- a/MdePkg/Include/Library/FileHandleLib.h +++ b/MdePkg/Include/Library/FileHandleLib.h @@ -1,14 +1,8 @@ /** @file Provides interface to EFI_FILE_HANDLE functionality. - Copyright (c) 2009 - 2017, Intel Corporation. All rights reserved.<BR> - 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. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -249,8 +243,8 @@ FileHandleFlush ( @param[in] DirHandle Handle to open file. @retval EFI_SUCCESS DirHandle is a directory. - @retval EFI_INVALID_PARAMETER DirHandle is NULL. - The file information returns from FileHandleGetInfo is NULL. + @retval EFI_INVALID_PARAMETER DirHandle is NULL. + The file information returns from FileHandleGetInfo is NULL. @retval EFI_NOT_FOUND DirHandle is not a directory. **/ EFI_STATUS @@ -357,8 +351,8 @@ FileHandleSetSize ( /** Function to get a full filename given a EFI_FILE_HANDLE somewhere lower on the - directory 'stack'. If the file is a directory, then append the '\' char at the - end of name string. If it's not a directory, then the last '\' should not be + directory 'stack'. If the file is a directory, then append the '\' char at the + end of name string. If it's not a directory, then the last '\' should not be added. @param[in] Handle Handle to the Directory or File to create path to. @@ -439,11 +433,11 @@ FileHandleReturnLine( /** Function to write a line of text to a file. - - If the file is a Unicode file (with UNICODE file tag) then write the unicode + + If the file is a Unicode file (with UNICODE file tag) then write the unicode text. If the file is an ASCII file then write the ASCII text. - If the size of file is zero (without file tag at the beginning) then write + If the size of file is zero (without file tag at the beginning) then write ASCII text as default. @param[in] Handle FileHandle to write to. @@ -453,7 +447,7 @@ FileHandleReturnLine( @retval EFI_SUCCESS The data was written. Buffer is NULL. @retval EFI_INVALID_PARAMETER Handle is NULL. - @retval EFI_OUT_OF_RESOURCES Unable to allocate temporary space for ASCII + @retval EFI_OUT_OF_RESOURCES Unable to allocate temporary space for ASCII string due to out of resources. @sa FileHandleWrite diff --git a/MdePkg/Include/Library/HobLib.h b/MdePkg/Include/Library/HobLib.h index 292321cd3d72..b1adb5276f96 100644 --- a/MdePkg/Include/Library/HobLib.h +++ b/MdePkg/Include/Library/HobLib.h @@ -6,16 +6,10 @@ defined in the PI Specification. A HOB is a Hand-Off Block, defined in the Framework architecture, that allows the PEI phase to pass information to the DXE phase. HOBs are position - independent and can be relocated easily to different memory memory locations. + independent and can be relocated easily to different memory locations. -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -190,7 +184,7 @@ BuildModuleHob ( This function builds a HOB that describes a chunk of system memory. It can only be invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. - + If there is no additional space for HOB creation, then ASSERT(). @param ResourceType The type of resource described by this HOB. @@ -343,6 +337,38 @@ BuildFv2Hob ( ); /** + Builds a EFI_HOB_TYPE_FV3 HOB. + + This function builds a EFI_HOB_TYPE_FV3 HOB. + It can only be invoked during PEI phase; + for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase. + + If there is no additional space for HOB creation, then ASSERT(). + If the FvImage buffer is not at its required alignment, then ASSERT(). + + @param BaseAddress The base address of the Firmware Volume. + @param Length The size of the Firmware Volume in bytes. + @param AuthenticationStatus The authentication status. + @param ExtractedFv TRUE if the FV was extracted as a file within + another firmware volume. FALSE otherwise. + @param FvName The name of the Firmware Volume. + Valid only if IsExtractedFv is TRUE. + @param FileName The name of the file. + Valid only if IsExtractedFv is TRUE. + +**/ +VOID +EFIAPI +BuildFv3Hob ( + IN EFI_PHYSICAL_ADDRESS BaseAddress, + IN UINT64 Length, + IN UINT32 AuthenticationStatus, + IN BOOLEAN ExtractedFv, + IN CONST EFI_GUID *FvName, OPTIONAL + IN CONST EFI_GUID *FileName OPTIONAL + ); + +/** Builds a Capsule Volume HOB. This function builds a Capsule Volume HOB. diff --git a/MdePkg/Include/Library/HstiLib.h b/MdePkg/Include/Library/HstiLib.h index 2ae87f67d19e..83d9bc46e330 100644 --- a/MdePkg/Include/Library/HstiLib.h +++ b/MdePkg/Include/Library/HstiLib.h @@ -2,13 +2,7 @@ Provides services to create, get and update HSTI table in AIP protocol. Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - 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. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/IoLib.h b/MdePkg/Include/Library/IoLib.h index 7c27f1cf6531..d0ffe98ecb14 100644 --- a/MdePkg/Include/Library/IoLib.h +++ b/MdePkg/Include/Library/IoLib.h @@ -1,16 +1,10 @@ /** @file Provide services to access I/O Ports and MMIO registers. -Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> Copyright (c) 2017, AMD Incorporated. All rights reserved.<BR> -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. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -20,14 +14,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Macro that converts PCI Segment and I/O Port to an address that can be passed to the I/O Library functions. - - Computes an address that is compatible with the I/O Library functions. - The unused upper bits of Segment, and Port are stripped prior to the + + Computes an address that is compatible with the I/O Library functions. + The unused upper bits of Segment, and Port are stripped prior to the generation of the address. - + @param Segment PCI Segment number. Range 0..65535. @param Port I/O Port number. Range 0..65535. - + @return An address that the I/o Library functions need. **/ @@ -178,7 +172,7 @@ IoAnd8 ( ); /** - Reads an 8-bit I/O port, performs a bitwise AND followed by a bitwise + Reads an 8-bit I/O port, performs a bitwise AND followed by a bitwise OR, and writes the result back to the 8-bit I/O port. Reads the 8-bit I/O port specified by Port, performs a bitwise AND between @@ -238,7 +232,7 @@ IoBitFieldRead8 ( Writes Value to the bit field of the I/O register. The bit field is specified by the StartBit and the EndBit. All other bits in the destination I/O - register are preserved. The value written to the I/O port is returned. + register are preserved. The value written to the I/O port is returned. If 8-bit I/O port operations are not supported, then ASSERT(). If StartBit is greater than 7, then ASSERT(). @@ -405,7 +399,7 @@ IoRead16 ( If 16-bit I/O port operations are not supported, then ASSERT(). If Port is not aligned on a 16-bit boundary, then ASSERT(). - + @param Port The I/O port to write. @param Value The value to write to the I/O port. @@ -507,7 +501,7 @@ IoOr16 ( If 16-bit I/O port operations are not supported, then ASSERT(). If Port is not aligned on a 16-bit boundary, then ASSERT(). - + @param Port The I/O port to write. @param AndData The value to AND with the read value from the I/O port. @@ -522,7 +516,7 @@ IoAnd16 ( ); /** - Reads a 16-bit I/O port, performs a bitwise AND followed by a bitwise + Reads a 16-bit I/O port, performs a bitwise AND followed by a bitwise OR, and writes the result back to the 16-bit I/O port. Reads the 16-bit I/O port specified by Port, performs a bitwise AND between @@ -534,7 +528,7 @@ IoAnd16 ( If 16-bit I/O port operations are not supported, then ASSERT(). If Port is not aligned on a 16-bit boundary, then ASSERT(). - + @param Port The I/O port to write. @param AndData The value to AND with the read value from the I/O port. @param OrData The value to OR with the result of the AND operation. @@ -735,7 +729,7 @@ IoBitFieldAndThenOr16 ( If 32-bit I/O port operations are not supported, then ASSERT(). If Port is not aligned on a 32-bit boundary, then ASSERT(). - + @param Port The I/O port to read. @return The value read. @@ -756,7 +750,7 @@ IoRead32 ( If 32-bit I/O port operations are not supported, then ASSERT(). If Port is not aligned on a 32-bit boundary, then ASSERT(). - + @param Port The I/O port to write. @param Value The value to write to the I/O port. @@ -873,7 +867,7 @@ IoAnd32 ( ); /** - Reads a 32-bit I/O port, performs a bitwise AND followed by a bitwise + Reads a 32-bit I/O port, performs a bitwise AND followed by a bitwise OR, and writes the result back to the 32-bit I/O port. Reads the 32-bit I/O port specified by Port, performs a bitwise AND between @@ -1174,7 +1168,7 @@ IoAnd64 ( ); /** - Reads a 64-bit I/O port, performs a bitwise AND followed by a bitwise + Reads a 64-bit I/O port, performs a bitwise AND followed by a bitwise OR, and writes the result back to the 64-bit I/O port. Reads the 64-bit I/O port specified by Port, performs a bitwise AND between @@ -1409,7 +1403,7 @@ MmioRead8 ( @param Address The MMIO register to write. @param Value The value to write to the MMIO register. - + @return Value. **/ @@ -1424,7 +1418,7 @@ MmioWrite8 ( Reads an 8-bit MMIO register, performs a bitwise OR, and writes the result back to the 8-bit MMIO register. - Reads the 8-bit MMIO register specified by Address, performs a bitwise + Reads the 8-bit MMIO register specified by Address, performs a bitwise OR between the read result and the value specified by OrData, and writes the result to the 8-bit MMIO register specified by Address. The value written to the MMIO register is returned. This function must guarantee that @@ -1471,7 +1465,7 @@ MmioAnd8 ( ); /** - Reads an 8-bit MMIO register, performs a bitwise AND followed by a bitwise + Reads an 8-bit MMIO register, performs a bitwise AND followed by a bitwise OR, and writes the result back to the 8-bit MMIO register. Reads the 8-bit MMIO register specified by Address, performs a bitwise AND @@ -1563,7 +1557,7 @@ MmioBitFieldWrite8 ( Reads a bit field in an 8-bit MMIO register, performs a bitwise OR, and writes the result back to the bit field in the 8-bit MMIO register. - Reads the 8-bit MMIO register specified by Address, performs a bitwise + Reads the 8-bit MMIO register specified by Address, performs a bitwise OR between the read result and the value specified by OrData, and writes the result to the 8-bit MMIO register specified by Address. The value written to the MMIO register is returned. This function must guarantee that @@ -1704,7 +1698,7 @@ MmioRead16 ( @param Address The MMIO register to write. @param Value The value to write to the MMIO register. - + @return Value. **/ @@ -1719,7 +1713,7 @@ MmioWrite16 ( Reads a 16-bit MMIO register, performs a bitwise OR, and writes the result back to the 16-bit MMIO register. - Reads the 16-bit MMIO register specified by Address, performs a bitwise + Reads the 16-bit MMIO register specified by Address, performs a bitwise OR between the read result and the value specified by OrData, and writes the result to the 16-bit MMIO register specified by Address. The value written to the MMIO register is returned. This function must guarantee that @@ -1768,7 +1762,7 @@ MmioAnd16 ( ); /** - Reads a 16-bit MMIO register, performs a bitwise AND followed by a bitwise + Reads a 16-bit MMIO register, performs a bitwise AND followed by a bitwise OR, and writes the result back to the 16-bit MMIO register. Reads the 16-bit MMIO register specified by Address, performs a bitwise AND @@ -1862,7 +1856,7 @@ MmioBitFieldWrite16 ( Reads a bit field in a 16-bit MMIO register, performs a bitwise OR, and writes the result back to the bit field in the 16-bit MMIO register. - Reads the 16-bit MMIO register specified by Address, performs a bitwise + Reads the 16-bit MMIO register specified by Address, performs a bitwise OR between the read result and the value specified by OrData, and writes the result to the 16-bit MMIO register specified by Address. The value written to the MMIO register is returned. This function must guarantee that @@ -2006,7 +2000,7 @@ MmioRead32 ( @param Address The MMIO register to write. @param Value The value to write to the MMIO register. - + @return Value. **/ @@ -2021,7 +2015,7 @@ MmioWrite32 ( Reads a 32-bit MMIO register, performs a bitwise OR, and writes the result back to the 32-bit MMIO register. - Reads the 32-bit MMIO register specified by Address, performs a bitwise + Reads the 32-bit MMIO register specified by Address, performs a bitwise OR between the read result and the value specified by OrData, and writes the result to the 32-bit MMIO register specified by Address. The value written to the MMIO register is returned. This function must guarantee that @@ -2070,7 +2064,7 @@ MmioAnd32 ( ); /** - Reads a 32-bit MMIO register, performs a bitwise AND followed by a bitwise + Reads a 32-bit MMIO register, performs a bitwise AND followed by a bitwise OR, and writes the result back to the 32-bit MMIO register. Reads the 32-bit MMIO register specified by Address, performs a bitwise AND @@ -2164,7 +2158,7 @@ MmioBitFieldWrite32 ( Reads a bit field in a 32-bit MMIO register, performs a bitwise OR, and writes the result back to the bit field in the 32-bit MMIO register. - Reads the 32-bit MMIO register specified by Address, performs a bitwise + Reads the 32-bit MMIO register specified by Address, performs a bitwise OR between the read result and the value specified by OrData, and writes the result to the 32-bit MMIO register specified by Address. The value written to the MMIO register is returned. This function must guarantee that @@ -2321,7 +2315,7 @@ MmioWrite64 ( Reads a 64-bit MMIO register, performs a bitwise OR, and writes the result back to the 64-bit MMIO register. - Reads the 64-bit MMIO register specified by Address, performs a bitwise + Reads the 64-bit MMIO register specified by Address, performs a bitwise OR between the read result and the value specified by OrData, and writes the result to the 64-bit MMIO register specified by Address. The value written to the MMIO register is returned. This function must guarantee that @@ -2370,7 +2364,7 @@ MmioAnd64 ( ); /** - Reads a 64-bit MMIO register, performs a bitwise AND followed by a bitwise + Reads a 64-bit MMIO register, performs a bitwise AND followed by a bitwise OR, and writes the result back to the 64-bit MMIO register. Reads the 64-bit MMIO register specified by Address, performs a bitwise AND @@ -2464,7 +2458,7 @@ MmioBitFieldWrite64 ( Reads a bit field in a 64-bit MMIO register, performs a bitwise OR, and writes the result back to the bit field in the 64-bit MMIO register. - Reads the 64-bit MMIO register specified by Address, performs a bitwise + Reads the 64-bit MMIO register specified by Address, performs a bitwise OR between the read result and the value specified by OrData, and writes the result to the 64-bit MMIO register specified by Address. The value written to the MMIO register is returned. This function must guarantee that @@ -2578,11 +2572,11 @@ MmioBitFieldAndThenOr64 ( /** Copy data from MMIO region to system memory by using 8-bit access. - Copy data from MMIO region specified by starting address StartAddress - to system memory specified by Buffer by using 8-bit access. The total + Copy data from MMIO region specified by starting address StartAddress + to system memory specified by Buffer by using 8-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). @@ -2604,13 +2598,13 @@ MmioReadBuffer8 ( /** Copy data from MMIO region to system memory by using 16-bit access. - Copy data from MMIO region specified by starting address StartAddress - to system memory specified by Buffer by using 16-bit access. The total + Copy data from MMIO region specified by starting address StartAddress + to system memory specified by Buffer by using 16-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 16-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). If Length is not aligned on a 16-bit boundary, then ASSERT(). @@ -2634,13 +2628,13 @@ MmioReadBuffer16 ( /** Copy data from MMIO region to system memory by using 32-bit access. - Copy data from MMIO region specified by starting address StartAddress - to system memory specified by Buffer by using 32-bit access. The total + Copy data from MMIO region specified by starting address StartAddress + to system memory specified by Buffer by using 32-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 32-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). If Length is not aligned on a 32-bit boundary, then ASSERT(). @@ -2664,13 +2658,13 @@ MmioReadBuffer32 ( /** Copy data from MMIO region to system memory by using 64-bit access. - Copy data from MMIO region specified by starting address StartAddress - to system memory specified by Buffer by using 64-bit access. The total + Copy data from MMIO region specified by starting address StartAddress + to system memory specified by Buffer by using 64-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 64-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). If Length is not aligned on a 64-bit boundary, then ASSERT(). @@ -2694,11 +2688,11 @@ MmioReadBuffer64 ( /** Copy data from system memory to MMIO region by using 8-bit access. - Copy data from system memory specified by Buffer to MMIO region specified - by starting address StartAddress by using 8-bit access. The total number + Copy data from system memory specified by Buffer to MMIO region specified + by starting address StartAddress by using 8-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). @@ -2720,13 +2714,13 @@ MmioWriteBuffer8 ( /** Copy data from system memory to MMIO region by using 16-bit access. - Copy data from system memory specified by Buffer to MMIO region specified - by starting address StartAddress by using 16-bit access. The total number + Copy data from system memory specified by Buffer to MMIO region specified + by starting address StartAddress by using 16-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 16-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). If Length is not aligned on a 16-bit boundary, then ASSERT(). @@ -2751,13 +2745,13 @@ MmioWriteBuffer16 ( /** Copy data from system memory to MMIO region by using 32-bit access. - Copy data from system memory specified by Buffer to MMIO region specified - by starting address StartAddress by using 32-bit access. The total number + Copy data from system memory specified by Buffer to MMIO region specified + by starting address StartAddress by using 32-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 32-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). If Length is not aligned on a 32-bit boundary, then ASSERT(). @@ -2782,13 +2776,13 @@ MmioWriteBuffer32 ( /** Copy data from system memory to MMIO region by using 64-bit access. - Copy data from system memory specified by Buffer to MMIO region specified - by starting address StartAddress by using 64-bit access. The total number + Copy data from system memory specified by Buffer to MMIO region specified + by starting address StartAddress by using 64-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 64-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). If Length is not aligned on a 64-bit boundary, then ASSERT(). diff --git a/MdePkg/Include/Library/MemoryAllocationLib.h b/MdePkg/Include/Library/MemoryAllocationLib.h index 204a8b51235f..14efb568955a 100644 --- a/MdePkg/Include/Library/MemoryAllocationLib.h +++ b/MdePkg/Include/Library/MemoryAllocationLib.h @@ -1,19 +1,13 @@ /** @file Provides services to allocate and free memory buffers of various memory types and alignments. - - The Memory Allocation Library abstracts various common memory allocation operations. This library - allows code to be written in a phase-independent manner because the allocation of memory in PEI, DXE, - and SMM (for example) is done via a different mechanism. Using a common library interface makes it - much easier to port algorithms from phase to phase. - -Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR> -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. + + The Memory Allocation Library abstracts various common memory allocation operations. This library + allows code to be written in a phase-independent manner because the allocation of memory in PEI, DXE, + and SMM (for example) is done via a different mechanism. Using a common library interface makes it + much easier to port algorithms from phase to phase. + +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -85,11 +79,11 @@ AllocateReservedPages ( must have been allocated on a previous call to the page allocation services of the Memory Allocation Library. If it is not possible to free allocated pages, then this function will perform no actions. - + If Buffer was not allocated with a page allocation function in the Memory Allocation Library, then ASSERT(). If Pages is zero, then ASSERT(). - + @param Buffer Pointer to the buffer of pages to free. @param Pages The number of 4 KB pages to free. @@ -108,7 +102,7 @@ FreePages ( alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is returned. If there is not enough memory at the specified alignment remaining to satisfy the request, then NULL is returned. - + If Alignment is not a power of two and Alignment is not zero, then ASSERT(). If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT(). @@ -133,7 +127,7 @@ AllocateAlignedPages ( alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is returned. If there is not enough memory at the specified alignment remaining to satisfy the request, then NULL is returned. - + If Alignment is not a power of two and Alignment is not zero, then ASSERT(). If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT(). @@ -158,7 +152,7 @@ AllocateAlignedRuntimePages ( alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is returned. If there is not enough memory at the specified alignment remaining to satisfy the request, then NULL is returned. - + If Alignment is not a power of two and Alignment is not zero, then ASSERT(). If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT(). @@ -182,13 +176,13 @@ AllocateAlignedReservedPages ( Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer must have been allocated on a previous call to the aligned page allocation services of the Memory - Allocation Library. If it is not possible to free allocated pages, then this function will + Allocation Library. If it is not possible to free allocated pages, then this function will perform no actions. - + If Buffer was not allocated with an aligned page allocation function in the Memory Allocation Library, then ASSERT(). If Pages is zero, then ASSERT(). - + @param Buffer Pointer to the buffer of pages to free. @param Pages The number of 4 KB pages to free. @@ -318,9 +312,9 @@ AllocateReservedZeroPool ( AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the request, then NULL is returned. - + If Buffer is NULL, then ASSERT(). - If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). @param AllocationSize The number of bytes to allocate and zero. @param Buffer The buffer to copy to the allocated buffer. @@ -342,9 +336,9 @@ AllocateCopyPool ( AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the request, then NULL is returned. - + If Buffer is NULL, then ASSERT(). - If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). @param AllocationSize The number of bytes to allocate and zero. @param Buffer The buffer to copy to the allocated buffer. @@ -366,9 +360,9 @@ AllocateRuntimeCopyPool ( AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the request, then NULL is returned. - + If Buffer is NULL, then ASSERT(). - If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). @param AllocationSize The number of bytes to allocate and zero. @param Buffer The buffer to copy to the allocated buffer. @@ -387,18 +381,18 @@ AllocateReservedCopyPool ( Reallocates a buffer of type EfiBootServicesData. Allocates and zeros the number bytes specified by NewSize from memory of type - EfiBootServicesData. If OldBuffer is not NULL, then the smaller of OldSize and - NewSize bytes are copied from OldBuffer to the newly allocated buffer, and - OldBuffer is freed. A pointer to the newly allocated buffer is returned. - If NewSize is 0, then a valid buffer of 0 size is returned. If there is not + EfiBootServicesData. If OldBuffer is not NULL, then the smaller of OldSize and + NewSize bytes are copied from OldBuffer to the newly allocated buffer, and + OldBuffer is freed. A pointer to the newly allocated buffer is returned. + If NewSize is 0, then a valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the request, then NULL is returned. - + If the allocation of the new buffer is successful and the smaller of NewSize and OldSize is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT(). @param OldSize The size, in bytes, of OldBuffer. @param NewSize The size, in bytes, of the buffer to reallocate. - @param OldBuffer The buffer to copy to the allocated buffer. This is an optional + @param OldBuffer The buffer to copy to the allocated buffer. This is an optional parameter that may be NULL. @return A pointer to the allocated buffer or NULL if allocation fails. @@ -416,10 +410,10 @@ ReallocatePool ( Reallocates a buffer of type EfiRuntimeServicesData. Allocates and zeros the number bytes specified by NewSize from memory of type - EfiRuntimeServicesData. If OldBuffer is not NULL, then the smaller of OldSize and - NewSize bytes are copied from OldBuffer to the newly allocated buffer, and - OldBuffer is freed. A pointer to the newly allocated buffer is returned. - If NewSize is 0, then a valid buffer of 0 size is returned. If there is not + EfiRuntimeServicesData. If OldBuffer is not NULL, then the smaller of OldSize and + NewSize bytes are copied from OldBuffer to the newly allocated buffer, and + OldBuffer is freed. A pointer to the newly allocated buffer is returned. + If NewSize is 0, then a valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the request, then NULL is returned. If the allocation of the new buffer is successful and the smaller of NewSize and OldSize @@ -427,7 +421,7 @@ ReallocatePool ( @param OldSize The size, in bytes, of OldBuffer. @param NewSize The size, in bytes, of the buffer to reallocate. - @param OldBuffer The buffer to copy to the allocated buffer. This is an optional + @param OldBuffer The buffer to copy to the allocated buffer. This is an optional parameter that may be NULL. @return A pointer to the allocated buffer or NULL if allocation fails. @@ -445,10 +439,10 @@ ReallocateRuntimePool ( Reallocates a buffer of type EfiReservedMemoryType. Allocates and zeros the number bytes specified by NewSize from memory of type - EfiReservedMemoryType. If OldBuffer is not NULL, then the smaller of OldSize and - NewSize bytes are copied from OldBuffer to the newly allocated buffer, and - OldBuffer is freed. A pointer to the newly allocated buffer is returned. - If NewSize is 0, then a valid buffer of 0 size is returned. If there is not + EfiReservedMemoryType. If OldBuffer is not NULL, then the smaller of OldSize and + NewSize bytes are copied from OldBuffer to the newly allocated buffer, and + OldBuffer is freed. A pointer to the newly allocated buffer is returned. + If NewSize is 0, then a valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the request, then NULL is returned. If the allocation of the new buffer is successful and the smaller of NewSize and OldSize @@ -456,7 +450,7 @@ ReallocateRuntimePool ( @param OldSize The size, in bytes, of OldBuffer. @param NewSize The size, in bytes, of the buffer to reallocate. - @param OldBuffer The buffer to copy to the allocated buffer. This is an optional + @param OldBuffer The buffer to copy to the allocated buffer. This is an optional parameter that may be NULL. @return A pointer to the allocated buffer or NULL if allocation fails. @@ -477,7 +471,7 @@ ReallocateReservedPool ( Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the pool allocation services of the Memory Allocation Library. If it is not possible to free pool resources, then this function will perform no actions. - + If Buffer was not allocated with a pool allocation function in the Memory Allocation Library, then ASSERT(). diff --git a/MdePkg/Include/Library/MmServicesTableLib.h b/MdePkg/Include/Library/MmServicesTableLib.h new file mode 100644 index 000000000000..e9e4abebea5c --- /dev/null +++ b/MdePkg/Include/Library/MmServicesTableLib.h @@ -0,0 +1,19 @@ +/** @file + Provides a service to retrieve a pointer to the Standalone MM Services Table. + Only available to MM_STANDALONE, SMM/DXE Combined and SMM module types. + +Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> +Copyright (c) 2016 - 2018, ARM Limited. All rights reserved.<BR> + +SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __MM_SERVICES_TABLE_LIB_H__ +#define __MM_SERVICES_TABLE_LIB_H__ + +#include <PiMm.h> + +extern EFI_MM_SYSTEM_TABLE *gMmst; + +#endif diff --git a/MdePkg/Include/Library/OrderedCollectionLib.h b/MdePkg/Include/Library/OrderedCollectionLib.h index e4191b82026f..6e1db6f859cc 100644 --- a/MdePkg/Include/Library/OrderedCollectionLib.h +++ b/MdePkg/Include/Library/OrderedCollectionLib.h @@ -6,13 +6,7 @@ Copyright (C) 2014, Red Hat, Inc. - This program and the accompanying materials are licensed and made available - under the terms and conditions of the BSD License that 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. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef __ORDERED_COLLECTION_LIB__ diff --git a/MdePkg/Include/Library/PalLib.h b/MdePkg/Include/Library/PalLib.h deleted file mode 100644 index e5c3473c61d4..000000000000 --- a/MdePkg/Include/Library/PalLib.h +++ /dev/null @@ -1,63 +0,0 @@ -/** @file - Provides library services to make PAL Calls. - - The PAL Library provides a service to make a PAL CALL. This service is identical - in functionality to AsmPalCall() in the functions of the Base Library specific to Intel Itanium architecture. - The only difference is that the PAL Entry Point is not passed in. Implementations - of this library class must manage PAL Entry Point on their own. For example, a PEI - implementation can use a PPI to lookup the PAL Entry Point, and a DXE implementation - can contain a constructor to look up the PAL Entry Point from a HOB. This library class - is only available on Intel Itanium-based platforms. - -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. - -**/ - -#ifndef __PAL_CALL_LIB_H__ -#define __PAL_CALL_LIB_H__ - -#include <IndustryStandard/Pal.h> - -/** - 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. 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 4 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. - This function is only available on Intel Itanium-based platforms. - - @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. - -**/ -PAL_CALL_RETURN -EFIAPI -PalCall ( - IN UINT64 Index, - IN UINT64 Arg2, - IN UINT64 Arg3, - IN UINT64 Arg4 - ); - -#endif - diff --git a/MdePkg/Include/Library/PcdLib.h b/MdePkg/Include/Library/PcdLib.h index fdb2df87aa0f..7a4a1bdaa3d8 100644 --- a/MdePkg/Include/Library/PcdLib.h +++ b/MdePkg/Include/Library/PcdLib.h @@ -8,20 +8,14 @@ LibPatchPcdSetPtr() interface. For FeatureFlag/Fixed PCD, the macro interface is translated to a variable or macro that is auto-generated by build tool in module's autogen.h/autogen.c. - The PcdGetXX(), PcdSetXX(), PcdToken(), and PcdGetNextTokenSpace() operations are - only available prior to ExitBootServices(). If access to PCD values are required + The PcdGetXX(), PcdSetXX(), PcdToken(), and PcdGetNextTokenSpace() operations are + only available prior to ExitBootServices(). If access to PCD values are required at runtime, then their values must be collected prior to ExitBootServices(). There are no restrictions on the use of FeaturePcd(), FixedPcdGetXX(), PatchPcdGetXX(), and PatchPcdSetXX(). -Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -127,7 +121,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @param TokenName The name of the PCD token to retrieve a current value for. - @return The Boolean value for the token. + @return The Boolean value for the token. **/ #define FixedPcdGetBool(TokenName) _PCD_VALUE_##TokenName @@ -142,7 +136,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @param TokenName The name of the PCD token to retrieve a current value for. - @return A pointer to the buffer. + @return A pointer to the buffer. **/ #define FixedPcdGetPtr(TokenName) ((VOID *)_PCD_VALUE_##TokenName) @@ -246,7 +240,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @param TokenName The name of the binary patchable PCD token to set the current value for. @param Value The 8-bit value to set. - + @return Return the Value that was set. **/ @@ -320,17 +314,17 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Sets a pointer to a binary patchable PCD token buffer based on a token name. - Sets the buffer for the token specified by TokenName. Buffer is returned. + Sets the buffer for the token specified by TokenName. Buffer is returned. If SizeOfBuffer is greater than the maximum size supported by TokenName, then set SizeOfBuffer - to the maximum size supported by TokenName and return NULL to indicate that the set operation - was not actually performed. If SizeOfBuffer is set to MAX_ADDRESS, then SizeOfBuffer must be + to the maximum size supported by TokenName and return NULL to indicate that the set operation + was not actually performed. If SizeOfBuffer is set to MAX_ADDRESS, then SizeOfBuffer must be set to the maximum size supported by TokenName and NULL must be returned. If TokenName is not a valid token in the token space, then the module will not build. If TokenName is not a patchable in module PCD, then the module will not build. - + If SizeOfBuffer is NULL, then ASSERT(). If SizeOfBuffer > 0 and Buffer is NULL, then ASSERT(). - + @param TokenName The name of the binary patchable PCD token to set the current value for. @param SizeOfBuffer A pointer to the size, in bytes, of Buffer. @param Buffer Pointer to the value to set. @@ -348,10 +342,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. ) /** Retrieves an 8-bit PCD token value based on a token name. - + Returns the 8-bit value for the token specified by TokenName. If TokenName is not a valid token in the token space, then the module will not build. - + @param TokenName The name of the PCD token to retrieve a current value for. @return 8-bit value for the token specified by TokenName. @@ -460,10 +454,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Retrieves the size of the PCD token based on a token name. - + Returns the size of the token specified by TokenName. If TokenName is not a valid token in the token space, then the module will not build. - + @param[in] TokenName The name of the PCD token to retrieve a current value size for. @return Return the size @@ -474,11 +468,11 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Retrieve the size of a given PCD token. - - Returns the size of the token specified by TokenNumber and Guid. - If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates + Returns the size of the token specified by TokenNumber and Guid. + If Guid is NULL, then ASSERT(). + + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param[in] TokenNumber The PCD token number to retrieve a current value size for. @@ -496,7 +490,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @param TokenName The name of the PCD token to retrieve a current value for. @param Value The 8-bit value to set. - + @return Return the Value that was set. **/ @@ -551,17 +545,17 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Sets a pointer to a PCD token buffer based on a token name. - Sets the buffer for the token specified by TokenName. Buffer is returned. - If SizeOfBuffer is greater than the maximum size supported by TokenName, - then set SizeOfBuffer to the maximum size supported by TokenName and return NULL - to indicate that the set operation was not actually performed. If SizeOfBuffer - is set to MAX_ADDRESS, then SizeOfBuffer must be set to the maximum size supported + Sets the buffer for the token specified by TokenName. Buffer is returned. + If SizeOfBuffer is greater than the maximum size supported by TokenName, + then set SizeOfBuffer to the maximum size supported by TokenName and return NULL + to indicate that the set operation was not actually performed. If SizeOfBuffer + is set to MAX_ADDRESS, then SizeOfBuffer must be set to the maximum size supported by TokenName and NULL must be returned. If TokenName is not a valid token in the token space, then the module will not build. - + If SizeOfBuffer is NULL, then ASSERT(). If SizeOfBuffer > 0 and Buffer is NULL, then ASSERT(). - + @param TokenName The name of the PCD token to set the current value for. @param SizeOfBuffer A pointer to the size, in bytes, of Buffer. @param Buffer A pointer to the buffer to set. @@ -571,11 +565,11 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ #define PcdSetPtr(TokenName, SizeOfBuffer, Buffer) \ _PCD_SET_MODE_PTR_##TokenName ((SizeOfBuffer), (Buffer)) - + /** Sets a Boolean PCD token value based on a token name. - Sets the Boolean value for the token specified by TokenName. Value is returned. + Sets the Boolean value for the token specified by TokenName. Value is returned. If TokenName is not a valid token in the token space, then the module will not build. @param TokenName The name of the PCD token to set the current value for. @@ -689,9 +683,9 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Returns the token number for the token specified by Guid and TokenName. If TokenName is not a valid token in the token space, then the module will not build. - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. - @param TokenName The name of the PCD token to retrieve a current value for. + @param TokenName The name of the PCD token to retrieve a current value for. @return Return the token number. @@ -702,14 +696,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Retrieves an 8-bit PCD token value based on a GUID and a token name. Returns the 8-bit value for the token specified by Guid and TokenName. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. - + If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. - @param TokenName The name of the PCD token to retrieve a current value for. + @param TokenName The name of the PCD token to retrieve a current value for. @return An 8-bit PCD token value. @@ -720,14 +714,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Retrieves a 16-bit PCD token value based on a GUID and a token name. Returns the 16-bit value for the token specified by Guid and TokenName. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. - @param TokenName The name of the PCD token to retrieve a current value for. + @param TokenName The name of the PCD token to retrieve a current value for. @return A 16-bit PCD token value. @@ -739,14 +733,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Retrieves a 32-bit PCD token value based on a GUID and a token name. Returns the 32-bit value for the token specified by Guid and TokenName. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. - @param TokenName The name of the PCD token to retrieve a current value for. + @param TokenName The name of the PCD token to retrieve a current value for. @return A 32-bit PCD token value. @@ -758,14 +752,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Retrieves a 64-bit PCD token value based on a GUID and a token name. Returns the 64-bit value for the token specified by Guid and TokenName. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. - @param TokenName The name of the PCD token to retrieve a current value for. + @param TokenName The name of the PCD token to retrieve a current value for. @return A 64-bit PCD token value. @@ -777,14 +771,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Retrieves a pointer to a PCD token buffer based on a GUID and a token name. Returns a pointer to the buffer for the token specified by Guid and TokenName. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. - @param TokenName The name of the PCD token to retrieve a current value for. + @param TokenName The name of the PCD token to retrieve a current value for. @return A pointer to a PCD token buffer. @@ -796,14 +790,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Retrieves a Boolean PCD token value based on a GUID and a token name. Returns the Boolean value for the token specified by Guid and TokenName. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. - @param TokenName The name of the PCD token to retrieve a current value for. + @param TokenName The name of the PCD token to retrieve a current value for. @return A Boolean PCD token value. @@ -817,15 +811,15 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Sets an 8-bit PCD token value based on a GUID and a token name. Sets the 8-bit value for the token specified by Guid and TokenName. Value is returned. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param TokenName The name of the PCD token to set the current value for. - @param Value The 8-bit value to set. + @param Value The 8-bit value to set. @return Return the Value that was set. @@ -837,15 +831,15 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Sets a 16-bit PCD token value based on a GUID and a token name. Sets the 16-bit value for the token specified by Guid and TokenName. Value is returned. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param TokenName The name of the PCD token to set the current value for. - @param Value The 16-bit value to set. + @param Value The 16-bit value to set. @return Return the Value that was set. @@ -857,15 +851,15 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Sets a 32-bit PCD token value based on a GUID and a token name. Sets the 32-bit value for the token specified by Guid and TokenName. Value is returned. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param TokenName The name of the PCD token to set the current value for. - @param Value The 32-bit value to set. + @param Value The 32-bit value to set. @return Return the Value that was set. @@ -877,15 +871,15 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Sets a 64-bit PCD token value based on a GUID and a token name. Sets the 64-bit value for the token specified by Guid and TokenName. Value is returned. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param TokenName The name of the PCD token to set the current value for. - @param Value The 64-bit value to set. + @param Value The 64-bit value to set. @return Return the Value that was set. @@ -896,25 +890,25 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Sets a pointer to a PCD token buffer based on a GUID and a token name. - Sets the buffer for the token specified by Guid and TokenName. Buffer is returned. - If SizeOfBuffer is greater than the maximum size supported by Guid and TokenName, - then set SizeOfBuffer to the maximum size supported by Guid and TokenName and return - NULL to indicate that the set operation was not actually performed. If SizeOfBuffer + Sets the buffer for the token specified by Guid and TokenName. Buffer is returned. + If SizeOfBuffer is greater than the maximum size supported by Guid and TokenName, + then set SizeOfBuffer to the maximum size supported by Guid and TokenName and return + NULL to indicate that the set operation was not actually performed. If SizeOfBuffer is set to MAX_ADDRESS, then SizeOfBuffer must be set to the maximum size supported by Guid and TokenName and NULL must be returned. - If TokenName is not a valid token in the token space specified by Guid, + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. - + If Guid is NULL, then ASSERT(). If SizeOfBuffer is NULL, then ASSERT(). If SizeOfBuffer > 0 and Buffer is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param TokenName The name of the PCD token to set the current value for. - @param SizeOfBuffer A pointer to the size, in bytes, of Buffer. + @param SizeOfBuffer A pointer to the size, in bytes, of Buffer. @param Buffer Pointer to the buffer to set. - + @return Return the pointer to the Buffer that was set. **/ @@ -925,20 +919,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Sets a Boolean PCD token value based on a GUID and a token name. - Sets the Boolean value for the token specified by Guid and TokenName. Value is returned. - If TokenName is not a valid token in the token space specified by Guid, + Sets the Boolean value for the token specified by Guid and TokenName. Value is returned. + If TokenName is not a valid token in the token space specified by Guid, then the module will not build. If Guid is NULL, then ASSERT(). - @param Guid Pointer to a 128-bit unique value that designates + @param Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. - @param TokenName The name of the PCD token to set the current value for. + @param TokenName The name of the PCD token to set the current value for. @param Value The Boolean value to set. @return Return the Value that was set. -**/ +**/ #define PcdSetExBool(Guid, TokenName, Value) \ LibPcdSetExBool((Guid), PcdTokenEx(Guid,TokenName), (Value)) #endif @@ -1088,12 +1082,12 @@ LibPcdSetSku ( /** This function provides a means by which to retrieve a value for a given PCD token. - - Returns the 8-bit value for the token specified by TokenNumber. + + Returns the 8-bit value for the token specified by TokenNumber. @param[in] TokenNumber The PCD token number to retrieve a current value for. - @return Returns the 8-bit value for the token specified by TokenNumber. + @return Returns the 8-bit value for the token specified by TokenNumber. **/ UINT8 @@ -1105,12 +1099,12 @@ LibPcdGet8 ( /** This function provides a means by which to retrieve a value for a given PCD token. - - Returns the 16-bit value for the token specified by TokenNumber. + + Returns the 16-bit value for the token specified by TokenNumber. @param[in] TokenNumber The PCD token number to retrieve a current value for. - @return Returns the 16-bit value for the token specified by TokenNumber. + @return Returns the 16-bit value for the token specified by TokenNumber. **/ UINT16 @@ -1122,8 +1116,8 @@ LibPcdGet16 ( /** This function provides a means by which to retrieve a value for a given PCD token. - - Returns the 32-bit value for the token specified by TokenNumber. + + Returns the 32-bit value for the token specified by TokenNumber. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1139,7 +1133,7 @@ LibPcdGet32 ( /** This function provides a means by which to retrieve a value for a given PCD token. - + Returns the 64-bit value for the token specified by TokenNumber. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1156,7 +1150,7 @@ LibPcdGet64 ( /** This function provides a means by which to retrieve a value for a given PCD token. - + Returns the pointer to the buffer of the token specified by TokenNumber. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1173,15 +1167,15 @@ LibPcdGetPtr ( /** This function provides a means by which to retrieve a value for a given PCD token. - - Returns the Boolean value of the token specified by TokenNumber. + + Returns the Boolean value of the token specified by TokenNumber. @param[in] TokenNumber The PCD token number to retrieve a current value for. - @return Returns the Boolean value of the token specified by TokenNumber. + @return Returns the Boolean value of the token specified by TokenNumber. **/ -BOOLEAN +BOOLEAN EFIAPI LibPcdGetBool ( IN UINTN TokenNumber @@ -1193,7 +1187,7 @@ LibPcdGetBool ( @param[in] TokenNumber The PCD token number to retrieve a current value for. - @return Returns the size of the token specified by TokenNumber. + @return Returns the size of the token specified by TokenNumber. **/ UINTN @@ -1205,12 +1199,12 @@ LibPcdGetSize ( /** This function provides a means by which to retrieve a value for a given PCD token. - + Returns the 8-bit value for the token specified by TokenNumber and Guid. - - If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates + If Guid is NULL, then ASSERT(). + + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1229,10 +1223,10 @@ LibPcdGetEx8 ( This function provides a means by which to retrieve a value for a given PCD token. Returns the 16-bit value for the token specified by TokenNumber and Guid. - - If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates + If Guid is NULL, then ASSERT(). + + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1249,9 +1243,9 @@ LibPcdGetEx16 ( /** Returns the 32-bit value for the token specified by TokenNumber and Guid. - If Guid is NULL, then ASSERT(). + If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1268,12 +1262,12 @@ LibPcdGetEx32 ( /** This function provides a means by which to retrieve a value for a given PCD token. - + Returns the 64-bit value for the token specified by TokenNumber and Guid. - - If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates + If Guid is NULL, then ASSERT(). + + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1290,12 +1284,12 @@ LibPcdGetEx64 ( /** This function provides a means by which to retrieve a value for a given PCD token. - + Returns the pointer to the buffer of token specified by TokenNumber and Guid. - - If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates + If Guid is NULL, then ASSERT(). + + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1312,12 +1306,12 @@ LibPcdGetExPtr ( /** This function provides a means by which to retrieve a value for a given PCD token. - - Returns the Boolean value of the token specified by TokenNumber and Guid. - - If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates + Returns the Boolean value of the token specified by TokenNumber and Guid. + + If Guid is NULL, then ASSERT(). + + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1334,12 +1328,12 @@ LibPcdGetExBool ( /** This function provides a means by which to retrieve the size of a given PCD token. - - Returns the size of the token specified by TokenNumber and Guid. - - If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates + Returns the size of the token specified by TokenNumber and Guid. + + If Guid is NULL, then ASSERT(). + + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to retrieve a value from. @param[in] TokenNumber The PCD token number to retrieve a current value for. @@ -1357,8 +1351,8 @@ LibPcdGetExSize ( #ifndef DISABLE_NEW_DEPRECATED_INTERFACES /** This function provides a means by which to set a value for a given PCD token. - - Sets the 8-bit value for the token specified by TokenNumber + + Sets the 8-bit value for the token specified by TokenNumber to the value specified by Value. Value is returned. @param[in] TokenNumber The PCD token number to set a current value for. @@ -1377,8 +1371,8 @@ LibPcdSet8 ( /** This function provides a means by which to set a value for a given PCD token. - - Sets the 16-bit value for the token specified by TokenNumber + + Sets the 16-bit value for the token specified by TokenNumber to the value specified by Value. Value is returned. @param[in] TokenNumber The PCD token number to set a current value for. @@ -1397,8 +1391,8 @@ LibPcdSet16 ( /** This function provides a means by which to set a value for a given PCD token. - - Sets the 32-bit value for the token specified by TokenNumber + + Sets the 32-bit value for the token specified by TokenNumber to the value specified by Value. Value is returned. @param[in] TokenNumber The PCD token number to set a current value for. @@ -1417,8 +1411,8 @@ LibPcdSet32 ( /** This function provides a means by which to set a value for a given PCD token. - - Sets the 64-bit value for the token specified by TokenNumber + + Sets the 64-bit value for the token specified by TokenNumber to the value specified by Value. Value is returned. @param[in] TokenNumber The PCD token number to set a current value for. @@ -1437,19 +1431,19 @@ LibPcdSet64 ( /** This function provides a means by which to set a value for a given PCD token. - - Sets a buffer for the token specified by TokenNumber to the value - specified by Buffer and SizeOfBuffer. Buffer is returned. - If SizeOfBuffer is greater than the maximum size support by TokenNumber, - then set SizeOfBuffer to the maximum size supported by TokenNumber and + + Sets a buffer for the token specified by TokenNumber to the value + specified by Buffer and SizeOfBuffer. Buffer is returned. + If SizeOfBuffer is greater than the maximum size support by TokenNumber, + then set SizeOfBuffer to the maximum size supported by TokenNumber and return NULL to indicate that the set operation was not actually performed. - If SizeOfBuffer is set to MAX_ADDRESS, then SizeOfBuffer must be set to the + If SizeOfBuffer is set to MAX_ADDRESS, then SizeOfBuffer must be set to the maximum size supported by TokenName and NULL must be returned. - + If SizeOfBuffer is NULL, then ASSERT(). If SizeOfBuffer > 0 and Buffer is NULL, then ASSERT(). - + @param[in] TokenNumber The PCD token number to set a current value for. @param[in, out] SizeOfBuffer The size, in bytes, of Buffer. @param[in] Buffer A pointer to the buffer to set. @@ -1468,8 +1462,8 @@ LibPcdSetPtr ( /** This function provides a means by which to set a value for a given PCD token. - - Sets the Boolean value for the token specified by TokenNumber + + Sets the Boolean value for the token specified by TokenNumber to the value specified by Value. Value is returned. @param[in] TokenNumber The PCD token number to set a current value for. @@ -1488,13 +1482,13 @@ LibPcdSetBool ( /** This function provides a means by which to set a value for a given PCD token. - - Sets the 8-bit value for the token specified by TokenNumber and + + Sets the 8-bit value for the token specified by TokenNumber and Guid to the value specified by Value. Value is returned. If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to set a value from. @param[in] TokenNumber The PCD token number to set a current value for. @param[in] Value The 8-bit value to set. @@ -1513,13 +1507,13 @@ LibPcdSetEx8 ( /** This function provides a means by which to set a value for a given PCD token. - - Sets the 16-bit value for the token specified by TokenNumber and + + Sets the 16-bit value for the token specified by TokenNumber and Guid to the value specified by Value. Value is returned. If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to set a value from. @param[in] TokenNumber The PCD token number to set a current value for. @param[in] Value The 16-bit value to set. @@ -1538,13 +1532,13 @@ LibPcdSetEx16 ( /** This function provides a means by which to set a value for a given PCD token. - - Sets the 32-bit value for the token specified by TokenNumber and + + Sets the 32-bit value for the token specified by TokenNumber and Guid to the value specified by Value. Value is returned. If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to set a value from. @param[in] TokenNumber The PCD token number to set a current value for. @param[in] Value The 32-bit value to set. @@ -1563,13 +1557,13 @@ LibPcdSetEx32 ( /** This function provides a means by which to set a value for a given PCD token. - - Sets the 64-bit value for the token specified by TokenNumber and + + Sets the 64-bit value for the token specified by TokenNumber and Guid to the value specified by Value. Value is returned. If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to set a value from. @param[in] TokenNumber The PCD token number to set a current value for. @param[in] Value The 64-bit value to set. @@ -1588,18 +1582,18 @@ LibPcdSetEx64 ( /** This function provides a means by which to set a value for a given PCD token. - - Sets a buffer for the token specified by TokenNumber to the value specified by - Buffer and SizeOfBuffer. Buffer is returned. If SizeOfBuffer is greater than - the maximum size support by TokenNumber, then set SizeOfBuffer to the maximum size - supported by TokenNumber and return NULL to indicate that the set operation + + Sets a buffer for the token specified by TokenNumber to the value specified by + Buffer and SizeOfBuffer. Buffer is returned. If SizeOfBuffer is greater than + the maximum size support by TokenNumber, then set SizeOfBuffer to the maximum size + supported by TokenNumber and return NULL to indicate that the set operation was not actually performed. - + If Guid is NULL, then ASSERT(). If SizeOfBuffer is NULL, then ASSERT(). If SizeOfBuffer > 0 and Buffer is NULL, then ASSERT(). - - @param[in] Guid Pointer to a 128-bit unique value that + + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to set a value from. @param[in] TokenNumber The PCD token number to set a current value for. @param[in, out] SizeOfBuffer The size, in bytes, of Buffer. @@ -1620,13 +1614,13 @@ LibPcdSetExPtr ( /** This function provides a means by which to set a value for a given PCD token. - - Sets the Boolean value for the token specified by TokenNumber and + + Sets the Boolean value for the token specified by TokenNumber and Guid to the value specified by Value. Value is returned. If Guid is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to set a value from. @param[in] TokenNumber The PCD token number to set a current value for. @param[in] Value The Boolean value to set. @@ -1927,7 +1921,7 @@ LibPcdSetExBoolS ( Secondly, it provides a mechanism for the module that did the registration to intercept the set operation and override the value been set if necessary. After the invocation of the callback function, TokenData will be used by PCD service PEIM or driver to modify th - internal data in PCD database. + internal data in PCD database. @param[in] CallBackGuid The PCD token GUID being set. @param[in] CallBackToken The PCD token number being set. @@ -1947,17 +1941,17 @@ VOID /** Set up a notification function that is called when a specified token is set. - - When the token specified by TokenNumber and Guid is set, - then notification function specified by NotificationFunction is called. + + When the token specified by TokenNumber and Guid is set, + then notification function specified by NotificationFunction is called. If Guid is NULL, then the default token space is used. If NotificationFunction is NULL, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates which - namespace to set a value from. If NULL, then the default + @param[in] Guid Pointer to a 128-bit unique value that designates which + namespace to set a value from. If NULL, then the default token space is used. @param[in] TokenNumber The PCD token number to monitor. - @param[in] NotificationFunction The function to call when the token + @param[in] NotificationFunction The function to call when the token specified by Guid and TokenNumber is set. **/ @@ -1972,12 +1966,12 @@ LibPcdCallbackOnSet ( /** Disable a notification function that was established with LibPcdCallbackonSet(). - + Disable a notification function that was previously established with LibPcdCallbackOnSet(). If NotificationFunction is NULL, then ASSERT(). - If LibPcdCallbackOnSet() was not previously called with Guid, TokenNumber, + If LibPcdCallbackOnSet() was not previously called with Guid, TokenNumber, and NotificationFunction, then ASSERT(). - + @param[in] Guid Specify the GUID token space. @param[in] TokenNumber Specify the token number. @param[in] NotificationFunction The callback function to be unregistered. @@ -1994,24 +1988,24 @@ LibPcdCancelCallback ( /** Retrieves the next token in a token space. - - Retrieves the next PCD token number from the token space specified by Guid. - If Guid is NULL, then the default token space is used. If TokenNumber is 0, - then the first token number is returned. Otherwise, the token number that - follows TokenNumber in the token space is returned. If TokenNumber is the last - token number in the token space, then 0 is returned. - + + Retrieves the next PCD token number from the token space specified by Guid. + If Guid is NULL, then the default token space is used. If TokenNumber is 0, + then the first token number is returned. Otherwise, the token number that + follows TokenNumber in the token space is returned. If TokenNumber is the last + token number in the token space, then 0 is returned. + If TokenNumber is not 0 and is not in the token space specified by Guid, then ASSERT(). - @param[in] Guid Pointer to a 128-bit unique value that designates which namespace + @param[in] Guid Pointer to a 128-bit unique value that designates which namespace to set a value from. If NULL, then the default token space is used. - @param[in] TokenNumber The previous PCD token number. If 0, then retrieves the first PCD + @param[in] TokenNumber The previous PCD token number. If 0, then retrieves the first PCD token number. @return The next valid token number. **/ -UINTN +UINTN EFIAPI LibPcdGetNextToken ( IN CONST GUID *Guid, OPTIONAL @@ -2022,12 +2016,12 @@ LibPcdGetNextToken ( /** Used to retrieve the list of available PCD token space GUIDs. - + Returns the PCD token space GUID that follows TokenSpaceGuid in the list of token spaces in the platform. If TokenSpaceGuid is NULL, then a pointer to the first PCD token spaces returned. If TokenSpaceGuid is the last PCD token space GUID in the list, then NULL is returned. - + @param TokenSpaceGuid Pointer to the a PCD token space GUID @return The next valid token namespace. @@ -2042,24 +2036,24 @@ LibPcdGetNextTokenSpace ( /** Sets a value of a patchable PCD entry that is type pointer. - - Sets the PCD entry specified by PatchVariable to the value specified by Buffer - and SizeOfBuffer. Buffer is returned. If SizeOfBuffer is greater than - MaximumDatumSize, then set SizeOfBuffer to MaximumDatumSize and return - NULL to indicate that the set operation was not actually performed. - If SizeOfBuffer is set to MAX_ADDRESS, then SizeOfBuffer must be set to + + Sets the PCD entry specified by PatchVariable to the value specified by Buffer + and SizeOfBuffer. Buffer is returned. If SizeOfBuffer is greater than + MaximumDatumSize, then set SizeOfBuffer to MaximumDatumSize and return + NULL to indicate that the set operation was not actually performed. + If SizeOfBuffer is set to MAX_ADDRESS, then SizeOfBuffer must be set to MaximumDatumSize and NULL must be returned. - + If PatchVariable is NULL, then ASSERT(). If SizeOfBuffer is NULL, then ASSERT(). If SizeOfBuffer > 0 and Buffer is NULL, then ASSERT(). - @param[out] PatchVariable A pointer to the global variable in a module that is + @param[out] PatchVariable A pointer to the global variable in a module that is the target of the set operation. @param[in] MaximumDatumSize The maximum size allowed for the PCD entry specified by PatchVariable. @param[in, out] SizeOfBuffer A pointer to the size, in bytes, of Buffer. @param[in] Buffer A pointer to the buffer to used to set the target variable. - + @return Return the pointer to the Buffer that was set. **/ @@ -2091,7 +2085,7 @@ LibPatchPcdSetPtr ( @param[in] MaximumDatumSize The maximum size allowed for the PCD entry specified by PatchVariable. @param[in, out] SizeOfBuffer A pointer to the size, in bytes, of Buffer. @param[in] Buffer A pointer to the buffer to used to set the target variable. - + @return The status of the set operation. **/ @@ -2106,26 +2100,26 @@ LibPatchPcdSetPtrS ( /** Sets a value and size of a patchable PCD entry that is type pointer. - - Sets the PCD entry specified by PatchVariable to the value specified by Buffer - and SizeOfBuffer. Buffer is returned. If SizeOfBuffer is greater than - MaximumDatumSize, then set SizeOfBuffer to MaximumDatumSize and return - NULL to indicate that the set operation was not actually performed. - If SizeOfBuffer is set to MAX_ADDRESS, then SizeOfBuffer must be set to + + Sets the PCD entry specified by PatchVariable to the value specified by Buffer + and SizeOfBuffer. Buffer is returned. If SizeOfBuffer is greater than + MaximumDatumSize, then set SizeOfBuffer to MaximumDatumSize and return + NULL to indicate that the set operation was not actually performed. + If SizeOfBuffer is set to MAX_ADDRESS, then SizeOfBuffer must be set to MaximumDatumSize and NULL must be returned. - + If PatchVariable is NULL, then ASSERT(). If SizeOfPatchVariable is NULL, then ASSERT(). If SizeOfBuffer is NULL, then ASSERT(). If SizeOfBuffer > 0 and Buffer is NULL, then ASSERT(). - @param[out] PatchVariable A pointer to the global variable in a module that is + @param[out] PatchVariable A pointer to the global variable in a module that is the target of the set operation. @param[out] SizeOfPatchVariable A pointer to the size, in bytes, of PatchVariable. @param[in] MaximumDatumSize The maximum size allowed for the PCD entry specified by PatchVariable. @param[in, out] SizeOfBuffer A pointer to the size, in bytes, of Buffer. @param[in] Buffer A pointer to the buffer to used to set the target variable. - + @return Return the pointer to the Buffer that was set. **/ @@ -2160,7 +2154,7 @@ LibPatchPcdSetPtrAndSize ( @param[in] MaximumDatumSize The maximum size allowed for the PCD entry specified by PatchVariable. @param[in, out] SizeOfBuffer A pointer to the size, in bytes, of Buffer. @param[in] Buffer A pointer to the buffer to used to set the target variable. - + @return The status of the set operation. **/ diff --git a/MdePkg/Include/Library/PciCf8Lib.h b/MdePkg/Include/Library/PciCf8Lib.h index d77f406ebd16..41324e5b60b9 100644 --- a/MdePkg/Include/Library/PciCf8Lib.h +++ b/MdePkg/Include/Library/PciCf8Lib.h @@ -1,18 +1,12 @@ /** @file Provides services to access PCI Configuration Space using the I/O ports 0xCF8 and 0xCFC. - - This library is identical to the PCI Library, except the access method for performing PCI - configuration cycles must be through I/O ports 0xCF8 and 0xCFC. This library only allows - access to PCI Segment #0. -Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> -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 + This library is identical to the PCI Library, except the access method for performing PCI + configuration cycles must be through I/O ports 0xCF8 and 0xCFC. This library only allows + access to PCI Segment #0. -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -40,20 +34,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. (((Offset) & 0xfff) | (((Function) & 0x07) << 12) | (((Device) & 0x1f) << 15) | (((Bus) & 0xff) << 20)) /** - Registers a PCI device so PCI configuration registers may be accessed after + Registers a PCI device so PCI configuration registers may be accessed after SetVirtualAddressMap(). - - Registers the PCI device specified by Address so all the PCI configuration registers + + Registers the PCI device specified by Address so all the PCI configuration registers associated with that PCI device may be accessed after SetVirtualAddressMap() is called. - + If Address > 0x0FFFFFFF, then ASSERT(). If the register specified by Address >= 0x100, then ASSERT(). @param Address Address that encodes the PCI Bus, Device, Function and Register. - + @retval RETURN_SUCCESS The PCI device was registered for runtime access. - @retval RETURN_UNSUPPORTED An attempt was made to call this function + @retval RETURN_UNSUPPORTED An attempt was made to call this function after ExitBootServices(). @retval RETURN_UNSUPPORTED The resources required to access the PCI device at runtime could not be mapped. @@ -1033,7 +1027,7 @@ PciCf8BitFieldAndThenOr32 ( Size into the buffer specified by Buffer. This function only allows the PCI configuration registers from a single PCI function to be read. Size is returned. When possible 32-bit PCI configuration read cycles are used to read - from StartAdress to StartAddress + Size. Due to alignment restrictions, 8-bit + from StartAddress to StartAddress + Size. Due to alignment restrictions, 8-bit and 16-bit PCI configuration read cycles may be used at the beginning and the end of the range. @@ -1066,7 +1060,7 @@ PciCf8ReadBuffer ( Size from the buffer specified by Buffer. This function only allows the PCI configuration registers from a single PCI function to be written. Size is returned. When possible 32-bit PCI configuration write cycles are used to - write from StartAdress to StartAddress + Size. Due to alignment restrictions, + write from StartAddress to StartAddress + Size. Due to alignment restrictions, 8-bit and 16-bit PCI configuration write cycles may be used at the beginning and the end of the range. diff --git a/MdePkg/Include/Library/PciExpressLib.h b/MdePkg/Include/Library/PciExpressLib.h index 80e9d1279cfd..59bb8100e2d7 100644 --- a/MdePkg/Include/Library/PciExpressLib.h +++ b/MdePkg/Include/Library/PciExpressLib.h @@ -1,24 +1,20 @@ /** @file Provides services to access PCI Configuration Space using the MMIO PCI Express window. - - This library is identical to the PCI Library, except the access method for performing PCI + + This library is identical to the PCI Library, except the access method for performing PCI configuration cycles must be through the 256 MB PCI Express MMIO window whose base address is defined by PcdPciExpressBaseAddress. -Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef __PCI_EXPRESS_LIB_H__ #define __PCI_EXPRESS_LIB_H__ +#include <IndustryStandard/PciExpress21.h> + /** Macro that converts PCI Bus, PCI Device, PCI Function and PCI Register to an address that can be passed to the PCI Library functions. @@ -35,24 +31,23 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @return The encode PCI address. **/ -#define PCI_EXPRESS_LIB_ADDRESS(Bus,Device,Function,Offset) \ - (((Offset) & 0xfff) | (((Function) & 0x07) << 12) | (((Device) & 0x1f) << 15) | (((Bus) & 0xff) << 20)) +#define PCI_EXPRESS_LIB_ADDRESS(Bus,Device,Function,Offset) PCI_ECAM_ADDRESS ((Bus), (Device), (Function), (Offset)) /** - Registers a PCI device so PCI configuration registers may be accessed after + Registers a PCI device so PCI configuration registers may be accessed after SetVirtualAddressMap(). - - Registers the PCI device specified by Address so all the PCI configuration - registers associated with that PCI device may be accessed after SetVirtualAddressMap() + + Registers the PCI device specified by Address so all the PCI configuration + registers associated with that PCI device may be accessed after SetVirtualAddressMap() is called. - + If Address > 0x0FFFFFFF, then ASSERT(). @param Address Address that encodes the PCI Bus, Device, Function and Register. - + @retval RETURN_SUCCESS The PCI device was registered for runtime access. - @retval RETURN_UNSUPPORTED An attempt was made to call this function + @retval RETURN_UNSUPPORTED An attempt was made to call this function after ExitBootServices(). @retval RETURN_UNSUPPORTED The resources required to access the PCI device at runtime could not be mapped. @@ -1002,7 +997,7 @@ PciExpressBitFieldAndThenOr32 ( Size into the buffer specified by Buffer. This function only allows the PCI configuration registers from a single PCI function to be read. Size is returned. When possible 32-bit PCI configuration read cycles are used to read - from StartAdress to StartAddress + Size. Due to alignment restrictions, 8-bit + from StartAddress to StartAddress + Size. Due to alignment restrictions, 8-bit and 16-bit PCI configuration read cycles may be used at the beginning and the end of the range. @@ -1034,7 +1029,7 @@ PciExpressReadBuffer ( Size from the buffer specified by Buffer. This function only allows the PCI configuration registers from a single PCI function to be written. Size is returned. When possible 32-bit PCI configuration write cycles are used to - write from StartAdress to StartAddress + Size. Due to alignment restrictions, + write from StartAddress to StartAddress + Size. Due to alignment restrictions, 8-bit and 16-bit PCI configuration write cycles may be used at the beginning and the end of the range. diff --git a/MdePkg/Include/Library/PciLib.h b/MdePkg/Include/Library/PciLib.h index 1b1de2904d81..1b3c13eb2f1d 100644 --- a/MdePkg/Include/Library/PciLib.h +++ b/MdePkg/Include/Library/PciLib.h @@ -1,23 +1,17 @@ /** @file Provides services to access PCI Configuration Space. - - These functions perform PCI configuration cycles using the default PCI configuration - access method. This may use I/O ports 0xCF8 and 0xCFC to perform PCI configuration accesses, - or it may use MMIO registers relative to the PcdPciExpressBaseAddress, or it may use some - alternate access method. Modules will typically use the PCI Library for its PCI configuration - accesses. However, if a module requires a mix of PCI access methods, the PCI CF8 Library or - PCI Express Library may be used in conjunction with the PCI Library. The functionality of - these three libraries is identical. The PCI CF8 Library and PCI Express Library simply use - explicit access methods. -Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> -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 + These functions perform PCI configuration cycles using the default PCI configuration + access method. This may use I/O ports 0xCF8 and 0xCFC to perform PCI configuration accesses, + or it may use MMIO registers relative to the PcdPciExpressBaseAddress, or it may use some + alternate access method. Modules will typically use the PCI Library for its PCI configuration + accesses. However, if a module requires a mix of PCI access methods, the PCI CF8 Library or + PCI Express Library may be used in conjunction with the PCI Library. The functionality of + these three libraries is identical. The PCI CF8 Library and PCI Express Library simply use + explicit access methods. -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -41,19 +35,19 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. (((Register) & 0xfff) | (((Function) & 0x07) << 12) | (((Device) & 0x1f) << 15) | (((Bus) & 0xff) << 20)) /** - Registers a PCI device so PCI configuration registers may be accessed after + Registers a PCI device so PCI configuration registers may be accessed after SetVirtualAddressMap(). - - Registers the PCI device specified by Address so all the PCI configuration registers + + Registers the PCI device specified by Address so all the PCI configuration registers associated with that PCI device may be accessed after SetVirtualAddressMap() is called. - + If Address > 0x0FFFFFFF, then ASSERT(). @param Address Address that encodes the PCI Bus, Device, Function and Register. - + @retval RETURN_SUCCESS The PCI device was registered for runtime access. - @retval RETURN_UNSUPPORTED An attempt was made to call this function + @retval RETURN_UNSUPPORTED An attempt was made to call this function after ExitBootServices(). @retval RETURN_UNSUPPORTED The resources required to access the PCI device at runtime could not be mapped. @@ -1003,7 +997,7 @@ PciBitFieldAndThenOr32 ( Size into the buffer specified by Buffer. This function only allows the PCI configuration registers from a single PCI function to be read. Size is returned. When possible 32-bit PCI configuration read cycles are used to read - from StartAdress to StartAddress + Size. Due to alignment restrictions, 8-bit + from StartAddress to StartAddress + Size. Due to alignment restrictions, 8-bit and 16-bit PCI configuration read cycles may be used at the beginning and the end of the range. @@ -1035,7 +1029,7 @@ PciReadBuffer ( Size from the buffer specified by Buffer. This function only allows the PCI configuration registers from a single PCI function to be written. Size is returned. When possible 32-bit PCI configuration write cycles are used to - write from StartAdress to StartAddress + Size. Due to alignment restrictions, + write from StartAddress to StartAddress + Size. Due to alignment restrictions, 8-bit and 16-bit PCI configuration write cycles may be used at the beginning and the end of the range. diff --git a/MdePkg/Include/Library/PciSegmentInfoLib.h b/MdePkg/Include/Library/PciSegmentInfoLib.h new file mode 100644 index 000000000000..228d75793b19 --- /dev/null +++ b/MdePkg/Include/Library/PciSegmentInfoLib.h @@ -0,0 +1,35 @@ +/** @file + Provides services to return segment information on a platform with multiple PCI segments. + + This library is consumed by PciSegmentLib to support multiple segment PCI configuration access. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __PCI_SEGMENT_INFO_LIB__ +#define __PCI_SEGMENT_INFO_LIB__ + +typedef struct { + UINT16 SegmentNumber; ///< Segment number. + UINT64 BaseAddress; ///< ECAM Base address. + UINT8 StartBusNumber; ///< Start BUS number, for verifying the PCI Segment address. + UINT8 EndBusNumber; ///< End BUS number, for verifying the PCI Segment address. +} PCI_SEGMENT_INFO; + +/** + Return an array of PCI_SEGMENT_INFO holding the segment information. + + Note: The returned array/buffer is owned by callee. + + @param Count Return the count of segments. + + @retval A callee owned array holding the segment information. +**/ +PCI_SEGMENT_INFO * +GetPciSegmentInfo ( + UINTN *Count + ); + +#endif diff --git a/MdePkg/Include/Library/PciSegmentLib.h b/MdePkg/Include/Library/PciSegmentLib.h index aad95ca31455..1054a7c46564 100644 --- a/MdePkg/Include/Library/PciSegmentLib.h +++ b/MdePkg/Include/Library/PciSegmentLib.h @@ -1,11 +1,11 @@ /** @file Provides services to access PCI Configuration Space on a platform with multiple PCI segments. - + The PCI Segment Library function provide services to read, write, and modify the PCI configuration - registers on PCI root bridges on any supported PCI segment. These library services take a single - address parameter that encodes the PCI Segment, PCI Bus, PCI Device, PCI Function, and PCI Register. + registers on PCI root bridges on any supported PCI segment. These library services take a single + address parameter that encodes the PCI Segment, PCI Bus, PCI Device, PCI Function, and PCI Register. The layout of this address parameter is as follows: - + PCI Register: Bits 0..11 PCI Function Bits 12..14 PCI Device Bits 15..19 @@ -13,24 +13,18 @@ Reserved Bits 28..31. Must be 0. PCI Segment Bits 32..47 Reserved Bits 48..63. Must be 0. - + | Reserved (MBZ) | Segment | Reserved (MBZ) | Bus | Device | Function | Register | 63 48 47 32 31 28 27 20 19 15 14 12 11 0 - These functions perform PCI configuration cycles using the default PCI configuration access - method. This may use I/O ports 0xCF8 and 0xCFC to perform PCI configuration accesses, or it - may use MMIO registers relative to the PcdPciExpressBaseAddress, or it may use some alternate - access method. Modules will typically use the PCI Segment Library for its PCI configuration - accesses when PCI Segments other than Segment #0 must be accessed. - -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -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 + These functions perform PCI configuration cycles using the default PCI configuration access + method. This may use I/O ports 0xCF8 and 0xCFC to perform PCI configuration accesses, or it + may use MMIO registers relative to the PcdPciExpressBaseAddress, or it may use some alternate + access method. Modules will typically use the PCI Segment Library for its PCI configuration + accesses when PCI Segments other than Segment #0 must be accessed. -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -71,16 +65,16 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. ) /** - Register a PCI device so PCI configuration registers may be accessed after + Register a PCI device so PCI configuration registers may be accessed after SetVirtualAddressMap(). - + If any reserved bits in Address are set, then ASSERT(). @param Address Address that encodes the PCI Bus, Device, Function and Register. - + @retval RETURN_SUCCESS The PCI device was registered for runtime access. - @retval RETURN_UNSUPPORTED An attempt was made to call this function + @retval RETURN_UNSUPPORTED An attempt was made to call this function after ExitBootServices(). @retval RETURN_UNSUPPORTED The resources required to access the PCI device at runtime could not be mapped. @@ -99,9 +93,9 @@ PciSegmentRegisterForRuntimeAccess ( Reads and returns the 8-bit PCI configuration register specified by Address. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). - + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. @return The 8-bit PCI configuration register specified by Address. @@ -118,7 +112,7 @@ PciSegmentRead8 ( Writes the 8-bit PCI configuration register specified by Address with the value specified by Value. Value is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. @@ -142,7 +136,7 @@ PciSegmentWrite8 ( and writes the result to the 8-bit PCI configuration register specified by Address. The value written to the PCI configuration register is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. @@ -184,18 +178,18 @@ PciSegmentAnd8 ( /** Performs a bitwise AND of an 8-bit PCI configuration register with an 8-bit value, followed a bitwise OR with another 8-bit value. - + Reads the 8-bit PCI configuration register specified by Address, performs a bitwise AND between the read result and the value specified by AndData, performs a bitwise OR between the result of the AND operation and the value specified by OrData, and writes the result to the 8-bit PCI configuration register specified by Address. The value written to the PCI configuration register is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. - @param AndData The value to AND with the PCI configuration register. + @param AndData The value to AND with the PCI configuration register. @param OrData The value to OR with the PCI configuration register. @return The value written to the PCI configuration register. @@ -345,8 +339,7 @@ PciSegmentBitFieldAnd8 ( /** Reads a bit field in an 8-bit port, performs a bitwise AND followed by a - bitwise OR, and writes the result back to the bit field in the - 8-bit port. + bitwise OR, and writes the result back to the bit field in the 8-bit port. Reads the 8-bit PCI configuration register specified by Address, performs a bitwise AND followed by a bitwise OR between the read result and @@ -389,10 +382,10 @@ PciSegmentBitFieldAndThenOr8 ( Reads and returns the 16-bit PCI configuration register specified by Address. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 16-bit boundary, then ASSERT(). - + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. @return The 16-bit PCI configuration register specified by Address. @@ -409,7 +402,7 @@ PciSegmentRead16 ( Writes the 16-bit PCI configuration register specified by Address with the value specified by Value. Value is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 16-bit boundary, then ASSERT(). @@ -431,11 +424,10 @@ PciSegmentWrite16 ( a 16-bit value. Reads the 16-bit PCI configuration register specified by Address, performs a - bitwise OR between the read result and the value specified by - OrData, and writes the result to the 16-bit PCI configuration register - specified by Address. The value written to the PCI configuration register is - returned. This function must guarantee that all PCI read and write operations - are serialized. + bitwise OR between the read result and the value specified by OrData, and + writes the result to the 16-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. This function + must guarantee that all PCI read and write operations are serialized. If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 16-bit boundary, then ASSERT(). @@ -462,10 +454,10 @@ PciSegmentOr16 ( and writes the result to the 16-bit PCI configuration register specified by Address. The value written to the PCI configuration register is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 16-bit boundary, then ASSERT(). - + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. @param AndData The value to AND with the PCI configuration register. @@ -482,19 +474,19 @@ PciSegmentAnd16 ( /** Performs a bitwise AND of a 16-bit PCI configuration register with a 16-bit value, followed a bitwise OR with another 16-bit value. - + Reads the 16-bit PCI configuration register specified by Address, performs a bitwise AND between the read result and the value specified by AndData, performs a bitwise OR between the result of the AND operation and the value specified by OrData, and writes the result to the 16-bit PCI configuration register specified by Address. The value written to the PCI configuration register is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 16-bit boundary, then ASSERT(). @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. - @param AndData The value to AND with the PCI configuration register. + @param AndData The value to AND with the PCI configuration register. @param OrData The value to OR with the PCI configuration register. @return The value written to the PCI configuration register. @@ -573,9 +565,15 @@ PciSegmentBitFieldWrite16 ( ); /** - Reads the 16-bit PCI configuration register specified by Address, - performs a bitwise OR between the read result and the value specified by OrData, - and writes the result to the 16-bit PCI configuration register specified by Address. + Reads a bit field in a 16-bit PCI configuration, performs a bitwise OR, writes + the result back to the bit field in the 16-bit port. + + Reads the 16-bit PCI configuration register specified by Address, performs a + bitwise OR between the read result and the value specified by + OrData, and writes the result to the 16-bit PCI configuration register + specified by Address. The value written to the PCI configuration register is + returned. This function must guarantee that all PCI read and write operations + are serialized. Extra left bits in OrData are stripped. If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 16-bit boundary, then ASSERT(). @@ -604,31 +602,31 @@ PciSegmentBitFieldOr16 ( ); /** - Reads a bit field in a 16-bit PCI configuration, performs a bitwise OR, - and writes the result back to the bit field in the 16-bit port. + Reads a bit field in a 16-bit PCI configuration register, performs a bitwise + AND, writes the result back to the bit field in the 16-bit register. + + Reads the 16-bit PCI configuration register specified by Address, performs a + bitwise AND between the read result and the value specified by AndData, and + writes the result to the 16-bit PCI configuration register specified by + Address. The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are + serialized. Extra left bits in AndData are stripped. - Reads the 16-bit PCI configuration register specified by Address, - performs a bitwise OR between the read result and the value specified by OrData, - and writes the result to the 16-bit PCI configuration register specified by Address. - The value written to the PCI configuration register is returned. - This function must guarantee that all PCI read and write operations are serialized. - Extra left bits in OrData are stripped. - If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 16-bit boundary, then ASSERT(). - If StartBit is greater than 7, then ASSERT(). - If EndBit is greater than 7, then ASSERT(). + If StartBit is greater than 15, then ASSERT(). + If EndBit is greater than 15, then ASSERT(). If EndBit is less than StartBit, then ASSERT(). If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. @param StartBit The ordinal of the least significant bit in the bit field. - The ordinal of the least significant bit in a byte is bit 0. + Range 0..15. @param EndBit The ordinal of the most significant bit in the bit field. - The ordinal of the most significant bit in a byte is bit 7. - @param AndData The value to AND with the read value from the PCI configuration register. + Range 0..15. + @param AndData The value to AND with the PCI configuration register. - @return The value written to the PCI configuration register. + @return The value written back to the PCI configuration register. **/ UINT16 @@ -686,7 +684,7 @@ PciSegmentBitFieldAndThenOr16 ( Reads and returns the 32-bit PCI configuration register specified by Address. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 32-bit boundary, then ASSERT(). @@ -706,7 +704,7 @@ PciSegmentRead32 ( Writes the 32-bit PCI configuration register specified by Address with the value specified by Value. Value is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 32-bit boundary, then ASSERT(). @@ -731,7 +729,7 @@ PciSegmentWrite32 ( and writes the result to the 32-bit PCI configuration register specified by Address. The value written to the PCI configuration register is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 32-bit boundary, then ASSERT(). @@ -756,7 +754,7 @@ PciSegmentOr32 ( and writes the result to the 32-bit PCI configuration register specified by Address. The value written to the PCI configuration register is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 32-bit boundary, then ASSERT(). @@ -776,14 +774,14 @@ PciSegmentAnd32 ( /** Performs a bitwise AND of a 32-bit PCI configuration register with a 32-bit value, followed a bitwise OR with another 32-bit value. - + Reads the 32-bit PCI configuration register specified by Address, performs a bitwise AND between the read result and the value specified by AndData, performs a bitwise OR between the result of the AND operation and the value specified by OrData, and writes the result to the 32-bit PCI configuration register specified by Address. The value written to the PCI configuration register is returned. This function must guarantee that all PCI read and write operations are serialized. - + If any reserved bits in Address are set, then ASSERT(). If Address is not aligned on a 32-bit boundary, then ASSERT(). @@ -906,7 +904,7 @@ PciSegmentBitFieldOr32 ( Reads a bit field in a 32-bit PCI configuration register, performs a bitwise AND, and writes the result back to the bit field in the 32-bit register. - + Reads the 32-bit PCI configuration register specified by Address, performs a bitwise AND between the read result and the value specified by AndData, and writes the result to the 32-bit PCI configuration register specified by Address. The value written to @@ -919,7 +917,7 @@ PciSegmentBitFieldOr32 ( If EndBit is less than StartBit, then ASSERT(). If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). - @param Address PCI configuration register to write. + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. @param StartBit The ordinal of the least significant bit in the bit field. Range 0..31. @param EndBit The ordinal of the most significant bit in the bit field. @@ -986,7 +984,7 @@ PciSegmentBitFieldAndThenOr32 ( Size into the buffer specified by Buffer. This function only allows the PCI configuration registers from a single PCI function to be read. Size is returned. When possible 32-bit PCI configuration read cycles are used to read - from StartAdress to StartAddress + Size. Due to alignment restrictions, 8-bit + from StartAddress to StartAddress + Size. Due to alignment restrictions, 8-bit and 16-bit PCI configuration read cycles may be used at the beginning and the end of the range. @@ -1018,7 +1016,7 @@ PciSegmentReadBuffer ( Size from the buffer specified by Buffer. This function only allows the PCI configuration registers from a single PCI function to be written. Size is returned. When possible 32-bit PCI configuration write cycles are used to - write from StartAdress to StartAddress + Size. Due to alignment restrictions, + write from StartAddress to StartAddress + Size. Due to alignment restrictions, 8-bit and 16-bit PCI configuration write cycles may be used at the beginning and the end of the range. diff --git a/MdePkg/Include/Library/PeCoffExtraActionLib.h b/MdePkg/Include/Library/PeCoffExtraActionLib.h index 1b73fc184ed1..97599d9a4783 100644 --- a/MdePkg/Include/Library/PeCoffExtraActionLib.h +++ b/MdePkg/Include/Library/PeCoffExtraActionLib.h @@ -1,16 +1,10 @@ /** @file Provides services to perform additional actions when a PE/COFF image is loaded - or unloaded. This is useful for environment where symbols need to be loaded + or unloaded. This is useful for environment where symbols need to be loaded and unloaded to support source level debugging. - Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> - 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. + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -37,9 +31,9 @@ PeCoffLoaderRelocateImageExtraAction ( /** Performs additional actions just before a PE/COFF image is unloaded. Any resources that were allocated by PeCoffLoaderRelocateImageExtraAction() must be freed. - + If ImageContext is NULL, then ASSERT(). - + @param ImageContext Pointer to the image context structure that describes the PE/COFF image that is being unloaded. diff --git a/MdePkg/Include/Library/PeCoffGetEntryPointLib.h b/MdePkg/Include/Library/PeCoffGetEntryPointLib.h index 053d139c3366..99f69a989b25 100644 --- a/MdePkg/Include/Library/PeCoffGetEntryPointLib.h +++ b/MdePkg/Include/Library/PeCoffGetEntryPointLib.h @@ -1,14 +1,8 @@ /** @file Provides a service to retrieve the PE/COFF entry point from a PE/COFF image. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that 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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -59,7 +53,7 @@ PeCoffLoaderGetMachineType ( /** Returns a pointer to the PDB file name for a PE/COFF image that has been - loaded into system memory with the PE/COFF Loader Library functions. + loaded into system memory with the PE/COFF Loader Library functions. Returns the PDB file name for the PE/COFF image specified by Pe32Data. If the PE/COFF image specified by Pe32Data is not a valid, then NULL is @@ -101,4 +95,22 @@ PeCoffGetSizeOfHeaders ( IN VOID *Pe32Data ); +/** + Returns PE/COFF image base specified by the address in this PE/COFF image. + + On DEBUG build, searches the PE/COFF image base forward the address in this + PE/COFF image and returns it. + + @param Address Address located in one PE/COFF image. + + @retval 0 RELEASE build or cannot find the PE/COFF image base. + @retval others PE/COFF image base found. + +**/ +UINTN +EFIAPI +PeCoffSearchImageBase ( + IN UINTN Address + ); + #endif diff --git a/MdePkg/Include/Library/PeCoffLib.h b/MdePkg/Include/Library/PeCoffLib.h index 78b8b10ddefd..54fe513ed5d0 100644 --- a/MdePkg/Include/Library/PeCoffLib.h +++ b/MdePkg/Include/Library/PeCoffLib.h @@ -2,17 +2,11 @@ Provides services to load and relocate a PE/COFF image. The PE/COFF Loader Library abstracts the implementation of a PE/COFF loader for - IA-32, x86, IPF, and EBC processor types. The library functions are memory-based + IA-32, x86, IPF, and EBC processor types. The library functions are memory-based and can be ported easily to any environment. - -Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that 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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -24,7 +18,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. // Return status codes from the PE/COFF Loader services // #define IMAGE_ERROR_SUCCESS 0 -#define IMAGE_ERROR_IMAGE_READ 1 +#define IMAGE_ERROR_IMAGE_READ 1 #define IMAGE_ERROR_INVALID_PE_HEADER_SIGNATURE 2 #define IMAGE_ERROR_INVALID_MACHINE_TYPE 3 #define IMAGE_ERROR_INVALID_SUBSYSTEM 4 @@ -39,30 +33,30 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Reads contents of a PE/COFF image. - A function of this type reads contents of the PE/COFF image specified by FileHandle. The read - operation copies ReadSize bytes from the PE/COFF image starting at byte offset FileOffset into - the buffer specified by Buffer. The size of the buffer actually read is returned in ReadSize. + A function of this type reads contents of the PE/COFF image specified by FileHandle. The read + operation copies ReadSize bytes from the PE/COFF image starting at byte offset FileOffset into + the buffer specified by Buffer. The size of the buffer actually read is returned in ReadSize. If FileOffset specifies an offset past the end of the PE/COFF image, a ReadSize of 0 is returned. - A function of this type must be registered in the ImageRead field of a PE_COFF_LOADER_IMAGE_CONTEXT - structure for the PE/COFF Loader Library service to function correctly. This function abstracts access - to a PE/COFF image so it can be implemented in an environment specific manner. For example, SEC and PEI - environments may access memory directly to read the contents of a PE/COFF image, and DXE or UEFI - environments may require protocol services to read the contents of PE/COFF image + A function of this type must be registered in the ImageRead field of a PE_COFF_LOADER_IMAGE_CONTEXT + structure for the PE/COFF Loader Library service to function correctly. This function abstracts access + to a PE/COFF image so it can be implemented in an environment specific manner. For example, SEC and PEI + environments may access memory directly to read the contents of a PE/COFF image, and DXE or UEFI + environments may require protocol services to read the contents of PE/COFF image stored on FLASH, disk, or network devices. - + If FileHandle is not a valid handle, then ASSERT(). If ReadSize is NULL, then ASSERT(). If Buffer is NULL, then ASSERT(). @param FileHandle Pointer to the file handle to read the PE/COFF image. @param FileOffset Offset into the PE/COFF image to begin the read operation. - @param ReadSize On input, the size in bytes of the requested read operation. + @param ReadSize On input, the size in bytes of the requested read operation. On output, the number of bytes actually read. @param Buffer Output buffer that contains the data read from the PE/COFF image. - - @retval RETURN_SUCCESS The specified portion of the PE/COFF image was + + @retval RETURN_SUCCESS The specified portion of the PE/COFF image was read and the size return in ReadSize. - @retval RETURN_DEVICE_ERROR The specified portion of the PE/COFF image + @retval RETURN_DEVICE_ERROR The specified portion of the PE/COFF image could not be read due to a device error. **/ @@ -110,8 +104,8 @@ typedef struct { VOID *Handle; /// /// Caller allocated buffer of size FixupDataSize that can be optionally allocated - /// prior to calling PeCoffLoaderRelocateImage(). - /// This buffer is filled with the information used to fix up the image. + /// prior to calling PeCoffLoaderRelocateImage(). + /// This buffer is filled with the information used to fix up the image. /// The fixups have been applied to the image and this entry is just for information. /// VOID *FixupData; @@ -122,7 +116,7 @@ typedef struct { UINT32 SectionAlignment; /// /// Set by PeCoffLoaderGetImageInfo() to offset to the PE/COFF header. - /// If the PE/COFF image does not start with a DOS header, this value is zero. + /// If the PE/COFF image does not start with a DOS header, this value is zero. /// Otherwise, it's the offset to the PE/COFF header. /// UINT32 PeCoffHeaderOffset; @@ -137,7 +131,7 @@ typedef struct { VOID *CodeView; /// /// Set by PeCoffLoaderLoadImage() to point to the PDB entry contained in the CodeView area. - /// The PdbPointer points to the filename of the PDB file used for source-level debug of + /// The PdbPointer points to the filename of the PDB file used for source-level debug of /// the image by a debugger. /// CHAR8 *PdbPointer; @@ -147,20 +141,20 @@ typedef struct { UINTN SizeOfHeaders; /// /// Not used by this library class. Other library classes that layer on top of this library - /// class fill in this value as part of their GetImageInfo call. + /// class fill in this value as part of their GetImageInfo call. /// This allows the caller of the library to know what type of memory needs to be allocated /// to load and relocate the image. /// UINT32 ImageCodeMemoryType; /// - /// Not used by this library class. Other library classes that layer on top of this library + /// Not used by this library class. Other library classes that layer on top of this library /// class fill in this value as part of their GetImageInfo call. /// This allows the caller of the library to know what type of memory needs to be allocated /// to load and relocate the image. /// UINT32 ImageDataMemoryType; /// - /// Set by any of the library functions if they encounter an error. + /// Set by any of the library functions if they encounter an error. /// UINT32 ImageError; /// @@ -182,7 +176,7 @@ typedef struct { /// BOOLEAN RelocationsStripped; /// - /// Set by PeCoffLoaderGetImageInfo() to TRUE if the image is a TE image. + /// Set by PeCoffLoaderGetImageInfo() to TRUE if the image is a TE image. /// For a definition of the TE Image format, see the Platform Initialization Pre-EFI /// Initialization Core Interface Specification. /// @@ -194,28 +188,28 @@ typedef struct { /// PHYSICAL_ADDRESS HiiResourceData; /// - /// Private storage for implementation specific data. + /// Private storage for implementation specific data. /// - UINT64 Context; + UINT64 Context; } PE_COFF_LOADER_IMAGE_CONTEXT; /** Retrieves information about a PE/COFF image. - Computes the PeCoffHeaderOffset, IsTeImage, ImageType, ImageAddress, ImageSize, - DestinationAddress, RelocationsStripped, SectionAlignment, SizeOfHeaders, and - DebugDirectoryEntryRva fields of the ImageContext structure. - If ImageContext is NULL, then return RETURN_INVALID_PARAMETER. - If the PE/COFF image accessed through the ImageRead service in the ImageContext - structure is not a supported PE/COFF image type, then return RETURN_UNSUPPORTED. - If any errors occur while computing the fields of ImageContext, - then the error status is returned in the ImageError field of ImageContext. + Computes the PeCoffHeaderOffset, IsTeImage, ImageType, ImageAddress, ImageSize, + DestinationAddress, RelocationsStripped, SectionAlignment, SizeOfHeaders, and + DebugDirectoryEntryRva fields of the ImageContext structure. + If ImageContext is NULL, then return RETURN_INVALID_PARAMETER. + If the PE/COFF image accessed through the ImageRead service in the ImageContext + structure is not a supported PE/COFF image type, then return RETURN_UNSUPPORTED. + If any errors occur while computing the fields of ImageContext, + then the error status is returned in the ImageError field of ImageContext. If the image is a TE image, then SectionAlignment is set to 0. - The ImageRead and Handle fields of ImageContext structure must be valid prior + The ImageRead and Handle fields of ImageContext structure must be valid prior to invoking this service. - @param ImageContext The pointer to the image context structure that - describes the PE/COFF image that needs to be + @param ImageContext The pointer to the image context structure that + describes the PE/COFF image that needs to be examined by this function. @retval RETURN_SUCCESS The information on the PE/COFF image was collected. @@ -236,12 +230,12 @@ PeCoffLoaderGetImageInfo ( ImageContext as the relocation base address. Otherwise, use the DestinationAddress field of ImageContext as the relocation base address. The caller must allocate the relocation fixup log buffer and fill in the FixupData field of ImageContext prior to calling this function. - - The ImageRead, Handle, PeCoffHeaderOffset, IsTeImage, Machine, ImageType, ImageAddress, - ImageSize, DestinationAddress, RelocationsStripped, SectionAlignment, SizeOfHeaders, - DebugDirectoryEntryRva, EntryPoint, FixupDataSize, CodeView, PdbPointer, and FixupData of + + The ImageRead, Handle, PeCoffHeaderOffset, IsTeImage, Machine, ImageType, ImageAddress, + ImageSize, DestinationAddress, RelocationsStripped, SectionAlignment, SizeOfHeaders, + DebugDirectoryEntryRva, EntryPoint, FixupDataSize, CodeView, PdbPointer, and FixupData of the ImageContext structure must be valid prior to invoking this service. - + If ImageContext is NULL, then ASSERT(). Note that if the platform does not maintain coherency between the instruction cache(s) and the data @@ -272,10 +266,10 @@ PeCoffLoaderRelocateImage ( specified by the ImageAddress and ImageSize fields of ImageContext. The caller must allocate the load buffer and fill in the ImageAddress and ImageSize fields prior to calling this function. The EntryPoint, FixupDataSize, CodeView, PdbPointer and HiiResourceData fields of ImageContext are computed. - The ImageRead, Handle, PeCoffHeaderOffset, IsTeImage, Machine, ImageType, ImageAddress, ImageSize, - DestinationAddress, RelocationsStripped, SectionAlignment, SizeOfHeaders, and DebugDirectoryEntryRva + The ImageRead, Handle, PeCoffHeaderOffset, IsTeImage, Machine, ImageType, ImageAddress, ImageSize, + DestinationAddress, RelocationsStripped, SectionAlignment, SizeOfHeaders, and DebugDirectoryEntryRva fields of the ImageContext structure must be valid prior to invoking this service. - + If ImageContext is NULL, then ASSERT(). Note that if the platform does not maintain coherency between the instruction cache(s) and the data @@ -305,25 +299,25 @@ PeCoffLoaderLoadImage ( /** Reads contents of a PE/COFF image from a buffer in system memory. - - This is the default implementation of a PE_COFF_LOADER_READ_FILE function - that assumes FileHandle pointer to the beginning of a PE/COFF image. - This function reads contents of the PE/COFF image that starts at the system memory - address specified by FileHandle. The read operation copies ReadSize bytes from the - PE/COFF image starting at byte offset FileOffset into the buffer specified by Buffer. + + This is the default implementation of a PE_COFF_LOADER_READ_FILE function + that assumes FileHandle pointer to the beginning of a PE/COFF image. + This function reads contents of the PE/COFF image that starts at the system memory + address specified by FileHandle. The read operation copies ReadSize bytes from the + PE/COFF image starting at byte offset FileOffset into the buffer specified by Buffer. The size of the buffer actually read is returned in ReadSize. - + If FileHandle is NULL, then ASSERT(). If ReadSize is NULL, then ASSERT(). If Buffer is NULL, then ASSERT(). @param FileHandle The pointer to base of the input stream @param FileOffset Offset into the PE/COFF image to begin the read operation. - @param ReadSize On input, the size in bytes of the requested read operation. + @param ReadSize On input, the size in bytes of the requested read operation. On output, the number of bytes actually read. @param Buffer Output buffer that contains the data read from the PE/COFF image. - @retval RETURN_SUCCESS The data is read from FileOffset from the Handle into + @retval RETURN_SUCCESS The data is read from FileOffset from the Handle into the buffer. **/ RETURN_STATUS @@ -338,26 +332,26 @@ PeCoffLoaderImageReadFromMemory ( /** Reapply fixups on a fixed up PE32/PE32+ image to allow virtual calling at EFI - runtime. - - This function reapplies relocation fixups to the PE/COFF image specified by ImageBase - and ImageSize so the image will execute correctly when the PE/COFF image is mapped - to the address specified by VirtualImageBase. RelocationData must be identical - to the FiuxupData buffer from the PE_COFF_LOADER_IMAGE_CONTEXT structure + runtime. + + This function reapplies relocation fixups to the PE/COFF image specified by ImageBase + and ImageSize so the image will execute correctly when the PE/COFF image is mapped + to the address specified by VirtualImageBase. RelocationData must be identical + to the FiuxupData buffer from the PE_COFF_LOADER_IMAGE_CONTEXT structure after this PE/COFF image was relocated with PeCoffLoaderRelocateImage(). Note that if the platform does not maintain coherency between the instruction cache(s) and the data cache(s) in hardware, then the caller is responsible for performing cache maintenance operations prior to transferring control to a PE/COFF image that is loaded using this library. - @param ImageBase The base address of a PE/COFF image that has been loaded + @param ImageBase The base address of a PE/COFF image that has been loaded and relocated into system memory. @param VirtImageBase The request virtual address that the PE/COFF image is to be fixed up for. @param ImageSize The size, in bytes, of the PE/COFF image. - @param RelocationData A pointer to the relocation data that was collected when the PE/COFF + @param RelocationData A pointer to the relocation data that was collected when the PE/COFF image was relocated using PeCoffLoaderRelocateImage(). - + **/ VOID EFIAPI @@ -370,15 +364,15 @@ PeCoffLoaderRelocateImageForRuntime ( /** Unloads a loaded PE/COFF image from memory and releases its taken resource. - Releases any environment specific resources that were allocated when the image - specified by ImageContext was loaded using PeCoffLoaderLoadImage(). - + Releases any environment specific resources that were allocated when the image + specified by ImageContext was loaded using PeCoffLoaderLoadImage(). + For NT32 emulator, the PE/COFF image loaded by system needs to release. - For real platform, the PE/COFF image loaded by Core doesn't needs to be unloaded, + For real platform, the PE/COFF image loaded by Core doesn't needs to be unloaded, this function can simply return RETURN_SUCCESS. - + If ImageContext is NULL, then ASSERT(). - + @param ImageContext Pointer to the image context structure that describes the PE/COFF image to be unloaded. diff --git a/MdePkg/Include/Library/PeiCoreEntryPoint.h b/MdePkg/Include/Library/PeiCoreEntryPoint.h index 11c68bae675e..35b52f7375a6 100644 --- a/MdePkg/Include/Library/PeiCoreEntryPoint.h +++ b/MdePkg/Include/Library/PeiCoreEntryPoint.h @@ -1,14 +1,8 @@ /** @file Module entry point library for PEI core. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -34,7 +28,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @param SecCoreData Points to a data structure containing information about the PEI core's operating environment, such as the size and location of - temporary RAM, the stack location and the BFV location. + temporary RAM, the stack location and the BFV location. @param PpiList Points to a list of one or more PPI descriptors to be installed initially by the PEI core. An empty PPI list consists of a single @@ -46,7 +40,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ VOID -EFIAPI +EFIAPI _ModuleEntryPoint( IN CONST EFI_SEC_PEI_HAND_OFF *SecCoreData, IN CONST EFI_PEI_PPI_DESCRIPTOR *PpiList @@ -59,7 +53,7 @@ _ModuleEntryPoint( @param SecCoreData Points to a data structure containing information about the PEI core's operating environment, such as the size and location of temporary RAM, - the stack location and the BFV location. + the stack location and the BFV location. @param PpiList Points to a list of one or more PPI descriptors to be installed initially by the PEI core. An empty PPI list consists of a single @@ -84,7 +78,7 @@ EfiMain ( This function must be called by the PEI Core once an initial PEI Services Table has been established. This function calls the set of library constructors for the set of library instances that a module depends on. This include library instances that a module depends on directly and library - instances that a module depends on indirectly through other libraries. + instances that a module depends on indirectly through other libraries. This function is autogenerated by build tools and those build tools are responsible for collecting the set of library instances, determining which ones have constructors, and calling the library constructors in the proper order based upon the dependencies of each of the library instances. @@ -107,13 +101,13 @@ ProcessLibraryConstructorList ( Autogenerated function that calls a set of module entry points. This function must be called by _ModuleEntryPoint(). - This function calls the set of module entry points. + This function calls the set of module entry points. This function is autogenerated by build tools and those build tools are responsible for collecting the module entry points and calling them in a specified order. @param SecCoreData Points to a data structure containing information about the PEI core's operating environment, such as the size and location of - temporary RAM, the stack location and the BFV location. + temporary RAM, the stack location and the BFV location. @param PpiList Points to a list of one or more PPI descriptors to be installed initially by the PEI core. An empty PPI list consists of a single @@ -121,7 +115,7 @@ ProcessLibraryConstructorList ( As part of its initialization phase, the PEI Foundation will add these SEC-hosted PPIs to its PPI database such that both the PEI Foundation and any modules can leverage the associated service calls - and/or code in these early PPIs. + and/or code in these early PPIs. @param Context A pointer to a private context structure defined by the PEI Core implementation. The implementation of _ModuleEntryPoint() must set this parameter is NULL to indicate that this is the first PEI phase. diff --git a/MdePkg/Include/Library/PeiServicesLib.h b/MdePkg/Include/Library/PeiServicesLib.h index 5135834cc7c4..de14fb902ff4 100644 --- a/MdePkg/Include/Library/PeiServicesLib.h +++ b/MdePkg/Include/Library/PeiServicesLib.h @@ -1,14 +1,8 @@ /** @file Provides library functions for all PEI Services. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -73,7 +67,7 @@ EFIAPI PeiServicesLocatePpi ( IN CONST EFI_GUID *Guid, IN UINTN Instance, - IN OUT EFI_PEI_PPI_DESCRIPTOR **PpiDescriptor, + IN OUT EFI_PEI_PPI_DESCRIPTOR **PpiDescriptor, OPTIONAL IN OUT VOID **Ppi ); @@ -225,7 +219,7 @@ PeiServicesFfsFindSectionData ( @param SectionType The value of the section type to find. @param SectionInstance Section instance to find. - @param FileHandle A pointer to the file header that contains the set + @param FileHandle A pointer to the file header that contains the set of sections to be searched. @param SectionData A pointer to the discovered section, if successful. @param AuthenticationStatus A pointer to the authentication status for this section. @@ -264,16 +258,16 @@ PeiServicesInstallPeiMemory ( ); /** - This service enables PEIMs to allocate memory after the permanent memory has been installed by a - PEIM. + This service enables PEIMs to allocate memory. @param MemoryType Type of memory to allocate. - @param Pages Number of pages to allocate. + @param Pages The number of pages to allocate. @param Memory Pointer of memory allocated. @retval EFI_SUCCESS The memory range was successfully allocated. - @retval EFI_INVALID_PARAMETER Type is not equal to AllocateAnyPages. - @retval EFI_NOT_AVAILABLE_YET Called with permanent memory not available. + @retval EFI_INVALID_PARAMETER Type is not equal to EfiLoaderCode, EfiLoaderData, EfiRuntimeServicesCode, + EfiRuntimeServicesData, EfiBootServicesCode, EfiBootServicesData, + EfiACPIReclaimMemory, EfiReservedMemoryType, or EfiACPIMemoryNVS. @retval EFI_OUT_OF_RESOURCES The pages could not be allocated. **/ @@ -286,6 +280,25 @@ PeiServicesAllocatePages ( ); /** + This service enables PEIMs to free memory. + + @param Memory Memory to be freed. + @param Pages The number of pages to free. + + @retval EFI_SUCCESS The requested pages were freed. + @retval EFI_INVALID_PARAMETER Memory is not a page-aligned address or Pages is invalid. + @retval EFI_NOT_FOUND The requested memory pages were not allocated with + AllocatePages(). + +**/ +EFI_STATUS +EFIAPI +PeiServicesFreePages ( + IN EFI_PHYSICAL_ADDRESS Memory, + IN UINTN Pages + ); + +/** This service allocates memory from the Hand-Off Block (HOB) heap. @param Size The number of bytes to allocate from the pool. @@ -318,9 +331,9 @@ PeiServicesResetSystem ( /** - This service is a wrapper for the PEI Service FfsFindByName(), except the pointer to the PEI Services - Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface - Specification for details. + This service is a wrapper for the PEI Service FfsFindByName(), except the pointer to the PEI Services + Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface + Specification for details. @param FileName A pointer to the name of the file to find within the firmware volume. @@ -328,7 +341,7 @@ PeiServicesResetSystem ( @param VolumeHandle The firmware volume to search FileHandle Upon exit, points to the found file's handle or NULL if it could not be found. - @param FileHandle Pointer to found file handle + @param FileHandle Pointer to found file handle @retval EFI_SUCCESS File was found. @@ -348,9 +361,9 @@ PeiServicesFfsFindFileByName ( /** - This service is a wrapper for the PEI Service FfsGetFileInfo(), except the pointer to the PEI Services - Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface - Specification for details. + This service is a wrapper for the PEI Service FfsGetFileInfo(), except the pointer to the PEI Services + Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface + Specification for details. @param FileHandle Handle of the file. @@ -358,15 +371,15 @@ PeiServicesFfsFindFileByName ( information. @retval EFI_SUCCESS File information returned. - + @retval EFI_INVALID_PARAMETER If FileHandle does not represent a valid file. - + @retval EFI_INVALID_PARAMETER If FileInfo is NULL. - + **/ EFI_STATUS -EFIAPI +EFIAPI PeiServicesFfsGetFileInfo ( IN CONST EFI_PEI_FILE_HANDLE FileHandle, OUT EFI_FV_FILE_INFO *FileInfo @@ -383,12 +396,12 @@ PeiServicesFfsGetFileInfo ( information. @retval EFI_SUCCESS File information returned. - + @retval EFI_INVALID_PARAMETER If FileHandle does not represent a valid file. - + @retval EFI_INVALID_PARAMETER If FileInfo is NULL. - + **/ EFI_STATUS EFIAPI @@ -398,9 +411,9 @@ PeiServicesFfsGetFileInfo2 ( ); /** - This service is a wrapper for the PEI Service FfsGetVolumeInfo(), except the pointer to the PEI Services - Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface - Specification for details. + This service is a wrapper for the PEI Service FfsGetVolumeInfo(), except the pointer to the PEI Services + Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface + Specification for details. @param VolumeHandle Handle of the volume. @@ -408,10 +421,10 @@ PeiServicesFfsGetFileInfo2 ( information. @retval EFI_SUCCESS File information returned. - + @retval EFI_INVALID_PARAMETER If FileHandle does not represent a valid file. - + @retval EFI_INVALID_PARAMETER If FileInfo is NULL. **/ @@ -424,13 +437,13 @@ PeiServicesFfsGetVolumeInfo ( /** - This service is a wrapper for the PEI Service RegisterForShadow(), except the pointer to the PEI Services - Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface - Specification for details. + This service is a wrapper for the PEI Service RegisterForShadow(), except the pointer to the PEI Services + Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface + Specification for details. @param FileHandle PEIM's file handle. Must be the currently executing PEIM. - + @retval EFI_SUCCESS The PEIM was successfully registered for shadowing. @@ -448,25 +461,25 @@ PeiServicesRegisterForShadow ( /** Install a EFI_PEI_FIRMWARE_VOLUME_INFO_PPI instance so the PEI Core will be notified about a new firmware volume. - - This function allocates, initializes, and installs a new EFI_PEI_FIRMWARE_VOLUME_INFO_PPI using + + This function allocates, initializes, and installs a new EFI_PEI_FIRMWARE_VOLUME_INFO_PPI using the parameters passed in to initialize the fields of the EFI_PEI_FIRMWARE_VOLUME_INFO_PPI instance. If the resources can not be allocated for EFI_PEI_FIRMWARE_VOLUME_INFO_PPI, then ASSERT(). If the EFI_PEI_FIRMWARE_VOLUME_INFO_PPI can not be installed, then ASSERT(). - + @param FvFormat Unique identifier of the format of the memory-mapped firmware volume. - This parameter is optional and may be NULL. + This parameter is optional and may be NULL. If NULL is specified, the EFI_FIRMWARE_FILE_SYSTEM2_GUID format is assumed. - @param FvInfo Points to a buffer which allows the EFI_PEI_FIRMWARE_VOLUME_PPI to process the volume. - The format of this buffer is specific to the FvFormat. For memory-mapped firmware volumes, + @param FvInfo Points to a buffer which allows the EFI_PEI_FIRMWARE_VOLUME_PPI to process the volume. + The format of this buffer is specific to the FvFormat. For memory-mapped firmware volumes, this typically points to the first byte of the firmware volume. - @param FvInfoSize The size, in bytes, of FvInfo. For memory-mapped firmware volumes, + @param FvInfoSize The size, in bytes, of FvInfo. For memory-mapped firmware volumes, this is typically the size of the firmware volume. - @param ParentFvName If the new firmware volume originated from a file in a different firmware volume, + @param ParentFvName If the new firmware volume originated from a file in a different firmware volume, then this parameter specifies the GUID name of the originating firmware volume. Otherwise, this parameter must be NULL. - @param ParentFileName If the new firmware volume originated from a file in a different firmware volume, + @param ParentFileName If the new firmware volume originated from a file in a different firmware volume, then this parameter specifies the GUID file name of the originating firmware file. Otherwise, this parameter must be NULL. **/ @@ -521,4 +534,26 @@ PeiServicesInstallFvInfo2Ppi ( IN UINT32 AuthenticationStatus ); +/** + Resets the entire platform. + + @param[in] ResetType The type of reset to perform. + @param[in] ResetStatus The status code for the reset. + @param[in] DataSize The size, in bytes, of ResetData. + @param[in] ResetData For a ResetType of EfiResetCold, EfiResetWarm, or EfiResetShutdown + the data buffer starts with a Null-terminated string, optionally + followed by additional binary data. The string is a description + that the caller may use to further indicate the reason for the + system reset. + +**/ +VOID +EFIAPI +PeiServicesResetSystem2 ( + IN EFI_RESET_TYPE ResetType, + IN EFI_STATUS ResetStatus, + IN UINTN DataSize, + IN VOID *ResetData OPTIONAL + ); + #endif diff --git a/MdePkg/Include/Library/PeiServicesTablePointerLib.h b/MdePkg/Include/Library/PeiServicesTablePointerLib.h index f1aa0d4bf349..eb81338943c1 100644 --- a/MdePkg/Include/Library/PeiServicesTablePointerLib.h +++ b/MdePkg/Include/Library/PeiServicesTablePointerLib.h @@ -1,14 +1,8 @@ /** @file Provides a service to retrieve a pointer to the PEI Services Table. -Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -18,10 +12,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Retrieves the cached value of the PEI Services Table pointer. - Returns the cached value of the PEI Services Table pointer in a CPU specific manner - as specified in the CPU binding section of the Platform Initialization Pre-EFI + Returns the cached value of the PEI Services Table pointer in a CPU specific manner + as specified in the CPU binding section of the Platform Initialization Pre-EFI Initialization Core Interface Specification. - + If the cached PEI Services Table pointer is NULL, then ASSERT(). @return The pointer to PeiServices. @@ -34,14 +28,14 @@ GetPeiServicesTablePointer ( ); /** - Caches a pointer PEI Services Table. - - Caches the pointer to the PEI Services Table specified by PeiServicesTablePointer - in a CPU specific manner as specified in the CPU binding section of the Platform Initialization - Pre-EFI Initialization Core Interface Specification. - + Caches a pointer PEI Services Table. + + Caches the pointer to the PEI Services Table specified by PeiServicesTablePointer + in a CPU specific manner as specified in the CPU binding section of the Platform Initialization + Pre-EFI Initialization Core Interface Specification. + If PeiServicesTablePointer is NULL, then ASSERT(). - + @param PeiServicesTablePointer The address of PeiServices pointer. **/ VOID @@ -51,16 +45,16 @@ SetPeiServicesTablePointer ( ); /** - Perform CPU specific actions required to migrate the PEI Services Table + Perform CPU specific actions required to migrate the PEI Services Table pointer from temporary RAM to permanent RAM. - For IA32 CPUs, the PEI Services Table pointer is stored in the 4 bytes + For IA32 CPUs, the PEI Services Table pointer is stored in the 4 bytes immediately preceding the Interrupt Descriptor Table (IDT) in memory. - For X64 CPUs, the PEI Services Table pointer is stored in the 8 bytes + For X64 CPUs, the PEI Services Table pointer is stored in the 8 bytes immediately preceding the Interrupt Descriptor Table (IDT) in memory. For Itanium and ARM CPUs, a the PEI Services Table Pointer is stored in - a dedicated CPU register. This means that there is no memory storage - associated with storing the PEI Services Table pointer, so no additional + a dedicated CPU register. This means that there is no memory storage + associated with storing the PEI Services Table pointer, so no additional migration actions are required for Itanium or ARM CPUs. **/ diff --git a/MdePkg/Include/Library/PeimEntryPoint.h b/MdePkg/Include/Library/PeimEntryPoint.h index 8364a0582e36..61473aafdd9d 100644 --- a/MdePkg/Include/Library/PeimEntryPoint.h +++ b/MdePkg/Include/Library/PeimEntryPoint.h @@ -1,14 +1,8 @@ /** @file Module entry point library for PEIM. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -16,7 +10,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define __MODULE_ENTRY_POINT_H__ /// -/// Declare the EFI/UEFI Specification Revision to which this driver is implemented +/// Declare the EFI/UEFI Specification Revision to which this driver is implemented /// extern CONST UINT32 _gPeimRevision; @@ -24,11 +18,11 @@ extern CONST UINT32 _gPeimRevision; /** The entry point of PE/COFF Image for a PEIM. - This function is the entry point for a PEIM. This function must call ProcessLibraryConstructorList() + This function is the entry point for a PEIM. This function must call ProcessLibraryConstructorList() and ProcessModuleEntryPointList(). The return value from ProcessModuleEntryPointList() is returned. If _gPeimRevision is not zero and PeiServices->Hdr.Revision is less than _gPeimRevison, then ASSERT(). - @param FileHandle Handle of the file being invoked. + @param FileHandle Handle of the file being invoked. @param PeiServices Describes the list of possible PEI Services. @retval EFI_SUCCESS The PEIM executed normally. @@ -44,10 +38,10 @@ _ModuleEntryPoint ( /** Required by the EBC compiler and identical in functionality to _ModuleEntryPoint(). - + This function is required to call _ModuleEntryPoint() passing in FileHandle and PeiServices. - @param FileHandle Handle of the file being invoked. + @param FileHandle Handle of the file being invoked. @param PeiServices Describes the list of possible PEI Services. @retval EFI_SUCCESS The PEIM executed normally. @@ -68,7 +62,7 @@ EfiMain ( This function must be called by _ModuleEntryPoint(). This function calls the set of library constructors for the set of library instances that a module depends on. This includes library instances that a module depends on directly and library - instances that a module depends on indirectly through other libraries. + instances that a module depends on indirectly through other libraries. This function is autogenerated by build tools and those build tools are responsible for collecting the set of library instances, determine which ones have constructors, and calling the library constructors in the proper order based upon each of the library instances own dependencies. @@ -88,16 +82,16 @@ ProcessLibraryConstructorList ( Autogenerated function that calls a set of module entry points. This function must be called by _ModuleEntryPoint(). - This function calls the set of module entry points. + This function calls the set of module entry points. This function is autogenerated by build tools and those build tools are responsible for collecting the module entry points and calling them in a specified order. - @param FileHandle Handle of the file being invoked. + @param FileHandle Handle of the file being invoked. @param PeiServices Describes the list of possible PEI Services. @retval EFI_SUCCESS The PEIM executed normally. @retval !EFI_SUCCESS The PEIM failed to execute normally. - + **/ EFI_STATUS EFIAPI diff --git a/MdePkg/Include/Library/PerformanceLib.h b/MdePkg/Include/Library/PerformanceLib.h index 28dfc6a8d40b..96b1e000f0e6 100644 --- a/MdePkg/Include/Library/PerformanceLib.h +++ b/MdePkg/Include/Library/PerformanceLib.h @@ -1,14 +1,8 @@ /** @file Provides services to log the execution times and retrieve them later. -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -20,9 +14,48 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /// #define PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED 0x00000001 +// +// Public Progress Identifiers for Event Records. +// +#define PERF_EVENT_ID 0x00 + +#define MODULE_START_ID 0x01 +#define MODULE_END_ID 0x02 +#define MODULE_LOADIMAGE_START_ID 0x03 +#define MODULE_LOADIMAGE_END_ID 0x04 +#define MODULE_DB_START_ID 0x05 +#define MODULE_DB_END_ID 0x06 +#define MODULE_DB_SUPPORT_START_ID 0x07 +#define MODULE_DB_SUPPORT_END_ID 0x08 +#define MODULE_DB_STOP_START_ID 0x09 +#define MODULE_DB_STOP_END_ID 0x0A + +#define PERF_EVENTSIGNAL_START_ID 0x10 +#define PERF_EVENTSIGNAL_END_ID 0x11 +#define PERF_CALLBACK_START_ID 0x20 +#define PERF_CALLBACK_END_ID 0x21 +#define PERF_FUNCTION_START_ID 0x30 +#define PERF_FUNCTION_END_ID 0x31 +#define PERF_INMODULE_START_ID 0x40 +#define PERF_INMODULE_END_ID 0x41 +#define PERF_CROSSMODULE_START_ID 0x50 +#define PERF_CROSSMODULE_END_ID 0x51 + +// +// Declare bits for PcdPerformanceLibraryPropertyMask and +// also used as the Type parameter of LogPerformanceMeasurementEnabled(). +// +#define PERF_CORE_START_IMAGE 0x0002 +#define PERF_CORE_LOAD_IMAGE 0x0004 +#define PERF_CORE_DB_SUPPORT 0x0008 +#define PERF_CORE_DB_START 0x0010 +#define PERF_CORE_DB_STOP 0x0020 + +#define PERF_GENERAL_TYPE 0x0040 + /** - Creates a record for the beginning of a performance measurement. - + Creates a record for the beginning of a performance measurement. + Creates a record that contains the Handle, Token, and Module. If TimeStamp is not zero, then TimeStamp is added to the record as the start time. If TimeStamp is zero, then this function reads the current time stamp @@ -51,8 +84,8 @@ StartPerformanceMeasurement ( ); /** - Fills in the end time of a performance measurement. - + Fills in the end time of a performance measurement. + Looks up the record that matches Handle, Token, and Module. If the record can not be found then return RETURN_NOT_FOUND. If the record is found and TimeStamp is not zero, @@ -83,7 +116,7 @@ EndPerformanceMeasurement ( ); /** - Attempts to retrieve a performance measurement log entry from the performance measurement log. + Attempts to retrieve a performance measurement log entry from the performance measurement log. It can also retrieve the log created by StartPerformanceMeasurementEx and EndPerformanceMeasurementEx, and then eliminate the Identifier. @@ -108,9 +141,9 @@ EndPerformanceMeasurement ( 0, then the first performance measurement log entry is retrieved. On exit, the key of the next performance lof entry entry. @param Handle Pointer to environment specific context used to identify the component - being measured. + being measured. @param Token Pointer to a Null-terminated ASCII string that identifies the component - being measured. + being measured. @param Module Pointer to a Null-terminated ASCII string that identifies the module being measured. @param StartTimeStamp Pointer to the 64-bit time stamp that was recorded when the measurement @@ -124,7 +157,7 @@ EndPerformanceMeasurement ( UINTN EFIAPI GetPerformanceMeasurement ( - IN UINTN LogEntryKey, + IN UINTN LogEntryKey, OUT CONST VOID **Handle, OUT CONST CHAR8 **Token, OUT CONST CHAR8 **Module, @@ -244,7 +277,7 @@ EndPerformanceMeasurementEx ( UINTN EFIAPI GetPerformanceMeasurementEx ( - IN UINTN LogEntryKey, + IN UINTN LogEntryKey, OUT CONST VOID **Handle, OUT CONST CHAR8 **Token, OUT CONST CHAR8 **Module, @@ -254,8 +287,8 @@ GetPerformanceMeasurementEx ( ); /** - Returns TRUE if the performance measurement macros are enabled. - + Returns TRUE if the performance measurement macros are enabled. + This function returns TRUE if the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set. Otherwise FALSE is returned. @@ -271,6 +304,373 @@ PerformanceMeasurementEnabled ( VOID ); + +/** + Check whether the specified performance measurement can be logged. + + This function returns TRUE when the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set + and the Type disable bit in PcdPerformanceLibraryPropertyMask is not set. + + @param Type - Type of the performance measurement entry. + + @retval TRUE The performance measurement can be logged. + @retval FALSE The performance measurement can NOT be logged. + +**/ +BOOLEAN +EFIAPI +LogPerformanceMeasurementEnabled ( + IN CONST UINTN Type + ); + +/** + Create performance record with event description. + + @param CallerIdentifier - Image handle or pointer to caller ID GUID + @param Guid - Pointer to a GUID. + Used for event signal perf and callback perf to cache the event guid. + @param String - Pointer to a string describing the measurement + @param Address - Pointer to a location in memory relevant to the measurement. + @param Identifier - Performance identifier describing the type of measurement. + + @retval RETURN_SUCCESS - Successfully created performance record + @retval RETURN_OUT_OF_RESOURCES - Ran out of space to store the records + @retval RETURN_INVALID_PARAMETER - Invalid parameter passed to function - NULL + pointer or invalid Identifier. + +**/ +RETURN_STATUS +EFIAPI +LogPerformanceMeasurement ( + IN CONST VOID *CallerIdentifier, OPTIONAL + IN CONST VOID *Guid, OPTIONAL + IN CONST CHAR8 *String, OPTIONAL + IN UINT64 Address, OPTIONAL + IN UINT32 Identifier + ); + +/** + Begin Macro to measure the performance of StartImage in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT1(dsiable PERF_CORE_START_IMAGE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_START_IMAGE_BEGIN(ModuleHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_START_IMAGE)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, 0, MODULE_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the performance of StartImage in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT1 (dsiable PERF_CORE_START_IMAGE)of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_START_IMAGE_END(ModuleHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_START_IMAGE)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, 0, MODULE_END_ID); \ + } \ + } while (FALSE) + +/** + Begin Macro to measure the performance of LoadImage in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT2 (dsiable PERF_CORE_LOAD_IAMGE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_LOAD_IMAGE_BEGIN(ModuleHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_LOAD_IMAGE)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, 0, MODULE_LOADIMAGE_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the performance of LoadImage in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT2 (dsiable PERF_CORE_LOAD_IAMGE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_LOAD_IMAGE_END(ModuleHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_LOAD_IMAGE)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, 0, MODULE_LOADIMAGE_END_ID); \ + } \ + } while (FALSE) + +/** + Start Macro to measure the performance of DriverBinding Support in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT3 (dsiable PERF_CORE_DB_SUPPORT) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_DRIVER_BINDING_SUPPORT_BEGIN(ModuleHandle, ControllerHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_DB_SUPPORT)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, (UINT64)(UINTN)ControllerHandle, MODULE_DB_SUPPORT_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the performance of DriverBinding Support in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT3 (dsiable PERF_CORE_DB_SUPPORT) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_DRIVER_BINDING_SUPPORT_END(ModuleHandle, ControllerHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_DB_SUPPORT)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, (UINT64)(UINTN)ControllerHandle, MODULE_DB_SUPPORT_END_ID); \ + } \ + } while (FALSE) + +/** + Begin Macro to measure the performance of DriverBinding Start in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT4 (dsiable PERF_CORE_DB_START) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_DRIVER_BINDING_START_BEGIN(ModuleHandle, ControllerHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_DB_START)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, (UINT64)(UINTN)ControllerHandle, MODULE_DB_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the performance of DriverBinding Start in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT4 (dsiable PERF_CORE_DB_START) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_DRIVER_BINDING_START_END(ModuleHandle, ControllerHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_DB_START)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, (UINT64)(UINTN)ControllerHandle, MODULE_DB_END_ID); \ + } \ + } while (FALSE) + +/** + Start Macro to measure the performance of DriverBinding Stop in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT5 (dsiable PERF_CORE_DB_STOP) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_DRIVER_BINDING_STOP_BEGIN(ModuleHandle, ControllerHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_DB_STOP)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, (UINT64)(UINTN)ControllerHandle, MODULE_DB_STOP_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the performance of DriverBinding Stop in core. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT5 (dsiable PERF_CORE_DB_STOP) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_DRIVER_BINDING_STOP_END(ModuleHandle, ControllerHandle) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_CORE_DB_STOP)) { \ + LogPerformanceMeasurement (ModuleHandle, NULL, NULL, (UINT64)(UINTN)ControllerHandle, MODULE_DB_STOP_END_ID); \ + } \ + } while (FALSE) + +/** + Macro to measure the time from power-on to this macro execution. + It can be used to log a meaningful thing which happens at a time point. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_EVENT(EventString) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, NULL, EventString , 0, PERF_EVENT_ID); \ + } \ + } while (FALSE) + +/** + Begin Macro to measure the perofrmance of evnent signal behavior in any module. + The event guid will be passed with this macro. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_EVENT_SIGNAL_BEGIN(EventGuid) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, EventGuid, __FUNCTION__ , 0, PERF_EVENTSIGNAL_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the perofrmance of evnent signal behavior in any module. + The event guid will be passed with this macro. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_EVENT_SIGNAL_END(EventGuid) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, EventGuid, __FUNCTION__ , 0, PERF_EVENTSIGNAL_END_ID); \ + } \ + } while (FALSE) + +/** + Begin Macro to measure the perofrmance of a callback function in any module. + The event guid which trigger the callback function will be passed with this macro. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_CALLBACK_BEGIN(TriggerGuid) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, TriggerGuid, __FUNCTION__ , 0, PERF_CALLBACK_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the perofrmance of a callback function in any module. + The event guid which trigger the callback function will be passed with this macro. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_CALLBACK_END(TriggerGuid) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, TriggerGuid, __FUNCTION__ , 0, PERF_CALLBACK_END_ID); \ + } \ + } while (FALSE) + +/** + Begin Macro to measure the perofrmance of a general function in any module. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_FUNCTION_BEGIN() \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, NULL, __FUNCTION__ , 0, PERF_FUNCTION_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the perofrmance of a general function in any module. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_FUNCTION_END() \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, NULL, __FUNCTION__ , 0, PERF_FUNCTION_END_ID); \ + } \ + } while (FALSE) + +/** + Begin Macro to measure the perofrmance of a behavior within one module. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_INMODULE_BEGIN(MeasurementString) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, NULL, MeasurementString, 0, PERF_INMODULE_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the perofrmance of a behavior within one module. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_INMODULE_END(MeasurementString) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, NULL, MeasurementString, 0, PERF_INMODULE_END_ID); \ + } \ + } while (FALSE) + +/** + Begin Macro to measure the perofrmance of a behavior in different modules. + Such as the performance of PEI phase, DXE phase, BDS phase. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_CROSSMODULE_BEGIN(MeasurementString) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, NULL, MeasurementString, 0, PERF_CROSSMODULE_START_ID); \ + } \ + } while (FALSE) + +/** + End Macro to measure the perofrmance of a behavior in different modules. + Such as the performance of PEI phase, DXE phase, BDS phase. + + If the PERFORMANCE_LIBRARY_PROPERTY_MEASUREMENT_ENABLED bit of PcdPerformanceLibraryPropertyMask is set, + and the BIT6 (dsiable PERF_GENERAL_TYPE) of PcdPerformanceLibraryPropertyMask is not set. + then LogPerformanceMeasurement() is called. + +**/ +#define PERF_CROSSMODULE_END(MeasurementString) \ + do { \ + if (LogPerformanceMeasurementEnabled (PERF_GENERAL_TYPE)) { \ + LogPerformanceMeasurement (&gEfiCallerIdGuid, NULL, MeasurementString, 0, PERF_CROSSMODULE_END_ID); \ + } \ + } while (FALSE) + /** Macro that calls EndPerformanceMeasurement(). diff --git a/MdePkg/Include/Library/PostCodeLib.h b/MdePkg/Include/Library/PostCodeLib.h index bfc0b227079a..df43c06ad8ea 100644 --- a/MdePkg/Include/Library/PostCodeLib.h +++ b/MdePkg/Include/Library/PostCodeLib.h @@ -1,14 +1,8 @@ /** @file Provides services to send progress/error codes to a POST card. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -21,14 +15,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Sends a 32-bit value to a POST card. - Sends the 32-bit value specified by Value to a POST card, and returns Value. - Some implementations of this library function may perform I/O operations - directly to a POST card device. Other implementations may send Value to - ReportStatusCode(), and the status code reporting mechanism will eventually + Sends the 32-bit value specified by Value to a POST card, and returns Value. + Some implementations of this library function may perform I/O operations + directly to a POST card device. Other implementations may send Value to + ReportStatusCode(), and the status code reporting mechanism will eventually display the 32-bit value on the status reporting device. - - PostCode() must actively prevent recursion. If PostCode() is called while - processing another Post Code Library function, then + + PostCode() must actively prevent recursion. If PostCode() is called while + processing another Post Code Library function, then PostCode() must return Value immediately. @param Value The 32-bit value to write to the POST card. @@ -47,21 +41,21 @@ PostCode ( Sends a 32-bit value to a POST and associated ASCII string. Sends the 32-bit value specified by Value to a POST card, and returns Value. - If Description is not NULL, then the ASCII string specified by Description is - also passed to the handler that displays the POST card value. Some - implementations of this library function may perform I/O operations directly - to a POST card device. Other implementations may send Value to ReportStatusCode(), - and the status code reporting mechanism will eventually display the 32-bit - value on the status reporting device. - - PostCodeWithDescription()must actively prevent recursion. If - PostCodeWithDescription() is called while processing another any other Post - Code Library function, then PostCodeWithDescription() must return Value + If Description is not NULL, then the ASCII string specified by Description is + also passed to the handler that displays the POST card value. Some + implementations of this library function may perform I/O operations directly + to a POST card device. Other implementations may send Value to ReportStatusCode(), + and the status code reporting mechanism will eventually display the 32-bit + value on the status reporting device. + + PostCodeWithDescription()must actively prevent recursion. If + PostCodeWithDescription() is called while processing another any other Post + Code Library function, then PostCodeWithDescription() must return Value immediately. @param Value The 32-bit value to write to the POST card. - @param Description Pointer to an ASCII string that is a description of the - POST code value. This is an optional parameter that may + @param Description Pointer to an ASCII string that is a description of the + POST code value. This is an optional parameter that may be NULL. @return The 32-bit value to write to the POST card. @@ -78,12 +72,12 @@ PostCodeWithDescription ( /** Returns TRUE if POST Codes are enabled. - This function returns TRUE if the POST_CODE_PROPERTY_POST_CODE_ENABLED + This function returns TRUE if the POST_CODE_PROPERTY_POST_CODE_ENABLED bit of PcdPostCodePropertyMask is set. Otherwise FALSE is returned. - @retval TRUE The POST_CODE_PROPERTY_POST_CODE_ENABLED bit of + @retval TRUE The POST_CODE_PROPERTY_POST_CODE_ENABLED bit of PcdPostCodeProperyMask is set. - @retval FALSE The POST_CODE_PROPERTY_POST_CODE_ENABLED bit of + @retval FALSE The POST_CODE_PROPERTY_POST_CODE_ENABLED bit of PcdPostCodeProperyMask is clear. **/ @@ -116,7 +110,7 @@ PostCodeDescriptionEnabled ( /** Sends a 32-bit value to a POST card. - If POST codes are enabled in PcdPostCodeProperyMask, then call PostCode() + If POST codes are enabled in PcdPostCodeProperyMask, then call PostCode() passing in Value. Value is returned. @param Value The 32-bit value to write to the POST card. @@ -129,13 +123,13 @@ PostCodeDescriptionEnabled ( /** Sends a 32-bit value to a POST and associated ASCII string. - If POST codes and POST code descriptions are enabled in - PcdPostCodeProperyMask, then call PostCodeWithDescription() passing in - Value and Description. If only POST codes are enabled, then call PostCode() + If POST codes and POST code descriptions are enabled in + PcdPostCodeProperyMask, then call PostCodeWithDescription() passing in + Value and Description. If only POST codes are enabled, then call PostCode() passing in Value. Value is returned. @param Value The 32-bit value to write to the POST card. - @param Description Pointer to an ASCII string that is a description of the + @param Description Pointer to an ASCII string that is a description of the POST code value. @return Value The 32-bit value to write to the POST card. diff --git a/MdePkg/Include/Library/PrintLib.h b/MdePkg/Include/Library/PrintLib.h index e9cd0842979d..8548e1ce5b62 100644 --- a/MdePkg/Include/Library/PrintLib.h +++ b/MdePkg/Include/Library/PrintLib.h @@ -2,45 +2,39 @@ Provides services to print a formatted string to a buffer. All combinations of Unicode and ASCII strings are supported. -Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that 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. - - The Print Library functions provide a simple means to produce formatted output - strings. Many of the output functions use a format string to describe how to - format the output of variable arguments. The format string consists of normal - text and argument descriptors. There are no restrictions for how the normal - text and argument descriptors can be mixed. The following end of line(EOL) +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent + + The Print Library functions provide a simple means to produce formatted output + strings. Many of the output functions use a format string to describe how to + format the output of variable arguments. The format string consists of normal + text and argument descriptors. There are no restrictions for how the normal + text and argument descriptors can be mixed. The following end of line(EOL) translations must be performed on the contents of the format string: - + - '\\r' is translated to '\\r' - '\\r\\n' is translated to '\\r\\n' - - '\\n' is translated to '\\r\\n' + - '\\n' is translated to '\\r\\n' - '\\n\\r' is translated to '\\r\\n' - - This does not follow the ANSI C standard for sprint(). The format of argument - descriptors is described below. The ANSI C standard for sprint() has been - followed for some of the format types, and has not been followed for others. + + This does not follow the ANSI C standard for sprint(). The format of argument + descriptors is described below. The ANSI C standard for sprint() has been + followed for some of the format types, and has not been followed for others. The exceptions are noted below. %[flags][width][.precision]type [flags]: - - - - - The field is left justified. If not flag is not specified, then the + - - + - The field is left justified. If not flag is not specified, then the field is right justified. - - space + - space - Prefix a space character to a number. Only valid for types X, x, and d. - - + - - Prefix a plus character to a number. Only valid for types X, x, and d. + - + + - Prefix a plus character to a number. Only valid for types X, x, and d. If both space and + are specified, then space is ignored. - 0 - - Pad with 0 characters to the left of a number. Only valid for types + - Pad with 0 characters to the left of a number. Only valid for types X, x, and d. - , - Place a comma every 3rd digit of the number. Only valid for type d. @@ -53,20 +47,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. [width]: - * - - The width of the field is specified by a UINTN argument in the + - The width of the field is specified by a UINTN argument in the argument list. - number - - The number specified as a decimal value represents the width of + - The number specified as a decimal value represents the width of the field. - NOTE: If [width] is not specified, then a field width of 0 is assumed. [.precision]: - * - - The precision of the field is specified by a UINTN argument in the + - The precision of the field is specified by a UINTN argument in the argument list. - number - - The number specified as a decimal value represents the precision of + - The number specified as a decimal value represents the precision of the field. - NOTE: If [.precision] is not specified, then a precision of 0 is assumed. @@ -75,102 +69,102 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - % - Print a %%. - c - - The argument is a Unicode character. ASCII characters can be printed + - The argument is a Unicode character. ASCII characters can be printed using this type too by making sure bits 8..15 of the argument are set to 0. - x - - The argument is an unsigned hexadecimal number. The characters used are 0..9 and - A..F. If the flag 'L' is not specified, then the argument is assumed + - The argument is an unsigned hexadecimal number. The characters used are 0..9 and + A..F. If the flag 'L' is not specified, then the argument is assumed to be size int. This does not follow ANSI C. - X - - The argument is an unsigned hexadecimal number and the number is padded with - zeros. This is equivalent to a format string of "0x". If the flag - 'L' is not specified, then the argument is assumed to be size int. + - The argument is an unsigned hexadecimal number and the number is padded with + zeros. This is equivalent to a format string of "0x". If the flag + 'L' is not specified, then the argument is assumed to be size int. This does not follow ANSI C. - d - - The argument is a signed decimal number. If the flag 'L' is not specified, - then the argument is assumed to be size int. + - The argument is a signed decimal number. If the flag 'L' is not specified, + then the argument is assumed to be size int. - u - - The argument is a unsigned decimal number. If the flag 'L' is not specified, + - The argument is a unsigned decimal number. If the flag 'L' is not specified, then the argument is assumed to be size int. - p - - The argument is a pointer that is a (VOID *), and it is printed as an + - The argument is a pointer that is a (VOID *), and it is printed as an unsigned hexadecimal number The characters used are 0..9 and A..F. - a - - The argument is a pointer to an ASCII string. + - The argument is a pointer to an ASCII string. This does not follow ANSI C. - S, s - - The argument is a pointer to a Unicode string. + - The argument is a pointer to a Unicode string. This does not follow ANSI C. - g - - The argument is a pointer to a GUID structure. The GUID is printed - in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. + - The argument is a pointer to a GUID structure. The GUID is printed + in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. This does not follow ANSI C. - t - - The argument is a pointer to an EFI_TIME structure. The time and - date are printed in the format "mm/dd/yyyy hh:mm" where mm is the - month zero padded, dd is the day zero padded, yyyy is the year zero - padded, hh is the hour zero padded, and mm is minutes zero padded. - This does not follow ANSI C. + - The argument is a pointer to an EFI_TIME structure. The time and + date are printed in the format "mm/dd/yyyy hh:mm" where mm is the + month zero padded, dd is the day zero padded, yyyy is the year zero + padded, hh is the hour zero padded, and mm is minutes zero padded. + This does not follow ANSI C. - r - - The argument is a RETURN_STATUS value. This value is converted to - a string following the table below. This does not follow ANSI C. - - RETURN_SUCCESS + - The argument is a RETURN_STATUS value. This value is converted to + a string following the table below. This does not follow ANSI C. + - RETURN_SUCCESS - "Success" - - RETURN_LOAD_ERROR + - RETURN_LOAD_ERROR - "Load Error" - - RETURN_INVALID_PARAMETER + - RETURN_INVALID_PARAMETER - "Invalid Parameter" - - RETURN_UNSUPPORTED + - RETURN_UNSUPPORTED - "Unsupported" - - RETURN_BAD_BUFFER_SIZE + - RETURN_BAD_BUFFER_SIZE - "Bad Buffer Size" - - RETURN_BUFFER_TOO_SMALL + - RETURN_BUFFER_TOO_SMALL - "Buffer Too Small" - - RETURN_NOT_READY + - RETURN_NOT_READY - "Not Ready" - - RETURN_DEVICE_ERROR + - RETURN_DEVICE_ERROR - "Device Error" - - RETURN_WRITE_PROTECTED + - RETURN_WRITE_PROTECTED - "Write Protected" - - RETURN_OUT_OF_RESOURCES + - RETURN_OUT_OF_RESOURCES - "Out of Resources" - - RETURN_VOLUME_CORRUPTED + - RETURN_VOLUME_CORRUPTED - "Volume Corrupt" - - RETURN_VOLUME_FULL + - RETURN_VOLUME_FULL - "Volume Full" - - RETURN_NO_MEDIA + - RETURN_NO_MEDIA - "No Media" - - RETURN_MEDIA_CHANGED + - RETURN_MEDIA_CHANGED - "Media changed" - - RETURN_NOT_FOUND + - RETURN_NOT_FOUND - "Not Found" - - RETURN_ACCESS_DENIED + - RETURN_ACCESS_DENIED - "Access Denied" - - RETURN_NO_RESPONSE + - RETURN_NO_RESPONSE - "No Response" - - RETURN_NO_MAPPING + - RETURN_NO_MAPPING - "No mapping" - - RETURN_TIMEOUT + - RETURN_TIMEOUT - "Time out" - - RETURN_NOT_STARTED + - RETURN_NOT_STARTED - "Not started" - - RETURN_ALREADY_STARTED + - RETURN_ALREADY_STARTED - "Already started" - - RETURN_ABORTED + - RETURN_ABORTED - "Aborted" - - RETURN_ICMP_ERROR + - RETURN_ICMP_ERROR - "ICMP Error" - - RETURN_TFTP_ERROR + - RETURN_TFTP_ERROR - "TFTP Error" - - RETURN_PROTOCOL_ERROR + - RETURN_PROTOCOL_ERROR - "Protocol Error" - - RETURN_WARN_UNKNOWN_GLYPH + - RETURN_WARN_UNKNOWN_GLYPH - "Warning Unknown Glyph" - - RETURN_WARN_DELETE_FAILURE + - RETURN_WARN_DELETE_FAILURE - "Warning Delete Failure" - - RETURN_WARN_WRITE_FAILURE + - RETURN_WARN_WRITE_FAILURE - "Warning Write Failure" - - RETURN_WARN_BUFFER_TOO_SMALL + - RETURN_WARN_BUFFER_TOO_SMALL - "Warning Buffer Too Small" **/ @@ -180,9 +174,9 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /// /// Define the maximum number of characters that are required to -/// encode with a NULL terminator a decimal, hexadecimal, GUID, +/// encode with a NULL terminator a decimal, hexadecimal, GUID, /// or TIME value. -/// +/// /// Maximum Length Decimal String = 28 /// "-9,223,372,036,854,775,808" /// Maximum Length Hexadecimal String = 17 @@ -195,7 +189,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define MAXIMUM_VALUE_CHARACTERS 38 /// -/// Flags bitmask values use in UnicodeValueToString() and +/// Flags bitmask values use in UnicodeValueToString() and /// AsciiValueToString() /// #define LEFT_JUSTIFY 0x01 @@ -497,26 +491,26 @@ UnicodeSPrintAsciiFormat ( [ATTENTION] This function is deprecated for security reason. Converts a decimal value to a Null-terminated Unicode string. - - Converts the decimal number specified by Value to a Null-terminated Unicode - string specified by Buffer containing at most Width characters. No padding of spaces + + Converts the decimal number specified by Value to a Null-terminated Unicode + string specified by Buffer containing at most Width characters. No padding of spaces is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. The number of Unicode characters in Buffer is returned, not including the Null-terminator. If the conversion contains more than Width characters, then only the first - Width characters are returned, and the total number of characters + Width characters are returned, and the total number of characters required to perform the conversion is returned. - Additional conversion parameters are specified in Flags. - + Additional conversion parameters are specified in Flags. + The Flags bit LEFT_JUSTIFY is always ignored. All conversions are left justified in Buffer. If Width is 0, PREFIX_ZERO is ignored in Flags. If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas are inserted every 3rd digit starting from the right. - If RADIX_HEX is set in Flags, then the output buffer will be + If RADIX_HEX is set in Flags, then the output buffer will be formatted in hexadecimal format. If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. - If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, - then Buffer is padded with '0' characters so the combination of the optional '-' + If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, + then Buffer is padded with '0' characters so the combination of the optional '-' sign character, '0' characters, digit characters for Value, and the Null-terminator add up to Width characters. If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). @@ -532,7 +526,7 @@ UnicodeSPrintAsciiFormat ( @param Value The 64-bit signed value to convert to a string. @param Width The maximum number of Unicode characters to place in Buffer, not including the Null-terminator. - + @return The number of Unicode characters in Buffer, not including the Null-terminator. **/ @@ -894,29 +888,29 @@ AsciiSPrintUnicodeFormat ( [ATTENTION] This function is deprecated for security reason. Converts a decimal value to a Null-terminated ASCII string. - - Converts the decimal number specified by Value to a Null-terminated ASCII string - specified by Buffer containing at most Width characters. No padding of spaces + + Converts the decimal number specified by Value to a Null-terminated ASCII string + specified by Buffer containing at most Width characters. No padding of spaces is ever performed. If Width is 0 then a width of MAXIMUM_VALUE_CHARACTERS is assumed. The number of ASCII characters in Buffer is returned, not including the Null-terminator. If the conversion contains more than Width characters, then only the first Width characters are returned, and the total number of characters required to perform the conversion is returned. - Additional conversion parameters are specified in Flags. + Additional conversion parameters are specified in Flags. The Flags bit LEFT_JUSTIFY is always ignored. All conversions are left justified in Buffer. If Width is 0, PREFIX_ZERO is ignored in Flags. If COMMA_TYPE is set in Flags, then PREFIX_ZERO is ignored in Flags, and commas are inserted every 3rd digit starting from the right. - If RADIX_HEX is set in Flags, then the output buffer will be + If RADIX_HEX is set in Flags, then the output buffer will be formatted in hexadecimal format. If Value is < 0 and RADIX_HEX is not set in Flags, then the fist character in Buffer is a '-'. - If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, - then Buffer is padded with '0' characters so the combination of the optional '-' + If PREFIX_ZERO is set in Flags and PREFIX_ZERO is not being ignored, + then Buffer is padded with '0' characters so the combination of the optional '-' sign character, '0' characters, digit characters for Value, and the Null-terminator add up to Width characters. - + If Buffer is NULL, then ASSERT(). If unsupported bits are set in Flags, then ASSERT(). If both COMMA_TYPE and RADIX_HEX are set in Flags, then ASSERT(). @@ -928,7 +922,7 @@ AsciiSPrintUnicodeFormat ( @param Value The 64-bit signed value to convert to a string. @param Width The maximum number of ASCII characters to place in Buffer, not including the Null-terminator. - + @return The number of ASCII characters in Buffer, not including the Null-terminator. **/ @@ -967,8 +961,7 @@ AsciiValueToString ( sign character, '0' characters, digit characters for Value, and the Null-terminator add up to Width characters. - If Buffer is not aligned on a 16-bit boundary, then ASSERT(). - If an error would be returned, then the function will also ASSERT(). + If an error would be returned, then the function will ASSERT(). @param Buffer The pointer to the output buffer for the produced Null-terminated Ascii string. @@ -1004,7 +997,7 @@ AsciiValueToStringS ( ); /** - Returns the number of characters that would be produced by if the formatted + Returns the number of characters that would be produced by if the formatted output were produced not including the Null-terminator. If FormatString is not aligned on a 16-bit boundary, then ASSERT(). @@ -1017,7 +1010,7 @@ AsciiValueToStringS ( @param[in] FormatString A Null-terminated Unicode format string. @param[in] Marker VA_LIST marker for the variable argument list. - @return The number of characters that would be produced, not including the + @return The number of characters that would be produced, not including the Null-terminator. **/ UINTN @@ -1028,7 +1021,7 @@ SPrintLength ( ); /** - Returns the number of characters that would be produced by if the formatted + Returns the number of characters that would be produced by if the formatted output were produced not including the Null-terminator. If FormatString is NULL, then ASSERT() and 0 is returned. @@ -1039,7 +1032,7 @@ SPrintLength ( @param[in] FormatString A Null-terminated ASCII format string. @param[in] Marker VA_LIST marker for the variable argument list. - @return The number of characters that would be produced, not including the + @return The number of characters that would be produced, not including the Null-terminator. **/ UINTN diff --git a/MdePkg/Include/Library/ReportStatusCodeLib.h b/MdePkg/Include/Library/ReportStatusCodeLib.h index 0fe55ca7d0db..0b77d78a043a 100644 --- a/MdePkg/Include/Library/ReportStatusCodeLib.h +++ b/MdePkg/Include/Library/ReportStatusCodeLib.h @@ -1,14 +1,8 @@ /** @file Provides services to log status code records. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that 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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -29,21 +23,21 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Converts a status code to an 8-bit POST code value. - Converts the status code specified by CodeType and Value to an 8-bit POST code - and returns the 8-bit POST code in PostCode. If CodeType is an - EFI_PROGRESS_CODE or CodeType is an EFI_ERROR_CODE, then bits 0..4 of PostCode - are set to bits 16..20 of Value, and bits 5..7 of PostCode are set to bits - 24..26 of Value., and TRUE is returned. Otherwise, FALSE is returned. + Converts the status code specified by CodeType and Value to an 8-bit POST code + and returns the 8-bit POST code in PostCode. If CodeType is an + EFI_PROGRESS_CODE or CodeType is an EFI_ERROR_CODE, then bits 0..4 of PostCode + are set to bits 16..20 of Value, and bits 5..7 of PostCode are set to bits + 24..26 of Value., and TRUE is returned. Otherwise, FALSE is returned. If PostCode is NULL, then ASSERT(). @param CodeType The type of status code being converted. @param Value The status code value being converted. - @param PostCode A pointer to the 8-bit POST code value to return. + @param PostCode A pointer to the 8-bit POST code value to return. - @retval TRUE The status code specified by CodeType and Value was converted + @retval TRUE The status code specified by CodeType and Value was converted to an 8-bit POST code and returned in PostCode. - @retval FALSE The status code specified by CodeType and Value could not be + @retval FALSE The status code specified by CodeType and Value could not be converted to an 8-bit POST code value. **/ @@ -60,15 +54,15 @@ CodeTypeToPostCode ( Extracts ASSERT() information from a status code structure. Converts the status code specified by CodeType, Value, and Data to the ASSERT() - arguments specified by Filename, Description, and LineNumber. If CodeType is - an EFI_ERROR_CODE, and CodeType has a severity of EFI_ERROR_UNRECOVERED, and - Value has an operation mask of EFI_SW_EC_ILLEGAL_SOFTWARE_STATE, extract - Filename, Description, and LineNumber from the optional data area of the - status code buffer specified by Data. The optional data area of Data contains - a Null-terminated ASCII string for the FileName, followed by a Null-terminated - ASCII string for the Description, followed by a 32-bit LineNumber. If the - ASSERT() information could be extracted from Data, then return TRUE. - Otherwise, FALSE is returned. + arguments specified by Filename, Description, and LineNumber. If CodeType is + an EFI_ERROR_CODE, and CodeType has a severity of EFI_ERROR_UNRECOVERED, and + Value has an operation mask of EFI_SW_EC_ILLEGAL_SOFTWARE_STATE, extract + Filename, Description, and LineNumber from the optional data area of the + status code buffer specified by Data. The optional data area of Data contains + a Null-terminated ASCII string for the FileName, followed by a Null-terminated + ASCII string for the Description, followed by a 32-bit LineNumber. If the + ASSERT() information could be extracted from Data, then return TRUE. + Otherwise, FALSE is returned. If Data is NULL, then ASSERT(). If Filename is NULL, then ASSERT(). @@ -77,15 +71,15 @@ CodeTypeToPostCode ( @param CodeType The type of status code being converted. @param Value The status code value being converted. - @param Data The pointer to status code data buffer. + @param Data The pointer to status code data buffer. @param Filename The pointer to the source file name that generated the ASSERT(). @param Description The pointer to the description of the ASSERT(). @param LineNumber The pointer to source line number that generated the ASSERT(). - @retval TRUE The status code specified by CodeType, Value, and Data was - converted ASSERT() arguments specified by Filename, Description, + @retval TRUE The status code specified by CodeType, Value, and Data was + converted ASSERT() arguments specified by Filename, Description, and LineNumber. - @retval FALSE The status code specified by CodeType, Value, and Data could + @retval FALSE The status code specified by CodeType, Value, and Data could not be converted to ASSERT() arguments. **/ @@ -93,8 +87,8 @@ BOOLEAN EFIAPI ReportStatusCodeExtractAssertInfo ( IN EFI_STATUS_CODE_TYPE CodeType, - IN EFI_STATUS_CODE_VALUE Value, - IN CONST EFI_STATUS_CODE_DATA *Data, + IN EFI_STATUS_CODE_VALUE Value, + IN CONST EFI_STATUS_CODE_DATA *Data, OUT CHAR8 **Filename, OUT CHAR8 **Description, OUT UINT32 *LineNumber @@ -104,13 +98,13 @@ ReportStatusCodeExtractAssertInfo ( /** Extracts DEBUG() information from a status code structure. - Converts the status code specified by Data to the DEBUG() arguments specified - by ErrorLevel, Marker, and Format. If type GUID in Data is - EFI_STATUS_CODE_DATA_TYPE_DEBUG_GUID, then extract ErrorLevel, Marker, and - Format from the optional data area of the status code buffer specified by Data. - The optional data area of Data contains a 32-bit ErrorLevel followed by Marker - which is 12 UINTN parameters, followed by a Null-terminated ASCII string for - the Format. If the DEBUG() information could be extracted from Data, then + Converts the status code specified by Data to the DEBUG() arguments specified + by ErrorLevel, Marker, and Format. If type GUID in Data is + EFI_STATUS_CODE_DATA_TYPE_DEBUG_GUID, then extract ErrorLevel, Marker, and + Format from the optional data area of the status code buffer specified by Data. + The optional data area of Data contains a 32-bit ErrorLevel followed by Marker + which is 12 UINTN parameters, followed by a Null-terminated ASCII string for + the Format. If the DEBUG() information could be extracted from Data, then return TRUE. Otherwise, FALSE is returned. If Data is NULL, then ASSERT(). @@ -118,22 +112,22 @@ ReportStatusCodeExtractAssertInfo ( If Marker is NULL, then ASSERT(). If Format is NULL, then ASSERT(). - @param Data The pointer to status code data buffer. + @param Data The pointer to status code data buffer. @param ErrorLevel The pointer to error level mask for a debug message. @param Marker The pointer to the variable argument list associated with Format. - @param Format The pointer to a Null-terminated ASCII format string of a + @param Format The pointer to a Null-terminated ASCII format string of a debug message. - @retval TRUE The status code specified by Data was converted DEBUG() arguments + @retval TRUE The status code specified by Data was converted DEBUG() arguments specified by ErrorLevel, Marker, and Format. - @retval FALSE The status code specified by Data could not be converted to + @retval FALSE The status code specified by Data could not be converted to DEBUG() arguments. **/ BOOLEAN EFIAPI ReportStatusCodeExtractDebugInfo ( - IN CONST EFI_STATUS_CODE_DATA *Data, + IN CONST EFI_STATUS_CODE_DATA *Data, OUT UINT32 *ErrorLevel, OUT BASE_LIST *Marker, OUT CHAR8 **Format @@ -143,20 +137,20 @@ ReportStatusCodeExtractDebugInfo ( /** Reports a status code. - Reports the status code specified by the parameters Type and Value. Status - code also require an instance, caller ID, and extended data. This function - passed in a zero instance, NULL extended data, and a caller ID of - gEfiCallerIdGuid, which is the GUID for the module. - - ReportStatusCode()must actively prevent recursion. If ReportStatusCode() + Reports the status code specified by the parameters Type and Value. Status + code also require an instance, caller ID, and extended data. This function + passed in a zero instance, NULL extended data, and a caller ID of + gEfiCallerIdGuid, which is the GUID for the module. + + ReportStatusCode()must actively prevent recursion. If ReportStatusCode() is called while processing another any other Report Status Code Library function, then ReportStatusCode() must return immediately. - @param Type Status code type. + @param Type Status code type. @param Value Status code value. @retval EFI_SUCCESS The status code was reported. - @retval EFI_DEVICE_ERROR There status code could not be reported due to a + @retval EFI_DEVICE_ERROR There status code could not be reported due to a device error. @retval EFI_UNSUPPORTED The report status code is not supported. @@ -172,26 +166,26 @@ ReportStatusCode ( /** Reports a status code with a Device Path Protocol as the extended data. - Allocates and fills in the extended data section of a status code with the - Device Path Protocol specified by DevicePath. This function is responsible - for allocating a buffer large enough for the standard header and the device + Allocates and fills in the extended data section of a status code with the + Device Path Protocol specified by DevicePath. This function is responsible + for allocating a buffer large enough for the standard header and the device path. The standard header is filled in with an implementation dependent GUID. The status code is reported with a zero instance and a caller ID of gEfiCallerIdGuid. - ReportStatusCodeWithDevicePath()must actively prevent recursion. If - ReportStatusCodeWithDevicePath() is called while processing another any other - Report Status Code Library function, then ReportStatusCodeWithDevicePath() + ReportStatusCodeWithDevicePath()must actively prevent recursion. If + ReportStatusCodeWithDevicePath() is called while processing another any other + Report Status Code Library function, then ReportStatusCodeWithDevicePath() must return EFI_DEVICE_ERROR immediately. If DevicePath is NULL, then ASSERT(). - @param Type The status code type. + @param Type The status code type. @param Value The status code value. @param DevicePath The pointer to the Device Path Protocol to be reported. - @retval EFI_SUCCESS The status code was reported with the extended + @retval EFI_SUCCESS The status code was reported with the extended data specified by DevicePath. - @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the + @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the extended data section. @retval EFI_UNSUPPORTED The report status code is not supported. @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function @@ -210,32 +204,32 @@ ReportStatusCodeWithDevicePath ( /** Reports a status code with an extended data buffer. - Allocates and fills in the extended data section of a status code with the - extended data specified by ExtendedData and ExtendedDataSize. ExtendedData - is assumed to be one of the data structures specified in Related Definitions. - These data structure do not have the standard header, so this function is - responsible for allocating a buffer large enough for the standard header and - the extended data passed into this function. The standard header is filled - in with an implementation dependent GUID. The status code is reported + Allocates and fills in the extended data section of a status code with the + extended data specified by ExtendedData and ExtendedDataSize. ExtendedData + is assumed to be one of the data structures specified in Related Definitions. + These data structure do not have the standard header, so this function is + responsible for allocating a buffer large enough for the standard header and + the extended data passed into this function. The standard header is filled + in with an implementation dependent GUID. The status code is reported with a zero instance and a caller ID of gEfiCallerIdGuid. - ReportStatusCodeWithExtendedData()must actively prevent recursion. If - ReportStatusCodeWithExtendedData() is called while processing another any other - Report Status Code Library function, then ReportStatusCodeWithExtendedData() + ReportStatusCodeWithExtendedData()must actively prevent recursion. If + ReportStatusCodeWithExtendedData() is called while processing another any other + Report Status Code Library function, then ReportStatusCodeWithExtendedData() must return EFI_DEVICE_ERROR immediately. If ExtendedData is NULL, then ASSERT(). If ExtendedDataSize is 0, then ASSERT(). - @param Type The status code type. + @param Type The status code type. @param Value The status code value. @param ExtendedData The pointer to the extended data buffer to be reported. - @param ExtendedDataSize The size, in bytes, of the extended data buffer to + @param ExtendedDataSize The size, in bytes, of the extended data buffer to be reported. - @retval EFI_SUCCESS The status code was reported with the extended + @retval EFI_SUCCESS The status code was reported with the extended data specified by ExtendedData and ExtendedDataSize. - @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the + @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the extended data section. @retval EFI_UNSUPPORTED The report status code is not supported. @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function @@ -255,39 +249,39 @@ ReportStatusCodeWithExtendedData ( /** Reports a status code with full parameters. - The function reports a status code. If ExtendedData is NULL and ExtendedDataSize - is 0, then an extended data buffer is not reported. If ExtendedData is not - NULL and ExtendedDataSize is not 0, then an extended data buffer is allocated. - ExtendedData is assumed not have the standard status code header, so this function - is responsible for allocating a buffer large enough for the standard header and - the extended data passed into this function. The standard header is filled in - with a GUID specified by ExtendedDataGuid. If ExtendedDataGuid is NULL, then a - GUID of gEfiStatusCodeSpecificDataGuid is used. The status code is reported with - an instance specified by Instance and a caller ID specified by CallerId. If + The function reports a status code. If ExtendedData is NULL and ExtendedDataSize + is 0, then an extended data buffer is not reported. If ExtendedData is not + NULL and ExtendedDataSize is not 0, then an extended data buffer is allocated. + ExtendedData is assumed not have the standard status code header, so this function + is responsible for allocating a buffer large enough for the standard header and + the extended data passed into this function. The standard header is filled in + with a GUID specified by ExtendedDataGuid. If ExtendedDataGuid is NULL, then a + GUID of gEfiStatusCodeSpecificDataGuid is used. The status code is reported with + an instance specified by Instance and a caller ID specified by CallerId. If CallerId is NULL, then a caller ID of gEfiCallerIdGuid is used. - ReportStatusCodeEx()must actively prevent recursion. If ReportStatusCodeEx() - is called while processing another any other Report Status Code Library function, + ReportStatusCodeEx()must actively prevent recursion. If ReportStatusCodeEx() + is called while processing another any other Report Status Code Library function, then ReportStatusCodeEx() must return EFI_DEVICE_ERROR immediately. If ExtendedData is NULL and ExtendedDataSize is not zero, then ASSERT(). If ExtendedData is not NULL and ExtendedDataSize is zero, then ASSERT(). - @param Type The status code type. + @param Type The status code type. @param Value The status code value. @param Instance The status code instance number. - @param CallerId The pointer to a GUID that identifies the caller of this - function. If this parameter is NULL, then a caller + @param CallerId The pointer to a GUID that identifies the caller of this + function. If this parameter is NULL, then a caller ID of gEfiCallerIdGuid is used. - @param ExtendedDataGuid The pointer to the GUID for the extended data buffer. - If this parameter is NULL, then a the status code + @param ExtendedDataGuid The pointer to the GUID for the extended data buffer. + If this parameter is NULL, then a the status code standard header is filled in with an implementation dependent GUID. - @param ExtendedData The pointer to the extended data buffer. This is an + @param ExtendedData The pointer to the extended data buffer. This is an optional parameter that may be NULL. @param ExtendedDataSize The size, in bytes, of the extended data buffer. @retval EFI_SUCCESS The status code was reported. - @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate + @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the extended data section if it was specified. @retval EFI_UNSUPPORTED The report status code is not supported. @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function @@ -310,12 +304,12 @@ ReportStatusCodeEx ( /** Returns TRUE if status codes of type EFI_PROGRESS_CODE are enabled - This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED + This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned. - @retval TRUE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of + @retval TRUE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of PcdReportStatusCodeProperyMask is set. - @retval FALSE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of + @retval FALSE The REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED bit of PcdReportStatusCodeProperyMask is clear. **/ @@ -329,12 +323,12 @@ ReportProgressCodeEnabled ( /** Returns TRUE if status codes of type EFI_ERROR_CODE are enabled - This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED + This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of PcdReportStatusCodeProperyMask is set. Otherwise, FALSE is returned. - @retval TRUE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of + @retval TRUE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of PcdReportStatusCodeProperyMask is set. - @retval FALSE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of + @retval FALSE The REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED bit of PcdReportStatusCodeProperyMask is clear. **/ @@ -348,12 +342,12 @@ ReportErrorCodeEnabled ( /** Returns TRUE if status codes of type EFI_DEBUG_CODE are enabled - This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED + This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of PcdReportStatusCodeProperyMask is set. Otherwise FALSE is returned. - @retval TRUE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of + @retval TRUE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of PcdReportStatusCodeProperyMask is set. - @retval FALSE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of + @retval FALSE The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of PcdReportStatusCodeProperyMask is clear. **/ @@ -367,11 +361,11 @@ ReportDebugCodeEnabled ( /** Reports a status code with minimal parameters if the status code type is enabled. - If the status code type specified by Type is enabled in - PcdReportStatusCodeProperyMask, then call ReportStatusCode() passing in Type + If the status code type specified by Type is enabled in + PcdReportStatusCodeProperyMask, then call ReportStatusCode() passing in Type and Value. - @param Type The status code type. + @param Type The status code type. @param Value The status code value. @retval EFI_SUCCESS The status code was reported. @@ -390,20 +384,20 @@ ReportDebugCodeEnabled ( /** - Reports a status code with a Device Path Protocol as the extended data if the + Reports a status code with a Device Path Protocol as the extended data if the status code type is enabled. - If the status code type specified by Type is enabled in - PcdReportStatusCodeProperyMask, then call ReportStatusCodeWithDevicePath() + If the status code type specified by Type is enabled in + PcdReportStatusCodeProperyMask, then call ReportStatusCodeWithDevicePath() passing in Type, Value, and DevicePath. - @param Type The status code type. + @param Type The status code type. @param Value The status code value. @param DevicePath Pointer to the Device Path Protocol to be reported. - @retval EFI_SUCCESS The status code was reported with the extended + @retval EFI_SUCCESS The status code was reported with the extended data specified by DevicePath. - @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the + @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the extended data section. @retval EFI_UNSUPPORTED The report status code is not supported. @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function @@ -421,22 +415,22 @@ ReportDebugCodeEnabled ( /** - Reports a status code with an extended data buffer if the status code type + Reports a status code with an extended data buffer if the status code type is enabled. - If the status code type specified by Type is enabled in - PcdReportStatusCodeProperyMask, then call ReportStatusCodeWithExtendedData() + If the status code type specified by Type is enabled in + PcdReportStatusCodeProperyMask, then call ReportStatusCodeWithExtendedData() passing in Type, Value, ExtendedData, and ExtendedDataSize. - @param Type The status code type. + @param Type The status code type. @param Value The status code value. @param ExtendedData The pointer to the extended data buffer to be reported. @param ExtendedDataSize The size, in bytes, of the extended data buffer to be reported. - @retval EFI_SUCCESS The status code was reported with the extended + @retval EFI_SUCCESS The status code was reported with the extended data specified by ExtendedData and ExtendedDataSize. - @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the + @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the extended data section. @retval EFI_UNSUPPORTED The report status code is not supported. @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function @@ -455,25 +449,25 @@ ReportDebugCodeEnabled ( /** Reports a status code specifying all parameters if the status code type is enabled. - If the status code type specified by Type is enabled in - PcdReportStatusCodeProperyMask, then call ReportStatusCodeEx() passing in Type, + If the status code type specified by Type is enabled in + PcdReportStatusCodeProperyMask, then call ReportStatusCodeEx() passing in Type, Value, Instance, CallerId, ExtendedDataGuid, ExtendedData, and ExtendedDataSize. - @param Type The status code type. + @param Type The status code type. @param Value The status code value. @param Instance The status code instance number. - @param CallerId The pointer to a GUID that identifies the caller of this - function. If this parameter is NULL, then a caller + @param CallerId The pointer to a GUID that identifies the caller of this + function. If this parameter is NULL, then a caller ID of gEfiCallerIdGuid is used. - @param ExtendedDataGuid Pointer to the GUID for the extended data buffer. - If this parameter is NULL, then a the status code + @param ExtendedDataGuid Pointer to the GUID for the extended data buffer. + If this parameter is NULL, then a the status code standard header is filled in with an implementation dependent GUID. - @param ExtendedData Pointer to the extended data buffer. This is an + @param ExtendedData Pointer to the extended data buffer. This is an optional parameter that may be NULL. @param ExtendedDataSize The size, in bytes, of the extended data buffer. @retval EFI_SUCCESS The status code was reported. - @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the + @retval EFI_OUT_OF_RESOURCES There were not enough resources to allocate the extended data section if it was specified. @retval EFI_UNSUPPORTED The report status code is not supported. @retval EFI_DEVICE_ERROR A call to a Report Status Code Library function diff --git a/MdePkg/Include/Library/ResourcePublicationLib.h b/MdePkg/Include/Library/ResourcePublicationLib.h index c15f58f48ebc..3e2a810e4280 100644 --- a/MdePkg/Include/Library/ResourcePublicationLib.h +++ b/MdePkg/Include/Library/ResourcePublicationLib.h @@ -1,14 +1,8 @@ /** @file Provides a service to publish discovered system resources. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -21,9 +15,9 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Declares that the system memory buffer specified by MemoryBegin and MemoryLength as permanent memory that may be used for general purpose use by software. The amount of memory available to software may be less than MemoryLength - if published memory has alignment restrictions. + if published memory has alignment restrictions. If MemoryLength is 0, then ASSERT(). - If MemoryLength is greater than (MAX_ADDRESS - MemoryBegin + 1), then ASSERT(). + If MemoryLength is greater than (MAX_ADDRESS - MemoryBegin + 1), then ASSERT(). @param MemoryBegin The start address of the memory being declared. @param MemoryLength The number of bytes of memory being declared. diff --git a/MdePkg/Include/Library/RngLib.h b/MdePkg/Include/Library/RngLib.h index 4b0b90cd346d..bed9d8e5beba 100644 --- a/MdePkg/Include/Library/RngLib.h +++ b/MdePkg/Include/Library/RngLib.h @@ -2,13 +2,7 @@ Provides random number generator services. Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> -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. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/S3BootScriptLib.h b/MdePkg/Include/Library/S3BootScriptLib.h index 160a6d869adb..4e8e4b3ffaac 100644 --- a/MdePkg/Include/Library/S3BootScriptLib.h +++ b/MdePkg/Include/Library/S3BootScriptLib.h @@ -1,20 +1,13 @@ -/** @file - Defines library APIs used by modules to save EFI Boot Script Opcodes. - These OpCode will be restored by S3 related modules. - Note that some of the API defined in the Library class may not - be provided in the Framework version library instance, which means some of these +/** @file + Defines library APIs used by modules to save EFI Boot Script Opcodes. + These OpCode will be restored by S3 related modules. + Note that some of the API defined in the Library class may not + be provided in the Framework version library instance, which means some of these APIs cannot be used if the underlying firmware is Framework and not PI. - Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR> + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> - 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. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -43,14 +36,14 @@ (((UINTN) Device) << 16) | \ (((UINTN) Function) << 8) | \ (((UINTN) (Register)) < 256 ? ((UINTN) (Register)) : (UINT64) (LShiftU64 ((UINT64) (Register), 32)))) - + /// /// S3 Boot Script Width. /// typedef enum { S3BootScriptWidthUint8, ///< 8-bit operation. S3BootScriptWidthUint16, ///< 16-bit operation. - S3BootScriptWidthUint32, ///< 32-bit operation. + S3BootScriptWidthUint32, ///< 32-bit operation. S3BootScriptWidthUint64, ///< 64-bit operation. S3BootScriptWidthFifoUint8, ///< 8-bit FIFO operation. S3BootScriptWidthFifoUint16, ///< 16-bit FIFO operation. @@ -71,7 +64,7 @@ typedef enum { @param[in] Count The number of I/O operations to perform. @param[in] Buffer The source buffer from which to write data. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. @@ -94,7 +87,7 @@ S3BootScriptSaveIoWrite ( @param[in] DataMask A pointer to the data mask to be AND-ed with the data read from the register. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. @@ -116,7 +109,7 @@ S3BootScriptSaveIoReadWrite ( @param[in] Count The number of memory operations to perform. @param[in] Buffer The source buffer from which to write the data. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. **/ @@ -133,13 +126,13 @@ S3BootScriptSaveMemWrite ( Adds a record for a memory modify operation into a specified boot script table. @param[in] Width The width of the I/O operations. - @param[in] Address The base address of the memory operations. Address needs + @param[in] Address The base address of the memory operations. Address needs alignment, if required @param[in] Data A pointer to the data to be OR-ed. - @param[in] DataMask A pointer to the data mask to be AND-ed with the data + @param[in] DataMask A pointer to the data mask to be AND-ed with the data read from the register. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. **/ @@ -160,7 +153,7 @@ S3BootScriptSaveMemReadWrite ( @param[in] Count The number of PCI operations to perform. @param[in] Buffer The source buffer from which to write the data. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. **/ @@ -181,7 +174,7 @@ S3BootScriptSavePciCfgWrite ( @param[in] Data A pointer to the data to be OR-ed.The size depends on Width. @param[in] DataMask A pointer to the data mask to be AND-ed. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN__SUCCESS The opcode was added. **/ @@ -203,7 +196,7 @@ S3BootScriptSavePciCfgReadWrite ( @param[in] Count The number of PCI operations to perform. @param[in] Buffer The source buffer from which to write the data. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. **/ @@ -226,7 +219,7 @@ S3BootScriptSavePciCfg2Write ( @param[in] Data A pointer to the data to be OR-ed. The size depends on Width. @param[in] DataMask A pointer to the data mask to be AND-ed. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. **/ @@ -243,23 +236,23 @@ S3BootScriptSavePciCfg2ReadWrite ( /** Adds a record for an SMBus command execution into a specified boot script table. - @param[in] SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS + @param[in] SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC. - @param[in] Operation Indicates which particular SMBus protocol it will use + @param[in] Operation Indicates which particular SMBus protocol it will use to execute the SMBus transactions. - @param[in] Length A pointer to signify the number of bytes that this + @param[in] Length A pointer to signify the number of bytes that this operation will do. - @param[in] Buffer Contains the value of data to execute to the SMBUS + @param[in] Buffer Contains the value of data to execute to the SMBUS slave device. - - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. **/ RETURN_STATUS EFIAPI S3BootScriptSaveSmbusExecute ( - IN UINTN SmBusAddress, + IN UINTN SmBusAddress, IN EFI_SMBUS_OPERATION Operation, IN UINTN *Length, IN VOID *Buffer @@ -269,8 +262,8 @@ S3BootScriptSaveSmbusExecute ( Adds a record for an execution stall on the processor into a specified boot script table. @param[in] Duration The duration in microseconds of the stall. - - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. **/ @@ -284,10 +277,10 @@ S3BootScriptSaveStall ( Adds a record for dispatching specified arbitrary code into a specified boot script table. @param[in] EntryPoint The entry point of the code to be dispatched. - @param[in] Context The argument to be passed into the EntryPoint of the code + @param[in] Context The argument to be passed into the EntryPoint of the code to be dispatched. - - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. **/ @@ -302,8 +295,8 @@ S3BootScriptSaveDispatch2 ( Adds a record for dispatching specified arbitrary code into a specified boot script table. @param[in] EntryPoint The entry point of the code to be dispatched. - - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. **/ @@ -314,7 +307,7 @@ S3BootScriptSaveDispatch ( ); /** - Adds a record for memory reads of the memory location and continues when the exit + Adds a record for memory reads of the memory location and continues when the exit criteria is satisfied, or after a defined duration. Please aware, below interface is different with PI specification, Vol 5: @@ -324,13 +317,13 @@ S3BootScriptSaveDispatch ( @param[in] Width The width of the memory operations. @param[in] Address The base address of the memory operations. - @param[in] BitMask A pointer to the bit mask to be AND-ed with the data read + @param[in] BitMask A pointer to the bit mask to be AND-ed with the data read from the register. @param[in] BitValue A pointer to the data value after to be Masked. @param[in] Duration The duration in microseconds of the stall. @param[in] LoopTimes The times of the register polling. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. @@ -347,13 +340,13 @@ S3BootScriptSaveMemPoll ( ); /** - Store arbitrary information in the boot script table. This opcode is a no-op on + Store arbitrary information in the boot script table. This opcode is a no-op on dispatch and is only used for debugging script issues. - + @param[in] InformationLength Length of the data in bytes @param[in] Information Information to be logged in the boot scrpit - - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. @@ -361,27 +354,27 @@ S3BootScriptSaveMemPoll ( RETURN_STATUS EFIAPI S3BootScriptSaveInformation ( - IN UINT32 InformationLength, + IN UINT32 InformationLength, IN VOID *Information ); /** Adds a record for I/O reads the I/O location and continues when the exit criteria is satisfied, or after a defined duration. - - @param Width The width of the I/O operations. + + @param Width The width of the I/O operations. @param Address The base address of the I/O operations. @param Data The comparison value used for the polling exit criteria. - @param DataMask The mask used for the polling criteria. The bits in - the bytes below Width which are zero in Data are + @param DataMask The mask used for the polling criteria. The bits in + the bytes below Width which are zero in Data are ignored when polling the memory address. - @param Delay The number of 100ns units to poll. Note that timer - available may be of insufficient granularity, so the + @param Delay The number of 100ns units to poll. Note that timer + available may be of insufficient granularity, so the delay may be longer. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. - @note The FRAMEWORK version implementation does not support this API + @note The FRAMEWORK version implementation does not support this API **/ RETURN_STATUS EFIAPI @@ -389,29 +382,29 @@ S3BootScriptSaveIoPoll ( IN S3_BOOT_SCRIPT_LIB_WIDTH Width, IN UINT64 Address, IN VOID *Data, - IN VOID *DataMask, - IN UINT64 Delay + IN VOID *DataMask, + IN UINT64 Delay ); /** - Adds a record for PCI configuration space reads and continues when the exit + Adds a record for PCI configuration space reads and continues when the exit criteria is satisfied ,or after a defined duration. - @param Width The width of the I/O operations. + @param Width The width of the I/O operations. @param Address The address within the PCI configuration space. - @param Data The comparison value used for the polling exit + @param Data The comparison value used for the polling exit criteria. - @param DataMask Mask used for the polling criteria. The bits in + @param DataMask Mask used for the polling criteria. The bits in the bytes below Width which are zero in Data are ignored when polling the memory address. - @param Delay The number of 100ns units to poll. Note that timer - available may be of insufficient granularity, so the + @param Delay The number of 100ns units to poll. Note that timer + available may be of insufficient granularity, so the delay may be longer. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. - @note The FRAMEWORK version implementation does not support this API + @note The FRAMEWORK version implementation does not support this API **/ RETURN_STATUS EFIAPI @@ -423,27 +416,27 @@ S3BootScriptSavePciPoll ( IN UINT64 Delay ); /** - Adds a record for PCI configuration space reads and continues when the exit criteria + Adds a record for PCI configuration space reads and continues when the exit criteria is satisfied, or after a defined duration. - @param Width The width of the I/O operations. + @param Width The width of the I/O operations. @param Segment The PCI segment number for Address. @param Address The address within the PCI configuration space. - @param Data The comparison value used for the polling exit + @param Data The comparison value used for the polling exit criteria. - @param DataMask Mask used for the polling criteria. The bits in + @param DataMask Mask used for the polling criteria. The bits in the bytes below Width which are zero in Data are ignored when polling the memory address - @param Delay The number of 100ns units to poll. Note that timer - available may be of insufficient granularity so the delay + @param Delay The number of 100ns units to poll. Note that timer + available may be of insufficient granularity so the delay may be longer. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. - @note A known Limitations in the implementation: When interpreting the opcode + @note A known Limitations in the implementation: When interpreting the opcode EFI_BOOT_SCRIPT_PCI_CONFIG2_WRITE_OPCODE, EFI_BOOT_SCRIPT_PCI_CONFIG2_READ_WRITE_OPCODE - and EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE, the 'Segment' parameter is assumed as + and EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE, the 'Segment' parameter is assumed as Zero, or else, assert. The FRAMEWORK version implementation does not support this API. @@ -459,13 +452,13 @@ S3BootScriptSavePci2Poll ( IN UINT64 Delay ); /** - Save ASCII string information specified by Buffer to boot script with opcode + Save ASCII string information specified by Buffer to boot script with opcode EFI_BOOT_SCRIPT_INFORMATION_OPCODE. - @param[in] String The Null-terminated ASCII string to store into the S3 boot + @param[in] String The Null-terminated ASCII string to store into the S3 boot script table. - @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform + @retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the operation. @retval RETURN_SUCCESS The opcode was added. @@ -477,27 +470,27 @@ S3BootScriptSaveInformationAsciiString ( ); /** - This is an function to close the S3 boot script table. The function could only - be called in BOOT time phase. To comply with the Framework spec definition on + This is an function to close the S3 boot script table. The function could only + be called in BOOT time phase. To comply with the Framework spec definition on EFI_BOOT_SCRIPT_SAVE_PROTOCOL.CloseTable(), this function will fulfill following things: 1. Closes the specified boot script table - 2. It allocates a new memory pool to duplicate all the boot scripts in the specified table. - Once this function is called, the table maintained by the library will be destroyed + 2. It allocates a new memory pool to duplicate all the boot scripts in the specified table. + Once this function is called, the table maintained by the library will be destroyed after it is copied into the allocated pool. - 3. Any attempts to add a script record after calling this function will cause a + 3. Any attempts to add a script record after calling this function will cause a new table to be created by the library. - 4. The base address of the allocated pool will be returned in Address. Note that - after using the boot script table, the CALLER is responsible for freeing the - pool that is allocated by this function. + 4. The base address of the allocated pool will be returned in Address. Note that + after using the boot script table, the CALLER is responsible for freeing the + pool that is allocated by this function. - In Spec PI1.1, this EFI_BOOT_SCRIPT_SAVE_PROTOCOL.CloseTable() is retired. This + In Spec PI1.1, this EFI_BOOT_SCRIPT_SAVE_PROTOCOL.CloseTable() is retired. This API is supplied here to meet the requirements of the Framework Spec. - + If anyone does call CloseTable() on a real platform, then the caller is responsible - for figuring out how to get the script to run on an S3 resume because the boot script + for figuring out how to get the script to run on an S3 resume because the boot script maintained by the lib will be destroyed. - - @return the base address of the new copy of the boot script table. + + @return the base address of the new copy of the boot script table. **/ UINT8* @@ -510,7 +503,7 @@ S3BootScriptCloseTable ( Executes the S3 boot script table. @retval RETURN_SUCCESS The boot script table was executed successfully. - @retval RETURN_UNSUPPORTED Invalid script table or opcode. + @retval RETURN_UNSUPPORTED Invalid script table or opcode. **/ RETURN_STATUS @@ -519,25 +512,25 @@ S3BootScriptExecute ( VOID ); /** - Move the last boot script entry to the position + Move the last boot script entry to the position - @param BeforeOrAfter Specifies whether the opcode is stored before - (TRUE) or after (FALSE) the positionin the boot - script table specified by Position. If Position - is NULL or points to NULL then the new opcode is - inserted at the beginning of the table (if TRUE) + @param BeforeOrAfter Specifies whether the opcode is stored before + (TRUE) or after (FALSE) the positionin the boot + script table specified by Position. If Position + is NULL or points to NULL then the new opcode is + inserted at the beginning of the table (if TRUE) or end of the table (if FALSE). - @param Position On entry, specifies the position in the boot script - table where the opcode will be inserted, either - before or after, depending on BeforeOrAfter. On - exit, specifies the position of the inserted opcode + @param Position On entry, specifies the position in the boot script + table where the opcode will be inserted, either + before or after, depending on BeforeOrAfter. On + exit, specifies the position of the inserted opcode in the boot script table. @retval RETURN_OUT_OF_RESOURCES The table is not available. - @retval RETURN_INVALID_PARAMETER The Position is not a valid position in the + @retval RETURN_INVALID_PARAMETER The Position is not a valid position in the boot script table. @retval RETURN_SUCCESS The opcode was inserted. - @note The FRAMEWORK version implementation does not support this API. + @note The FRAMEWORK version implementation does not support this API. **/ RETURN_STATUS EFIAPI @@ -549,28 +542,28 @@ S3BootScriptMoveLastOpcode ( Find a label within the boot script table and, if not present, optionally create it. @param BeforeOrAfter Specifies whether the opcode is stored before (TRUE) - or after (FALSE) the position in the boot script table + or after (FALSE) the position in the boot script table specified by Position. - @param CreateIfNotFound Specifies whether the label will be created if the + @param CreateIfNotFound Specifies whether the label will be created if the label does not exists (TRUE) or not (FALSE). - @param Position On entry, specifies the position in the boot script - table where the opcode will be inserted, either - before or after, depending on BeforeOrAfter. On exit, - specifies the positionof the inserted opcode in + @param Position On entry, specifies the position in the boot script + table where the opcode will be inserted, either + before or after, depending on BeforeOrAfter. On exit, + specifies the positionof the inserted opcode in the boot script table. - @param Label Points to the label which will be inserted in the + @param Label Points to the label which will be inserted in the boot script table. - @retval EFI_SUCCESS The operation succeeded. A record was added into + @retval EFI_SUCCESS The operation succeeded. A record was added into the specified script table. - @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script - is not supported. If the opcode is unknow or not + @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script + is not supported. If the opcode is unknow or not supported because of the PCD Feature Flags. @retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script. - @note The FRAMEWORK version implementation does not support this API + @note The FRAMEWORK version implementation does not support this API **/ RETURN_STATUS -EFIAPI +EFIAPI S3BootScriptLabel ( IN BOOLEAN BeforeOrAfter, IN BOOLEAN CreateIfNotFound, @@ -585,14 +578,14 @@ S3BootScriptLabel ( @retval EFI_SUCCESS The operation succeeded. A record was added into the specified script table. - @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script + @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script is not supported. If the opcode is unknow or not s upported because of the PCD Feature Flags. @retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script. - @note The FRAMEWORK version implementation does not support this API + @note The FRAMEWORK version implementation does not support this API **/ RETURN_STATUS -EFIAPI +EFIAPI S3BootScriptCompare ( IN UINT8 *Position1, IN UINT8 *Position2, diff --git a/MdePkg/Include/Library/S3IoLib.h b/MdePkg/Include/Library/S3IoLib.h index 5905eaf7191d..f276050d09b8 100644 --- a/MdePkg/Include/Library/S3IoLib.h +++ b/MdePkg/Include/Library/S3IoLib.h @@ -1,18 +1,11 @@ /** @file I/O and MMIO Library Services that do I/O and also enable the I/O operation to be replayed during an S3 resume. This library class maps directly on top - of the IoLib class. + of the IoLib class. - Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> - 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. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -117,7 +110,7 @@ S3IoAnd8 ( /** Reads an 8-bit I/O port, performs a bitwise AND followed by a bitwise - inclusive OR, writes the result back to the 8-bit I/O port, and saves + inclusive OR, writes the result back to the 8-bit I/O port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 8-bit I/O port specified by Port, performs a bitwise AND between @@ -179,7 +172,7 @@ S3IoBitFieldRead8 ( Writes Value to the bit field of the I/O register. The bit field is specified by the StartBit and the EndBit. All other bits in the destination I/O - register are preserved. The value written to the I/O port is returned. + register are preserved. The value written to the I/O port is returned. Remaining bits in Value are stripped. If 8-bit I/O port operations are not supported, then ASSERT(). @@ -209,7 +202,7 @@ S3IoBitFieldWrite8 ( /** Reads a bit field in an 8-bit port, performs a bitwise OR, writes the - result back to the bit field in the 8-bit port, and saves the value in the + result back to the bit field in the 8-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 8-bit I/O port specified by Port, performs a bitwise OR @@ -245,7 +238,7 @@ S3IoBitFieldOr8 ( /** Reads a bit field in an 8-bit port, performs a bitwise AND, writes the - result back to the bit field in the 8-bit port, and saves the value in the + result back to the bit field in the 8-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 8-bit I/O port specified by Port, performs a bitwise AND between @@ -365,7 +358,7 @@ S3IoWrite16 ( /** Reads a 16-bit I/O port, performs a bitwise OR, writes the - result back to the 16-bit I/O port, and saves the value in the S3 script to + result back to the 16-bit I/O port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 16-bit I/O port specified by Port, performs a bitwise OR @@ -474,7 +467,7 @@ S3IoBitFieldRead16 ( ); /** - Writes a bit field to an I/O register, and saves the value in the S3 script + Writes a bit field to an I/O register, and saves the value in the S3 script to be replayed on S3 resume. Writes Value to the bit field of the I/O register. The bit field is specified @@ -509,7 +502,7 @@ S3IoBitFieldWrite16 ( /** Reads a bit field in a 16-bit port, performs a bitwise OR, writes the - result back to the bit field in the 16-bit port, and saves the value in the + result back to the bit field in the 16-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 16-bit I/O port specified by Port, performs a bitwise OR @@ -545,7 +538,7 @@ S3IoBitFieldOr16 ( /** Reads a bit field in a 16-bit port, performs a bitwise AND, writes the - result back to the bit field in the 16-bit port, and saves the value in the + result back to the bit field in the 16-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 16-bit I/O port specified by Port, performs a bitwise AND between @@ -582,7 +575,7 @@ S3IoBitFieldAnd16 ( /** Reads a bit field in a 16-bit port, performs a bitwise AND followed by a bitwise OR, writes the result back to the bit field in the - 16-bit port, and saves the value in the S3 script to be replayed on S3 + 16-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 16-bit I/O port specified by Port, performs a bitwise AND followed @@ -666,7 +659,7 @@ S3IoWrite32 ( /** Reads a 32-bit I/O port, performs a bitwise OR, writes the - result back to the 32-bit I/O port, and saves the value in the S3 script to + result back to the 32-bit I/O port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit I/O port specified by Port, performs a bitwise OR @@ -718,7 +711,7 @@ S3IoAnd32 ( /** Reads a 32-bit I/O port, performs a bitwise AND followed by a bitwise - inclusive OR, writes the result back to the 32-bit I/O port, and saves + inclusive OR, writes the result back to the 32-bit I/O port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit I/O port specified by Port, performs a bitwise AND between @@ -810,7 +803,7 @@ S3IoBitFieldWrite32 ( /** Reads a bit field in a 32-bit port, performs a bitwise OR, writes the - result back to the bit field in the 32-bit port, and saves the value in the + result back to the bit field in the 32-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit I/O port specified by Port, performs a bitwise OR @@ -846,7 +839,7 @@ S3IoBitFieldOr32 ( /** Reads a bit field in a 32-bit port, performs a bitwise AND, writes the - result back to the bit field in the 32-bit port, and saves the value in the + result back to the bit field in the 32-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit I/O port specified by Port, performs a bitwise AND between @@ -883,7 +876,7 @@ S3IoBitFieldAnd32 ( /** Reads a bit field in a 32-bit port, performs a bitwise AND followed by a bitwise OR, writes the result back to the bit field in the - 32-bit port, and saves the value in the S3 script to be replayed on S3 + 32-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit I/O port specified by Port, performs a bitwise AND followed @@ -967,7 +960,7 @@ S3IoWrite64 ( /** Reads a 64-bit I/O port, performs a bitwise OR, writes the - result back to the 64-bit I/O port, and saves the value in the S3 script to + result back to the 64-bit I/O port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 64-bit I/O port specified by Port, performs a bitwise OR @@ -1111,7 +1104,7 @@ S3IoBitFieldWrite64 ( /** Reads a bit field in a 64-bit port, performs a bitwise OR, writes the - result back to the bit field in the 64-bit port, and saves the value in the + result back to the bit field in the 64-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 64-bit I/O port specified by Port, performs a bitwise OR @@ -1147,7 +1140,7 @@ S3IoBitFieldOr64 ( /** Reads a bit field in a 64-bit port, performs a bitwise AND, writes the - result back to the bit field in the 64-bit port, and saves the value in the + result back to the bit field in the 64-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 64-bit I/O port specified by Port, performs a bitwise AND between @@ -1184,7 +1177,7 @@ S3IoBitFieldAnd64 ( /** Reads a bit field in a 64-bit port, performs a bitwise AND followed by a bitwise OR, writes the result back to the bit field in the - 64-bit port, and saves the value in the S3 script to be replayed on S3 + 64-bit port, and saves the value in the S3 script to be replayed on S3 resume. Reads the 64-bit I/O port specified by Port, performs a bitwise AND followed @@ -1223,7 +1216,7 @@ S3IoBitFieldAndThenOr64 ( ); /** - Reads an 8-bit MMIO register, and saves the value in the S3 script to be + Reads an 8-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 8-bit MMIO register specified by Address. The 8-bit read value is @@ -1244,7 +1237,7 @@ S3MmioRead8 ( ); /** - Writes an 8-bit MMIO register, and saves the value in the S3 script to be + Writes an 8-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Writes the 8-bit MMIO register specified by Address with the value specified @@ -1268,7 +1261,7 @@ S3MmioWrite8 ( /** Reads an 8-bit MMIO register, performs a bitwise OR, writes the - result back to the 8-bit MMIO register, and saves the value in the S3 script + result back to the 8-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 8-bit MMIO register specified by Address, performs a bitwise @@ -1294,7 +1287,7 @@ S3MmioOr8 ( /** Reads an 8-bit MMIO register, performs a bitwise AND, writes the result - back to the 8-bit MMIO register, and saves the value in the S3 script to be + back to the 8-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 8-bit MMIO register specified by Address, performs a bitwise AND @@ -1320,7 +1313,7 @@ S3MmioAnd8 ( /** Reads an 8-bit MMIO register, performs a bitwise AND followed by a bitwise - inclusive OR, writes the result back to the 8-bit MMIO register, and saves + inclusive OR, writes the result back to the 8-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 8-bit MMIO register specified by Address, performs a bitwise AND @@ -1410,7 +1403,7 @@ S3MmioBitFieldWrite8 ( ); /** - Reads a bit field in an 8-bit MMIO register, performs a bitwise OR, + Reads a bit field in an 8-bit MMIO register, performs a bitwise OR, writes the result back to the bit field in the 8-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. @@ -1571,7 +1564,7 @@ S3MmioWrite16 ( /** Reads a 16-bit MMIO register, performs a bitwise OR, writes the - result back to the 16-bit MMIO register, and saves the value in the S3 script + result back to the 16-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 16-bit MMIO register specified by Address, performs a bitwise @@ -1597,7 +1590,7 @@ S3MmioOr16 ( /** Reads a 16-bit MMIO register, performs a bitwise AND, writes the result - back to the 16-bit MMIO register, and saves the value in the S3 script to be + back to the 16-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 16-bit MMIO register specified by Address, performs a bitwise AND @@ -1623,7 +1616,7 @@ S3MmioAnd16 ( /** Reads a 16-bit MMIO register, performs a bitwise AND followed by a bitwise - inclusive OR, writes the result back to the 16-bit MMIO register, and + inclusive OR, writes the result back to the 16-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 16-bit MMIO register specified by Address, performs a bitwise AND @@ -1713,8 +1706,8 @@ S3MmioBitFieldWrite16 ( ); /** - Reads a bit field in a 16-bit MMIO register, performs a bitwise OR, - writes the result back to the bit field in the 16-bit MMIO register, and + Reads a bit field in a 16-bit MMIO register, performs a bitwise OR, + writes the result back to the bit field in the 16-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 16-bit MMIO register specified by Address, performs a bitwise @@ -1751,7 +1744,7 @@ S3MmioBitFieldOr16 ( /** Reads a bit field in a 16-bit MMIO register, performs a bitwise AND, and - writes the result back to the bit field in the 16-bit MMIO register and + writes the result back to the bit field in the 16-bit MMIO register and saves the value in the S3 script to be replayed on S3 resume. Reads the 16-bit MMIO register specified by Address, performs a bitwise AND @@ -1828,7 +1821,7 @@ S3MmioBitFieldAndThenOr16 ( ); /** - Reads a 32-bit MMIO register saves the value in the S3 script to be + Reads a 32-bit MMIO register saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit MMIO register specified by Address. The 32-bit read value is @@ -1849,7 +1842,7 @@ S3MmioRead32 ( ); /** - Writes a 32-bit MMIO register, and saves the value in the S3 script to be + Writes a 32-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Writes the 32-bit MMIO register specified by Address with the value specified @@ -1873,7 +1866,7 @@ S3MmioWrite32 ( /** Reads a 32-bit MMIO register, performs a bitwise OR, writes the - result back to the 32-bit MMIO register, and saves the value in the S3 script + result back to the 32-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit MMIO register specified by Address, performs a bitwise @@ -1899,7 +1892,7 @@ S3MmioOr32 ( /** Reads a 32-bit MMIO register, performs a bitwise AND, writes the result - back to the 32-bit MMIO register, and saves the value in the S3 script to be + back to the 32-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit MMIO register specified by Address, performs a bitwise AND @@ -1925,7 +1918,7 @@ S3MmioAnd32 ( /** Reads a 32-bit MMIO register, performs a bitwise AND followed by a bitwise - inclusive OR, writes the result back to the 32-bit MMIO register, and + inclusive OR, writes the result back to the 32-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit MMIO register specified by Address, performs a bitwise AND @@ -1953,7 +1946,7 @@ S3MmioAndThenOr32 ( ); /** - Reads a bit field of a MMIO register, and saves the value in the S3 script + Reads a bit field of a MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the bit field in a 32-bit MMIO register. The bit field is specified by @@ -1982,7 +1975,7 @@ S3MmioBitFieldRead32 ( ); /** - Writes a bit field to a MMIO register, and saves the value in the S3 script + Writes a bit field to a MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Writes Value to the bit field of the MMIO register. The bit field is @@ -2015,8 +2008,8 @@ S3MmioBitFieldWrite32 ( ); /** - Reads a bit field in a 32-bit MMIO register, performs a bitwise OR, - writes the result back to the bit field in the 32-bit MMIO register, and + Reads a bit field in a 32-bit MMIO register, performs a bitwise OR, + writes the result back to the bit field in the 32-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit MMIO register specified by Address, performs a bitwise @@ -2053,7 +2046,7 @@ S3MmioBitFieldOr32 ( /** Reads a bit field in a 32-bit MMIO register, performs a bitwise AND, and - writes the result back to the bit field in the 32-bit MMIO register and + writes the result back to the bit field in the 32-bit MMIO register and saves the value in the S3 script to be replayed on S3 resume. Reads the 32-bit MMIO register specified by Address, performs a bitwise AND @@ -2130,7 +2123,7 @@ S3MmioBitFieldAndThenOr32 ( ); /** - Reads a 64-bit MMIO register, and saves the value in the S3 script to be + Reads a 64-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 64-bit MMIO register specified by Address. The 64-bit read value is @@ -2151,7 +2144,7 @@ S3MmioRead64 ( ); /** - Writes a 64-bit MMIO register, and saves the value in the S3 script to be + Writes a 64-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Writes the 64-bit MMIO register specified by Address with the value specified @@ -2175,7 +2168,7 @@ S3MmioWrite64 ( /** Reads a 64-bit MMIO register, performs a bitwise OR, writes the - result back to the 64-bit MMIO register, and saves the value in the S3 script + result back to the 64-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 64-bit MMIO register specified by Address, performs a bitwise @@ -2201,7 +2194,7 @@ S3MmioOr64 ( /** Reads a 64-bit MMIO register, performs a bitwise AND, writes the result - back to the 64-bit MMIO register, and saves the value in the S3 script to be + back to the 64-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 64-bit MMIO register specified by Address, performs a bitwise AND @@ -2227,7 +2220,7 @@ S3MmioAnd64 ( /** Reads a 64-bit MMIO register, performs a bitwise AND followed by a bitwise - inclusive OR, writes the result back to the 64-bit MMIO register, and + inclusive OR, writes the result back to the 64-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 64-bit MMIO register specified by Address, performs a bitwise AND @@ -2317,8 +2310,8 @@ S3MmioBitFieldWrite64 ( ); /** - Reads a bit field in a 64-bit MMIO register, performs a bitwise OR, - writes the result back to the bit field in the 64-bit MMIO register, and + Reads a bit field in a 64-bit MMIO register, performs a bitwise OR, + writes the result back to the bit field in the 64-bit MMIO register, and saves the value in the S3 script to be replayed on S3 resume. Reads the 64-bit MMIO register specified by Address, performs a bitwise @@ -2435,11 +2428,11 @@ S3MmioBitFieldAndThenOr64 ( Copies data from MMIO region to system memory by using 8-bit access, and saves the value in the S3 script to be replayed on S3 resume. - Copy data from MMIO region specified by starting address StartAddress - to system memory specified by Buffer by using 8-bit access. The total + Copy data from MMIO region specified by starting address StartAddress + to system memory specified by Buffer by using 8-bit access. The total number of bytes to be copied is specified by Length. Buffer is returned. - - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). @@ -2462,13 +2455,13 @@ S3MmioReadBuffer8 ( Copies data from MMIO region to system memory by using 16-bit access, and saves the value in the S3 script to be replayed on S3 resume. - Copy data from MMIO region specified by starting address StartAddress - to system memory specified by Buffer by using 16-bit access. The total + Copy data from MMIO region specified by starting address StartAddress + to system memory specified by Buffer by using 16-bit access. The total number of bytes to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 16-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). If Length is not aligned on a 16-bit boundary, then ASSERT(). @@ -2493,13 +2486,13 @@ S3MmioReadBuffer16 ( Copies data from MMIO region to system memory by using 32-bit access, and saves the value in the S3 script to be replayed on S3 resume. - Copy data from MMIO region specified by starting address StartAddress - to system memory specified by Buffer by using 32-bit access. The total + Copy data from MMIO region specified by starting address StartAddress + to system memory specified by Buffer by using 32-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 32-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). If Length is not aligned on a 32-bit boundary, then ASSERT(). @@ -2524,13 +2517,13 @@ S3MmioReadBuffer32 ( Copies data from MMIO region to system memory by using 64-bit access, and saves the value in the S3 script to be replayed on S3 resume. - Copy data from MMIO region specified by starting address StartAddress - to system memory specified by Buffer by using 64-bit access. The total + Copy data from MMIO region specified by starting address StartAddress + to system memory specified by Buffer by using 64-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 64-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). If Length is not aligned on a 64-bit boundary, then ASSERT(). @@ -2555,11 +2548,11 @@ S3MmioReadBuffer64 ( Copies data from system memory to MMIO region by using 8-bit access, and saves the value in the S3 script to be replayed on S3 resume. - Copy data from system memory specified by Buffer to MMIO region specified - by starting address StartAddress by using 8-bit access. The total number + Copy data from system memory specified by Buffer to MMIO region specified + by starting address StartAddress by using 8-bit access. The total number of byte to be copied is specified by Length. Buffer is returned. - - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). @@ -2582,13 +2575,13 @@ S3MmioWriteBuffer8 ( Copies data from system memory to MMIO region by using 16-bit access, and saves the value in the S3 script to be replayed on S3 resume. - Copy data from system memory specified by Buffer to MMIO region specified - by starting address StartAddress by using 16-bit access. The total number + Copy data from system memory specified by Buffer to MMIO region specified + by starting address StartAddress by using 16-bit access. The total number of bytes to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 16-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). If Length is not aligned on a 16-bit boundary, then ASSERT(). @@ -2614,13 +2607,13 @@ S3MmioWriteBuffer16 ( Copies data from system memory to MMIO region by using 32-bit access, and saves the value in the S3 script to be replayed on S3 resume. - Copy data from system memory specified by Buffer to MMIO region specified - by starting address StartAddress by using 32-bit access. The total number + Copy data from system memory specified by Buffer to MMIO region specified + by starting address StartAddress by using 32-bit access. The total number of bytes to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 32-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). If Length is not aligned on a 32-bit boundary, then ASSERT(). @@ -2643,16 +2636,16 @@ S3MmioWriteBuffer32 ( ); /** - Copies data from system memory to MMIO region by using 64-bit access, + Copies data from system memory to MMIO region by using 64-bit access, and saves the value in the S3 script to be replayed on S3 resume. - Copy data from system memory specified by Buffer to MMIO region specified - by starting address StartAddress by using 64-bit access. The total number + Copy data from system memory specified by Buffer to MMIO region specified + by starting address StartAddress by using 64-bit access. The total number of bytes to be copied is specified by Length. Buffer is returned. - + If StartAddress is not aligned on a 64-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - StartAddress + 1), then ASSERT(). If Length is greater than (MAX_ADDRESS -Buffer + 1), then ASSERT(). If Length is not aligned on a 64-bit boundary, then ASSERT(). diff --git a/MdePkg/Include/Library/S3PciLib.h b/MdePkg/Include/Library/S3PciLib.h index 3d8f497f9930..2d9ddc317c4c 100644 --- a/MdePkg/Include/Library/S3PciLib.h +++ b/MdePkg/Include/Library/S3PciLib.h @@ -1,18 +1,11 @@ /** @file The PCI configuration Library Services that carry out PCI configuration and enable the PCI operations to be replayed during an S3 resume. This library class - maps directly on top of the PciLib class. + maps directly on top of the PciLib class. - Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR> + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> - 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. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -36,8 +29,8 @@ (((Register) & 0xfff) | (((Function) & 0x07) << 12) | (((Device) & 0x1f) << 15) | (((Bus) & 0xff) << 20)) /** - - Reads and returns the 8-bit PCI configuration register specified by Address, + + Reads and returns the 8-bit PCI configuration register specified by Address, and saves the value in the S3 script to be replayed on S3 resume. This function must guarantee that all PCI read and write operations are serialized. @@ -813,7 +806,7 @@ S3PciAndThenOr32 ( If StartBit is greater than 31, then ASSERT(). If EndBit is greater than 31, then ASSERT(). If EndBit is less than StartBit, then ASSERT(). - + @param[in] Address The PCI configuration register to read. @param[in] StartBit The ordinal of the least significant bit in the bit field. Range 0..31. diff --git a/MdePkg/Include/Library/S3PciSegmentLib.h b/MdePkg/Include/Library/S3PciSegmentLib.h new file mode 100644 index 000000000000..5e8d70b4b05b --- /dev/null +++ b/MdePkg/Include/Library/S3PciSegmentLib.h @@ -0,0 +1,1031 @@ +/** @file + The multiple segments PCI configuration Library Services that carry out + PCI configuration and enable the PCI operations to be replayed during an + S3 resume. This library class maps directly on top of the PciSegmentLib class. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __S3_PCI_SEGMENT_LIB__ +#define __S3_PCI_SEGMENT_LIB__ + + +/** + Macro that converts PCI Segment, PCI Bus, PCI Device, PCI Function, + and PCI Register to an address that can be passed to the S3 PCI Segment Library functions. + + Computes an address that is compatible with the PCI Segment Library functions. + The unused upper bits of Segment, Bus, Device, Function, + and Register are stripped prior to the generation of the address. + + @param Segment PCI Segment number. Range 0..65535. + @param Bus PCI Bus number. Range 0..255. + @param Device PCI Device number. Range 0..31. + @param Function PCI Function number. Range 0..7. + @param Register PCI Register number. Range 0..255 for PCI. Range 0..4095 for PCI Express. + + @return The address that is compatible with the PCI Segment Library functions. + +**/ +#define S3_PCI_SEGMENT_LIB_ADDRESS(Segment,Bus,Device,Function,Register) \ + ((Segment != 0) ? \ + ( ((Register) & 0xfff) | \ + (((Function) & 0x07) << 12) | \ + (((Device) & 0x1f) << 15) | \ + (((Bus) & 0xff) << 20) | \ + (LShiftU64 ((Segment) & 0xffff, 32)) \ + ) : \ + ( ((Register) & 0xfff) | \ + (((Function) & 0x07) << 12) | \ + (((Device) & 0x1f) << 15) | \ + (((Bus) & 0xff) << 20) \ + ) \ + ) + +/** + Reads an 8-bit PCI configuration register, and saves the value in the S3 script to + be replayed on S3 resume. + + Reads and returns the 8-bit PCI configuration register specified by Address. + This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + + @return The 8-bit PCI configuration register specified by Address. + +**/ +UINT8 +EFIAPI +S3PciSegmentRead8 ( + IN UINT64 Address + ); + +/** + Writes an 8-bit PCI configuration register, and saves the value in the S3 script to + be replayed on S3 resume. + + Writes the 8-bit PCI configuration register specified by Address with the value specified by Value. + Value is returned. This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param Value The value to write. + + @return The value written to the PCI configuration register. + +**/ +UINT8 +EFIAPI +S3PciSegmentWrite8 ( + IN UINT64 Address, + IN UINT8 Value + ); + +/** + Performs a bitwise OR of an 8-bit PCI configuration register with an 8-bit value, and saves + the value in the S3 script to be replayed on S3 resume. + + Reads the 8-bit PCI configuration register specified by Address, + performs a bitwise OR between the read result and the value specified by OrData, + and writes the result to the 8-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param OrData The value to OR with the PCI configuration register. + + @return The value written to the PCI configuration register. + +**/ +UINT8 +EFIAPI +S3PciSegmentOr8 ( + IN UINT64 Address, + IN UINT8 OrData + ); + +/** + Performs a bitwise AND of an 8-bit PCI configuration register with an 8-bit value, and + saves the value in the S3 script to be replayed on S3 resume. + + Reads the 8-bit PCI configuration register specified by Address, + performs a bitwise AND between the read result and the value specified by AndData, + and writes the result to the 8-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are serialized. + If any reserved bits in Address are set, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param AndData The value to AND with the PCI configuration register. + + @return The value written to the PCI configuration register. + +**/ +UINT8 +EFIAPI +S3PciSegmentAnd8 ( + IN UINT64 Address, + IN UINT8 AndData + ); + +/** + Performs a bitwise AND of an 8-bit PCI configuration register with an 8-bit value, + followed a bitwise OR with another 8-bit value, and saves the value in the S3 script to + be replayed on S3 resume. + + Reads the 8-bit PCI configuration register specified by Address, + performs a bitwise AND between the read result and the value specified by AndData, + performs a bitwise OR between the result of the AND operation and the value specified by OrData, + and writes the result to the 8-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param AndData The value to AND with the PCI configuration register. + @param OrData The value to OR with the PCI configuration register. + + @return The value written to the PCI configuration register. + +**/ +UINT8 +EFIAPI +S3PciSegmentAndThenOr8 ( + IN UINT64 Address, + IN UINT8 AndData, + IN UINT8 OrData + ); + +/** + Reads a bit field of a PCI configuration register, and saves the value in the + S3 script to be replayed on S3 resume. + + Reads the bit field in an 8-bit PCI configuration register. The bit field is + specified by the StartBit and the EndBit. The value of the bit field is + returned. + + If any reserved bits in Address are set, then ASSERT(). + If StartBit is greater than 7, then ASSERT(). + If EndBit is greater than 7, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + + @param Address PCI configuration register to read. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..7. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..7. + + @return The value of the bit field read from the PCI configuration register. + +**/ +UINT8 +EFIAPI +S3PciSegmentBitFieldRead8 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit + ); + +/** + Writes a bit field to a PCI configuration register, and saves the value in + the S3 script to be replayed on S3 resume. + + Writes Value to the bit field of the PCI configuration register. The bit + field is specified by the StartBit and the EndBit. All other bits in the + destination PCI configuration register are preserved. The new value of the + 8-bit register is returned. + + If any reserved bits in Address are set, then ASSERT(). + If StartBit is greater than 7, then ASSERT(). + If EndBit is greater than 7, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..7. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..7. + @param Value New value of the bit field. + + @return The value written back to the PCI configuration register. + +**/ +UINT8 +EFIAPI +S3PciSegmentBitFieldWrite8 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT8 Value + ); + +/** + Reads a bit field in an 8-bit PCI configuration, performs a bitwise OR, writes + the result back to the bit field in the 8-bit port, and saves the value in the + S3 script to be replayed on S3 resume. + + Reads the 8-bit PCI configuration register specified by Address, performs a + bitwise OR between the read result and the value specified by + OrData, and writes the result to the 8-bit PCI configuration register + specified by Address. The value written to the PCI configuration register is + returned. This function must guarantee that all PCI read and write operations + are serialized. Extra left bits in OrData are stripped. + + If any reserved bits in Address are set, then ASSERT(). + If StartBit is greater than 7, then ASSERT(). + If EndBit is greater than 7, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..7. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..7. + @param OrData The value to OR with the PCI configuration register. + + @return The value written back to the PCI configuration register. + +**/ +UINT8 +EFIAPI +S3PciSegmentBitFieldOr8 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT8 OrData + ); + +/** + Reads a bit field in an 8-bit PCI configuration register, performs a bitwise + AND, writes the result back to the bit field in the 8-bit register, and + saves the value in the S3 script to be replayed on S3 resume. + + Reads the 8-bit PCI configuration register specified by Address, performs a + bitwise AND between the read result and the value specified by AndData, and + writes the result to the 8-bit PCI configuration register specified by + Address. The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are + serialized. Extra left bits in AndData are stripped. + + If any reserved bits in Address are set, then ASSERT(). + If StartBit is greater than 7, then ASSERT(). + If EndBit is greater than 7, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..7. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..7. + @param AndData The value to AND with the PCI configuration register. + + @return The value written back to the PCI configuration register. + +**/ +UINT8 +EFIAPI +S3PciSegmentBitFieldAnd8 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT8 AndData + ); + +/** + Reads a bit field in an 8-bit port, performs a bitwise AND followed by a + bitwise OR, writes the result back to the bit field in the 8-bit port, + and saves the value in the S3 script to be replayed on S3 resume. + + Reads the 8-bit PCI configuration register specified by Address, performs a + bitwise AND followed by a bitwise OR between the read result and + the value specified by AndData, and writes the result to the 8-bit PCI + configuration register specified by Address. The value written to the PCI + configuration register is returned. This function must guarantee that all PCI + read and write operations are serialized. Extra left bits in both AndData and + OrData are stripped. + + If any reserved bits in Address are set, then ASSERT(). + If StartBit is greater than 7, then ASSERT(). + If EndBit is greater than 7, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..7. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..7. + @param AndData The value to AND with the PCI configuration register. + @param OrData The value to OR with the result of the AND operation. + + @return The value written back to the PCI configuration register. + +**/ +UINT8 +EFIAPI +S3PciSegmentBitFieldAndThenOr8 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT8 AndData, + IN UINT8 OrData + ); + +/** + Reads a 16-bit PCI configuration register, and saves the value in the S3 script + to be replayed on S3 resume. + + Reads and returns the 16-bit PCI configuration register specified by Address. + This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 16-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + + @return The 16-bit PCI configuration register specified by Address. + +**/ +UINT16 +EFIAPI +S3PciSegmentRead16 ( + IN UINT64 Address + ); + +/** + Writes a 16-bit PCI configuration register, and saves the value in the S3 script to + be replayed on S3 resume. + + Writes the 16-bit PCI configuration register specified by Address with the value specified by Value. + Value is returned. This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 16-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param Value The value to write. + + @return The parameter of Value. + +**/ +UINT16 +EFIAPI +S3PciSegmentWrite16 ( + IN UINT64 Address, + IN UINT16 Value + ); + +/** + Performs a bitwise OR of a 16-bit PCI configuration register with a 16-bit + value, and saves the value in the S3 script to be replayed on S3 resume. + + Reads the 16-bit PCI configuration register specified by Address, performs a + bitwise OR between the read result and the value specified by OrData, and + writes the result to the 16-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. This function + must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 16-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function and + Register. + @param OrData The value to OR with the PCI configuration register. + + @return The value written back to the PCI configuration register. + +**/ +UINT16 +EFIAPI +S3PciSegmentOr16 ( + IN UINT64 Address, + IN UINT16 OrData + ); + +/** + Performs a bitwise AND of a 16-bit PCI configuration register with a 16-bit value, and + saves the value in the S3 script to be replayed on S3 resume. + + Reads the 16-bit PCI configuration register specified by Address, + performs a bitwise AND between the read result and the value specified by AndData, + and writes the result to the 16-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 16-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param AndData The value to AND with the PCI configuration register. + + @return The value written to the PCI configuration register. + +**/ +UINT16 +EFIAPI +S3PciSegmentAnd16 ( + IN UINT64 Address, + IN UINT16 AndData + ); + +/** + Performs a bitwise AND of a 16-bit PCI configuration register with a 16-bit value, + followed a bitwise OR with another 16-bit value, and saves the value in the S3 script to + be replayed on S3 resume. + + Reads the 16-bit PCI configuration register specified by Address, + performs a bitwise AND between the read result and the value specified by AndData, + performs a bitwise OR between the result of the AND operation and the value specified by OrData, + and writes the result to the 16-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 16-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param AndData The value to AND with the PCI configuration register. + @param OrData The value to OR with the PCI configuration register. + + @return The value written to the PCI configuration register. + +**/ +UINT16 +EFIAPI +S3PciSegmentAndThenOr16 ( + IN UINT64 Address, + IN UINT16 AndData, + IN UINT16 OrData + ); + +/** + Reads a bit field of a PCI configuration register, and saves the value in the + S3 script to be replayed on S3 resume. + + Reads the bit field in a 16-bit PCI configuration register. The bit field is + specified by the StartBit and the EndBit. The value of the bit field is + returned. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 16-bit boundary, then ASSERT(). + If StartBit is greater than 15, then ASSERT(). + If EndBit is greater than 15, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + + @param Address PCI configuration register to read. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..15. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..15. + + @return The value of the bit field read from the PCI configuration register. + +**/ +UINT16 +EFIAPI +S3PciSegmentBitFieldRead16 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit + ); + +/** + Writes a bit field to a PCI configuration register, and saves the value in + the S3 script to be replayed on S3 resume. + + Writes Value to the bit field of the PCI configuration register. The bit + field is specified by the StartBit and the EndBit. All other bits in the + destination PCI configuration register are preserved. The new value of the + 16-bit register is returned. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 16-bit boundary, then ASSERT(). + If StartBit is greater than 15, then ASSERT(). + If EndBit is greater than 15, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..15. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..15. + @param Value New value of the bit field. + + @return The value written back to the PCI configuration register. + +**/ +UINT16 +EFIAPI +S3PciSegmentBitFieldWrite16 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT16 Value + ); + +/** + Reads a bit field in a 16-bit PCI configuration, performs a bitwise OR, writes + the result back to the bit field in the 16-bit port, and saves the value in the + S3 script to be replayed on S3 resume. + + Reads the 16-bit PCI configuration register specified by Address, performs a + bitwise OR between the read result and the value specified by + OrData, and writes the result to the 16-bit PCI configuration register + specified by Address. The value written to the PCI configuration register is + returned. This function must guarantee that all PCI read and write operations + are serialized. Extra left bits in OrData are stripped. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 16-bit boundary, then ASSERT(). + If StartBit is greater than 15, then ASSERT(). + If EndBit is greater than 15, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..15. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..15. + @param OrData The value to OR with the PCI configuration register. + + @return The value written back to the PCI configuration register. + +**/ +UINT16 +EFIAPI +S3PciSegmentBitFieldOr16 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT16 OrData + ); + +/** + Reads a bit field in a 16-bit PCI configuration register, performs a bitwise + AND, writes the result back to the bit field in the 16-bit register, and + saves the value in the S3 script to be replayed on S3 resume. + + Reads the 16-bit PCI configuration register specified by Address, performs a + bitwise AND between the read result and the value specified by AndData, and + writes the result to the 16-bit PCI configuration register specified by + Address. The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are + serialized. Extra left bits in AndData are stripped. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 16-bit boundary, then ASSERT(). + If StartBit is greater than 15, then ASSERT(). + If EndBit is greater than 15, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..15. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..15. + @param AndData The value to AND with the PCI configuration register. + + @return The value written back to the PCI configuration register. + +**/ +UINT16 +EFIAPI +S3PciSegmentBitFieldAnd16 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT16 AndData + ); + +/** + Reads a bit field in a 16-bit port, performs a bitwise AND followed by a + bitwise OR, writes the result back to the bit field in the 16-bit port, + and saves the value in the S3 script to be replayed on S3 resume. + + Reads the 16-bit PCI configuration register specified by Address, performs a + bitwise AND followed by a bitwise OR between the read result and + the value specified by AndData, and writes the result to the 16-bit PCI + configuration register specified by Address. The value written to the PCI + configuration register is returned. This function must guarantee that all PCI + read and write operations are serialized. Extra left bits in both AndData and + OrData are stripped. + + If any reserved bits in Address are set, then ASSERT(). + If StartBit is greater than 15, then ASSERT(). + If EndBit is greater than 15, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..15. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..15. + @param AndData The value to AND with the PCI configuration register. + @param OrData The value to OR with the result of the AND operation. + + @return The value written back to the PCI configuration register. + +**/ +UINT16 +EFIAPI +S3PciSegmentBitFieldAndThenOr16 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT16 AndData, + IN UINT16 OrData + ); + +/** + Reads a 32-bit PCI configuration register, and saves the value in the S3 script + to be replayed on S3 resume. + + Reads and returns the 32-bit PCI configuration register specified by Address. + This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 32-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + + @return The 32-bit PCI configuration register specified by Address. + +**/ +UINT32 +EFIAPI +S3PciSegmentRead32 ( + IN UINT64 Address + ); + +/** + Writes a 32-bit PCI configuration register, and saves the value in the S3 script to + be replayed on S3 resume. + + Writes the 32-bit PCI configuration register specified by Address with the value specified by Value. + Value is returned. This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 32-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param Value The value to write. + + @return The parameter of Value. + +**/ +UINT32 +EFIAPI +S3PciSegmentWrite32 ( + IN UINT64 Address, + IN UINT32 Value + ); + +/** + Performs a bitwise OR of a 32-bit PCI configuration register with a 32-bit + value, and saves the value in the S3 script to be replayed on S3 resume. + + Reads the 32-bit PCI configuration register specified by Address, performs a + bitwise OR between the read result and the value specified by OrData, and + writes the result to the 32-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. This function + must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 32-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and + Register. + @param OrData The value to OR with the PCI configuration register. + + @return The value written back to the PCI configuration register. + +**/ +UINT32 +EFIAPI +S3PciSegmentOr32 ( + IN UINT64 Address, + IN UINT32 OrData + ); + +/** + Performs a bitwise AND of a 32-bit PCI configuration register with a 32-bit value, and + saves the value in the S3 script to be replayed on S3 resume. + + Reads the 32-bit PCI configuration register specified by Address, + performs a bitwise AND between the read result and the value specified by AndData, + and writes the result to the 32-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 32-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param AndData The value to AND with the PCI configuration register. + + @return The value written to the PCI configuration register. + +**/ +UINT32 +EFIAPI +S3PciSegmentAnd32 ( + IN UINT64 Address, + IN UINT32 AndData + ); + +/** + Performs a bitwise AND of a 32-bit PCI configuration register with a 32-bit value, + followed a bitwise OR with another 32-bit value, and saves the value in the S3 script to + be replayed on S3 resume. + + Reads the 32-bit PCI configuration register specified by Address, + performs a bitwise AND between the read result and the value specified by AndData, + performs a bitwise OR between the result of the AND operation and the value specified by OrData, + and writes the result to the 32-bit PCI configuration register specified by Address. + The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are serialized. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 32-bit boundary, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param AndData The value to AND with the PCI configuration register. + @param OrData The value to OR with the PCI configuration register. + + @return The value written to the PCI configuration register. + +**/ +UINT32 +EFIAPI +S3PciSegmentAndThenOr32 ( + IN UINT64 Address, + IN UINT32 AndData, + IN UINT32 OrData + ); + +/** + Reads a bit field of a PCI configuration register, and saves the value in the + S3 script to be replayed on S3 resume. + + Reads the bit field in a 32-bit PCI configuration register. The bit field is + specified by the StartBit and the EndBit. The value of the bit field is + returned. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 32-bit boundary, then ASSERT(). + If StartBit is greater than 31, then ASSERT(). + If EndBit is greater than 31, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + + @param Address PCI configuration register to read. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..31. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..31. + + @return The value of the bit field read from the PCI configuration register. + +**/ +UINT32 +EFIAPI +S3PciSegmentBitFieldRead32 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit + ); + +/** + Writes a bit field to a PCI configuration register, and saves the value in + the S3 script to be replayed on S3 resume. + + Writes Value to the bit field of the PCI configuration register. The bit + field is specified by the StartBit and the EndBit. All other bits in the + destination PCI configuration register are preserved. The new value of the + 32-bit register is returned. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 32-bit boundary, then ASSERT(). + If StartBit is greater than 31, then ASSERT(). + If EndBit is greater than 31, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..31. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..31. + @param Value New value of the bit field. + + @return The value written back to the PCI configuration register. + +**/ +UINT32 +EFIAPI +S3PciSegmentBitFieldWrite32 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT32 Value + ); + +/** + Reads a bit field in a 32-bit PCI configuration, performs a bitwise OR, writes + the result back to the bit field in the 32-bit port, and saves the value in the + S3 script to be replayed on S3 resume. + + Reads the 32-bit PCI configuration register specified by Address, performs a + bitwise OR between the read result and the value specified by + OrData, and writes the result to the 32-bit PCI configuration register + specified by Address. The value written to the PCI configuration register is + returned. This function must guarantee that all PCI read and write operations + are serialized. Extra left bits in OrData are stripped. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 32-bit boundary, then ASSERT(). + If StartBit is greater than 31, then ASSERT(). + If EndBit is greater than 31, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..31. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..31. + @param OrData The value to OR with the PCI configuration register. + + @return The value written back to the PCI configuration register. + +**/ +UINT32 +EFIAPI +S3PciSegmentBitFieldOr32 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT32 OrData + ); + +/** + Reads a bit field in a 32-bit PCI configuration register, performs a bitwise + AND, and writes the result back to the bit field in the 32-bit register, and + saves the value in the S3 script to be replayed on S3 resume. + + Reads the 32-bit PCI configuration register specified by Address, performs a + bitwise AND between the read result and the value specified by AndData, and + writes the result to the 32-bit PCI configuration register specified by + Address. The value written to the PCI configuration register is returned. + This function must guarantee that all PCI read and write operations are + serialized. Extra left bits in AndData are stripped. + + If any reserved bits in Address are set, then ASSERT(). + If Address is not aligned on a 32-bit boundary, then ASSERT(). + If StartBit is greater than 31, then ASSERT(). + If EndBit is greater than 31, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address Address that encodes the PCI Segment, Bus, Device, Function, and Register. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..31. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..31. + @param AndData The value to AND with the PCI configuration register. + + @return The value written back to the PCI configuration register. + +**/ +UINT32 +EFIAPI +S3PciSegmentBitFieldAnd32 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT32 AndData + ); + +/** + Reads a bit field in a 32-bit port, performs a bitwise AND followed by a + bitwise OR, writes the result back to the bit field in the 32-bit port, + and saves the value in the S3 script to be replayed on S3 resume. + + Reads the 32-bit PCI configuration register specified by Address, performs a + bitwise AND followed by a bitwise OR between the read result and + the value specified by AndData, and writes the result to the 32-bit PCI + configuration register specified by Address. The value written to the PCI + configuration register is returned. This function must guarantee that all PCI + read and write operations are serialized. Extra left bits in both AndData and + OrData are stripped. + + If any reserved bits in Address are set, then ASSERT(). + If StartBit is greater than 31, then ASSERT(). + If EndBit is greater than 31, then ASSERT(). + If EndBit is less than StartBit, then ASSERT(). + If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT(). + + @param Address PCI configuration register to write. + @param StartBit The ordinal of the least significant bit in the bit field. + Range 0..31. + @param EndBit The ordinal of the most significant bit in the bit field. + Range 0..31. + @param AndData The value to AND with the PCI configuration register. + @param OrData The value to OR with the result of the AND operation. + + @return The value written back to the PCI configuration register. + +**/ +UINT32 +EFIAPI +S3PciSegmentBitFieldAndThenOr32 ( + IN UINT64 Address, + IN UINTN StartBit, + IN UINTN EndBit, + IN UINT32 AndData, + IN UINT32 OrData + ); + +/** + Reads a range of PCI configuration registers into a caller supplied buffer, + and saves the value in the S3 script to be replayed on S3 resume. + + Reads the range of PCI configuration registers specified by StartAddress and + Size into the buffer specified by Buffer. This function only allows the PCI + configuration registers from a single PCI function to be read. Size is + returned. When possible 32-bit PCI configuration read cycles are used to read + from StartAdress to StartAddress + Size. Due to alignment restrictions, 8-bit + and 16-bit PCI configuration read cycles may be used at the beginning and the + end of the range. + + If any reserved bits in StartAddress are set, then ASSERT(). + If ((StartAddress & 0xFFF) + Size) > 0x1000, then ASSERT(). + If Size > 0 and Buffer is NULL, then ASSERT(). + + @param StartAddress Starting address that encodes the PCI Segment, Bus, Device, + Function and Register. + @param Size Size in bytes of the transfer. + @param Buffer Pointer to a buffer receiving the data read. + + @return Size + +**/ +UINTN +EFIAPI +S3PciSegmentReadBuffer ( + IN UINT64 StartAddress, + IN UINTN Size, + OUT VOID *Buffer + ); + +/** + Copies the data in a caller supplied buffer to a specified range of PCI + configuration space, and saves the value in the S3 script to be replayed on S3 + resume. + + Writes the range of PCI configuration registers specified by StartAddress and + Size from the buffer specified by Buffer. This function only allows the PCI + configuration registers from a single PCI function to be written. Size is + returned. When possible 32-bit PCI configuration write cycles are used to + write from StartAdress to StartAddress + Size. Due to alignment restrictions, + 8-bit and 16-bit PCI configuration write cycles may be used at the beginning + and the end of the range. + + If any reserved bits in StartAddress are set, then ASSERT(). + If ((StartAddress & 0xFFF) + Size) > 0x1000, then ASSERT(). + If Size > 0 and Buffer is NULL, then ASSERT(). + + @param StartAddress Starting address that encodes the PCI Segment, Bus, Device, + Function and Register. + @param Size Size in bytes of the transfer. + @param Buffer Pointer to a buffer containing the data to write. + + @return The parameter of Size. + +**/ +UINTN +EFIAPI +S3PciSegmentWriteBuffer ( + IN UINT64 StartAddress, + IN UINTN Size, + IN VOID *Buffer + ); + +#endif diff --git a/MdePkg/Include/Library/S3SmbusLib.h b/MdePkg/Include/Library/S3SmbusLib.h index 2f24378d2d58..471725641e41 100644 --- a/MdePkg/Include/Library/S3SmbusLib.h +++ b/MdePkg/Include/Library/S3SmbusLib.h @@ -3,16 +3,9 @@ to be replayed during an S3 resume. This library class maps directly on top of the SmbusLib class. - Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR> + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> - 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. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -35,13 +28,13 @@ SMBUS Command, SMBUS Data Length, and PEC. @param[out] Status The return status for the executed command. This is an optional parameter and may be NULL. - RETURN_SUCCESS The SMBUS command was executed. - RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. RETURN_DEVICE_ERROR The request was not completed because a failure was recorded in the Host Status Register bit. Device errors are a result of a transaction collision, illegal command field, unclaimed cycle (host initiated), or bus error (collision). - RETURN_UNSUPPORTED The SMBus operation is not supported. + RETURN_UNSUPPORTED The SMBus operation is not supported. **/ VOID @@ -67,13 +60,13 @@ S3SmBusQuickRead ( SMBUS Command, SMBUS Data Length, and PEC. @param[out] Status The return status for the executed command. This is an optional parameter and may be NULL. - RETURN_SUCCESS The SMBUS command was executed. - RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. RETURN_DEVICE_ERROR The request was not completed because a failure was recorded in the Host Status Register bit. Device errors are a result of a transaction collision, illegal command field, unclaimed cycle (host initiated), or bus error (collision). - RETURN_UNSUPPORTED The SMBus operation is not supported. + RETURN_UNSUPPORTED The SMBus operation is not supported. **/ VOID @@ -99,14 +92,14 @@ S3SmBusQuickWrite ( SMBUS Command, SMBUS Data Length, and PEC. @param[out] Status The return status for the executed command. This is an optional parameter and may be NULL. - RETURN_SUCCESS The SMBUS command was executed. - RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. + RETURN_SUCCESS The SMBUS command was executed. + RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. RETURN_DEVICE_ERROR The request was not completed because a failure was recorded in the Host Status Register bit. Device errors are a result of a transaction collision, illegal command field, unclaimed cycle (host initiated), or bus error (collision). RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). - RETURN_UNSUPPORTED The SMBus operation is not supported. + RETURN_UNSUPPORTED The SMBus operation is not supported. @return The byte received from the SMBUS. diff --git a/MdePkg/Include/Library/S3StallLib.h b/MdePkg/Include/Library/S3StallLib.h index e723d18bda01..aab86679dc8b 100644 --- a/MdePkg/Include/Library/S3StallLib.h +++ b/MdePkg/Include/Library/S3StallLib.h @@ -1,18 +1,11 @@ /** @file Stall Services that perform stalls and also enable the Stall operatation to be replayed during an S3 resume. This library class maps directly on top - of the Timer class. + of the Timer class. - Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR> + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> - 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. + SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/SafeIntLib.h b/MdePkg/Include/Library/SafeIntLib.h new file mode 100644 index 000000000000..e2f376f79f6f --- /dev/null +++ b/MdePkg/Include/Library/SafeIntLib.h @@ -0,0 +1,3013 @@ +/** @file + This library provides helper functions to prevent integer overflow during + type conversion, addition, subtraction, and multiplication. + + Copyright (c) 2017, Microsoft Corporation + + All rights reserved. + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ +#ifndef __INT_SAFE_LIB_H__ +#define __INT_SAFE_LIB_H__ + +// +// It is common for -1 to be used as an error value +// +#define INT8_ERROR ((INT8) -1) +#define UINT8_ERROR MAX_UINT8 +#define CHAR8_ERROR ((CHAR8)(MAX_INT8)) +#define INT16_ERROR ((INT16) -1) +#define UINT16_ERROR MAX_UINT16 +#define CHAR16_ERROR MAX_UINT16 +#define INT32_ERROR ((INT32) -1) +#define UINT32_ERROR MAX_UINT32 +#define INT64_ERROR ((INT64) -1) +#define UINT64_ERROR MAX_UINT64 +#define INTN_ERROR ((INTN) -1) +#define UINTN_ERROR MAX_UINTN + +// +// CHAR16 is defined to be the same as UINT16, so for CHAR16 +// operations redirect to the UINT16 ones: +// +#define SafeInt8ToChar16 SafeInt8ToUint16 +#define SafeInt16ToChar16 SafeInt16ToUint16 +#define SafeInt32ToChar16 SafeInt32ToUint16 +#define SafeUint32ToChar16 SafeUint32ToUint16 +#define SafeInt64ToChar16 SafeInt64ToUint16 +#define SafeUint64ToChar16 SafeUint64ToUint16 +#define SafeIntnToChar16 SafeIntnToUint16 +#define SafeUintnToChar16 SafeUintnToUint16 + +#define SafeChar16ToInt8 SafeUint16ToInt8 +#define SafeChar16ToUint8 SafeUint16ToUint8 +#define SafeChar16ToChar8 SafeUint16ToChar8 +#define SafeChar16ToInt16 SafeUint16ToInt16 + +#define SafeChar16Mult SafeUint16Mult +#define SafeChar16Sub SafeUint16Sub +#define SafeChar16Add SafeUint16Add + +// +// Conversion functions +// +// There are three reasons for having conversion functions: +// +// 1. We are converting from a signed type to an unsigned type of the same +// size, or vice-versa. +// +// 2. We are converting to a smaller type, and we could therefore possibly +// overflow. +// +// 3. We are converting to a bigger type, and we are signed and the type we are +// converting to is unsigned. +// + +/** + INT8 -> UINT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt8ToUint8 ( + IN INT8 Operand, + OUT UINT8 *Result + ); + +/** + INT8 -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt8ToChar8 ( + IN INT8 Operand, + OUT CHAR8 *Result + ); + +/** + INT8 -> UINT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt8ToUint16 ( + IN INT8 Operand, + OUT UINT16 *Result + ); + +/** + INT8 -> UINT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt8ToUint32 ( + IN INT8 Operand, + OUT UINT32 *Result + ); + +/** + INT8 -> UINTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt8ToUintn ( + IN INT8 Operand, + OUT UINTN *Result + ); + +/** + INT8 -> UINT64 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt8ToUint64 ( + IN INT8 Operand, + OUT UINT64 *Result + ); + +/** + UINT8 -> INT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint8ToInt8 ( + IN UINT8 Operand, + OUT INT8 *Result + ); + +/** + UINT8 -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint8ToChar8 ( + IN UINT8 Operand, + OUT CHAR8 *Result + ); + +/** + INT16 -> INT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16ToInt8 ( + IN INT16 Operand, + OUT INT8 *Result + ); + +/** + INT16 -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16ToChar8 ( + IN INT16 Operand, + OUT CHAR8 *Result + ); + +/** + INT16 -> UINT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16ToUint8 ( + IN INT16 Operand, + OUT UINT8 *Result + ); + +/** + INT16 -> UINT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16ToUint16 ( + IN INT16 Operand, + OUT UINT16 *Result + ); + +/** + INT16 -> UINT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16ToUint32 ( + IN INT16 Operand, + OUT UINT32 *Result + ); + +/** + INT16 -> UINTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16ToUintn ( + IN INT16 Operand, + OUT UINTN *Result + ); + +/** + INT16 -> UINT64 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16ToUint64 ( + IN INT16 Operand, + OUT UINT64 *Result + ); + +/** + UINT16 -> INT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint16ToInt8 ( + IN UINT16 Operand, + OUT INT8 *Result + ); + +/** + UINT16 -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint16ToChar8 ( + IN UINT16 Operand, + OUT CHAR8 *Result + ); + +/** + UINT16 -> UINT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint16ToUint8 ( + IN UINT16 Operand, + OUT UINT8 *Result + ); + +/** + UINT16 -> INT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint16ToInt16 ( + IN UINT16 Operand, + OUT INT16 *Result + ); + +/** + INT32 -> INT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32ToInt8 ( + IN INT32 Operand, + OUT INT8 *Result + ); + +/** + INT32 -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32ToChar8 ( + IN INT32 Operand, + OUT CHAR8 *Result + ); + +/** + INT32 -> UINT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32ToUint8 ( + IN INT32 Operand, + OUT UINT8 *Result + ); + +/** + INT32 -> INT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32ToInt16 ( + IN INT32 Operand, + OUT INT16 *Result + ); + +/** + INT32 -> UINT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32ToUint16 ( + IN INT32 Operand, + OUT UINT16 *Result + ); + + +/** + INT32 -> UINT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32ToUint32 ( + IN INT32 Operand, + OUT UINT32 *Result + ); + +/** + INT32 -> UINTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32ToUintn ( + IN INT32 Operand, + OUT UINTN *Result + ); + +/** + INT32 -> UINT64 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32ToUint64 ( + IN INT32 Operand, + OUT UINT64 *Result + ); + +/** + UINT32 -> INT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32ToInt8 ( + IN UINT32 Operand, + OUT INT8 *Result + ); + +/** + UINT32 -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32ToChar8 ( + IN UINT32 Operand, + OUT CHAR8 *Result + ); + +/** + UINT32 -> UINT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32ToUint8 ( + IN UINT32 Operand, + OUT UINT8 *Result + ); + +/** + UINT32 -> INT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32ToInt16 ( + IN UINT32 Operand, + OUT INT16 *Result + ); + +/** + UINT32 -> UINT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32ToUint16 ( + IN UINT32 Operand, + OUT UINT16 *Result + ); + +/** + UINT32 -> INT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32ToInt32 ( + IN UINT32 Operand, + OUT INT32 *Result + ); + +/** + UINT32 -> INTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32ToIntn ( + IN UINT32 Operand, + OUT INTN *Result + ); + +/** + INTN -> INT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnToInt8 ( + IN INTN Operand, + OUT INT8 *Result + ); + +/** + INTN -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnToChar8 ( + IN INTN Operand, + OUT CHAR8 *Result + ); + +/** + INTN -> UINT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnToUint8 ( + IN INTN Operand, + OUT UINT8 *Result + ); + +/** + INTN -> INT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnToInt16 ( + IN INTN Operand, + OUT INT16 *Result + ); + +/** + INTN -> UINT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnToUint16 ( + IN INTN Operand, + OUT UINT16 *Result + ); + +/** + INTN -> INT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnToInt32 ( + IN INTN Operand, + OUT INT32 *Result + ); + +/** + INTN -> UINT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnToUint32 ( + IN INTN Operand, + OUT UINT32 *Result + ); + +/** + INTN -> UINTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnToUintn ( + IN INTN Operand, + OUT UINTN *Result + ); + +/** + INTN -> UINT64 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnToUint64 ( + IN INTN Operand, + OUT UINT64 *Result + ); + +/** + UINTN -> INT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnToInt8 ( + IN UINTN Operand, + OUT INT8 *Result + ); + +/** + UINTN -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnToChar8 ( + IN UINTN Operand, + OUT CHAR8 *Result + ); + +/** + UINTN -> UINT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnToUint8 ( + IN UINTN Operand, + OUT UINT8 *Result + ); + +/** + UINTN -> INT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnToInt16 ( + IN UINTN Operand, + OUT INT16 *Result + ); + +/** + UINTN -> UINT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnToUint16 ( + IN UINTN Operand, + OUT UINT16 *Result + ); + +/** + UINTN -> INT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnToInt32 ( + IN UINTN Operand, + OUT INT32 *Result + ); + +/** + UINTN -> UINT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnToUint32 ( + IN UINTN Operand, + OUT UINT32 *Result + ); + +/** + UINTN -> INTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnToIntn ( + IN UINTN Operand, + OUT INTN *Result + ); + +/** + UINTN -> INT64 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnToInt64 ( + IN UINTN Operand, + OUT INT64 *Result + ); + +/** + INT64 -> INT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToInt8 ( + IN INT64 Operand, + OUT INT8 *Result + ); + +/** + INT64 -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToChar8 ( + IN INT64 Operand, + OUT CHAR8 *Result + ); + +/** + INT64 -> UINT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToUint8 ( + IN INT64 Operand, + OUT UINT8 *Result + ); + +/** + INT64 -> INT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToInt16 ( + IN INT64 Operand, + OUT INT16 *Result + ); + +/** + INT64 -> UINT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToUint16 ( + IN INT64 Operand, + OUT UINT16 *Result + ); + +/** + INT64 -> INT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToInt32 ( + IN INT64 Operand, + OUT INT32 *Result + ); + +/** + INT64 -> UINT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToUint32 ( + IN INT64 Operand, + OUT UINT32 *Result + ); + +/** + INT64 -> INTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToIntn ( + IN INT64 Operand, + OUT INTN *Result + ); + +/** + INT64 -> UINTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToUintn ( + IN INT64 Operand, + OUT UINTN *Result + ); + +/** + INT64 -> UINT64 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64ToUint64 ( + IN INT64 Operand, + OUT UINT64 *Result + ); + +/** + UINT64 -> INT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToInt8 ( + IN UINT64 Operand, + OUT INT8 *Result + ); + +/** + UINT64 -> CHAR8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToChar8 ( + IN UINT64 Operand, + OUT CHAR8 *Result + ); + +/** + UINT64 -> UINT8 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToUint8 ( + IN UINT64 Operand, + OUT UINT8 *Result + ); + +/** + UINT64 -> INT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToInt16 ( + IN UINT64 Operand, + OUT INT16 *Result + ); + +/** + UINT64 -> UINT16 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToUint16 ( + IN UINT64 Operand, + OUT UINT16 *Result + ); + +/** + UINT64 -> INT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToInt32 ( + IN UINT64 Operand, + OUT INT32 *Result + ); + +/** + UINT64 -> UINT32 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToUint32 ( + IN UINT64 Operand, + OUT UINT32 *Result + ); + +/** + UINT64 -> INTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToIntn ( + IN UINT64 Operand, + OUT INTN *Result + ); + +/** + UINT64 -> UINTN conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to UINTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToUintn ( + IN UINT64 Operand, + OUT UINTN *Result + ); + +/** + UINT64 -> INT64 conversion + + Converts the value specified by Operand to a value specified by Result type + and stores the converted value into the caller allocated output buffer + specified by Result. The caller must pass in a Result buffer that is at + least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the conversion results in an overflow or an underflow condition, then + Result is set to INT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Operand Operand to be converted to new type + @param[out] Result Pointer to the result of conversion + + @retval RETURN_SUCCESS Successful conversion + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64ToInt64 ( + IN UINT64 Operand, + OUT INT64 *Result + ); + +// +// Addition functions +// + +/** + UINT8 addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint8Add ( + IN UINT8 Augend, + IN UINT8 Addend, + OUT UINT8 *Result + ); + +/** + UINT16 addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint16Add ( + IN UINT16 Augend, + IN UINT16 Addend, + OUT UINT16 *Result + ); + +/** + UINT32 addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32Add ( + IN UINT32 Augend, + IN UINT32 Addend, + OUT UINT32 *Result + ); + +/** + UINTN addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnAdd ( + IN UINTN Augend, + IN UINTN Addend, + OUT UINTN *Result + ); + +/** + UINT64 addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64Add ( + IN UINT64 Augend, + IN UINT64 Addend, + OUT UINT64 *Result + ); + +// +// Subtraction functions +// + +/** + UINT8 subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint8Sub ( + IN UINT8 Minuend, + IN UINT8 Subtrahend, + OUT UINT8 *Result + ); + +/** + UINT16 subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint16Sub ( + IN UINT16 Minuend, + IN UINT16 Subtrahend, + OUT UINT16 *Result + ); + +/** + UINT32 subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32Sub ( + IN UINT32 Minuend, + IN UINT32 Subtrahend, + OUT UINT32 *Result + ); + +/** + UINTN subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnSub ( + IN UINTN Minuend, + IN UINTN Subtrahend, + OUT UINTN *Result + ); + +/** + UINT64 subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64Sub ( + IN UINT64 Minuend, + IN UINT64 Subtrahend, + OUT UINT64 *Result + ); + +// +// Multiplication functions +// + +/** + UINT8 multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint8Mult ( + IN UINT8 Multiplicand, + IN UINT8 Multiplier, + OUT UINT8 *Result + ); + +/** + UINT16 multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint16Mult ( + IN UINT16 Multiplicand, + IN UINT16 Multiplier, + OUT UINT16 *Result + ); + +/** + UINT32 multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint32Mult ( + IN UINT32 Multiplicand, + IN UINT32 Multiplier, + OUT UINT32 *Result + ); + +/** + UINTN multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUintnMult ( + IN UINTN Multiplicand, + IN UINTN Multiplier, + OUT UINTN *Result + ); + +/** + UINT64 multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to UINT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeUint64Mult ( + IN UINT64 Multiplicand, + IN UINT64 Multiplier, + OUT UINT64 *Result + ); + +// +// Signed operations +// +// Strongly consider using unsigned numbers. +// +// Signed numbers are often used where unsigned numbers should be used. +// For example file sizes and array indices should always be unsigned. +// Subtracting a larger positive signed number from a smaller positive +// signed number with SafeInt32Sub will succeed, producing a negative number, +// that then must not be used as an array index (but can occasionally be +// used as a pointer index.) Similarly for adding a larger magnitude +// negative number to a smaller magnitude positive number. +// +// This library does not protect you from such errors. It tells you if your +// integer operations overflowed, not if you are doing the right thing +// with your non-overflowed integers. +// +// Likewise you can overflow a buffer with a non-overflowed unsigned index. +// + +// +// Signed addition functions +// + +/** + INT8 Addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt8Add ( + IN INT8 Augend, + IN INT8 Addend, + OUT INT8 *Result + ); + +/** + CHAR8 Addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeChar8Add ( + IN CHAR8 Augend, + IN CHAR8 Addend, + OUT CHAR8 *Result + ); + +/** + INT16 Addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16Add ( + IN INT16 Augend, + IN INT16 Addend, + OUT INT16 *Result + ); + +/** + INT32 Addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32Add ( + IN INT32 Augend, + IN INT32 Addend, + OUT INT32 *Result + ); + +/** + INTN Addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnAdd ( + IN INTN Augend, + IN INTN Addend, + OUT INTN *Result + ); + +/** + INT64 Addition + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Augend A number to which addend will be added + @param[in] Addend A number to be added to another + @param[out] Result Pointer to the result of addition + + @retval RETURN_SUCCESS Successful addition + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64Add ( + IN INT64 Augend, + IN INT64 Addend, + OUT INT64 *Result + ); + +// +// Signed subtraction functions +// + +/** + INT8 Subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt8Sub ( + IN INT8 Minuend, + IN INT8 Subtrahend, + OUT INT8 *Result + ); + +/** + CHAR8 Subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeChar8Sub ( + IN CHAR8 Minuend, + IN CHAR8 Subtrahend, + OUT CHAR8 *Result + ); + +/** + INT16 Subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16Sub ( + IN INT16 Minuend, + IN INT16 Subtrahend, + OUT INT16 *Result + ); + +/** + INT32 Subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32Sub ( + IN INT32 Minuend, + IN INT32 Subtrahend, + OUT INT32 *Result + ); + +/** + INTN Subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnSub ( + IN INTN Minuend, + IN INTN Subtrahend, + OUT INTN *Result + ); + +/** + INT64 Subtraction + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Minuend A number from which another is to be subtracted. + @param[in] Subtrahend A number to be subtracted from another + @param[out] Result Pointer to the result of subtraction + + @retval RETURN_SUCCESS Successful subtraction + @retval RETURN_BUFFER_TOO_SMALL Underflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64Sub ( + IN INT64 Minuend, + IN INT64 Subtrahend, + OUT INT64 *Result + ); + +// +// Signed multiplication functions +// + +/** + INT8 multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt8Mult ( + IN INT8 Multiplicand, + IN INT8 Multiplier, + OUT INT8 *Result + ); + +/** + CHAR8 multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to CHAR8_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeChar8Mult ( + IN CHAR8 Multiplicand, + IN CHAR8 Multiplier, + OUT CHAR8 *Result + ); + +/** + INT16 multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT16_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt16Mult ( + IN INT16 Multiplicand, + IN INT16 Multiplier, + OUT INT16 *Result + ); + +/** + INT32 multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT32_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt32Mult ( + IN INT32 Multiplicand, + IN INT32 Multiplier, + OUT INT32 *Result + ); + +/** + INTN multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INTN_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeIntnMult ( + IN INTN Multiplicand, + IN INTN Multiplier, + OUT INTN *Result + ); + +/** + INT64 multiplication + + Performs the requested operation using the input parameters into a value + specified by Result type and stores the converted value into the caller + allocated output buffer specified by Result. The caller must pass in a + Result buffer that is at least as large as the Result type. + + If Result is NULL, RETURN_INVALID_PARAMETER is returned. + + If the requested operation results in an overflow or an underflow condition, + then Result is set to INT64_ERROR and RETURN_BUFFER_TOO_SMALL is returned. + + @param[in] Multiplicand A number that is to be multiplied by another + @param[in] Multiplier A number by which the multiplicand is to be multiplied + @param[out] Result Pointer to the result of multiplication + + @retval RETURN_SUCCESS Successful multiplication + @retval RETURN_BUFFER_TOO_SMALL Overflow + @retval RETURN_INVALID_PARAMETER Result is NULL +**/ +RETURN_STATUS +EFIAPI +SafeInt64Mult ( + IN INT64 Multiplicand, + IN INT64 Multiplier, + OUT INT64 *Result + ); + +#endif // __INT_SAFE_LIB_H__ diff --git a/MdePkg/Include/Library/SalLib.h b/MdePkg/Include/Library/SalLib.h deleted file mode 100644 index 94e4af8e591c..000000000000 --- a/MdePkg/Include/Library/SalLib.h +++ /dev/null @@ -1,59 +0,0 @@ -/** @file - Provides library services to make SAL Calls. - -Copyright (c) 2007 - 2008, Intel Corporation. All rights reserved.<BR> -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. - -**/ - -#ifndef __SAL_LIB__ -#define __SAL_LIB__ - -#include <IndustryStandard/Sal.h> - -/** - Makes a SAL procedure call. - - This is a wrapper function to make a SAL procedure call. - No parameter checking is performed on the 8 input parameters, - but there are some common rules that the caller should follow - when making a SAL call. Any address passed to SAL 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. - This function is only available on Intel Itanium-based platforms. - - @param Index The SAL procedure Index number - @param Arg2 The 2nd parameter for SAL procedure calls - @param Arg3 The 3rd parameter for SAL procedure calls - @param Arg4 The 4th parameter for SAL procedure calls - @param Arg5 The 5th parameter for SAL procedure calls - @param Arg6 The 6th parameter for SAL procedure calls - @param Arg7 The 7th parameter for SAL procedure calls - @param Arg8 The 8th parameter for SAL procedure calls - - @return SAL returned registers. - -**/ -SAL_RETURN_REGS -EFIAPI -SalCall ( - IN UINT64 Index, - IN UINT64 Arg2, - IN UINT64 Arg3, - IN UINT64 Arg4, - IN UINT64 Arg5, - IN UINT64 Arg6, - IN UINT64 Arg7, - IN UINT64 Arg8 - ); - -#endif diff --git a/MdePkg/Include/Library/SerialPortLib.h b/MdePkg/Include/Library/SerialPortLib.h index f56b76debd8b..1cd57656f28d 100644 --- a/MdePkg/Include/Library/SerialPortLib.h +++ b/MdePkg/Include/Library/SerialPortLib.h @@ -1,15 +1,9 @@ /** @file This library class provides common serial I/O port functions. -Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR> +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> Copyright (c) 2012 - 2014, ARM Ltd. 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. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -21,11 +15,11 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Initialize the serial device hardware. - + If no initialization is required, then return RETURN_SUCCESS. If the serial device was successfully initialized, then return RETURN_SUCCESS. If the serial device could not be initialized, then return RETURN_DEVICE_ERROR. - + @retval RETURN_SUCCESS The serial device was initialized. @retval RETURN_DEVICE_ERROR The serial device could not be initialized. @@ -37,19 +31,19 @@ SerialPortInitialize ( ); /** - Write data from buffer to serial device. - - Writes NumberOfBytes data bytes from Buffer to the serial device. + Write data from buffer to serial device. + + Writes NumberOfBytes data bytes from Buffer to the serial device. The number of bytes actually written to the serial device is returned. If the return value is less than NumberOfBytes, then the write operation failed. - If Buffer is NULL, then ASSERT(). + If Buffer is NULL, then ASSERT(). If NumberOfBytes is zero, then return 0. @param Buffer Pointer to the data buffer to be written. @param NumberOfBytes Number of bytes to written to the serial device. @retval 0 NumberOfBytes is 0. - @retval >0 The number of bytes written to the serial device. + @retval >0 The number of bytes written to the serial device. If this value is less than NumberOfBytes, then the write operation failed. **/ @@ -63,11 +57,11 @@ SerialPortWrite ( /** Read data from serial device and save the datas in buffer. - + Reads NumberOfBytes data bytes from a serial device into the buffer - specified by Buffer. The number of bytes actually read is returned. + specified by Buffer. The number of bytes actually read is returned. If the return value is less than NumberOfBytes, then the rest operation failed. - If Buffer is NULL, then ASSERT(). + If Buffer is NULL, then ASSERT(). If NumberOfBytes is zero, then return 0. @param Buffer Pointer to the data buffer to store the data read from the serial device. diff --git a/MdePkg/Include/Library/SmbusLib.h b/MdePkg/Include/Library/SmbusLib.h index 35bf932ac690..ac747bc7470f 100644 --- a/MdePkg/Include/Library/SmbusLib.h +++ b/MdePkg/Include/Library/SmbusLib.h @@ -2,14 +2,8 @@ Provides library functions to access SMBUS devices. Libraries of this class must be ported to a specific SMBUS controller. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -23,7 +17,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. Computes an address that is compatible with the SMBUS Library functions. The unused upper bits of SlaveAddress, Command, and Length are stripped prior to the generation of the address. - + @param SlaveAddress SMBUS Slave Address. Range 0..127. @param Command SMBUS Command. Range 0..255. @param Length SMBUS Data Length. Range 0..32. @@ -39,36 +33,36 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** Macro that returns the SMBUS Slave Address value from an SmBusAddress Parameter value. - - @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC + + @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC **/ #define SMBUS_LIB_SLAVE_ADDRESS(SmBusAddress) (((SmBusAddress) >> 1) & 0x7f) /** Macro that returns the SMBUS Command value from an SmBusAddress Parameter value. - + @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC **/ #define SMBUS_LIB_COMMAND(SmBusAddress) (((SmBusAddress) >> 8) & 0xff) /** Macro that returns the SMBUS Data Length value from an SmBusAddress Parameter value. - - @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC + + @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC **/ #define SMBUS_LIB_LENGTH(SmBusAddress) (((SmBusAddress) >> 16) & 0x3f) /** Macro that returns the SMBUS PEC value from an SmBusAddress Parameter value. - - @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC + + @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC **/ #define SMBUS_LIB_PEC(SmBusAddress) ((BOOLEAN) (((SmBusAddress) & BIT22) != 0)) /** Macro that returns the set of reserved bits from an SmBusAddress Parameter value. - - @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC + + @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC **/ #define SMBUS_LIB_RESERVED(SmBusAddress) ((SmBusAddress) & ~(BIT23 - 2)) @@ -282,7 +276,7 @@ SmBusWriteDataByte ( If Status is not NULL, then the status of the executed command is returned in Status. If Length in SmBusAddress is not zero, then ASSERT(). If any reserved bits of SmBusAddress are set, then ASSERT(). - + @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC. @param Status Return status for the executed command. @@ -424,7 +418,7 @@ SmBusReadBlock ( The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. Bytes are written to the SMBUS from Buffer. The number of bytes written is returned, and will never return a value larger than 32-bytes. - If Status is not NULL, then the status of the executed command is returned in Status. + If Status is not NULL, then the status of the executed command is returned in Status. If Length in SmBusAddress is zero or greater than 32, then ASSERT(). If Buffer is NULL, then ASSERT(). If any reserved bits of SmBusAddress are set, then ASSERT(). diff --git a/MdePkg/Include/Library/SmiHandlerProfileLib.h b/MdePkg/Include/Library/SmiHandlerProfileLib.h index a544addd133b..3db65f9e356b 100644 --- a/MdePkg/Include/Library/SmiHandlerProfileLib.h +++ b/MdePkg/Include/Library/SmiHandlerProfileLib.h @@ -13,13 +13,7 @@ be responsible to call the services to register information to SMM Core. Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> -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. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -66,6 +60,10 @@ SmiHandlerProfileRegisterHandler ( For the SmmChildDispatch protocol, the HandlerGuid must be the GUID of SmmChildDispatch protocol. @param Handler The SMI handler. + @param Context The context of the SMI handler. + If it is NOT NULL, it will be used to check what is registered. + @param ContextSize The size of the context in bytes. + If Context is NOT NULL, it will be used to check what is registered. @retval EFI_SUCCESS The original record is removed. @retval EFI_UNSUPPORTED The feature is unsupported. @@ -75,7 +73,9 @@ EFI_STATUS EFIAPI SmiHandlerProfileUnregisterHandler ( IN EFI_GUID *HandlerGuid, - IN EFI_SMM_HANDLER_ENTRY_POINT2 Handler + IN EFI_SMM_HANDLER_ENTRY_POINT2 Handler, + IN VOID *Context, OPTIONAL + IN UINTN ContextSize OPTIONAL ); #endif diff --git a/MdePkg/Include/Library/SmmIoLib.h b/MdePkg/Include/Library/SmmIoLib.h new file mode 100644 index 000000000000..49b45f8890a8 --- /dev/null +++ b/MdePkg/Include/Library/SmmIoLib.h @@ -0,0 +1,36 @@ +/** @file + Provides services for SMM IO Operation. + + The SMM IO Library provides function for checking if IO resource is accessible inside of SMM. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SMM_IO_LIB_H_ +#define _SMM_IO_LIB_H_ + +/** + This function check if the MMIO resource is valid per processor architecture and + valid per platform design. + + @param BaseAddress The MMIO start address to be checked. + @param Length The MMIO length to be checked. + @param Owner A GUID representing the owner of the resource. + This GUID may be used by producer to correlate the device ownership of the resource. + NULL means no specific owner. + + @retval TRUE This MMIO resource is valid per processor architecture and valid per platform design. + @retval FALSE This MMIO resource is not valid per processor architecture or valid per platform design. +**/ +BOOLEAN +EFIAPI +SmmIsMmioValid ( + IN EFI_PHYSICAL_ADDRESS BaseAddress, + IN UINT64 Length, + IN EFI_GUID *Owner OPTIONAL + ); + +#endif + diff --git a/MdePkg/Include/Library/SmmLib.h b/MdePkg/Include/Library/SmmLib.h index 999c41038428..7623ce2e1c17 100644 --- a/MdePkg/Include/Library/SmmLib.h +++ b/MdePkg/Include/Library/SmmLib.h @@ -1,16 +1,10 @@ /** @file Library class name: SmmLib - - SMM Library Services that abstracts both S/W SMI generation and detection. - Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR> - 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 + SMM Library Services that abstracts both S/W SMI generation and detection. - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -19,7 +13,7 @@ /** - Triggers an SMI at boot time. + Triggers an SMI at boot time. This function triggers a software SMM interrupt at boot time. @@ -32,7 +26,7 @@ TriggerBootServiceSoftwareSmi ( /** - Triggers an SMI at run time. + Triggers an SMI at run time. This function triggers a software SMM interrupt at run time. @@ -45,13 +39,13 @@ TriggerRuntimeSoftwareSmi ( /** - Test if a boot time software SMI happened. + Test if a boot time software SMI happened. This function tests if a software SMM interrupt happened. If a software SMM interrupt happened and it was triggered at boot time, it returns TRUE. Otherwise, it returns FALSE. @retval TRUE A software SMI triggered at boot time happened. - @retval FLASE No software SMI happened, or the software SMI was triggered at run time. + @retval FALSE No software SMI happened, or the software SMI was triggered at run time. **/ BOOLEAN @@ -62,13 +56,13 @@ IsBootServiceSoftwareSmi ( /** - Test if a run time software SMI happened. + Test if a run time software SMI happened. This function tests if a software SMM interrupt happened. If a software SMM interrupt happened and it was triggered at run time, it returns TRUE. Otherwise, it returns FALSE. @retval TRUE A software SMI triggered at run time happened. - @retval FLASE No software SMI happened or the software SMI was triggered at boot time. + @retval FALSE No software SMI happened or the software SMI was triggered at boot time. **/ BOOLEAN @@ -78,8 +72,8 @@ IsRuntimeSoftwareSmi ( ); /** - Clear APM SMI Status Bit; Set the EOS bit. - + Clear APM SMI Status Bit; Set the EOS bit. + **/ VOID EFIAPI diff --git a/MdePkg/Include/Library/SmmMemLib.h b/MdePkg/Include/Library/SmmMemLib.h index d460ae9577b8..feb81d11c922 100644 --- a/MdePkg/Include/Library/SmmMemLib.h +++ b/MdePkg/Include/Library/SmmMemLib.h @@ -4,15 +4,9 @@ The SMM Mem Library provides function for checking if buffer is outside SMRAM and valid. It also provides functions for copy data from SMRAM to non-SMRAM, from non-SMRAM to SMRAM, from non-SMRAM to non-SMRAM, or set data in non-SMRAM. - - Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> - 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. + Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -68,12 +62,12 @@ SmmCopyMemToSmram ( If the check passes, it copies memory and returns EFI_SUCCESS. If the check fails, it returns EFI_SECURITY_VIOLATION. The implementation must be reentrant. - + @param DestinationBuffer The pointer to the destination buffer of the memory copy. @param SourceBuffer The pointer to the source buffer of the memory copy. @param Length The number of bytes to copy from SourceBuffer to DestinationBuffer. - @retval EFI_SECURITY_VIOLATION The DesinationBuffer is invalid per processor architecture or overlap with SMRAM. + @retval EFI_SECURITY_VIOLATION The DestinationBuffer is invalid per processor architecture or overlap with SMRAM. @retval EFI_SUCCESS Memory is copied. **/ @@ -93,12 +87,12 @@ SmmCopyMemFromSmram ( If the check passes, it copies memory and returns EFI_SUCCESS. If the check fails, it returns EFI_SECURITY_VIOLATION. The implementation must be reentrant, and it must handle the case where source buffer overlaps destination buffer. - + @param DestinationBuffer The pointer to the destination buffer of the memory copy. @param SourceBuffer The pointer to the source buffer of the memory copy. @param Length The number of bytes to copy from SourceBuffer to DestinationBuffer. - @retval EFI_SECURITY_VIOLATION The DesinationBuffer is invalid per processor architecture or overlap with SMRAM. + @retval EFI_SECURITY_VIOLATION The DestinationBuffer is invalid per processor architecture or overlap with SMRAM. @retval EFI_SECURITY_VIOLATION The SourceBuffer is invalid per processor architecture or overlap with SMRAM. @retval EFI_SUCCESS Memory is copied. @@ -118,11 +112,11 @@ SmmCopyMem ( It checks if target buffer is valid per processor architecture and not overlap with SMRAM. If the check passes, it fills memory and returns EFI_SUCCESS. If the check fails, it returns EFI_SECURITY_VIOLATION. - + @param Buffer The memory to set. @param Length The number of bytes to set. @param Value The value with which to fill Length bytes of Buffer. - + @retval EFI_SECURITY_VIOLATION The Buffer is invalid per processor architecture or overlap with SMRAM. @retval EFI_SUCCESS Memory is set. @@ -135,4 +129,4 @@ SmmSetMem ( IN UINT8 Value ); -#endif
\ No newline at end of file +#endif diff --git a/MdePkg/Include/Library/SmmPeriodicSmiLib.h b/MdePkg/Include/Library/SmmPeriodicSmiLib.h index dee4d98f55d6..c9682be2c8c6 100644 --- a/MdePkg/Include/Library/SmmPeriodicSmiLib.h +++ b/MdePkg/Include/Library/SmmPeriodicSmiLib.h @@ -1,14 +1,8 @@ /** @file Provides services to enable and disable periodic SMI handlers. -Copyright (c) 2011, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -19,15 +13,15 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /** This function returns a pointer to a table of supported periodic - SMI tick periods in 100 ns units sorted from largest to smallest. - The table contains a array of UINT64 values terminated by a tick + SMI tick periods in 100 ns units sorted from largest to smallest. + The table contains a array of UINT64 values terminated by a tick period value of 0. The returned table must be treated as read-only data and must not be freed. - - @return A pointer to a table of UINT64 tick period values in - 100ns units sorted from largest to smallest terminated + + @return A pointer to a table of UINT64 tick period values in + 100ns units sorted from largest to smallest terminated by a tick period of 0. - + **/ UINT64 * EFIAPI @@ -53,30 +47,30 @@ PeriodicSmiExecutionTime ( ); /** - This function returns control back to the SMM Foundation. When the next + This function returns control back to the SMM Foundation. When the next periodic SMI for the currently executing handler is triggered, the periodic SMI handler will restarted from its registered DispatchFunction entry point. - If this function is not called from within an enabled periodic SMI handler, + If this function is not called from within an enabled periodic SMI handler, then control is returned to the calling function. **/ VOID -EFIAPI +EFIAPI PeriodicSmiExit ( VOID ); /** - This function yields control back to the SMM Foundation. When the next + This function yields control back to the SMM Foundation. When the next periodic SMI for the currently executing handler is triggered, the periodic - SMI handler will be resumed and this function will return. Use of this - function requires a seperate stack for the periodic SMI handler. A non zero - stack size must be specified in PeriodicSmiEnable() for this function to be - used. - + SMI handler will be resumed and this function will return. Use of this + function requires a separate stack for the periodic SMI handler. A non zero + stack size must be specified in PeriodicSmiEnable() for this function to be + used. + If the stack size passed into PeriodicSmiEnable() was zero, the 0 is returned. - - If this function is not called from within an enabled periodic SMI handler, + + If this function is not called from within an enabled periodic SMI handler, then 0 is returned. @return The actual time in 100ns units elapsed since this function was @@ -84,21 +78,21 @@ PeriodicSmiExit ( **/ UINT64 -EFIAPI +EFIAPI PeriodicSmiYield ( VOID ); /** - This function is a prototype for a periodic SMI handler function + This function is a prototype for a periodic SMI handler function that may be enabled with PeriodicSmiEnable() and disabled with PeriodicSmiDisable(). @param[in] Context Content registered with PeriodicSmiEnable(). @param[in] ElapsedTime The actual time in 100ns units elapsed since - this function was called. A value of 0 indicates + this function was called. A value of 0 indicates an unknown amount of time. - + **/ typedef VOID @@ -106,48 +100,48 @@ VOID IN CONST VOID *Context OPTIONAL, IN UINT64 ElapsedTime ); - + /** This function enables a periodic SMI handler. - - @param[in, out] DispatchHandle A pointer to the handle associated with the - enabled periodic SMI handler. This is an - optional parameter that may be NULL. If it is - NULL, then the handle will not be returned, - which means that the periodic SMI handler can + + @param[in, out] DispatchHandle A pointer to the handle associated with the + enabled periodic SMI handler. This is an + optional parameter that may be NULL. If it is + NULL, then the handle will not be returned, + which means that the periodic SMI handler can never be disabled. @param[in] DispatchFunction A pointer to a periodic SMI handler function. @param[in] Context Optional content to pass into DispatchFunction. - @param[in] TickPeriod The requested tick period in 100ns units that - control should be givien to the periodic SMI + @param[in] TickPeriod The requested tick period in 100ns units that + control should be given to the periodic SMI handler. Must be one of the supported values returned by PeriodicSmiSupportedPickPeriod(). @param[in] Cpu Specifies the CPU that is required to execute - the periodic SMI handler. If Cpu is - PERIODIC_SMI_LIBRARY_ANY_CPU, then the periodic - SMI handler will always be executed on the SMST - CurrentlyExecutingCpu, which may vary across - periodic SMIs. If Cpu is between 0 and the SMST + the periodic SMI handler. If Cpu is + PERIODIC_SMI_LIBRARY_ANY_CPU, then the periodic + SMI handler will always be executed on the SMST + CurrentlyExecutingCpu, which may vary across + periodic SMIs. If Cpu is between 0 and the SMST NumberOfCpus, then the periodic SMI will always be executed on the requested CPU. @param[in] StackSize The size, in bytes, of the stack to allocate for use by the periodic SMI handler. If 0, then the default stack will be used. - + @retval EFI_INVALID_PARAMETER DispatchFunction is NULL. - @retval EFI_UNSUPPORTED TickPeriod is not a supported tick period. The - supported tick periods can be retrieved using + @retval EFI_UNSUPPORTED TickPeriod is not a supported tick period. The + supported tick periods can be retrieved using PeriodicSmiSupportedTickPeriod(). - @retval EFI_INVALID_PARAMETER Cpu is not PERIODIC_SMI_LIBRARY_ANY_CPU or in + @retval EFI_INVALID_PARAMETER Cpu is not PERIODIC_SMI_LIBRARY_ANY_CPU or in the range 0 to SMST NumberOfCpus. - @retval EFI_OUT_OF_RESOURCES There are not enough resources to enable the + @retval EFI_OUT_OF_RESOURCES There are not enough resources to enable the periodic SMI handler. - @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the - stack speficied by StackSize. + @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the + stack specified by StackSize. @retval EFI_SUCCESS The periodic SMI handler was enabled. - + **/ -EFI_STATUS +EFI_STATUS EFIAPI PeriodicSmiEnable ( IN OUT EFI_HANDLE *DispatchHandle, OPTIONAL @@ -161,24 +155,24 @@ PeriodicSmiEnable ( /** This function disables a periodic SMI handler that has been previously enabled with PeriodicSmiEnable(). - - @param[in] DispatchHandle A handle associated with a previously enabled periodic + + @param[in] DispatchHandle A handle associated with a previously enabled periodic SMI handler. This is an optional parameter that may be NULL. If it is NULL, then the active periodic SMI handlers is disabled. @retval FALSE DispatchHandle is NULL and there is no active periodic SMI handler. - @retval FALSE The periodic SMI handler specified by DispatchHandle has + @retval FALSE The periodic SMI handler specified by DispatchHandle has not been enabled with PeriodicSmiEnable(). - @retval TRUE The periodic SMI handler specified by DispatchHandle has + @retval TRUE The periodic SMI handler specified by DispatchHandle has been disabled. If DispatchHandle is NULL, then the active periodic SMI handler has been disabled. - + **/ -BOOLEAN +BOOLEAN EFIAPI PeriodicSmiDisable ( IN EFI_HANDLE DispatchHandle OPTIONAL ); - + #endif diff --git a/MdePkg/Include/Library/SmmServicesTableLib.h b/MdePkg/Include/Library/SmmServicesTableLib.h index b8c0d5660fc3..110d70b89c0f 100644 --- a/MdePkg/Include/Library/SmmServicesTableLib.h +++ b/MdePkg/Include/Library/SmmServicesTableLib.h @@ -2,14 +2,8 @@ Provides a service to retrieve a pointer to the SMM Services Table. Only available to SMM module types. -Copyright (c) 2009, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -24,14 +18,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. extern EFI_SMM_SYSTEM_TABLE2 *gSmst; /** - This function allows the caller to determine if the driver is executing in + This function allows the caller to determine if the driver is executing in System Management Mode(SMM). - This function returns TRUE if the driver is executing in SMM and FALSE if the + This function returns TRUE if the driver is executing in SMM and FALSE if the driver is not executing in SMM. @retval TRUE The driver is executing in System Management Mode (SMM). - @retval FALSE The driver is not executing in System Management Mode (SMM). + @retval FALSE The driver is not executing in System Management Mode (SMM). **/ BOOLEAN diff --git a/MdePkg/Include/Library/StandaloneMmDriverEntryPoint.h b/MdePkg/Include/Library/StandaloneMmDriverEntryPoint.h new file mode 100644 index 000000000000..9de5f362837b --- /dev/null +++ b/MdePkg/Include/Library/StandaloneMmDriverEntryPoint.h @@ -0,0 +1,125 @@ +/** @file + Module entry point library for Standalone MM Drivers. + +Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> +Copyright (c) 2016 - 2018, ARM Limited. All rights reserved.<BR> +Copyright (c) 2018, Linaro, Limited. All rights reserved.<BR> + +SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __MODULE_ENTRY_POINT_H__ +#define __MODULE_ENTRY_POINT_H__ + +/// +/// Declare the PI Specification Revision that this driver requires to execute +/// correctly. +/// +extern CONST UINT32 _gMmRevision; + +/** + The entry point of PE/COFF Image for a Standalone MM Driver. + + This function is the entry point for a Standalone MM Driver. + This function must call ProcessLibraryConstructorList() and + ProcessModuleEntryPointList(). + If the return status from ProcessModuleEntryPointList() + is an error status, then ProcessLibraryDestructorList() must be called. + The return value from ProcessModuleEntryPointList() is returned. + If _gMmRevision is not zero and MmSystemTable->Hdr.Revision is + less than _gMmRevision, then return EFI_INCOMPATIBLE_VERSION. + + @param ImageHandle The image handle of the Standalone MM Driver. + @param MmSystemTable A pointer to the MM System Table. + + @retval EFI_SUCCESS The Standalone MM Driver exited normally. + @retval EFI_INCOMPATIBLE_VERSION _gMmRevision is greater than + MmSystemTable->Hdr.Revision. + @retval Other Return value from + ProcessModuleEntryPointList(). + +**/ +EFI_STATUS +EFIAPI +_ModuleEntryPoint ( + IN EFI_HANDLE ImageHandle, + IN EFI_MM_SYSTEM_TABLE *MmSystemTable + ); + + +/** + Auto generated function that calls the library constructors for all of the + module's dependent libraries. + + This function must be called by _ModuleEntryPoint(). + This function calls the set of library constructors for the set of library + instances that a module depends on. This includes library instances that a + module depends on directly and library instances that a module depends on + indirectly through other libraries. This function is auto generated by build + tools and those build tools are responsible for collecting the set of library + instances, determine which ones have constructors, and calling the library + constructors in the proper order based upon each of the library instances own + dependencies. + + @param ImageHandle The image handle of the Standalone MM Driver. + @param MmSystemTable A pointer to the MM System Table. + +**/ +VOID +EFIAPI +ProcessLibraryConstructorList ( + IN EFI_HANDLE ImageHandle, + IN EFI_MM_SYSTEM_TABLE *MmSystemTable + ); + + +/** + Auto generated function that calls the library descructors for all of the + module's dependent libraries. + + This function may be called by _ModuleEntryPoint(). + This function calls the set of library destructors for the set of library + instances that a module depends on. This includes library instances that a + module depends on directly and library instances that a module depends on + indirectly through other libraries. + This function is auto generated by build tools and those build tools are + responsible for collecting the set of library instances, determine which ones + have destructors, and calling the library destructors in the proper order + based upon each of the library instances own dependencies. + + @param ImageHandle The image handle of the Standalone MM Driver. + @param MmSystemTable A pointer to the MM System Table. + +**/ +VOID +EFIAPI +ProcessLibraryDestructorList ( + IN EFI_HANDLE ImageHandle, + IN EFI_MM_SYSTEM_TABLE *MmSystemTable + ); + + +/** + Auto generated function that calls a set of module entry points. + + This function must be called by _ModuleEntryPoint(). + This function calls the set of module entry points. + This function is auto generated by build tools and those build tools are + responsible for collecting the module entry points and calling them in a + specified order. + + @param ImageHandle The image handle of the Standalone MM Driver. + @param MmSystemTable A pointer to the MM System Table. + + @retval EFI_SUCCESS The Standalone MM Driver executed normally. + @retval !EFI_SUCCESS The Standalone MM Driver failed to execute normally. +**/ +EFI_STATUS +EFIAPI +ProcessModuleEntryPointList ( + IN EFI_HANDLE ImageHandle, + IN EFI_MM_SYSTEM_TABLE *MmSystemTable + ); + +#endif diff --git a/MdePkg/Include/Library/SynchronizationLib.h b/MdePkg/Include/Library/SynchronizationLib.h index bfdf6f4222ed..fc01b10cd4b7 100644 --- a/MdePkg/Include/Library/SynchronizationLib.h +++ b/MdePkg/Include/Library/SynchronizationLib.h @@ -1,14 +1,8 @@ /** @file Provides synchronization functions. -Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -26,7 +20,7 @@ typedef volatile UINTN SPIN_LOCK; optimal spin lock performance. This function retrieves the spin lock alignment requirements for optimal - performance on a given CPU architecture. The spin lock alignment is byte alignment. + performance on a given CPU architecture. The spin lock alignment is byte alignment. It must be a power of two and is returned by this function. If there are no alignment requirements, then 1 must be returned. The spin lock synchronization functions must function correctly if the spin lock size and alignment values @@ -144,8 +138,7 @@ ReleaseSpinLock ( Performs an atomic increment of the 32-bit unsigned integer specified by Value and returns the incremented value. The increment operation must be - performed using MP safe mechanisms. The state of the return value is not - guaranteed to be MP safe. + performed using MP safe mechanisms. If Value is NULL, then ASSERT(). @@ -166,8 +159,7 @@ InterlockedIncrement ( Performs an atomic decrement of the 32-bit unsigned integer specified by Value and returns the decremented value. The decrement operation must be - performed using MP safe mechanisms. The state of the return value is not - guaranteed to be MP safe. + performed using MP safe mechanisms. If Value is NULL, then ASSERT(). diff --git a/MdePkg/Include/Library/TimerLib.h b/MdePkg/Include/Library/TimerLib.h index f0d898a9894f..a4c2d8818b78 100644 --- a/MdePkg/Include/Library/TimerLib.h +++ b/MdePkg/Include/Library/TimerLib.h @@ -2,13 +2,7 @@ Provides calibrated delay and performance counter services. Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> -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. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/UefiApplicationEntryPoint.h b/MdePkg/Include/Library/UefiApplicationEntryPoint.h index c84282397c73..b5c00c1457bc 100644 --- a/MdePkg/Include/Library/UefiApplicationEntryPoint.h +++ b/MdePkg/Include/Library/UefiApplicationEntryPoint.h @@ -1,14 +1,8 @@ /** @file Module entry point library for UEFI Applications. -Copyright (c) 2007 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -16,7 +10,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define __UEFI_APPLICATION_ENTRY_POINT_H__ /// -/// Declare the EFI/UEFI Specification Revision to which this driver is implemented +/// Declare the EFI/UEFI Specification Revision to which this driver is implemented /// extern CONST UINT32 _gUefiDriverRevision; @@ -47,7 +41,7 @@ _ModuleEntryPoint ( /** - Required by the EBC compiler and identical in functionality to _ModuleEntryPoint(). + Required by the EBC compiler and identical in functionality to _ModuleEntryPoint(). @param ImageHandle The image handle of the UEFI Application. @param SystemTable A pointer to the EFI System Table. @@ -67,13 +61,13 @@ EfiMain ( /** Invokes the library destructors for all dependent libraries and terminates - the UEFI Application. + the UEFI Application. This function calls ProcessLibraryDestructorList() and the EFI Boot Service Exit() with a status specified by Status. @param Status Status returned by the application that is exiting. - + **/ VOID EFIAPI @@ -89,7 +83,7 @@ Exit ( This function must be called by _ModuleEntryPoint(). This function calls the set of library constructors for the set of library instances that a module depends on. This includes library instances that a module depends on - directly and library instances that a module depends on indirectly through other libraries. + directly and library instances that a module depends on indirectly through other libraries. This function is autogenerated by build tools and those build tools are responsible for collecting the set of library instances, determine which ones have constructors, and calling the library constructors in the proper order based upon each of the library @@ -97,7 +91,7 @@ Exit ( @param ImageHandle The image handle of the UEFI Application. @param SystemTable A pointer to the EFI System Table. - + **/ VOID EFIAPI @@ -114,7 +108,7 @@ ProcessLibraryConstructorList ( This function may be called by _ModuleEntryPoint()or Exit(). This function calls the set of library destructors for the set of library instances that a module depends on. This includes library instances that a module depends on - directly and library instances that a module depends on indirectly through other libraries. + directly and library instances that a module depends on indirectly through other libraries. This function is autogenerated by build tools and those build tools are responsible for collecting the set of library instances, determine which ones have destructors, and calling the library destructors in the proper order based upon each of the library @@ -134,7 +128,7 @@ ProcessLibraryDestructorList ( /** This function calls the set of module entry points. It must be called by _ModuleEntryPoint(). - This function is autogenerated by build tools and those build tools are + This function is autogenerated by build tools and those build tools are responsible for collecting the module entry points and calling them in a specified order. @param ImageHandle The image handle of the UEFI Application. diff --git a/MdePkg/Include/Library/UefiBootServicesTableLib.h b/MdePkg/Include/Library/UefiBootServicesTableLib.h index b382a8d51ed7..499071bc04b9 100644 --- a/MdePkg/Include/Library/UefiBootServicesTableLib.h +++ b/MdePkg/Include/Library/UefiBootServicesTableLib.h @@ -3,13 +3,7 @@ Only available to DXE and UEFI module types. Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/UefiDecompressLib.h b/MdePkg/Include/Library/UefiDecompressLib.h index 2a7a91e5c1d9..510e80aa9c3b 100644 --- a/MdePkg/Include/Library/UefiDecompressLib.h +++ b/MdePkg/Include/Library/UefiDecompressLib.h @@ -1,19 +1,13 @@ /** @file Provides services to decompress a buffer using the UEFI Decompress algorithm. - The UEFI Decompress Library enables the decompression of objects that - were compressed using the UEFI compression scheme. The UEFI Decompress - Library is independent of environment and requires the caller to allocate + The UEFI Decompress Library enables the decompression of objects that + were compressed using the UEFI compression scheme. The UEFI Decompress + Library is independent of environment and requires the caller to allocate all required memory buffers. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -21,18 +15,18 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define __UEFI_DECPOMPRESS_LIB_H__ /** - Given a compressed source buffer, this function retrieves the size of - the uncompressed buffer and the size of the scratch buffer required + Given a compressed source buffer, this function retrieves the size of + the uncompressed buffer and the size of the scratch buffer required to decompress the compressed source buffer. - Retrieves the size of the uncompressed buffer and the temporary scratch buffer + Retrieves the size of the uncompressed buffer and the temporary scratch buffer required to decompress the buffer specified by Source and SourceSize. If the size of the uncompressed buffer or the size of the scratch buffer cannot - be determined from the compressed data specified by Source and SourceData, + be determined from the compressed data specified by Source and SourceData, then RETURN_INVALID_PARAMETER is returned. Otherwise, the size of the uncompressed buffer is returned in DestinationSize, the size of the scratch buffer is returned in ScratchSize, and RETURN_SUCCESS is returned. - This function does not have scratch buffer available to perform a thorough + This function does not have scratch buffer available to perform a thorough checking of the validity of the source data. It just retrieves the "Original Size" field from the beginning bytes of the source data and output it as DestinationSize. And ScratchSize is specific to the decompression implementation. @@ -47,16 +41,16 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. that will be generated when the compressed buffer specified by Source and SourceSize is decompressed. @param ScratchSize A pointer to the size, in bytes, of the scratch buffer that - is required to decompress the compressed buffer specified + is required to decompress the compressed buffer specified by Source and SourceSize. - @retval RETURN_SUCCESS The size of the uncompressed data was returned - in DestinationSize and the size of the scratch + @retval RETURN_SUCCESS The size of the uncompressed data was returned + in DestinationSize and the size of the scratch buffer was returned in ScratchSize. - @retval RETURN_INVALID_PARAMETER - The size of the uncompressed data or the size of - the scratch buffer cannot be determined from - the compressed data specified by Source + @retval RETURN_INVALID_PARAMETER + The size of the uncompressed data or the size of + the scratch buffer cannot be determined from + the compressed data specified by Source and SourceSize. **/ RETURN_STATUS @@ -74,10 +68,10 @@ UefiDecompressGetInfo ( Extracts decompressed data to its original form. This function is designed so that the decompression algorithm can be implemented without using any memory services. As a result, this function is not allowed to - call any memory allocation services in its implementation. It is the caller's + call any memory allocation services in its implementation. It is the caller's responsibility to allocate and free the Destination and Scratch buffers. - If the compressed source data specified by Source is successfully decompressed - into Destination, then RETURN_SUCCESS is returned. If the compressed source data + If the compressed source data specified by Source is successfully decompressed + into Destination, then RETURN_SUCCESS is returned. If the compressed source data specified by Source is not in a valid compressed data format, then RETURN_INVALID_PARAMETER is returned. @@ -88,13 +82,13 @@ UefiDecompressGetInfo ( @param Source The source buffer containing the compressed data. @param Destination The destination buffer to store the decompressed data @param Scratch A temporary scratch buffer that is used to perform the decompression. - This is an optional parameter that may be NULL if the + This is an optional parameter that may be NULL if the required scratch buffer size is 0. - - @retval RETURN_SUCCESS Decompression completed successfully, and + + @retval RETURN_SUCCESS Decompression completed successfully, and the uncompressed buffer is returned in Destination. - @retval RETURN_INVALID_PARAMETER - The source buffer specified by Source is corrupted + @retval RETURN_INVALID_PARAMETER + The source buffer specified by Source is corrupted (not in a valid compressed format). **/ RETURN_STATUS diff --git a/MdePkg/Include/Library/UefiDriverEntryPoint.h b/MdePkg/Include/Library/UefiDriverEntryPoint.h index f0812bc2722a..9eb0adf35f9d 100644 --- a/MdePkg/Include/Library/UefiDriverEntryPoint.h +++ b/MdePkg/Include/Library/UefiDriverEntryPoint.h @@ -2,14 +2,8 @@ Module entry point library for UEFI drivers, DXE Drivers, DXE Runtime Drivers, and DXE SMM Drivers. -Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -22,18 +16,18 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. extern CONST UINT32 _gDxeRevision; /// -/// Declare the EFI/UEFI Specification Revision to which this driver is implemented +/// Declare the EFI/UEFI Specification Revision to which this driver is implemented /// extern CONST UINT32 _gUefiDriverRevision; /// -/// Declare the number of unload handler in the image. +/// Declare the number of unload handler in the image. /// extern CONST UINT8 _gDriverUnloadImageCount; /** - The entry point of PE/COFF Image for a DXE Driver, DXE Runtime Driver, DXE SMM Driver, or UEFI Driver. + The entry point of PE/COFF Image for a DXE Driver, DXE Runtime Driver, DXE SMM Driver, or UEFI Driver. This function is the entry point for a DXE Driver, DXE Runtime Driver, DXE SMM Driver, or UEFI Driver. This function must call ProcessLibraryConstructorList() and @@ -64,7 +58,7 @@ _ModuleEntryPoint ( /** - Required by the EBC compiler and identical in functionality to _ModuleEntryPoint(). + Required by the EBC compiler and identical in functionality to _ModuleEntryPoint(). This function is required to call _ModuleEntryPoint() passing in ImageHandle, and SystemTable. @@ -86,7 +80,7 @@ EfiMain ( /** Invokes the library destructors for all dependent libraries and terminates the - DXE Driver, DXE Runtime Driver, DXE SMM Driver, or UEFI Driver. + DXE Driver, DXE Runtime Driver, DXE SMM Driver, or UEFI Driver. This function calls ProcessLibraryDestructorList() and the EFI Boot Service Exit() with a status specified by Status. @@ -108,7 +102,7 @@ ExitDriver ( This function must be called by _ModuleEntryPoint(). This function calls the set of library constructors for the set of library instances that a module depends on. This includes library instances that a module depends on - directly and library instances that a module depends on indirectly through other libraries. + directly and library instances that a module depends on indirectly through other libraries. This function is autogenerated by build tools and those build tools are responsible for collecting the set of library instances, determine which ones have constructors, and calling the library constructors in the proper order based upon each of the library @@ -133,7 +127,7 @@ ProcessLibraryConstructorList ( This function may be called by _ModuleEntryPoint() or ExitDriver(). This function calls the set of library destructors for the set of library instances that a module depends on. This includes library instances that a module depends on - directly and library instances that a module depends on indirectly through other libraries. + directly and library instances that a module depends on indirectly through other libraries. This function is autogenerated by build tools and those build tools are responsible for collecting the set of library instances, determine which ones have destructors, and calling the library destructors in the proper order based upon each of the library instances own dependencies. @@ -154,7 +148,7 @@ ProcessLibraryDestructorList ( Autogenerated function that calls a set of module entry points. This function must be called by _ModuleEntryPoint(). - This function calls the set of module entry points. + This function calls the set of module entry points. This function is autogenerated by build tools and those build tools are responsible for collecting the module entry points and calling them in a specified order. @@ -176,7 +170,7 @@ ProcessModuleEntryPointList ( Autogenerated function that calls a set of module unload handlers. This function must be called from the unload handler registered by _ModuleEntryPoint(). - This function calls the set of module unload handlers. + This function calls the set of module unload handlers. This function is autogenerated by build tools and those build tools are responsible for collecting the module unload handlers and calling them in a specified order. diff --git a/MdePkg/Include/Library/UefiLib.h b/MdePkg/Include/Library/UefiLib.h index d91bcf83954f..fb39f5f0d487 100644 --- a/MdePkg/Include/Library/UefiLib.h +++ b/MdePkg/Include/Library/UefiLib.h @@ -2,30 +2,27 @@ Provides library functions for common UEFI operations. Only available to DXE and UEFI module types. - The UEFI Library provides functions and macros that simplify the development of - UEFI Drivers and UEFI Applications. These functions and macros help manage EFI - events, build simple locks utilizing EFI Task Priority Levels (TPLs), install - EFI Driver Model related protocols, manage Unicode string tables for UEFI Drivers, + The UEFI Library provides functions and macros that simplify the development of + UEFI Drivers and UEFI Applications. These functions and macros help manage EFI + events, build simple locks utilizing EFI Task Priority Levels (TPLs), install + EFI Driver Model related protocols, manage Unicode string tables for UEFI Drivers, and print messages on the console output and standard error devices. Note that a reserved macro named MDEPKG_NDEBUG is introduced for the intention of size reduction when compiler optimization is disabled. If MDEPKG_NDEBUG is defined, then debug and assert related macros wrapped by it are the NULL implementations. -Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that 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. +Copyright (c) 2019, NVIDIA Corporation. All rights reserved. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef __UEFI_LIB_H__ #define __UEFI_LIB_H__ +#include <IndustryStandard/Acpi.h> + #include <Protocol/DriverBinding.h> #include <Protocol/DriverConfiguration.h> #include <Protocol/ComponentName.h> @@ -33,6 +30,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #include <Protocol/DriverDiagnostics.h> #include <Protocol/DriverDiagnostics2.h> #include <Protocol/GraphicsOutput.h> +#include <Protocol/DevicePath.h> +#include <Protocol/SimpleFileSystem.h> #include <Library/BaseLib.h> @@ -54,7 +53,7 @@ typedef enum { } EFI_LOCK_STATE; /// -/// EFI Lock +/// EFI Lock /// typedef struct { EFI_TPL Tpl; @@ -99,8 +98,8 @@ typedef struct { #define EFI_TIMER_PERIOD_SECONDS(Seconds) MultU64x32((UINT64)(Seconds), 10000000) /** - Macro that returns the a pointer to the next EFI_MEMORY_DESCRIPTOR in an array - returned from GetMemoryMap(). + Macro that returns the a pointer to the next EFI_MEMORY_DESCRIPTOR in an array + returned from GetMemoryMap(). @param MemoryDescriptor A pointer to an EFI_MEMORY_DESCRIPTOR. @@ -115,7 +114,7 @@ typedef struct { /** Retrieves a pointer to the system configuration table from the EFI System Table based on a specified GUID. - + This function searches the list of configuration tables stored in the EFI System Table for a table with a GUID that matches TableGuid. If a match is found, then a pointer to the configuration table is returned in Table, and EFI_SUCCESS is returned. If a matching GUID @@ -132,7 +131,7 @@ typedef struct { **/ EFI_STATUS EFIAPI -EfiGetSystemConfigurationTable ( +EfiGetSystemConfigurationTable ( IN EFI_GUID *TableGuid, OUT VOID **Table ); @@ -146,7 +145,7 @@ EfiGetSystemConfigurationTable ( no instances of ProtocolGuid in the handle database at the time this function is invoked, then the notification function is still executed one time. In addition, every time a protocol of type ProtocolGuid instance is installed or reinstalled, the notification function is also - executed. This function returns the notification event that was created. + executed. This function returns the notification event that was created. If ProtocolGuid is NULL, then ASSERT(). If NotifyTpl is not a legal TPL value, then ASSERT(). If NotifyFunction is NULL, then ASSERT(). @@ -159,7 +158,7 @@ EfiGetSystemConfigurationTable ( @param NotifyContext The context parameter to pass to NotifyFunction. @param Registration A pointer to a memory location to receive the registration value. This value is passed to LocateHandle() to obtain new handles that - have been added that support the ProtocolGuid-specified protocol. + have been added that support the ProtocolGuid-specified protocol. @return The notification event that was created. @@ -179,7 +178,7 @@ EfiCreateProtocolNotifyEvent( This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext. This event is signaled with EfiNamedEventSignal(). This provides the ability for one or more - listeners on the same event named by the GUID specified by Name. + listeners on the same event named by the GUID specified by Name. If Name is NULL, then ASSERT(). If NotifyTpl is not a legal TPL value, then ASSERT(). If NotifyFunction is NULL, then ASSERT(). @@ -187,7 +186,7 @@ EfiCreateProtocolNotifyEvent( @param Name Supplies GUID name of the event. @param NotifyTpl Supplies the task priority level of the event notifications. @param NotifyFunction Supplies the function to notify when the event is signaled. - @param NotifyContext The context parameter to pass to NotifyFunction. + @param NotifyContext The context parameter to pass to NotifyFunction. @param Registration A pointer to a memory location to receive the registration value. @retval EFI_SUCCESS A named event was created. @@ -257,13 +256,13 @@ EfiEventEmptyFunction ( IN VOID *Context ); -/** +/** Returns the current TPL. - This function returns the current TPL. There is no EFI service to directly - retrieve the current TPL. Instead, the RaiseTPL() function is used to raise - the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level - can then immediately be restored back to the current TPL level with a call + This function returns the current TPL. There is no EFI service to directly + retrieve the current TPL. Instead, the RaiseTPL() function is used to raise + the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level + can then immediately be restored back to the current TPL level with a call to RestoreTPL(). @return The current TPL. @@ -278,8 +277,8 @@ EfiGetCurrentTpl ( /** Initializes a basic mutual exclusion lock. - This function initializes a basic mutual exclusion lock to the released state - and returns the lock. Each lock provides mutual exclusion access at its task + This function initializes a basic mutual exclusion lock to the released state + and returns the lock. Each lock provides mutual exclusion access at its task priority level. Since there is no preemption or multiprocessor support in EFI, acquiring the lock only consists of raising to the locks TPL. If Lock is NULL, then ASSERT(). @@ -301,8 +300,8 @@ EfiInitializeLock ( /** Initializes a basic mutual exclusion lock. - This macro initializes the contents of a basic mutual exclusion lock to the - released state. Each lock provides mutual exclusion access at its task + This macro initializes the contents of a basic mutual exclusion lock to the + released state. Each lock provides mutual exclusion access at its task priority level. Since there is no preemption or multiprocessor support in EFI, acquiring the lock only consists of raising to the locks TPL. @@ -318,10 +317,10 @@ EfiInitializeLock ( /** Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state. - If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED - bit of PcdDebugProperyMask is set, then this macro evaluates the EFI_LOCK + If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED + bit of PcdDebugProperyMask is set, then this macro evaluates the EFI_LOCK structure specified by Lock. If Lock is not in the locked state, then - DebugAssert() is called passing in the source filename, source line number, + DebugAssert() is called passing in the source filename, source line number, and Lock. If Lock is NULL, then ASSERT(). @@ -329,7 +328,7 @@ EfiInitializeLock ( @param LockParameter A pointer to the lock to acquire. **/ -#if !defined(MDEPKG_NDEBUG) +#if !defined(MDEPKG_NDEBUG) #define ASSERT_LOCKED(LockParameter) \ do { \ if (DebugAssertEnabled ()) { \ @@ -347,8 +346,8 @@ EfiInitializeLock ( /** Acquires ownership of a lock. - This function raises the system's current task priority level to the task - priority level of the mutual exclusion lock. Then, it places the lock in the + This function raises the system's current task priority level to the task + priority level of the mutual exclusion lock. Then, it places the lock in the acquired state. If Lock is NULL, then ASSERT(). If Lock is not initialized, then ASSERT(). @@ -388,8 +387,8 @@ EfiAcquireLockOrFail ( /** Releases ownership of a lock. - This function transitions a mutual exclusion lock from the acquired state to - the released state, and restores the system's task priority level to its + This function transitions a mutual exclusion lock from the acquired state to + the released state, and restores the system's task priority level to its previous level. If Lock is NULL, then ASSERT(). If Lock is not initialized, then ASSERT(). @@ -411,7 +410,7 @@ EfiReleaseLock ( currently managing the controller specified by ControllerHandle. This test is performed by evaluating if the the protocol specified by ProtocolGuid is present on ControllerHandle and is was opened by DriverBindingHandle with an - attribute of EFI_OPEN_PROTOCOL_BY_DRIVER. + attribute of EFI_OPEN_PROTOCOL_BY_DRIVER. If ProtocolGuid is NULL, then ASSERT(). @param ControllerHandle A handle for a controller to test. @@ -444,10 +443,10 @@ EfiTestManagedDevice ( ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. If ProtocolGuid is NULL, then ASSERT(). - @param ControllerHandle A handle for a (parent) controller to test. + @param ControllerHandle A handle for a (parent) controller to test. @param ChildHandle A child handle to test. @param ProtocolGuid Supplies the protocol that the child controller - opens on its parent controller. + opens on its parent controller. @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle. @retval EFI_UNSUPPORTED ChildHandle is not a child of the @@ -463,32 +462,50 @@ EfiTestChildHandle ( ); /** + This function checks the supported languages list for a target language, + This only supports RFC 4646 Languages. + + @param SupportedLanguages The supported languages + @param TargetLanguage The target language + + @retval Returns EFI_SUCCESS if the language is supported, + EFI_UNSUPPORTED otherwise + +**/ +EFI_STATUS +EFIAPI +IsLanguageSupported ( + IN CONST CHAR8 *SupportedLanguages, + IN CONST CHAR8 *TargetLanguage + ); + +/** This function looks up a Unicode string in UnicodeStringTable. If Language is a member of SupportedLanguages and a Unicode string is found in UnicodeStringTable that matches the language code specified by Language, then it is returned in UnicodeString. - @param Language A pointer to the ISO 639-2 language code for the + @param Language A pointer to the ISO 639-2 language code for the Unicode string to look up and return. - @param SupportedLanguages A pointer to the set of ISO 639-2 language codes - that the Unicode string table supports. Language + @param SupportedLanguages A pointer to the set of ISO 639-2 language codes + that the Unicode string table supports. Language must be a member of this set. @param UnicodeStringTable A pointer to the table of Unicode strings. @param UnicodeString A pointer to the Unicode string from UnicodeStringTable that matches the language specified by Language. - @retval EFI_SUCCESS The Unicode string that matches the language + @retval EFI_SUCCESS The Unicode string that matches the language specified by Language was found - in the table of Unicode strings UnicodeStringTable, + in the table of Unicode strings UnicodeStringTable, and it was returned in UnicodeString. @retval EFI_INVALID_PARAMETER Language is NULL. @retval EFI_INVALID_PARAMETER UnicodeString is NULL. @retval EFI_UNSUPPORTED SupportedLanguages is NULL. @retval EFI_UNSUPPORTED UnicodeStringTable is NULL. - @retval EFI_UNSUPPORTED The language specified by Language is not a + @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages. - @retval EFI_UNSUPPORTED The language specified by Language is not + @retval EFI_UNSUPPORTED The language specified by Language is not supported by UnicodeStringTable. **/ @@ -513,7 +530,7 @@ LookupUnicodeString ( return. If Iso639Language is TRUE, then this ASCII string is not assumed to be Null-terminated, and only the first three characters are used. If Iso639Language is FALSE, then this ASCII - string must be Null-terminated. + string must be Null-terminated. @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains a set of ISO 639-2 or RFC 4646 language codes that the Unicode string table supports. Language must be a member of this set. @@ -533,11 +550,11 @@ LookupUnicodeString ( @retval EFI_SUCCESS The Unicode string that matches the language specified by Language was found in the table of Unicode strings UnicodeStringTable, and it was returned in UnicodeString. - @retval EFI_INVALID_PARAMETER Language is NULL. - @retval EFI_INVALID_PARAMETER UnicodeString is NULL. - @retval EFI_UNSUPPORTED SupportedLanguages is NULL. - @retval EFI_UNSUPPORTED UnicodeStringTable is NULL. - @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER UnicodeString is NULL. + @retval EFI_UNSUPPORTED SupportedLanguages is NULL. + @retval EFI_UNSUPPORTED UnicodeStringTable is NULL. + @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages. @retval EFI_UNSUPPORTED The language specified by Language is not supported by UnicodeStringTable. **/ @@ -554,13 +571,13 @@ LookupUnicodeString2 ( /** This function adds a Unicode string to UnicodeStringTable. - If Language is a member of SupportedLanguages then UnicodeString is added to - UnicodeStringTable. New buffers are allocated for both Language and - UnicodeString. The contents of Language and UnicodeString are copied into - these new buffers. These buffers are automatically freed when + If Language is a member of SupportedLanguages then UnicodeString is added to + UnicodeStringTable. New buffers are allocated for both Language and + UnicodeString. The contents of Language and UnicodeString are copied into + these new buffers. These buffers are automatically freed when FreeUnicodeStringTable() is called. - @param Language A pointer to the ISO 639-2 language code for the Unicode + @param Language A pointer to the ISO 639-2 language code for the Unicode string to add. @param SupportedLanguages A pointer to the set of ISO 639-2 language codes that the Unicode string table supports. @@ -568,29 +585,29 @@ LookupUnicodeString2 ( @param UnicodeStringTable A pointer to the table of Unicode strings. @param UnicodeString A pointer to the Unicode string to add. - @retval EFI_SUCCESS The Unicode string that matches the language - specified by Language was found in the table of - Unicode strings UnicodeStringTable, and it was + @retval EFI_SUCCESS The Unicode string that matches the language + specified by Language was found in the table of + Unicode strings UnicodeStringTable, and it was returned in UnicodeString. @retval EFI_INVALID_PARAMETER Language is NULL. @retval EFI_INVALID_PARAMETER UnicodeString is NULL. @retval EFI_INVALID_PARAMETER UnicodeString is an empty string. @retval EFI_UNSUPPORTED SupportedLanguages is NULL. - @retval EFI_ALREADY_STARTED A Unicode string with language Language is + @retval EFI_ALREADY_STARTED A Unicode string with language Language is already present in UnicodeStringTable. - @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another + @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another Unicode string to UnicodeStringTable. - @retval EFI_UNSUPPORTED The language specified by Language is not a + @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages. **/ EFI_STATUS EFIAPI AddUnicodeString ( - IN CONST CHAR8 *Language, - IN CONST CHAR8 *SupportedLanguages, - IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable, - IN CONST CHAR16 *UnicodeString + IN CONST CHAR8 *Language, + IN CONST CHAR8 *SupportedLanguages, + IN OUT EFI_UNICODE_STRING_TABLE **UnicodeStringTable, + IN CONST CHAR16 *UnicodeString ); /** @@ -617,39 +634,39 @@ AddUnicodeString ( RFC 4646 language codes separated by ';'. @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE is defined in "Related Definitions". - @param UnicodeString A pointer to the Unicode string to add. + @param UnicodeString A pointer to the Unicode string to add. @param Iso639Language Specifies the supported language code format. If it is TRUE, then Language and SupportedLanguages follow ISO 639-2 language code format. Otherwise, they follow RFC 4646 language code format. @retval EFI_SUCCESS The Unicode string that matches the language specified by Language was found in the table of Unicode strings UnicodeStringTable, - and it was returned in UnicodeString. - @retval EFI_INVALID_PARAMETER Language is NULL. - @retval EFI_INVALID_PARAMETER UnicodeString is NULL. - @retval EFI_INVALID_PARAMETER UnicodeString is an empty string. - @retval EFI_UNSUPPORTED SupportedLanguages is NULL. + and it was returned in UnicodeString. + @retval EFI_INVALID_PARAMETER Language is NULL. + @retval EFI_INVALID_PARAMETER UnicodeString is NULL. + @retval EFI_INVALID_PARAMETER UnicodeString is an empty string. + @retval EFI_UNSUPPORTED SupportedLanguages is NULL. @retval EFI_ALREADY_STARTED A Unicode string with language Language is already present in - UnicodeStringTable. - @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another Unicode string UnicodeStringTable. + UnicodeStringTable. + @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another Unicode string UnicodeStringTable. @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages. **/ EFI_STATUS EFIAPI AddUnicodeString2 ( - IN CONST CHAR8 *Language, - IN CONST CHAR8 *SupportedLanguages, - IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable, - IN CONST CHAR16 *UnicodeString, - IN BOOLEAN Iso639Language + IN CONST CHAR8 *Language, + IN CONST CHAR8 *SupportedLanguages, + IN OUT EFI_UNICODE_STRING_TABLE **UnicodeStringTable, + IN CONST CHAR16 *UnicodeString, + IN BOOLEAN Iso639Language ); /** This function frees the table of Unicode strings in UnicodeStringTable. If UnicodeStringTable is NULL, then EFI_SUCCESS is returned. - Otherwise, each language code, and each Unicode string in the Unicode string + Otherwise, each language code, and each Unicode string in the Unicode string table are freed, and EFI_SUCCESS is returned. @param UnicodeStringTable A pointer to the table of Unicode strings. @@ -668,8 +685,8 @@ FreeUnicodeStringTable ( /** [ATTENTION] This function will be deprecated for security reason. - Returns a pointer to an allocated buffer that contains the contents of a - variable retrieved through the UEFI Runtime Service GetVariable(). The + Returns a pointer to an allocated buffer that contains the contents of a + variable retrieved through the UEFI Runtime Service GetVariable(). The returned buffer is allocated using AllocatePool(). The caller is responsible for freeing this buffer with FreePool(). @@ -694,10 +711,10 @@ GetVariable ( /** [ATTENTION] This function will be deprecated for security reason. - Returns a pointer to an allocated buffer that contains the contents of a - variable retrieved through the UEFI Runtime Service GetVariable(). This + Returns a pointer to an allocated buffer that contains the contents of a + variable retrieved through the UEFI Runtime Service GetVariable(). This function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables. - The returned buffer is allocated using AllocatePool(). The caller is + The returned buffer is allocated using AllocatePool(). The caller is responsible for freeing this buffer with FreePool(). If Name is NULL, then ASSERT(). @@ -718,8 +735,8 @@ GetEfiGlobalVariable ( /** - Returns the status whether get the variable success. The function retrieves - variable through the UEFI Runtime Service GetVariable(). The + Returns the status whether get the variable success. The function retrieves + variable through the UEFI Runtime Service GetVariable(). The returned buffer is allocated using AllocatePool(). The caller is responsible for freeing this buffer with FreePool(). @@ -732,9 +749,9 @@ GetEfiGlobalVariable ( @param[out] Value The buffer point saved the variable info. @param[out] Size The buffer size of the variable. - @return EFI_OUT_OF_RESOURCES Allocate buffer failed. - @return EFI_SUCCESS Find the specified variable. - @return Others Errors Return errors from call to gRT->GetVariable. + @retval EFI_OUT_OF_RESOURCES Allocate buffer failed. + @retval EFI_SUCCESS Find the specified variable. + @retval Others Errors Return errors from call to gRT->GetVariable. **/ EFI_STATUS @@ -747,10 +764,10 @@ GetVariable2 ( ); /** - Returns a pointer to an allocated buffer that contains the contents of a - variable retrieved through the UEFI Runtime Service GetVariable(). This + Returns a pointer to an allocated buffer that contains the contents of a + variable retrieved through the UEFI Runtime Service GetVariable(). This function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables. - The returned buffer is allocated using AllocatePool(). The caller is + The returned buffer is allocated using AllocatePool(). The caller is responsible for freeing this buffer with FreePool(). If Name is NULL, then ASSERT(). @@ -760,9 +777,9 @@ GetVariable2 ( @param[out] Value The buffer point saved the variable info. @param[out] Size The buffer size of the variable. - @return EFI_OUT_OF_RESOURCES Allocate buffer failed. - @return EFI_SUCCESS Find the specified variable. - @return Others Errors Return errors from call to gRT->GetVariable. + @retval EFI_OUT_OF_RESOURCES Allocate buffer failed. + @retval EFI_SUCCESS Find the specified variable. + @retval Others Errors Return errors from call to gRT->GetVariable. **/ EFI_STATUS @@ -773,77 +790,110 @@ GetEfiGlobalVariable2 ( OUT UINTN *Size OPTIONAL ); +/** Return the attributes of the variable. + + Returns the status whether get the variable success. The function retrieves + variable through the UEFI Runtime Service GetVariable(). The + returned buffer is allocated using AllocatePool(). The caller is responsible + for freeing this buffer with FreePool(). The attributes are returned if + the caller provides a valid Attribute parameter. + + If Name is NULL, then ASSERT(). + If Guid is NULL, then ASSERT(). + If Value is NULL, then ASSERT(). + + @param[in] Name The pointer to a Null-terminated Unicode string. + @param[in] Guid The pointer to an EFI_GUID structure + @param[out] Value The buffer point saved the variable info. + @param[out] Size The buffer size of the variable. + @param[out] Attr The pointer to the variable attributes as found in var store + + @retval EFI_OUT_OF_RESOURCES Allocate buffer failed. + @retval EFI_SUCCESS Find the specified variable. + @retval Others Errors Return errors from call to gRT->GetVariable. + +**/ +EFI_STATUS +EFIAPI +GetVariable3( + IN CONST CHAR16 *Name, + IN CONST EFI_GUID *Guid, + OUT VOID **Value, + OUT UINTN *Size OPTIONAL, + OUT UINT32 *Attr OPTIONAL + ); + /** - Returns a pointer to an allocated buffer that contains the best matching language - from a set of supported languages. - - This function supports both ISO 639-2 and RFC 4646 language codes, but language - code types may not be mixed in a single call to this function. The language - code returned is allocated using AllocatePool(). The caller is responsible for + Returns a pointer to an allocated buffer that contains the best matching language + from a set of supported languages. + + This function supports both ISO 639-2 and RFC 4646 language codes, but language + code types may not be mixed in a single call to this function. The language + code returned is allocated using AllocatePool(). The caller is responsible for freeing the allocated buffer using FreePool(). This function supports a variable - argument list that allows the caller to pass in a prioritized list of language - codes to test against all the language codes in SupportedLanguages. + argument list that allows the caller to pass in a prioritized list of language + codes to test against all the language codes in SupportedLanguages. If SupportedLanguages is NULL, then ASSERT(). @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string that - contains a set of language codes in the format + contains a set of language codes in the format specified by Iso639Language. - @param[in] Iso639Language If TRUE, then all language codes are assumed to be - in ISO 639-2 format. If FALSE, then all language + @param[in] Iso639Language If not zero, then all language codes are assumed to be + in ISO 639-2 format. If zero, then all language codes are assumed to be in RFC 4646 language format - @param[in] ... A variable argument list that contains pointers to + @param[in] ... A variable argument list that contains pointers to Null-terminated ASCII strings that contain one or more language codes in the format specified by Iso639Language. The first language code from each of these language code lists is used to determine if it is an exact or - close match to any of the language codes in + close match to any of the language codes in SupportedLanguages. Close matches only apply to RFC 4646 language codes, and the matching algorithm from RFC 4647 - is used to determine if a close match is present. If + is used to determine if a close match is present. If an exact or close match is found, then the matching language code from SupportedLanguages is returned. If no matches are found, then the next variable argument - parameter is evaluated. The variable argument list + parameter is evaluated. The variable argument list is terminated by a NULL. @retval NULL The best matching language could not be found in SupportedLanguages. - @retval NULL There are not enough resources available to return the best matching + @retval NULL There are not enough resources available to return the best matching language. - @retval Other A pointer to a Null-terminated ASCII string that is the best matching + @retval Other A pointer to a Null-terminated ASCII string that is the best matching language in SupportedLanguages. **/ CHAR8 * EFIAPI GetBestLanguage ( - IN CONST CHAR8 *SupportedLanguages, - IN BOOLEAN Iso639Language, + IN CONST CHAR8 *SupportedLanguages, + IN UINTN Iso639Language, ... ); /** - Draws a dialog box to the console output device specified by + Draws a dialog box to the console output device specified by ConOut defined in the EFI_SYSTEM_TABLE and waits for a keystroke - from the console input device specified by ConIn defined in the + from the console input device specified by ConIn defined in the EFI_SYSTEM_TABLE. If there are no strings in the variable argument list, then ASSERT(). If all the strings in the variable argument list are empty, then ASSERT(). @param[in] Attribute Specifies the foreground and background color of the popup. - @param[out] Key A pointer to the EFI_KEY value of the key that was + @param[out] Key A pointer to the EFI_KEY value of the key that was pressed. This is an optional parameter that may be NULL. If it is NULL then no wait for a keypress will be performed. @param[in] ... The variable argument list that contains pointers to Null- - terminated Unicode strings to display in the dialog box. + terminated Unicode strings to display in the dialog box. The variable argument list is terminated by a NULL. **/ VOID EFIAPI CreatePopUp ( - IN UINTN Attribute, + IN UINTN Attribute, OUT EFI_INPUT_KEY *Key, OPTIONAL ... ); @@ -875,13 +925,13 @@ GetGlyphWidth ( of the Unicode characters in String can not be determined, then 0 is returned. The display width of String can be computed by summing the display widths of each Unicode character in String. Unicode characters that are narrow glyphs have a width of 1, and Unicode - characters that are width glyphs have a width of 2. + characters that are width glyphs have a width of 2. If String is not aligned on a 16-bit boundary, then ASSERT(). @param String A pointer to a Null-terminated Unicode string. @return The display length of the Null-terminated Unicode string specified by String. - + **/ UINTN EFIAPI @@ -894,7 +944,7 @@ UnicodeStringDisplayLength ( // /** Create, Signal, and Close the Ready to Boot event using EfiSignalEventReadyToBoot(). - + This function abstracts the signaling of the Ready to Boot Event. The Framework moved from a proprietary to UEFI 2.0 based mechanism. This library abstracts the caller from how this event is created to prevent to code form having to change with the @@ -947,8 +997,8 @@ EfiCreateEventLegacyBoot ( /** Create an EFI event in the Legacy Boot Event Group and allows - the caller to specify a notification function. - + the caller to specify a notification function. + This function abstracts the creation of the Legacy Boot Event. The Framework moved from a proprietary to UEFI 2.0 based mechanism. This library abstracts the caller from how this event is created to prevent @@ -977,10 +1027,10 @@ EfiCreateEventLegacyBootEx ( Create an EFI event in the Ready To Boot Event Group. Prior to UEFI 2.0 this was done via a non-standard UEFI extension, and this library - abstracts the implementation mechanism of this event from the caller. - This function abstracts the creation of the Ready to Boot Event. The Framework - moved from a proprietary to UEFI 2.0-based mechanism. This library abstracts - the caller from how this event is created to prevent the code form having to + abstracts the implementation mechanism of this event from the caller. + This function abstracts the creation of the Ready to Boot Event. The Framework + moved from a proprietary to UEFI 2.0-based mechanism. This library abstracts + the caller from how this event is created to prevent the code form having to change with the version of the specification supported. If ReadyToBootEvent is NULL, then ASSERT(). @@ -998,8 +1048,8 @@ EfiCreateEventReadyToBoot ( /** Create an EFI event in the Ready To Boot Event Group and allows - the caller to specify a notification function. - + the caller to specify a notification function. + This function abstracts the creation of the Ready to Boot Event. The Framework moved from a proprietary to UEFI 2.0 based mechanism. This library abstracts the caller from how this event is created to prevent @@ -1026,16 +1076,16 @@ EfiCreateEventReadyToBootEx ( /** Initialize a Firmware Volume (FV) Media Device Path node. - - The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification. - This library function abstracts initializing a device path node. - Initialize the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure. This device - path changed in the DXE CIS version 0.92 in a non back ward compatible way to - not conflict with the UEFI 2.0 specification. This function abstracts the + + The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification. + This library function abstracts initializing a device path node. + Initialize the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure. This device + path changed in the DXE CIS version 0.92 in a non back ward compatible way to + not conflict with the UEFI 2.0 specification. This function abstracts the differences from the caller. If FvDevicePathNode is NULL, then ASSERT(). If NameGuid is NULL, then ASSERT(). - + @param FvDevicePathNode The pointer to a FV device path node to initialize @param NameGuid FV file name to use in FvDevicePathNode @@ -1048,14 +1098,14 @@ EfiInitializeFwVolDevicepathNode ( ); /** - Check to see if the Firmware Volume (FV) Media Device Path is valid - - The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification. + Check to see if the Firmware Volume (FV) Media Device Path is valid + + The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification. This library function abstracts validating a device path node. - Check the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure to see if it's valid. - If it is valid, then return the GUID file name from the device path node. Otherwise, - return NULL. This device path changed in the DXE CIS version 0.92 in a non backward - compatible way to not conflict with the UEFI 2.0 specification. This function abstracts + Check the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure to see if it's valid. + If it is valid, then return the GUID file name from the device path node. Otherwise, + return NULL. This device path changed in the DXE CIS version 0.92 in a non backward + compatible way to not conflict with the UEFI 2.0 specification. This function abstracts the differences from the caller. If FvDevicePathNode is NULL, then ASSERT(). @@ -1071,23 +1121,23 @@ EfiGetNameGuidFromFwVolDevicePathNode ( IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode ); -/** - Prints a formatted Unicode string to the console output device specified by +/** + Prints a formatted Unicode string to the console output device specified by ConOut defined in the EFI_SYSTEM_TABLE. - This function prints a formatted Unicode string to the console output device - specified by ConOut in EFI_SYSTEM_TABLE and returns the number of Unicode - characters that printed to ConOut. If the length of the formatted Unicode - string is greater than PcdUefiLibMaxPrintBufferSize, then only the first + This function prints a formatted Unicode string to the console output device + specified by ConOut in EFI_SYSTEM_TABLE and returns the number of Unicode + characters that printed to ConOut. If the length of the formatted Unicode + string is greater than PcdUefiLibMaxPrintBufferSize, then only the first PcdUefiLibMaxPrintBufferSize characters are sent to ConOut. If Format is NULL, then ASSERT(). If Format is not aligned on a 16-bit boundary, then ASSERT(). If gST->ConOut is NULL, then ASSERT(). @param Format A null-terminated Unicode format string. - @param ... The variable argument list whose contents are accessed based + @param ... The variable argument list whose contents are accessed based on the format string specified by Format. - + @return Number of Unicode characters printed to ConOut. **/ @@ -1098,23 +1148,23 @@ Print ( ... ); -/** - Prints a formatted Unicode string to the console output device specified by +/** + Prints a formatted Unicode string to the console output device specified by StdErr defined in the EFI_SYSTEM_TABLE. - This function prints a formatted Unicode string to the console output device - specified by StdErr in EFI_SYSTEM_TABLE and returns the number of Unicode - characters that printed to StdErr. If the length of the formatted Unicode - string is greater than PcdUefiLibMaxPrintBufferSize, then only the first + This function prints a formatted Unicode string to the console output device + specified by StdErr in EFI_SYSTEM_TABLE and returns the number of Unicode + characters that printed to StdErr. If the length of the formatted Unicode + string is greater than PcdUefiLibMaxPrintBufferSize, then only the first PcdUefiLibMaxPrintBufferSize characters are sent to StdErr. If Format is NULL, then ASSERT(). If Format is not aligned on a 16-bit boundary, then ASSERT(). If gST->StdErr is NULL, then ASSERT(). @param Format A null-terminated Unicode format string. - @param ... The variable argument list whose contents are accessed based + @param ... The variable argument list whose contents are accessed based on the format string specified by Format. - + @return Number of Unicode characters printed to StdErr. **/ @@ -1125,22 +1175,22 @@ ErrorPrint ( ... ); -/** - Prints a formatted ASCII string to the console output device specified by +/** + Prints a formatted ASCII string to the console output device specified by ConOut defined in the EFI_SYSTEM_TABLE. - This function prints a formatted ASCII string to the console output device - specified by ConOut in EFI_SYSTEM_TABLE and returns the number of ASCII - characters that printed to ConOut. If the length of the formatted ASCII - string is greater than PcdUefiLibMaxPrintBufferSize, then only the first + This function prints a formatted ASCII string to the console output device + specified by ConOut in EFI_SYSTEM_TABLE and returns the number of ASCII + characters that printed to ConOut. If the length of the formatted ASCII + string is greater than PcdUefiLibMaxPrintBufferSize, then only the first PcdUefiLibMaxPrintBufferSize characters are sent to ConOut. If Format is NULL, then ASSERT(). If gST->ConOut is NULL, then ASSERT(). @param Format A null-terminated ASCII format string. - @param ... The variable argument list whose contents are accessed based + @param ... The variable argument list whose contents are accessed based on the format string specified by Format. - + @return Number of ASCII characters printed to ConOut. **/ @@ -1151,22 +1201,22 @@ AsciiPrint ( ... ); -/** - Prints a formatted ASCII string to the console output device specified by +/** + Prints a formatted ASCII string to the console output device specified by StdErr defined in the EFI_SYSTEM_TABLE. - This function prints a formatted ASCII string to the console output device - specified by StdErr in EFI_SYSTEM_TABLE and returns the number of ASCII - characters that printed to StdErr. If the length of the formatted ASCII - string is greater than PcdUefiLibMaxPrintBufferSize, then only the first + This function prints a formatted ASCII string to the console output device + specified by StdErr in EFI_SYSTEM_TABLE and returns the number of ASCII + characters that printed to StdErr. If the length of the formatted ASCII + string is greater than PcdUefiLibMaxPrintBufferSize, then only the first PcdUefiLibMaxPrintBufferSize characters are sent to StdErr. If Format is NULL, then ASSERT(). If gST->StdErr is NULL, then ASSERT(). @param Format A null-terminated ASCII format string. - @param ... The variable argument list whose contents are accessed based + @param ... The variable argument list whose contents are accessed based on the format string specified by Format. - + @return Number of ASCII characters printed to ConErr. **/ @@ -1179,22 +1229,22 @@ AsciiErrorPrint ( /** - Prints a formatted Unicode string to a graphics console device specified by + Prints a formatted Unicode string to a graphics console device specified by ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE at the given (X,Y) coordinates. - This function prints a formatted Unicode string to the graphics console device - specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of - Unicode characters displayed, not including partial characters that may be clipped + This function prints a formatted Unicode string to the graphics console device + specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of + Unicode characters displayed, not including partial characters that may be clipped by the right edge of the display. If the length of the formatted Unicode string is - greater than PcdUefiLibMaxPrintBufferSize, then at most the first + greater than PcdUefiLibMaxPrintBufferSize, then at most the first PcdUefiLibMaxPrintBufferSize characters are printed. The EFI_HII_FONT_PROTOCOL - is used to convert the string to a bitmap using the glyphs registered with the + is used to convert the string to a bitmap using the glyphs registered with the HII database. No wrapping is performed, so any portions of the string the fall outside the active display region will not be displayed. - If a graphics console device is not associated with the ConsoleOutputHandle + If a graphics console device is not associated with the ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE then no string is printed, and 0 is returned. - If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no + If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no string is printed, and 0 is returned. If Format is NULL, then ASSERT(). If Format is not aligned on a 16-bit boundary, then ASSERT(). @@ -1207,13 +1257,13 @@ AsciiErrorPrint ( then the foreground color of the current ConOut device in the EFI_SYSTEM_TABLE is used. @param BackGround The background color of the string being printed. This is - an optional parameter that may be NULL. If it is NULL, + an optional parameter that may be NULL. If it is NULL, then the background color of the current ConOut device in the EFI_SYSTEM_TABLE is used. - @param Format A null-terminated Unicode format string. See Print Library + @param Format A null-terminated Unicode format string. See Print Library for the supported format string syntax. - @param ... Variable argument list whose contents are accessed based on - the format string specified by Format. + @param ... Variable argument list whose contents are accessed based on + the format string specified by Format. @return The number of Unicode characters printed. @@ -1230,22 +1280,22 @@ PrintXY ( ); /** - Prints a formatted ASCII string to a graphics console device specified by + Prints a formatted ASCII string to a graphics console device specified by ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE at the given (X,Y) coordinates. - This function prints a formatted ASCII string to the graphics console device - specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of - ASCII characters displayed, not including partial characters that may be clipped + This function prints a formatted ASCII string to the graphics console device + specified by ConsoleOutputHandle in EFI_SYSTEM_TABLE and returns the number of + ASCII characters displayed, not including partial characters that may be clipped by the right edge of the display. If the length of the formatted ASCII string is - greater than PcdUefiLibMaxPrintBufferSize, then at most the first + greater than PcdUefiLibMaxPrintBufferSize, then at most the first PcdUefiLibMaxPrintBufferSize characters are printed. The EFI_HII_FONT_PROTOCOL - is used to convert the string to a bitmap using the glyphs registered with the + is used to convert the string to a bitmap using the glyphs registered with the HII database. No wrapping is performed, so any portions of the string the fall outside the active display region will not be displayed. - If a graphics console device is not associated with the ConsoleOutputHandle + If a graphics console device is not associated with the ConsoleOutputHandle defined in the EFI_SYSTEM_TABLE then no string is printed, and 0 is returned. - If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no + If the EFI_HII_FONT_PROTOCOL is not present in the handle database, then no string is printed, and 0 is returned. If Format is NULL, then ASSERT(). If gST->ConsoleOutputHandle is NULL, then ASSERT(). @@ -1257,13 +1307,13 @@ PrintXY ( then the foreground color of the current ConOut device in the EFI_SYSTEM_TABLE is used. @param BackGround The background color of the string being printed. This is - an optional parameter that may be NULL. If it is NULL, + an optional parameter that may be NULL. If it is NULL, then the background color of the current ConOut device in the EFI_SYSTEM_TABLE is used. - @param Format A null-terminated ASCII format string. See Print Library + @param Format A null-terminated ASCII format string. See Print Library for the supported format string syntax. - @param ... The variable argument list whose contents are accessed based on - the format string specified by Format. + @param ... The variable argument list whose contents are accessed based on + the format string specified by Format. @return The number of ASCII characters printed. @@ -1279,15 +1329,16 @@ AsciiPrintXY ( ... ); + /** Installs and completes the initialization of a Driver Binding Protocol instance. - + Installs the Driver Binding Protocol specified by DriverBinding onto the handle specified by DriverBindingHandle. If DriverBindingHandle is NULL, then DriverBinding is installed onto a newly created handle. DriverBindingHandle is typically the same as the driver's ImageHandle, but it can be different if the driver produces multiple - Driver Binding Protocols. - If DriverBinding is NULL, then ASSERT(). + Driver Binding Protocols. + If DriverBinding is NULL, then ASSERT(). If DriverBinding can not be installed onto a handle, then ASSERT(). @param ImageHandle The image handle of the driver. @@ -1312,6 +1363,25 @@ EfiLibInstallDriverBinding ( /** + Uninstalls a Driver Binding Protocol instance. + + If DriverBinding is NULL, then ASSERT(). + If DriverBinding can not be uninstalled, then ASSERT(). + + @param DriverBinding A Driver Binding Protocol instance that this driver produced. + + @retval EFI_SUCCESS The protocol uninstallation successfully completed. + @retval Others Status from gBS->UninstallMultipleProtocolInterfaces(). + +**/ +EFI_STATUS +EFIAPI +EfiLibUninstallDriverBinding ( + IN EFI_DRIVER_BINDING_PROTOCOL *DriverBinding + ); + + +/** Installs and completes the initialization of a Driver Binding Protocol instance and optionally installs the Component Name, Driver Configuration and Driver Diagnostics Protocols. @@ -1320,10 +1390,10 @@ EfiLibInstallDriverBinding ( Protocols onto the driver's DriverBindingHandle. If DriverBindingHandle is NULL, then the protocols are installed onto a newly created handle. DriverBindingHandle is typically the same as the driver's ImageHandle, but it can be different if the - driver produces multiple Driver Binding Protocols. - If DriverBinding is NULL, then ASSERT(). + driver produces multiple Driver Binding Protocols. + If DriverBinding is NULL, then ASSERT(). If the installation fails, then ASSERT(). - + @param ImageHandle The image handle of the driver. @param SystemTable The EFI System Table that was passed to the driver's entry point. @param DriverBinding A Driver Binding Protocol instance that this driver is producing. @@ -1350,6 +1420,31 @@ EfiLibInstallAllDriverProtocols ( ); +/** + Uninstalls a Driver Binding Protocol instance and optionally uninstalls the + Component Name, Driver Configuration and Driver Diagnostics Protocols. + + If DriverBinding is NULL, then ASSERT(). + If the uninstallation fails, then ASSERT(). + + @param DriverBinding A Driver Binding Protocol instance that this driver produced. + @param ComponentName A Component Name Protocol instance that this driver produced. + @param DriverConfiguration A Driver Configuration Protocol instance that this driver produced. + @param DriverDiagnostics A Driver Diagnostics Protocol instance that this driver produced. + + @retval EFI_SUCCESS The protocol uninstallation successfully completed. + @retval Others Status from gBS->UninstallMultipleProtocolInterfaces(). + +**/ +EFI_STATUS +EFIAPI +EfiLibUninstallAllDriverProtocols ( + IN EFI_DRIVER_BINDING_PROTOCOL *DriverBinding, + IN CONST EFI_COMPONENT_NAME_PROTOCOL *ComponentName, OPTIONAL + IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL *DriverConfiguration, OPTIONAL + IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL *DriverDiagnostics OPTIONAL + ); + /** Installs Driver Binding Protocol with optional Component Name and Component Name 2 Protocols. @@ -1358,8 +1453,8 @@ EfiLibInstallAllDriverProtocols ( optional Component Name and optional Component Name 2 protocols onto the driver's DriverBindingHandle. If DriverBindingHandle is NULL, then the protocols are installed onto a newly created handle. DriverBindingHandle is typically the same as the driver's - ImageHandle, but it can be different if the driver produces multiple Driver Binding Protocols. - If DriverBinding is NULL, then ASSERT(). + ImageHandle, but it can be different if the driver produces multiple Driver Binding Protocols. + If DriverBinding is NULL, then ASSERT(). If the installation fails, then ASSERT(). @param ImageHandle The image handle of the driver. @@ -1387,6 +1482,29 @@ EfiLibInstallDriverBindingComponentName2 ( /** + Uninstalls Driver Binding Protocol with optional Component Name and Component Name 2 Protocols. + + If DriverBinding is NULL, then ASSERT(). + If the uninstallation fails, then ASSERT(). + + @param DriverBinding A Driver Binding Protocol instance that this driver produced. + @param ComponentName A Component Name Protocol instance that this driver produced. + @param ComponentName2 A Component Name 2 Protocol instance that this driver produced. + + @retval EFI_SUCCESS The protocol installation successfully completed. + @retval Others Status from gBS->UninstallMultipleProtocolInterfaces(). + +**/ +EFI_STATUS +EFIAPI +EfiLibUninstallDriverBindingComponentName2 ( + IN EFI_DRIVER_BINDING_PROTOCOL *DriverBinding, + IN CONST EFI_COMPONENT_NAME_PROTOCOL *ComponentName, OPTIONAL + IN CONST EFI_COMPONENT_NAME2_PROTOCOL *ComponentName2 OPTIONAL + ); + + +/** Installs Driver Binding Protocol with optional Component Name, Component Name 2, Driver Configuration, Driver Configuration 2, Driver Diagnostics, and Driver Diagnostics 2 Protocols. @@ -1394,8 +1512,8 @@ EfiLibInstallDriverBindingComponentName2 ( Component Name, optional Component Name 2, optional Driver Configuration, optional Driver Configuration 2, optional Driver Diagnostic, and optional Driver Diagnostic 2 Protocols onto the driver's DriverBindingHandle. DriverBindingHandle is typically the same as the driver's ImageHandle, but it can be different if the driver - produces multiple Driver Binding Protocols. - If DriverBinding is NULL, then ASSERT(). + produces multiple Driver Binding Protocols. + If DriverBinding is NULL, then ASSERT(). If the installation fails, then ASSERT(). @@ -1430,25 +1548,59 @@ EfiLibInstallAllDriverProtocols2 ( IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL *DriverDiagnostics2 OPTIONAL ); -/** + +/** + Uninstalls Driver Binding Protocol with optional Component Name, Component Name 2, Driver + Configuration, Driver Configuration 2, Driver Diagnostics, and Driver Diagnostics 2 Protocols. + + If DriverBinding is NULL, then ASSERT(). + If the installation fails, then ASSERT(). + + + @param DriverBinding A Driver Binding Protocol instance that this driver produced. + @param ComponentName A Component Name Protocol instance that this driver produced. + @param ComponentName2 A Component Name 2 Protocol instance that this driver produced. + @param DriverConfiguration A Driver Configuration Protocol instance that this driver produced. + @param DriverConfiguration2 A Driver Configuration Protocol 2 instance that this driver produced. + @param DriverDiagnostics A Driver Diagnostics Protocol instance that this driver produced. + @param DriverDiagnostics2 A Driver Diagnostics Protocol 2 instance that this driver produced. + + @retval EFI_SUCCESS The protocol uninstallation successfully completed. + @retval Others Status from gBS->UninstallMultipleProtocolInterfaces(). + +**/ +EFI_STATUS +EFIAPI +EfiLibUninstallAllDriverProtocols2 ( + IN EFI_DRIVER_BINDING_PROTOCOL *DriverBinding, + IN CONST EFI_COMPONENT_NAME_PROTOCOL *ComponentName, OPTIONAL + IN CONST EFI_COMPONENT_NAME2_PROTOCOL *ComponentName2, OPTIONAL + IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL *DriverConfiguration, OPTIONAL + IN CONST EFI_DRIVER_CONFIGURATION2_PROTOCOL *DriverConfiguration2, OPTIONAL + IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL *DriverDiagnostics, OPTIONAL + IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL *DriverDiagnostics2 OPTIONAL + ); + + +/** Appends a formatted Unicode string to a Null-terminated Unicode string - - This function appends a formatted Unicode string to the Null-terminated + + This function appends a formatted Unicode string to the Null-terminated Unicode string specified by String. String is optional and may be NULL. - Storage for the formatted Unicode string returned is allocated using + Storage for the formatted Unicode string returned is allocated using AllocatePool(). The pointer to the appended string is returned. The caller is responsible for freeing the returned string. - + If String is not NULL and not aligned on a 16-bit boundary, then ASSERT(). If FormatString is NULL, then ASSERT(). If FormatString is not aligned on a 16-bit boundary, then ASSERT(). - + @param[in] String A Null-terminated Unicode string. @param[in] FormatString A Null-terminated Unicode format string. @param[in] Marker VA_LIST marker for the variable argument list. @retval NULL There was not enough available memory. - @return Null-terminated Unicode string is that is the formatted + @return Null-terminated Unicode string is that is the formatted string appended to String. **/ CHAR16* @@ -1459,27 +1611,27 @@ CatVSPrint ( IN VA_LIST Marker ); -/** +/** Appends a formatted Unicode string to a Null-terminated Unicode string - - This function appends a formatted Unicode string to the Null-terminated + + This function appends a formatted Unicode string to the Null-terminated Unicode string specified by String. String is optional and may be NULL. - Storage for the formatted Unicode string returned is allocated using + Storage for the formatted Unicode string returned is allocated using AllocatePool(). The pointer to the appended string is returned. The caller is responsible for freeing the returned string. - + If String is not NULL and not aligned on a 16-bit boundary, then ASSERT(). If FormatString is NULL, then ASSERT(). If FormatString is not aligned on a 16-bit boundary, then ASSERT(). - + @param[in] String A Null-terminated Unicode string. @param[in] FormatString A Null-terminated Unicode format string. - @param[in] ... The variable argument list whose contents are - accessed based on the format string specified by + @param[in] ... The variable argument list whose contents are + accessed based on the format string specified by FormatString. @retval NULL There was not enough available memory. - @return Null-terminated Unicode string is that is the formatted + @return Null-terminated Unicode string is that is the formatted string appended to String. **/ CHAR16 * @@ -1490,4 +1642,173 @@ CatSPrint ( ... ); +/** + Returns an array of protocol instance that matches the given protocol. + + @param[in] Protocol Provides the protocol to search for. + @param[out] NoProtocols The number of protocols returned in Buffer. + @param[out] Buffer A pointer to the buffer to return the requested + array of protocol instances that match Protocol. + The returned buffer is allocated using + EFI_BOOT_SERVICES.AllocatePool(). The caller is + responsible for freeing this buffer with + EFI_BOOT_SERVICES.FreePool(). + + @retval EFI_SUCCESS The array of protocols was returned in Buffer, + and the number of protocols in Buffer was + returned in NoProtocols. + @retval EFI_NOT_FOUND No protocols found. + @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the + matching results. + @retval EFI_INVALID_PARAMETER Protocol is NULL. + @retval EFI_INVALID_PARAMETER NoProtocols is NULL. + @retval EFI_INVALID_PARAMETER Buffer is NULL. + +**/ +EFI_STATUS +EFIAPI +EfiLocateProtocolBuffer ( + IN EFI_GUID *Protocol, + OUT UINTN *NoProtocols, + OUT VOID ***Buffer + ); + +/** + Open or create a file or directory, possibly creating the chain of + directories leading up to the directory. + + EfiOpenFileByDevicePath() first locates EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on + FilePath, and opens the root directory of that filesystem with + EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume(). + + On the remaining device path, the longest initial sequence of + FILEPATH_DEVICE_PATH nodes is node-wise traversed with + EFI_FILE_PROTOCOL.Open(). + + (As a consequence, if OpenMode includes EFI_FILE_MODE_CREATE, and Attributes + includes EFI_FILE_DIRECTORY, and each FILEPATH_DEVICE_PATH specifies a single + pathname component, then EfiOpenFileByDevicePath() ensures that the specified + series of subdirectories exist on return.) + + The EFI_FILE_PROTOCOL identified by the last FILEPATH_DEVICE_PATH node is + output to the caller; intermediate EFI_FILE_PROTOCOL instances are closed. If + there are no FILEPATH_DEVICE_PATH nodes past the node that identifies the + filesystem, then the EFI_FILE_PROTOCOL of the root directory of the + filesystem is output to the caller. If a device path node that is different + from FILEPATH_DEVICE_PATH is encountered relative to the filesystem, the + traversal is stopped with an error, and a NULL EFI_FILE_PROTOCOL is output. + + @param[in,out] FilePath On input, the device path to the file or directory + to open or create. The caller is responsible for + ensuring that the device path pointed-to by FilePath + is well-formed. On output, FilePath points one past + the last node in the original device path that has + been successfully processed. FilePath is set on + output even if EfiOpenFileByDevicePath() returns an + error. + + @param[out] File On error, File is set to NULL. On success, File is + set to the EFI_FILE_PROTOCOL of the root directory + of the filesystem, if there are no + FILEPATH_DEVICE_PATH nodes in FilePath; otherwise, + File is set to the EFI_FILE_PROTOCOL identified by + the last node in FilePath. + + @param[in] OpenMode The OpenMode parameter to pass to + EFI_FILE_PROTOCOL.Open(). + + @param[in] Attributes The Attributes parameter to pass to + EFI_FILE_PROTOCOL.Open(). + + @retval EFI_SUCCESS The file or directory has been opened or + created. + + @retval EFI_INVALID_PARAMETER FilePath is NULL; or File is NULL; or FilePath + contains a device path node, past the node + that identifies + EFI_SIMPLE_FILE_SYSTEM_PROTOCOL, that is not a + FILEPATH_DEVICE_PATH node. + + @retval EFI_OUT_OF_RESOURCES Memory allocation failed. + + @return Error codes propagated from the + LocateDevicePath() and OpenProtocol() boot + services, and from the + EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume() + and EFI_FILE_PROTOCOL.Open() member functions. +**/ +EFI_STATUS +EFIAPI +EfiOpenFileByDevicePath ( + IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, + OUT EFI_FILE_PROTOCOL **File, + IN UINT64 OpenMode, + IN UINT64 Attributes + ); + +/** + This function locates next ACPI table in XSDT/RSDT based on Signature and + previous returned Table. + + If PreviousTable is NULL: + This function will locate the first ACPI table in XSDT/RSDT based on + Signature in gEfiAcpi20TableGuid system configuration table first, and then + gEfiAcpi10TableGuid system configuration table. + This function will locate in XSDT first, and then RSDT. + For DSDT, this function will locate XDsdt in FADT first, and then Dsdt in + FADT. + For FACS, this function will locate XFirmwareCtrl in FADT first, and then + FirmwareCtrl in FADT. + + If PreviousTable is not NULL: + 1. If it could be located in XSDT in gEfiAcpi20TableGuid system configuration + table, then this function will just locate next table in XSDT in + gEfiAcpi20TableGuid system configuration table. + 2. If it could be located in RSDT in gEfiAcpi20TableGuid system configuration + table, then this function will just locate next table in RSDT in + gEfiAcpi20TableGuid system configuration table. + 3. If it could be located in RSDT in gEfiAcpi10TableGuid system configuration + table, then this function will just locate next table in RSDT in + gEfiAcpi10TableGuid system configuration table. + + It's not supported that PreviousTable is not NULL but PreviousTable->Signature + is not same with Signature, NULL will be returned. + + @param Signature ACPI table signature. + @param PreviousTable Pointer to previous returned table to locate next + table, or NULL to locate first table. + + @return Next ACPI table or NULL if not found. + +**/ +EFI_ACPI_COMMON_HEADER * +EFIAPI +EfiLocateNextAcpiTable ( + IN UINT32 Signature, + IN EFI_ACPI_COMMON_HEADER *PreviousTable OPTIONAL + ); + +/** + This function locates first ACPI table in XSDT/RSDT based on Signature. + + This function will locate the first ACPI table in XSDT/RSDT based on + Signature in gEfiAcpi20TableGuid system configuration table first, and then + gEfiAcpi10TableGuid system configuration table. + This function will locate in XSDT first, and then RSDT. + For DSDT, this function will locate XDsdt in FADT first, and then Dsdt in + FADT. + For FACS, this function will locate XFirmwareCtrl in FADT first, and then + FirmwareCtrl in FADT. + + @param Signature ACPI table signature. + + @return First ACPI table or NULL if not found. + +**/ +EFI_ACPI_COMMON_HEADER * +EFIAPI +EfiLocateFirstAcpiTable ( + IN UINT32 Signature + ); + #endif diff --git a/MdePkg/Include/Library/UefiRuntimeLib.h b/MdePkg/Include/Library/UefiRuntimeLib.h index 03d7fb768f20..dd2576bb7d5c 100644 --- a/MdePkg/Include/Library/UefiRuntimeLib.h +++ b/MdePkg/Include/Library/UefiRuntimeLib.h @@ -2,14 +2,8 @@ Provides library functions for each of the UEFI Runtime Services. Only available to DXE and UEFI module types. -Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> -This program and the accompanying materials are licensed and made available under -the terms and conditions of the BSD License that 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. +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ #ifndef __UEFI_RUNTIME_LIB__ @@ -34,7 +28,7 @@ EfiAtRuntime ( ); /** - This function allows the caller to determine if UEFI SetVirtualAddressMap() has been called. + This function allows the caller to determine if UEFI SetVirtualAddressMap() has been called. This function returns TRUE after all the EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE functions have executed as a result of the OS calling SetVirtualAddressMap(). Prior to this time FALSE @@ -329,9 +323,8 @@ EfiGetNextHighMonotonicCount ( Null-terminated Unicode string, optionally followed by additional binary data. The string is a description that the caller may use to further indicate the reason for the system reset. ResetData is only valid if ResetStatus is something other then EFI_SUCCESS. This pointer must be a physical - address. For a ResetType of EfiRestUpdate the data buffer also starts with a Null-terminated string - that is followed by a physical VOID * to an EFI_CAPSULE_HEADER. - + address. For a ResetType of EfiResetPlatformSpecific the data buffer also starts with a Null-terminated + string that is followed by an EFI_GUID that describes the specific type of reset to perform. **/ VOID EFIAPI @@ -343,7 +336,7 @@ EfiResetSystem ( ); /** - This service is a wrapper for the UEFI Runtime Service ConvertPointer(). + This service is a wrapper for the UEFI Runtime Service ConvertPointer(). The ConvertPointer() function is used by an EFI component during the SetVirtualAddressMap() operation. ConvertPointer()must be called using physical address pointers during the execution of SetVirtualAddressMap(). @@ -371,7 +364,7 @@ EfiConvertPointer ( Determines the new virtual address that is to be used on subsequent memory accesses. For IA32, x64, and EBC, this service is a wrapper for the UEFI Runtime Service - ConvertPointer(). See the UEFI Specification for details. + ConvertPointer(). See the UEFI Specification for details. For IPF, this function interprets Address as a pointer to an EFI_PLABEL structure and both the EntryPoint and GP fields of an EFI_PLABEL are converted from physical to virtiual addressing. Since IPF allows the GP to point to an address outside diff --git a/MdePkg/Include/Library/UefiRuntimeServicesTableLib.h b/MdePkg/Include/Library/UefiRuntimeServicesTableLib.h index 609f2abeea72..daacc2a9e712 100644 --- a/MdePkg/Include/Library/UefiRuntimeServicesTableLib.h +++ b/MdePkg/Include/Library/UefiRuntimeServicesTableLib.h @@ -11,13 +11,7 @@ Only available to DXE and UEFI module types. Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/UefiScsiLib.h b/MdePkg/Include/Library/UefiScsiLib.h index 5257f765845b..d35ee6b097d8 100644 --- a/MdePkg/Include/Library/UefiScsiLib.h +++ b/MdePkg/Include/Library/UefiScsiLib.h @@ -5,14 +5,8 @@ for hard drive, CD and DVD devices that are the most common SCSI boot targets used by UEFI platforms. This library class depends on SCSI I/O Protocol defined in UEFI Specification and SCSI-2 industry standard. -Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR> -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. +Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR> +SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -52,7 +46,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. optional and may be NULL. @param[in, out] SenseDataLength On input, a pointer to the length in bytes of the SenseData buffer. On output, a pointer to - the number of bytes written to the SenseData buffer. + the number of bytes written to the SenseData buffer. @param[out] HostAdapterStatus The status of the SCSI Host Controller that produces the SCSI bus containing the SCSI target specified by ScsiIo when the SCSI Request Packet was executed. @@ -62,7 +56,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. by ScsiIo when the SCSI Request Packet was executed on the SCSI Host Controller. See the EFI SCSI I/O Protocol in the UEFI Specification for details on - the possible return values. + the possible return values. @retval EFI_SUCCESS The command was executed successfully. See HostAdapterStatus, TargetStatus, SenseDataLength, @@ -135,7 +129,7 @@ ScsiTestUnitReadyCommand ( If SenseDataLength is 0, then this parameter is optional and may be NULL. @param[in, out] SenseDataLength On input, the length in bytes of the SenseData buffer. - On output, the number of bytes written to the SenseData buffer. + On output, the number of bytes written to the SenseData buffer. @param[out] HostAdapterStatus The status of the SCSI Host Controller that produces the SCSI bus containing the SCSI target specified by ScsiIo when the SCSI @@ -147,12 +141,12 @@ ScsiTestUnitReadyCommand ( executed on the SCSI Host Controller. See the EFI SCSI I/O Protocol in the UEFI Specification for details on the possible - return values. + return values. @param[in, out] InquiryDataBuffer A pointer to inquiry data that was generated by the execution of the SCSI Request Packet. This buffer must be allocated by the caller. If InquiryDataLength is 0, then this parameter - is optional and may be NULL. + is optional and may be NULL. @param[in, out] InquiryDataLength On input, a pointer to the length in bytes of the InquiryDataBuffer buffer. On output, a pointer to the number of bytes @@ -160,7 +154,7 @@ ScsiTestUnitReadyCommand ( @param[in] EnableVitalProductData If TRUE, then the supported vital product data is returned in InquiryDataBuffer. If FALSE, then the standard inquiry data is - returned in InquiryDataBuffer. + returned in InquiryDataBuffer. @retval EFI_SUCCESS The command was executed successfully. See HostAdapterStatus, TargetStatus, SenseDataLength, and SenseData in that order @@ -237,7 +231,7 @@ ScsiInquiryCommand ( If SenseDataLength is 0, then this parameter is optional and may be NULL. @param[in, out] SenseDataLength On input, the length in bytes of the SenseData buffer. - On output, the number of bytes written to the SenseData buffer. + On output, the number of bytes written to the SenseData buffer. @param[out] HostAdapterStatus The status of the SCSI Host Controller that produces the SCSI bus containing the SCSI target specified by ScsiIo when the SCSI @@ -249,12 +243,12 @@ ScsiInquiryCommand ( executed on the SCSI Host Controller. See the EFI SCSI I/O Protocol in the UEFI Specification for details on the possible - return values. + return values. @param[in, out] InquiryDataBuffer A pointer to inquiry data that was generated by the execution of the SCSI Request Packet. This buffer must be allocated by the caller. If InquiryDataLength is 0, then this parameter - is optional and may be NULL. + is optional and may be NULL. @param[in, out] InquiryDataLength On input, a pointer to the length in bytes of the InquiryDataBuffer buffer. On output, a pointer to the number of bytes @@ -344,7 +338,7 @@ ScsiInquiryCommandEx ( If SenseDataLength is 0, then this parameter is optional and may be NULL. @param[in, out] SenseDataLength On input, the length in bytes of the SenseData buffer. - On output, the number of bytes written to the SenseData buffer. + On output, the number of bytes written to the SenseData buffer. @param[out] HostAdapterStatus The status of the SCSI Host Controller that produces the SCSI bus containing the SCSI target specified by ScsiIo when the SCSI Request Packet @@ -360,14 +354,14 @@ ScsiInquiryCommandEx ( execution of the SCSI Request Packet. This buffer must be allocated by the caller. If DataLength is 0, then this parameter is optional - and may be NULL. + and may be NULL. @param[in, out] DataLength On input, a pointer to the length in bytes of the DataBuffer buffer. On output, a pointer to the number of bytes written to the DataBuffer - buffer. + buffer. @param[in] DBDField Specifies the DBD field of the CDB for this SCSI Command. - @param[in] PageControl Specifies the PC field of the CDB for this SCSI Command. - @param[in] PageCode Specifies the Page Control field of the CDB for this SCSI Command. + @param[in] PageControl Specifies the PC field of the CDB for this SCSI Command. + @param[in] PageCode Specifies the Page Control field of the CDB for this SCSI Command. @retval EFI_SUCCESS The command was executed successfully. See HostAdapterStatus, TargetStatus, SenseDataLength, @@ -820,6 +814,134 @@ ScsiWrite16Command ( /** + Execute Security Protocol In SCSI command on a specific SCSI target. + + Executes the SCSI Security Protocol In command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after + Timeout 100 ns units. + If ScsiIo is NULL, then ASSERT(). + If SenseDataLength is NULL, then ASSERT(). + If HostAdapterStatus is NULL, then ASSERT(). + If TargetStatus is NULL, then ASSERT(). + If TransferLength is NULL, then ASSERT(). + + If SenseDataLength is non-zero and SenseData is not NULL, SenseData must meet buffer + alignment requirement defined in EFI_SCSI_IO_PROTOCOL. Otherwise EFI_INVALID_PARAMETER + gets returned. + + If DataLength is non-zero and DataBuffer is not NULL, DataBuffer must meet buffer + alignment requirement defined in EFI_SCSI_IO_PROTOCOL. Otherwise EFI_INVALID_PARAMETER + gets returned. + + @param[in] ScsiIo SCSI IO Protocol to use. + @param[in] Timeout The length of timeout period. + @param[in, out] SenseData A pointer to output sense data. + @param[in, out] SenseDataLength The length of output sense data. + @param[out] HostAdapterStatus The status of Host Adapter. + @param[out] TargetStatus The status of the target. + @param[in] SecurityProtocol The Security Protocol to use. + @param[in] SecurityProtocolSpecific The Security Protocol Specific data. + @param[in] Inc512 If TRUE, 512 increment (INC_512) bit will be set for the + SECURITY PROTOCOL IN command. + @param[in] DataLength The size in bytes of the data buffer. + @param[in, out] DataBuffer A pointer to a data buffer. + @param[out] TransferLength A pointer to a buffer to store the size in + bytes of the data written to the data buffer. + + @retval EFI_SUCCESS Command is executed successfully. + @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was executed, but the entire DataBuffer could + not be transferred. The actual number of bytes transferred is returned in TransferLength. + @retval EFI_NOT_READY The SCSI Request Packet could not be sent because there are too many + SCSI Command Packets already queued. + @retval EFI_DEVICE_ERROR A device error occurred while attempting to send SCSI Request Packet. + @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet is not supported by + the SCSI initiator(i.e., SCSI Host Controller) + @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI Request Packet to execute. + @retval EFI_INVALID_PARAMETER The contents of the SCSI Request Packet are invalid. + +**/ +EFI_STATUS +EFIAPI +ScsiSecurityProtocolInCommand ( + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN UINT8 SecurityProtocol, + IN UINT16 SecurityProtocolSpecific, + IN BOOLEAN Inc512, + IN UINTN DataLength, + IN OUT VOID *DataBuffer, OPTIONAL + OUT UINTN *TransferLength + ); + + +/** + Execute Security Protocol Out SCSI command on a specific SCSI target. + + Executes the SCSI Security Protocol Out command on the SCSI target specified by ScsiIo. + If Timeout is zero, then this function waits indefinitely for the command to complete. + If Timeout is greater than zero, then the command is executed and will timeout after + Timeout 100 ns units. + If ScsiIo is NULL, then ASSERT(). + If SenseDataLength is NULL, then ASSERT(). + If HostAdapterStatus is NULL, then ASSERT(). + If TargetStatus is NULL, then ASSERT(). + + If SenseDataLength is non-zero and SenseData is not NULL, SenseData must meet buffer + alignment requirement defined in EFI_SCSI_IO_PROTOCOL. Otherwise EFI_INVALID_PARAMETER + gets returned. + + If DataLength is non-zero and DataBuffer is not NULL, DataBuffer must meet buffer + alignment requirement defined in EFI_SCSI_IO_PROTOCOL. Otherwise EFI_INVALID_PARAMETER + gets returned. + + @param[in] ScsiIo SCSI IO Protocol to use. + @param[in] Timeout The length of timeout period. + @param[in, out] SenseData A pointer to output sense data. + @param[in, out] SenseDataLength The length of output sense data. + @param[out] HostAdapterStatus The status of Host Adapter. + @param[out] TargetStatus The status of the target. + @param[in] SecurityProtocol The Security Protocol to use. + @param[in] SecurityProtocolSpecific The Security Protocol Specific data. + @param[in] Inc512 If TRUE, 512 increment (INC_512) bit will be set for the + SECURITY PROTOCOL OUT command. + @param[in] DataLength The size in bytes of the transfer data. + @param[in, out] DataBuffer A pointer to a data buffer. + + @retval EFI_SUCCESS Command is executed successfully. + @retval EFI_BAD_BUFFER_SIZE The SCSI Request Packet was executed, but the entire DataBuffer could + not be transferred. The actual number of bytes transferred is returned in DataLength. + @retval EFI_NOT_READY The SCSI Request Packet could not be sent because there are too many + SCSI Command Packets already queued. + @retval EFI_DEVICE_ERROR A device error occurred while attempting to send SCSI Request Packet. + @retval EFI_UNSUPPORTED The command described by the SCSI Request Packet is not supported by + the SCSI initiator(i.e., SCSI Host Controller) + @retval EFI_TIMEOUT A timeout occurred while waiting for the SCSI Request Packet to execute. + @retval EFI_INVALID_PARAMETER The contents of the SCSI Request Packet are invalid. + +**/ +EFI_STATUS +EFIAPI +ScsiSecurityProtocolOutCommand ( + IN EFI_SCSI_IO_PROTOCOL *ScsiIo, + IN UINT64 Timeout, + IN OUT VOID *SenseData, OPTIONAL + IN OUT UINT8 *SenseDataLength, + OUT UINT8 *HostAdapterStatus, + OUT UINT8 *TargetStatus, + IN UINT8 SecurityProtocol, + IN UINT16 SecurityProtocolSpecific, + IN BOOLEAN Inc512, + IN UINTN DataLength, + IN OUT VOID *DataBuffer OPTIONAL + ); + + +/** Execute blocking/non-blocking Read(10) SCSI command on a specific SCSI target. diff --git a/MdePkg/Include/Library/UefiUsbLib.h b/MdePkg/Include/Library/UefiUsbLib.h index a2eab6961125..256c060ea7c3 100644 --- a/MdePkg/Include/Library/UefiUsbLib.h +++ b/MdePkg/Include/Library/UefiUsbLib.h @@ -3,13 +3,7 @@ and the standard requests defined in USB 1.1 spec. Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> -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. +SPDX-License-Identifier: BSD-2-Clause-Patent **/ diff --git a/MdePkg/Include/Library/UnitTestLib.h b/MdePkg/Include/Library/UnitTestLib.h new file mode 100644 index 000000000000..b176a9556335 --- /dev/null +++ b/MdePkg/Include/Library/UnitTestLib.h @@ -0,0 +1,757 @@ +/** @file + Provides a unit test framework. This allows tests to focus on testing logic + and the framework to focus on runnings, reporting, statistics, etc. + + Copyright (c) Microsoft Corporation.<BR> + Copyright (c) 2020, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent +**/ + +#ifndef __UNIT_TEST_LIB_H__ +#define __UNIT_TEST_LIB_H__ + +/// +/// Unit Test Status +/// +typedef UINT32 UNIT_TEST_STATUS; +#define UNIT_TEST_PASSED (0) +#define UNIT_TEST_ERROR_PREREQUISITE_NOT_MET (1) +#define UNIT_TEST_ERROR_TEST_FAILED (2) +#define UNIT_TEST_ERROR_CLEANUP_FAILED (3) +#define UNIT_TEST_SKIPPED (0xFFFFFFFD) +#define UNIT_TEST_RUNNING (0xFFFFFFFE) +#define UNIT_TEST_PENDING (0xFFFFFFFF) + +/// +/// Declare PcdUnitTestLogLevel bits and UnitTestLog() ErrorLevel parameter. +/// +#define UNIT_TEST_LOG_LEVEL_ERROR BIT0 +#define UNIT_TEST_LOG_LEVEL_WARN BIT1 +#define UNIT_TEST_LOG_LEVEL_INFO BIT2 +#define UNIT_TEST_LOG_LEVEL_VERBOSE BIT3 + +/// +/// Unit Test Framework Handle +/// +struct UNIT_TEST_FRAMEWORK_OBJECT; +typedef struct UNIT_TEST_FRAMEWORK_OBJECT *UNIT_TEST_FRAMEWORK_HANDLE; + +/// +/// Unit Test Suite Handle +/// +struct UNIT_TEST_SUITE_OBJECT; +typedef struct UNIT_TEST_SUITE_OBJECT *UNIT_TEST_SUITE_HANDLE; + +/// +/// Unit Test Handle +/// +struct UNIT_TEST_OBJECT; +typedef struct UNIT_TEST_OBJECT *UNIT_TEST_HANDLE; + +/// +/// Unit Test Context +/// +typedef VOID* UNIT_TEST_CONTEXT; + +/** + The prototype for a single UnitTest case function. + + Functions with this prototype are registered to be dispatched by the + UnitTest framework, and results are recorded as test Pass or Fail. + + @param[in] Context [Optional] An optional parameter that enables: + 1) test-case reuse with varied parameters and + 2) test-case re-entry for Target tests that need a + reboot. This parameter is a VOID* and it is the + responsibility of the test author to ensure that the + contents are well understood by all test cases that may + consume it. + + @retval UNIT_TEST_PASSED The Unit test has completed and the test + case was successful. + @retval UNIT_TEST_ERROR_TEST_FAILED A test case assertion has failed. + +**/ +typedef +UNIT_TEST_STATUS +(EFIAPI *UNIT_TEST_FUNCTION)( + IN UNIT_TEST_CONTEXT Context + ); + +/** + Unit-Test Prerequisite Function pointer type. + + Functions with this prototype are registered to be dispatched by the unit test + framework prior to a given test case. If this prereq function returns + UNIT_TEST_ERROR_PREREQUISITE_NOT_MET, the test case will be skipped. + + @param[in] Context [Optional] An optional parameter that enables: + 1) test-case reuse with varied parameters and + 2) test-case re-entry for Target tests that need a + reboot. This parameter is a VOID* and it is the + responsibility of the test author to ensure that the + contents are well understood by all test cases that may + consume it. + + @retval UNIT_TEST_PASSED Unit test case prerequisites + are met. + @retval UNIT_TEST_ERROR_PREREQUISITE_NOT_MET Test case should be skipped. + +**/ +typedef +UNIT_TEST_STATUS +(EFIAPI *UNIT_TEST_PREREQUISITE)( + IN UNIT_TEST_CONTEXT Context + ); + +/** + Unit-Test Cleanup (after) function pointer type. + + Functions with this prototype are registered to be dispatched by the + unit test framework after a given test case. This will be called even if the + test case returns an error, but not if the prerequisite fails and the test is + skipped. The purpose of this function is to clean up any global state or + test data. + + @param[in] Context [Optional] An optional parameter that enables: + 1) test-case reuse with varied parameters and + 2) test-case re-entry for Target tests that need a + reboot. This parameter is a VOID* and it is the + responsibility of the test author to ensure that the + contents are well understood by all test cases that may + consume it. + + @retval UNIT_TEST_PASSED Test case cleanup succeeded. + @retval UNIT_TEST_ERROR_CLEANUP_FAILED Test case cleanup failed. + +**/ +typedef +VOID +(EFIAPI *UNIT_TEST_CLEANUP)( + IN UNIT_TEST_CONTEXT Context + ); + +/** + Unit-Test Test Suite Setup (before) function pointer type. Functions with this + prototype are registered to be dispatched by the UnitTest framework prior to + running any of the test cases in a test suite. It will only be run once at + the beginning of the suite (not prior to each case). + + The purpose of this function is to set up any global state or test data. +**/ +typedef +VOID +(EFIAPI *UNIT_TEST_SUITE_SETUP)( + VOID + ); + +/** + Unit-Test Test Suite Teardown (after) function pointer type. Functions with + this prototype are registered to be dispatched by the UnitTest framework after + running all of the test cases in a test suite. It will only be run once at + the end of the suite. + + The purpose of this function is to clean up any global state or test data. +**/ +typedef +VOID +(EFIAPI *UNIT_TEST_SUITE_TEARDOWN)( + VOID + ); + +/** + Method to Initialize the Unit Test framework. This function registers the + test name and also initializes the internal state of the test framework to + receive any new suites and tests. + + @param[out] FrameworkHandle Unit test framework to be created. + @param[in] Title Null-terminated ASCII string that is the user + friendly name of the framework. String is + copied. + @param[in] ShortTitle Null-terminated ASCII short string that is the + short name of the framework with no spaces. + String is copied. + @param[in] VersionString Null-terminated ASCII version string for the + framework. String is copied. + + @retval EFI_SUCCESS The unit test framework was initialized. + @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. + @retval EFI_INVALID_PARAMETER Title is NULL. + @retval EFI_INVALID_PARAMETER ShortTitle is NULL. + @retval EFI_INVALID_PARAMETER VersionString is NULL. + @retval EFI_INVALID_PARAMETER ShortTitle is invalid. + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to + initialize the unit test framework. +**/ +EFI_STATUS +EFIAPI +InitUnitTestFramework ( + OUT UNIT_TEST_FRAMEWORK_HANDLE *FrameworkHandle, + IN CHAR8 *Title, + IN CHAR8 *ShortTitle, + IN CHAR8 *VersionString + ); + +/** + Registers a Unit Test Suite in the Unit Test Framework. + At least one test suite must be registered, because all test cases must be + within a unit test suite. + + @param[out] SuiteHandle Unit test suite to create + @param[in] FrameworkHandle Unit test framework to add unit test suite to + @param[in] Title Null-terminated ASCII string that is the user + friendly name of the test suite. String is + copied. + @param[in] Name Null-terminated ASCII string that is the short + name of the test suite with no spaces. String + is copied. + @param[in] Setup Setup function, runs before suite. This is an + optional parameter that may be NULL. + @param[in] Teardown Teardown function, runs after suite. This is an + optional parameter that may be NULL. + + @retval EFI_SUCCESS The unit test suite was created. + @retval EFI_INVALID_PARAMETER SuiteHandle is NULL. + @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. + @retval EFI_INVALID_PARAMETER Title is NULL. + @retval EFI_INVALID_PARAMETER Name is NULL. + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to + initialize the unit test suite. +**/ +EFI_STATUS +EFIAPI +CreateUnitTestSuite ( + OUT UNIT_TEST_SUITE_HANDLE *SuiteHandle, + IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle, + IN CHAR8 *Title, + IN CHAR8 *Name, + IN UNIT_TEST_SUITE_SETUP Setup OPTIONAL, + IN UNIT_TEST_SUITE_TEARDOWN Teardown OPTIONAL + ); + +/** + Adds test case to Suite + + @param[in] SuiteHandle Unit test suite to add test to. + @param[in] Description Null-terminated ASCII string that is the user + friendly description of a test. String is copied. + @param[in] Name Null-terminated ASCII string that is the short name + of the test with no spaces. String is copied. + @param[in] Function Unit test function. + @param[in] Prerequisite Prerequisite function, runs before test. This is + an optional parameter that may be NULL. + @param[in] CleanUp Clean up function, runs after test. This is an + optional parameter that may be NULL. + @param[in] Context Pointer to context. This is an optional parameter + that may be NULL. + + @retval EFI_SUCCESS The unit test case was added to Suite. + @retval EFI_INVALID_PARAMETER SuiteHandle is NULL. + @retval EFI_INVALID_PARAMETER Description is NULL. + @retval EFI_INVALID_PARAMETER Name is NULL. + @retval EFI_INVALID_PARAMETER Function is NULL. + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to + add the unit test case to Suite. +**/ +EFI_STATUS +EFIAPI +AddTestCase ( + IN UNIT_TEST_SUITE_HANDLE SuiteHandle, + IN CHAR8 *Description, + IN CHAR8 *Name, + IN UNIT_TEST_FUNCTION Function, + IN UNIT_TEST_PREREQUISITE Prerequisite OPTIONAL, + IN UNIT_TEST_CLEANUP CleanUp OPTIONAL, + IN UNIT_TEST_CONTEXT Context OPTIONAL + ); + +/** + Execute all unit test cases in all unit test suites added to a Framework. + + Once a unit test framework is initialized and all unit test suites and unit + test cases are registered, this function will cause the unit test framework to + dispatch all unit test cases in sequence and record the results for reporting. + + @param[in] FrameworkHandle A handle to the current running framework that + dispatched the test. Necessary for recording + certain test events with the framework. + + @retval EFI_SUCCESS All test cases were dispatched. + @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. +**/ +EFI_STATUS +EFIAPI +RunAllTestSuites ( + IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle + ); + +/** + Cleanup a test framework. + + After tests are run, this will teardown the entire framework and free all + allocated data within. + + @param[in] FrameworkHandle A handle to the current running framework that + dispatched the test. Necessary for recording + certain test events with the framework. + + @retval EFI_SUCCESS All resources associated with framework were + freed. + @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. +**/ +EFI_STATUS +EFIAPI +FreeUnitTestFramework ( + IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle + ); + +/** + Leverages a framework-specific mechanism (see UnitTestPersistenceLib if you're + a framework author) to save the state of the executing framework along with + any allocated data so that the test may be resumed upon reentry. A test case + should pass any needed context (which, to prevent an infinite loop, should be + at least the current execution count) which will be saved by the framework and + passed to the test case upon resume. + + Generally called from within a test case prior to quitting or rebooting. + + @param[in] FrameworkHandle A handle to the current running framework that + dispatched the test. Necessary for recording + certain test events with the framework. + @param[in] ContextToSave A buffer of test case-specific data to be saved + along with framework state. Will be passed as + "Context" to the test case upon resume. This + is an optional parameter that may be NULL. + @param[in] ContextToSaveSize Size of the ContextToSave buffer. + + @retval EFI_SUCCESS The framework state and context were saved. + @retval EFI_INVALID_PARAMETER FrameworkHandle is NULL. + @retval EFI_INVALID_PARAMETER ContextToSave is not NULL and + ContextToSaveSize is 0. + @retval EFI_INVALID_PARAMETER ContextToSave is >= 4GB. + @retval EFI_OUT_OF_RESOURCES There are not enough resources available to + save the framework and context state. + @retval EFI_DEVICE_ERROR The framework and context state could not be + saved to a persistent storage device due to a + device error. +**/ +EFI_STATUS +EFIAPI +SaveFrameworkState ( + IN UNIT_TEST_FRAMEWORK_HANDLE FrameworkHandle, + IN UNIT_TEST_CONTEXT ContextToSave OPTIONAL, + IN UINTN ContextToSaveSize + ); + +/** + This macro uses the framework assertion logic to check an expression for + "TRUE". If the expression evaluates to TRUE, execution continues. + Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. + + @param[in] Expression Expression to be evaluated for TRUE. +**/ +#define UT_ASSERT_TRUE(Expression) \ + if(!UnitTestAssertTrue ((Expression), __FUNCTION__, __LINE__, __FILE__, #Expression)) { \ + return UNIT_TEST_ERROR_TEST_FAILED; \ + } + +/** + This macro uses the framework assertion logic to check an expression for + "FALSE". If the expression evaluates to FALSE, execution continues. + Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. + + @param[in] Expression Expression to be evaluated for FALSE. +**/ +#define UT_ASSERT_FALSE(Expression) \ + if(!UnitTestAssertFalse ((Expression), __FUNCTION__, __LINE__, __FILE__, #Expression)) { \ + return UNIT_TEST_ERROR_TEST_FAILED; \ + } + +/** + This macro uses the framework assertion logic to check whether two simple + values are equal. If the values are equal, execution continues. + Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. + + @param[in] ValueA Value to be compared for equality (64-bit comparison). + @param[in] ValueB Value to be compared for equality (64-bit comparison). +**/ +#define UT_ASSERT_EQUAL(ValueA, ValueB) \ + if(!UnitTestAssertEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, __LINE__, __FILE__, #ValueA, #ValueB)) { \ + return UNIT_TEST_ERROR_TEST_FAILED; \ + } + +/** + This macro uses the framework assertion logic to check whether two memory + buffers are equal. If the buffers are equal, execution continues. + Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. + + @param[in] BufferA Pointer to a buffer for comparison. + @param[in] BufferB Pointer to a buffer for comparison. + @param[in] Length Number of bytes to compare in BufferA and BufferB. +**/ +#define UT_ASSERT_MEM_EQUAL(BufferA, BufferB, Length) \ + if(!UnitTestAssertMemEqual ((VOID *)(UINTN)(BufferA), (VOID *)(UINTN)(BufferB), (UINTN)Length, __FUNCTION__, __LINE__, __FILE__, #BufferA, #BufferB)) { \ + return UNIT_TEST_ERROR_TEST_FAILED; \ + } + +/** + This macro uses the framework assertion logic to check whether two simple + values are non-equal. If the values are non-equal, execution continues. + Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. + + @param[in] ValueA Value to be compared for inequality (64-bit comparison). + @param[in] ValueB Value to be compared for inequality (64-bit comparison). +**/ +#define UT_ASSERT_NOT_EQUAL(ValueA, ValueB) \ + if(!UnitTestAssertNotEqual ((UINT64)(ValueA), (UINT64)(ValueB), __FUNCTION__, __LINE__, __FILE__, #ValueA, #ValueB)) { \ + return UNIT_TEST_ERROR_TEST_FAILED; \ + } + +/** + This macro uses the framework assertion logic to check whether an EFI_STATUS + value is !EFI_ERROR(). If the status is !EFI_ERROR(), execution continues. + Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. + + @param[in] Status EFI_STATUS value to check. +**/ +#define UT_ASSERT_NOT_EFI_ERROR(Status) \ + if(!UnitTestAssertNotEfiError ((Status), __FUNCTION__, __LINE__, __FILE__, #Status)) { \ + return UNIT_TEST_ERROR_TEST_FAILED; \ + } + +/** + This macro uses the framework assertion logic to check whether two EFI_STATUS + values are equal. If the values are equal, execution continues. + Otherwise, the test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. + + @param[in] Status EFI_STATUS values to compare for equality. + @param[in] Expected EFI_STATUS values to compare for equality. +**/ +#define UT_ASSERT_STATUS_EQUAL(Status, Expected) \ + if(!UnitTestAssertStatusEqual ((Status), (Expected), __FUNCTION__, __LINE__, __FILE__, #Status)) { \ + return UNIT_TEST_ERROR_TEST_FAILED; \ + } + +/** + This macro uses the framework assertion logic to check whether a pointer is + not NULL. If the pointer is not NULL, execution continues. Otherwise, the + test case immediately returns UNIT_TEST_ERROR_TEST_FAILED. + + @param[in] Pointer Pointer to be checked against NULL. +**/ +#define UT_ASSERT_NOT_NULL(Pointer) \ + if(!UnitTestAssertNotNull ((Pointer), __FUNCTION__, __LINE__, __FILE__, #Pointer)) { \ + return UNIT_TEST_ERROR_TEST_FAILED; \ + } + +/** + If Expression is TRUE, then TRUE is returned. + If Expression is FALSE, then an assert is triggered and the location of the + assert provided by FunctionName, LineNumber, FileName, and Description are + recorded and FALSE is returned. + + @param[in] Expression The BOOLEAN result of the expression evaluation. + @param[in] FunctionName Null-terminated ASCII string of the function + executing the assert macro. + @param[in] LineNumber The source file line number of the assert macro. + @param[in] FileName Null-terminated ASCII string of the filename + executing the assert macro. + @param[in] Description Null-terminated ASCII string of the expression being + evaluated. + + @retval TRUE Expression is TRUE. + @retval FALSE Expression is FALSE. +**/ +BOOLEAN +EFIAPI +UnitTestAssertTrue ( + IN BOOLEAN Expression, + IN CONST CHAR8 *FunctionName, + IN UINTN LineNumber, + IN CONST CHAR8 *FileName, + IN CONST CHAR8 *Description + ); + +/** + If Expression is FALSE, then TRUE is returned. + If Expression is TRUE, then an assert is triggered and the location of the + assert provided by FunctionName, LineNumber, FileName, and Description are + recorded and FALSE is returned. + + @param[in] Expression The BOOLEAN result of the expression evaluation. + @param[in] FunctionName Null-terminated ASCII string of the function + executing the assert macro. + @param[in] LineNumber The source file line number of the assert macro. + @param[in] FileName Null-terminated ASCII string of the filename + executing the assert macro. + @param[in] Description Null-terminated ASCII string of the expression being + evaluated. + + @retval TRUE Expression is FALSE. + @retval FALSE Expression is TRUE. +**/ +BOOLEAN +EFIAPI +UnitTestAssertFalse ( + IN BOOLEAN Expression, + IN CONST CHAR8 *FunctionName, + IN UINTN LineNumber, + IN CONST CHAR8 *FileName, + IN CONST CHAR8 *Description + ); + +/** + If Status is not an EFI_ERROR(), then TRUE is returned. + If Status is an EFI_ERROR(), then an assert is triggered and the location of + the assert provided by FunctionName, LineNumber, FileName, and Description are + recorded and FALSE is returned. + + @param[in] Status The EFI_STATUS value to evaluate. + @param[in] FunctionName Null-terminated ASCII string of the function + executing the assert macro. + @param[in] LineNumber The source file line number of the assert macro. + @param[in] FileName Null-terminated ASCII string of the filename + executing the assert macro. + @param[in] Description Null-terminated ASCII string of the status + expression being evaluated. + + @retval TRUE Status is not an EFI_ERROR(). + @retval FALSE Status is an EFI_ERROR(). +**/ +BOOLEAN +EFIAPI +UnitTestAssertNotEfiError ( + IN EFI_STATUS Status, + IN CONST CHAR8 *FunctionName, + IN UINTN LineNumber, + IN CONST CHAR8 *FileName, + IN CONST CHAR8 *Description + ); + +/** + If ValueA is equal ValueB, then TRUE is returned. + If ValueA is not equal to ValueB, then an assert is triggered and the location + of the assert provided by FunctionName, LineNumber, FileName, DescriptionA, + and DescriptionB are recorded and FALSE is returned. + + @param[in] ValueA 64-bit value. + @param[in] ValueB 64-bit value. + @param[in] FunctionName Null-terminated ASCII string of the function + executing the assert macro. + @param[in] LineNumber The source file line number of the assert macro. + @param[in] FileName Null-terminated ASCII string of the filename + executing the assert macro. + @param[in] DescriptionA Null-terminated ASCII string that is a description + of ValueA. + @param[in] DescriptionB Null-terminated ASCII string that is a description + of ValueB. + + @retval TRUE ValueA is equal to ValueB. + @retval FALSE ValueA is not equal to ValueB. +**/ +BOOLEAN +EFIAPI +UnitTestAssertEqual ( + IN UINT64 ValueA, + IN UINT64 ValueB, + IN CONST CHAR8 *FunctionName, + IN UINTN LineNumber, + IN CONST CHAR8 *FileName, + IN CONST CHAR8 *DescriptionA, + IN CONST CHAR8 *DescriptionB + ); + +/** + If the contents of BufferA are identical to the contents of BufferB, then TRUE + is returned. If the contents of BufferA are not identical to the contents of + BufferB, then an assert is triggered and the location of the assert provided + by FunctionName, LineNumber, FileName, DescriptionA, and DescriptionB are + recorded and FALSE is returned. + + @param[in] BufferA Pointer to a buffer for comparison. + @param[in] BufferB Pointer to a buffer for comparison. + @param[in] Length Number of bytes to compare in BufferA and BufferB. + @param[in] FunctionName Null-terminated ASCII string of the function + executing the assert macro. + @param[in] LineNumber The source file line number of the assert macro. + @param[in] FileName Null-terminated ASCII string of the filename + executing the assert macro. + @param[in] DescriptionA Null-terminated ASCII string that is a description + of BufferA. + @param[in] DescriptionB Null-terminated ASCII string that is a description + of BufferB. + + @retval TRUE The contents of BufferA are identical to the contents of + BufferB. + @retval FALSE The contents of BufferA are not identical to the contents of + BufferB. +**/ +BOOLEAN +EFIAPI +UnitTestAssertMemEqual ( + IN VOID *BufferA, + IN VOID *BufferB, + IN UINTN Length, + IN CONST CHAR8 *FunctionName, + IN UINTN LineNumber, + IN CONST CHAR8 *FileName, + IN CONST CHAR8 *DescriptionA, + IN CONST CHAR8 *DescriptionB + ); + +/** + If ValueA is not equal ValueB, then TRUE is returned. + If ValueA is equal to ValueB, then an assert is triggered and the location + of the assert provided by FunctionName, LineNumber, FileName, DescriptionA + and DescriptionB are recorded and FALSE is returned. + + @param[in] ValueA 64-bit value. + @param[in] ValueB 64-bit value. + @param[in] FunctionName Null-terminated ASCII string of the function + executing the assert macro. + @param[in] LineNumber The source file line number of the assert macro. + @param[in] FileName Null-terminated ASCII string of the filename + executing the assert macro. + @param[in] DescriptionA Null-terminated ASCII string that is a description + of ValueA. + @param[in] DescriptionB Null-terminated ASCII string that is a description + of ValueB. + + @retval TRUE ValueA is not equal to ValueB. + @retval FALSE ValueA is equal to ValueB. +**/ +BOOLEAN +EFIAPI +UnitTestAssertNotEqual ( + IN UINT64 ValueA, + IN UINT64 ValueB, + IN CONST CHAR8 *FunctionName, + IN UINTN LineNumber, + IN CONST CHAR8 *FileName, + IN CONST CHAR8 *DescriptionA, + IN CONST CHAR8 *DescriptionB + ); + +/** + If Status is equal to Expected, then TRUE is returned. + If Status is not equal to Expected, then an assert is triggered and the + location of the assert provided by FunctionName, LineNumber, FileName, and + Description are recorded and FALSE is returned. + + @param[in] Status EFI_STATUS value returned from an API under test. + @param[in] Expected The expected EFI_STATUS return value from an API + under test. + @param[in] FunctionName Null-terminated ASCII string of the function + executing the assert macro. + @param[in] LineNumber The source file line number of the assert macro. + @param[in] FileName Null-terminated ASCII string of the filename + executing the assert macro. + @param[in] Description Null-terminated ASCII string that is a description + of Status. + + @retval TRUE Status is equal to Expected. + @retval FALSE Status is not equal to Expected. +**/ +BOOLEAN +EFIAPI +UnitTestAssertStatusEqual ( + IN EFI_STATUS Status, + IN EFI_STATUS Expected, + IN CONST CHAR8 *FunctionName, + IN UINTN LineNumber, + IN CONST CHAR8 *FileName, + IN CONST CHAR8 *Description + ); + +/** + If Pointer is not equal to NULL, then TRUE is returned. + If Pointer is equal to NULL, then an assert is triggered and the location of + the assert provided by FunctionName, LineNumber, FileName, and PointerName + are recorded and FALSE is returned. + + @param[in] Pointer Pointer value to be checked against NULL. + @param[in] Expected The expected EFI_STATUS return value from a function + under test. + @param[in] FunctionName Null-terminated ASCII string of the function + executing the assert macro. + @param[in] LineNumber The source file line number of the assert macro. + @param[in] FileName Null-terminated ASCII string of the filename + executing the assert macro. + @param[in] PointerName Null-terminated ASCII string that is a description + of Pointer. + + @retval TRUE Pointer is not equal to NULL. + @retval FALSE Pointer is equal to NULL. +**/ +BOOLEAN +EFIAPI +UnitTestAssertNotNull ( + IN VOID *Pointer, + IN CONST CHAR8 *FunctionName, + IN UINTN LineNumber, + IN CONST CHAR8 *FileName, + IN CONST CHAR8 *PointerName + ); + +/** + Test logging macro that records an ERROR message in the test framework log. + Record is associated with the currently executing test case. + + @param[in] Format Formatting string following the format defined in + MdePkg/Include/Library/PrintLib.h. + @param[in] ... Print args. +**/ +#define UT_LOG_ERROR(Format, ...) \ + UnitTestLog (UNIT_TEST_LOG_LEVEL_ERROR, Format, ##__VA_ARGS__) + +/** + Test logging macro that records a WARNING message in the test framework log. + Record is associated with the currently executing test case. + + @param[in] Format Formatting string following the format defined in + MdePkg/Include/Library/PrintLib.h. + @param[in] ... Print args. +**/ +#define UT_LOG_WARNING(Format, ...) \ + UnitTestLog (UNIT_TEST_LOG_LEVEL_WARN, Format, ##__VA_ARGS__) + +/** + Test logging macro that records an INFO message in the test framework log. + Record is associated with the currently executing test case. + + @param[in] Format Formatting string following the format defined in + MdePkg/Include/Library/PrintLib.h. + @param[in] ... Print args. +**/ +#define UT_LOG_INFO(Format, ...) \ + UnitTestLog (UNIT_TEST_LOG_LEVEL_INFO, Format, ##__VA_ARGS__) + +/** + Test logging macro that records a VERBOSE message in the test framework log. + Record is associated with the currently executing test case. + + @param[in] Format Formatting string following the format defined in + MdePkg/Include/Library/PrintLib.h. + @param[in] ... Print args. +**/ +#define UT_LOG_VERBOSE(Format, ...) \ + UnitTestLog (UNIT_TEST_LOG_LEVEL_VERBOSE, Format, ##__VA_ARGS__) + +/** + Test logging function that records a messages in the test framework log. + Record is associated with the currently executing test case. + + @param[in] ErrorLevel The error level of the unit test log message. + @param[in] Format Formatting string following the format defined in the + MdePkg/Include/Library/PrintLib.h. + @param[in] ... Print args. +**/ +VOID +EFIAPI +UnitTestLog ( + IN UINTN ErrorLevel, + IN CONST CHAR8 *Format, + ... + ); + +#endif |