X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=UefiCpuPkg%2FInclude%2FLibrary%2FMtrrLib.h;h=95ffbc8bf172a589a95d75e82dc679c9e568452d;hp=e2f2491eee1a231b36bc61331246bf8257799786;hb=0acd869796ded1266e69487dff717cd69d6031f9;hpb=3ba736f39cdb1d587089885dcde4b501eea9962e diff --git a/UefiCpuPkg/Include/Library/MtrrLib.h b/UefiCpuPkg/Include/Library/MtrrLib.h index e2f2491eee..95ffbc8bf1 100644 --- a/UefiCpuPkg/Include/Library/MtrrLib.h +++ b/UefiCpuPkg/Include/Library/MtrrLib.h @@ -1,14 +1,8 @@ /** @file MTRR setting library - Copyright (c) 2008 - 2010, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.
+ SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -16,7 +10,7 @@ #define _MTRR_LIB_H_ // -// According to IA32 SDM, MTRRs number and msr offset are always consistent +// According to IA32 SDM, MTRRs number and MSR offset are always consistent // for IA32 processor family // @@ -26,37 +20,11 @@ #define MTRR_NUMBER_OF_VARIABLE_MTRR 32 // // Firmware need reserve 2 MTRR for OS +// Note: It is replaced by PCD PcdCpuNumberOfReservedVariableMtrrs // #define RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER 2 #define MTRR_NUMBER_OF_FIXED_MTRR 11 -// -// Below macro is deprecated, and should not be used. -// -#define FIRMWARE_VARIABLE_MTRR_NUMBER 6 -#define MTRR_LIB_IA32_MTRR_CAP 0x0FE -#define MTRR_LIB_IA32_MTRR_CAP_VCNT_MASK 0x0FF -#define MTRR_LIB_IA32_MTRR_FIX64K_00000 0x250 -#define MTRR_LIB_IA32_MTRR_FIX16K_80000 0x258 -#define MTRR_LIB_IA32_MTRR_FIX16K_A0000 0x259 -#define MTRR_LIB_IA32_MTRR_FIX4K_C0000 0x268 -#define MTRR_LIB_IA32_MTRR_FIX4K_C8000 0x269 -#define MTRR_LIB_IA32_MTRR_FIX4K_D0000 0x26A -#define MTRR_LIB_IA32_MTRR_FIX4K_D8000 0x26B -#define MTRR_LIB_IA32_MTRR_FIX4K_E0000 0x26C -#define MTRR_LIB_IA32_MTRR_FIX4K_E8000 0x26D -#define MTRR_LIB_IA32_MTRR_FIX4K_F0000 0x26E -#define MTRR_LIB_IA32_MTRR_FIX4K_F8000 0x26F -#define MTRR_LIB_IA32_VARIABLE_MTRR_BASE 0x200 -// -// Below macro is deprecated, and should not be used. -// -#define MTRR_LIB_IA32_VARIABLE_MTRR_END 0x20F -#define MTRR_LIB_IA32_MTRR_DEF_TYPE 0x2FF -#define MTRR_LIB_MSR_VALID_MASK 0xFFFFFFFFFULL -#define MTRR_LIB_CACHE_VALID_ADDRESS 0xFFFFFF000ULL -#define MTRR_LIB_CACHE_MTRR_ENABLED 0x800 -#define MTRR_LIB_CACHE_FIXED_MTRR_ENABLED 0x400 // // Structure to describe a fixed MTRR @@ -83,19 +51,19 @@ typedef struct { // Structure to hold base and mask pair for variable MTRR register // typedef struct _MTRR_VARIABLE_SETTING_ { - UINT64 Base; - UINT64 Mask; + UINT64 Base; + UINT64 Mask; } MTRR_VARIABLE_SETTING; // // Array for variable MTRRs // typedef struct _MTRR_VARIABLE_SETTINGS_ { - MTRR_VARIABLE_SETTING Mtrr[MTRR_NUMBER_OF_VARIABLE_MTRR]; -} MTRR_VARIABLE_SETTINGS; + MTRR_VARIABLE_SETTING Mtrr[MTRR_NUMBER_OF_VARIABLE_MTRR]; +} MTRR_VARIABLE_SETTINGS; // -// Array for fixed mtrrs +// Array for fixed MTRRs // typedef struct _MTRR_FIXED_SETTINGS_ { UINT64 Mtrr[MTRR_NUMBER_OF_FIXED_MTRR]; @@ -114,11 +82,12 @@ typedef struct _MTRR_SETTINGS_ { // Memory cache types // typedef enum { - CacheUncacheable = 0, - CacheWriteCombining = 1, - CacheWriteThrough = 4, - CacheWriteProtected = 5, - CacheWriteBack = 6 + CacheUncacheable = 0, + CacheWriteCombining = 1, + CacheWriteThrough = 4, + CacheWriteProtected = 5, + CacheWriteBack = 6, + CacheInvalid = 7 } MTRR_MEMORY_CACHE_TYPE; #define MTRR_CACHE_UNCACHEABLE 0 @@ -128,6 +97,12 @@ typedef enum { #define MTRR_CACHE_WRITE_BACK 6 #define MTRR_CACHE_INVALID_TYPE 7 +typedef struct { + UINT64 BaseAddress; + UINT64 Length; + MTRR_MEMORY_CACHE_TYPE Type; +} MTRR_MEMORY_RANGE; + /** Returns the variable MTRR count for the CPU. @@ -135,6 +110,7 @@ typedef enum { **/ UINT32 +EFIAPI GetVariableMtrrCount ( VOID ); @@ -146,6 +122,7 @@ GetVariableMtrrCount ( **/ UINT32 +EFIAPI GetFirmwareVariableMtrrCount ( VOID ); @@ -153,21 +130,35 @@ GetFirmwareVariableMtrrCount ( /** This function attempts to set the attributes for a memory range. - @param BaseAddress The physical address that is the start address of a memory region. - @param Length The size in bytes of the memory region. - @param Attributes The bit mask of attributes to set for the memory region. + @param[in] BaseAddress The physical address that is the start + address of a memory region. + @param[in] Length The size in bytes of the memory region. + @param[in] Attribute The bit mask of attributes to set for the + memory region. - @retval RETURN_SUCCESS The attributes were set for the memory region. + @retval RETURN_SUCCESS The attributes were set for the memory + region. @retval RETURN_INVALID_PARAMETER Length is zero. - @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the - memory resource range specified by BaseAddress and Length. - @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource - range specified by BaseAddress and Length. - @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by - BaseAddress and Length cannot be modified. - @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of - the memory resource range. - + @retval RETURN_UNSUPPORTED The processor does not support one or + more bytes of the memory resource range + specified by BaseAddress and Length. + @retval RETURN_UNSUPPORTED The bit mask of attributes is not support + for the memory resource range specified + by BaseAddress and Length. + @retval RETURN_ACCESS_DENIED The attributes for the memory resource + range specified by BaseAddress and Length + cannot be modified. + @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to + modify the attributes of the memory + resource range. + Multiple memory range attributes setting by calling this API multiple + times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean + the number of CPU MTRRs are too small to set such memory attributes. + Pass the multiple memory range attributes to one call of + MtrrSetMemoryAttributesInMtrrSettings() may succeed. + @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation. + Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify + external scratch buffer. **/ RETURN_STATUS EFIAPI @@ -182,7 +173,7 @@ MtrrSetMemoryAttribute ( This function will get the memory cache type of the specific address. This function is mainly for debugging purposes. - @param Address The specific address + @param[in] Address The specific address @return The memory cache type of the specific address @@ -197,9 +188,9 @@ MtrrGetMemoryAttribute ( /** This function will get the raw value in variable MTRRs - @param VariableSettings A buffer to hold variable MTRRs content. + @param[out] VariableSettings A buffer to hold variable MTRRs content. - @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable mtrr + @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable MTRR **/ MTRR_VARIABLE_SETTINGS* @@ -210,9 +201,9 @@ MtrrGetVariableMtrr ( /** - This function sets fixed MTRRs + This function sets variable MTRRs - @param VariableSettings A buffer to hold variable MTRRs content. + @param[in] VariableSettings A buffer to hold variable MTRRs content. @return The pointer of VariableSettings @@ -227,7 +218,7 @@ MtrrSetVariableMtrr ( /** This function gets the content in fixed MTRRs - @param FixedSettings A buffer to hold fixed MTRRs content. + @param[out] FixedSettings A buffer to hold fixed MTRRs content. @return The pointer of FixedSettings @@ -242,7 +233,7 @@ MtrrGetFixedMtrr ( /** This function sets fixed MTRRs - @param FixedSettings A buffer holding fixed MTRRs content. + @param[in] FixedSettings A buffer holding fixed MTRRs content. @return The pointer of FixedSettings @@ -257,7 +248,7 @@ MtrrSetFixedMtrr ( /** This function gets the content in all MTRRs (variable and fixed) - @param MtrrSetting A buffer to hold all MTRRs content. + @param[out] MtrrSetting A buffer to hold all MTRRs content. @return The pointer of MtrrSetting @@ -272,7 +263,7 @@ MtrrGetAllMtrrs ( /** This function sets all MTRRs (variable and fixed) - @param MtrrSetting A buffer to hold all MTRRs content. + @param[in] MtrrSetting A buffer to hold all MTRRs content. @return The pointer of MtrrSetting @@ -290,12 +281,13 @@ MtrrSetAllMtrrs ( This function shadows the content of variable MTRRs into an internal array: VariableMtrr - @param MtrrValidBitsMask The mask for the valid bit of the MTRR - @param MtrrValidAddressMask The valid address mask for MTRR since the base address in - MTRR must align to 4K, so valid address mask equal to - MtrrValidBitsMask & 0xfffffffffffff000ULL - @param VariableMtrr The array to shadow variable MTRRs content - @return The ruturn value of this paramter indicates the number of + @param[in] MtrrValidBitsMask The mask for the valid bit of the MTRR + @param[in] MtrrValidAddressMask The valid address mask for MTRR since the base address in + MTRR must align to 4K, so valid address mask equal to + MtrrValidBitsMask & 0xfffffffffffff000ULL + @param[out] VariableMtrr The array to shadow variable MTRRs content + + @return The return value of this parameter indicates the number of MTRRs which has been used. **/ UINT32 @@ -311,7 +303,107 @@ MtrrGetMemoryAttributeInVariableMtrr ( This function prints all MTRRs for debugging. **/ VOID +EFIAPI MtrrDebugPrintAllMtrrs ( + VOID + ); + +/** + Checks if MTRR is supported. + + @retval TRUE MTRR is supported. + @retval FALSE MTRR is not supported. + +**/ +BOOLEAN +EFIAPI +IsMtrrSupported ( + VOID + ); + +/** + Returns the default MTRR cache type for the system. + + @return The default MTRR cache type. + +**/ +MTRR_MEMORY_CACHE_TYPE +EFIAPI +MtrrGetDefaultMemoryType ( + VOID ); +/** + This function attempts to set the attributes into MTRR setting buffer for a memory range. + + @param[in, out] MtrrSetting MTRR setting buffer to be set. + @param[in] BaseAddress The physical address that is the start address + of a memory region. + @param[in] Length The size in bytes of the memory region. + @param[in] Attribute The bit mask of attributes to set for the + memory region. + + @retval RETURN_SUCCESS The attributes were set for the memory region. + @retval RETURN_INVALID_PARAMETER Length is zero. + @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the + memory resource range specified by BaseAddress and Length. + @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource + range specified by BaseAddress and Length. + @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by + BaseAddress and Length cannot be modified. + @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of + the memory resource range. + Multiple memory range attributes setting by calling this API multiple + times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean + the number of CPU MTRRs are too small to set such memory attributes. + Pass the multiple memory range attributes to one call of + MtrrSetMemoryAttributesInMtrrSettings() may succeed. + @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation. + Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify + external scratch buffer. +**/ +RETURN_STATUS +EFIAPI +MtrrSetMemoryAttributeInMtrrSettings ( + IN OUT MTRR_SETTINGS *MtrrSetting, + IN PHYSICAL_ADDRESS BaseAddress, + IN UINT64 Length, + IN MTRR_MEMORY_CACHE_TYPE Attribute + ); + +/** + This function attempts to set the attributes into MTRR setting buffer for multiple memory ranges. + + @param[in, out] MtrrSetting MTRR setting buffer to be set. + @param[in] Scratch A temporary scratch buffer that is used to perform the calculation. + @param[in, out] ScratchSize Pointer to the size in bytes of the scratch buffer. + It may be updated to the actual required size when the calculation + needs more scratch buffer. + @param[in] Ranges Pointer to an array of MTRR_MEMORY_RANGE. + When range overlap happens, the last one takes higher priority. + When the function returns, either all the attributes are set successfully, + or none of them is set. + @param[in] RangeCount Count of MTRR_MEMORY_RANGE. + + @retval RETURN_SUCCESS The attributes were set for all the memory ranges. + @retval RETURN_INVALID_PARAMETER Length in any range is zero. + @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the + memory resource range specified by BaseAddress and Length in any range. + @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource + range specified by BaseAddress and Length in any range. + @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of + the memory resource ranges. + @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by + BaseAddress and Length cannot be modified. + @retval RETURN_BUFFER_TOO_SMALL The scratch buffer is too small for MTRR calculation. +**/ +RETURN_STATUS +EFIAPI +MtrrSetMemoryAttributesInMtrrSettings ( + IN OUT MTRR_SETTINGS *MtrrSetting, + IN VOID *Scratch, + IN OUT UINTN *ScratchSize, + IN CONST MTRR_MEMORY_RANGE *Ranges, + IN UINTN RangeCount + ); #endif // _MTRR_LIB_H_