/** @file\r
MTRR setting library\r
\r
- Copyright (c) 2008 - 2010, Intel Corporation\r
- All rights reserved. This program and the accompanying materials\r
- are licensed and made available under the terms and conditions of the BSD License\r
- which accompanies this distribution. The full text of the license may be found at\r
- http://opensource.org/licenses/bsd-license.php\r
-\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+ Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#define _MTRR_LIB_H_\r
\r
//\r
-// According to IA32 SDM, MTRRs number and msr offset are always consistent\r
+// According to IA32 SDM, MTRRs number and MSR offset are always consistent\r
// for IA32 processor family\r
//\r
\r
//\r
-// We can not use Pcd as macro to define structure, so we have to define MAX_MTRR_NUMBER_OF_VARIABLE_MTRR\r
+// The semantics of below macro is MAX_MTRR_NUMBER_OF_VARIABLE_MTRR, the real number can be read out from MTRR_CAP register.\r
//\r
-#define MAX_MTRR_NUMBER_OF_VARIABLE_MTRR 32\r
+#define MTRR_NUMBER_OF_VARIABLE_MTRR 32\r
//\r
// Firmware need reserve 2 MTRR for OS\r
+// Note: It is replaced by PCD PcdCpuNumberOfReservedVariableMtrrs\r
//\r
#define RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER 2\r
\r
#define MTRR_NUMBER_OF_FIXED_MTRR 11\r
-#define MTRR_LIB_IA32_MTRR_CAP 0x0FE\r
-#define MTRR_LIB_IA32_MTRR_CAP_VCNT_MASK 0x0FF\r
-#define MTRR_LIB_IA32_MTRR_FIX64K_00000 0x250\r
-#define MTRR_LIB_IA32_MTRR_FIX16K_80000 0x258\r
-#define MTRR_LIB_IA32_MTRR_FIX16K_A0000 0x259\r
-#define MTRR_LIB_IA32_MTRR_FIX4K_C0000 0x268\r
-#define MTRR_LIB_IA32_MTRR_FIX4K_C8000 0x269\r
-#define MTRR_LIB_IA32_MTRR_FIX4K_D0000 0x26A\r
-#define MTRR_LIB_IA32_MTRR_FIX4K_D8000 0x26B\r
-#define MTRR_LIB_IA32_MTRR_FIX4K_E0000 0x26C\r
-#define MTRR_LIB_IA32_MTRR_FIX4K_E8000 0x26D\r
-#define MTRR_LIB_IA32_MTRR_FIX4K_F0000 0x26E\r
-#define MTRR_LIB_IA32_MTRR_FIX4K_F8000 0x26F\r
-#define MTRR_LIB_IA32_VARIABLE_MTRR_BASE 0x200\r
-#define MTRR_LIB_IA32_MTRR_DEF_TYPE 0x2FF\r
-#define MTRR_LIB_MSR_VALID_MASK 0xFFFFFFFFFULL\r
-#define MTRR_LIB_CACHE_VALID_ADDRESS 0xFFFFFF000ULL\r
-#define MTRR_LIB_CACHE_MTRR_ENABLED 0x800\r
-#define MTRR_LIB_CACHE_FIXED_MTRR_ENABLED 0x400\r
\r
//\r
// Structure to describe a fixed MTRR\r
// Structure to hold base and mask pair for variable MTRR register\r
//\r
typedef struct _MTRR_VARIABLE_SETTING_ {\r
- UINT64 Base;\r
- UINT64 Mask;\r
+ UINT64 Base;\r
+ UINT64 Mask;\r
} MTRR_VARIABLE_SETTING;\r
\r
//\r
// Array for variable MTRRs\r
//\r
typedef struct _MTRR_VARIABLE_SETTINGS_ {\r
- MTRR_VARIABLE_SETTING Mtrr[MAX_MTRR_NUMBER_OF_VARIABLE_MTRR];\r
-} MTRR_VARIABLE_SETTINGS;\r
+ MTRR_VARIABLE_SETTING Mtrr[MTRR_NUMBER_OF_VARIABLE_MTRR];\r
+} MTRR_VARIABLE_SETTINGS;\r
\r
//\r
-// Array for fixed mtrrs\r
+// Array for fixed MTRRs\r
//\r
typedef struct _MTRR_FIXED_SETTINGS_ {\r
UINT64 Mtrr[MTRR_NUMBER_OF_FIXED_MTRR];\r
// Memory cache types\r
//\r
typedef enum {\r
- CacheUncacheable = 0,\r
- CacheWriteCombining = 1,\r
- CacheWriteThrough = 4,\r
- CacheWriteProtected = 5,\r
- CacheWriteBack = 6\r
+ CacheUncacheable = 0,\r
+ CacheWriteCombining = 1,\r
+ CacheWriteThrough = 4,\r
+ CacheWriteProtected = 5,\r
+ CacheWriteBack = 6,\r
+ CacheInvalid = 7\r
} MTRR_MEMORY_CACHE_TYPE;\r
\r
#define MTRR_CACHE_UNCACHEABLE 0\r
#define MTRR_CACHE_WRITE_BACK 6\r
#define MTRR_CACHE_INVALID_TYPE 7\r
\r
+typedef struct {\r
+ UINT64 BaseAddress;\r
+ UINT64 Length;\r
+ MTRR_MEMORY_CACHE_TYPE Type;\r
+} MTRR_MEMORY_RANGE;\r
+\r
/**\r
Returns the variable MTRR count for the CPU.\r
\r
\r
**/\r
UINT32\r
+EFIAPI\r
GetVariableMtrrCount (\r
VOID\r
);\r
\r
**/\r
UINT32\r
+EFIAPI\r
GetFirmwareVariableMtrrCount (\r
VOID\r
);\r
/**\r
This function attempts to set the attributes for a memory range.\r
\r
- @param BaseAddress The physical address that is the start address of a memory region.\r
- @param Length The size in bytes of the memory region.\r
- @param Attributes The bit mask of attributes to set for the memory region.\r
+ @param[in] BaseAddress The physical address that is the start\r
+ address of a memory region.\r
+ @param[in] Length The size in bytes of the memory region.\r
+ @param[in] Attribute The bit mask of attributes to set for the\r
+ memory region.\r
\r
- @retval RETURN_SUCCESS The attributes were set for the memory region.\r
+ @retval RETURN_SUCCESS The attributes were set for the memory\r
+ region.\r
@retval RETURN_INVALID_PARAMETER Length is zero.\r
- @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the\r
- memory resource range specified by BaseAddress and Length.\r
- @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource\r
- range specified by BaseAddress and Length.\r
- @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by\r
- BaseAddress and Length cannot be modified.\r
- @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of\r
- the memory resource range.\r
-\r
+ @retval RETURN_UNSUPPORTED The processor does not support one or\r
+ more bytes of the memory resource range\r
+ specified by BaseAddress and Length.\r
+ @retval RETURN_UNSUPPORTED The bit mask of attributes is not support\r
+ for the memory resource range specified\r
+ by BaseAddress and Length.\r
+ @retval RETURN_ACCESS_DENIED The attributes for the memory resource\r
+ range specified by BaseAddress and Length\r
+ cannot be modified.\r
+ @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to\r
+ modify the attributes of the memory\r
+ resource range.\r
+ Multiple memory range attributes setting by calling this API multiple\r
+ times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean\r
+ the number of CPU MTRRs are too small to set such memory attributes.\r
+ Pass the multiple memory range attributes to one call of\r
+ MtrrSetMemoryAttributesInMtrrSettings() may succeed.\r
+ @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.\r
+ Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify\r
+ external scratch buffer.\r
**/\r
RETURN_STATUS\r
EFIAPI\r
This function will get the memory cache type of the specific address.\r
This function is mainly for debugging purposes.\r
\r
- @param Address The specific address\r
+ @param[in] Address The specific address\r
\r
@return The memory cache type of the specific address\r
\r
/**\r
This function will get the raw value in variable MTRRs\r
\r
- @param VariableSettings A buffer to hold variable MTRRs content.\r
+ @param[out] VariableSettings A buffer to hold variable MTRRs content.\r
\r
- @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable mtrr\r
+ @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable MTRR\r
\r
**/\r
MTRR_VARIABLE_SETTINGS*\r
\r
\r
/**\r
- This function sets fixed MTRRs\r
+ This function sets variable MTRRs\r
\r
- @param VariableSettings A buffer to hold variable MTRRs content.\r
+ @param[in] VariableSettings A buffer to hold variable MTRRs content.\r
\r
@return The pointer of VariableSettings\r
\r
/**\r
This function gets the content in fixed MTRRs\r
\r
- @param FixedSettings A buffer to hold fixed MTRRs content.\r
+ @param[out] FixedSettings A buffer to hold fixed MTRRs content.\r
\r
@return The pointer of FixedSettings\r
\r
/**\r
This function sets fixed MTRRs\r
\r
- @param FixedSettings A buffer holding fixed MTRRs content.\r
+ @param[in] FixedSettings A buffer holding fixed MTRRs content.\r
\r
@return The pointer of FixedSettings\r
\r
/**\r
This function gets the content in all MTRRs (variable and fixed)\r
\r
- @param MtrrSetting A buffer to hold all MTRRs content.\r
+ @param[out] MtrrSetting A buffer to hold all MTRRs content.\r
\r
@return The pointer of MtrrSetting\r
\r
/**\r
This function sets all MTRRs (variable and fixed)\r
\r
- @param MtrrSetting A buffer to hold all MTRRs content.\r
+ @param[in] MtrrSetting A buffer to hold all MTRRs content.\r
\r
@return The pointer of MtrrSetting\r
\r
This function shadows the content of variable MTRRs into\r
an internal array: VariableMtrr\r
\r
- @param MtrrValidBitsMask The mask for the valid bit of the MTRR\r
- @param MtrrValidAddressMask The valid address mask for MTRR since the base address in\r
- MTRR must align to 4K, so valid address mask equal to\r
- MtrrValidBitsMask & 0xfffffffffffff000ULL\r
- @param VariableMtrrCount On input, it means the array number of variable MTRRs passed in.\r
- On output, it means the number of MTRRs which has been used if EFI_SUCCESS,\r
- or the number of MTRR required if BUFFER_TOO_SMALL.\r
- @param VariableMtrr The array to shadow variable MTRRs content\r
-\r
- @retval RETURN_SUCCESS The variable MTRRs are returned.\r
- @retval RETURN_BUFFER_TOO_SMALL The input buffer is too small to hold the variable MTRRs.\r
+ @param[in] MtrrValidBitsMask The mask for the valid bit of the MTRR\r
+ @param[in] MtrrValidAddressMask The valid address mask for MTRR since the base address in\r
+ MTRR must align to 4K, so valid address mask equal to\r
+ MtrrValidBitsMask & 0xfffffffffffff000ULL\r
+ @param[out] VariableMtrr The array to shadow variable MTRRs content\r
\r
+ @return The return value of this parameter indicates the number of\r
+ MTRRs which has been used.\r
**/\r
-RETURN_STATUS\r
+UINT32\r
EFIAPI\r
MtrrGetMemoryAttributeInVariableMtrr (\r
IN UINT64 MtrrValidBitsMask,\r
IN UINT64 MtrrValidAddressMask,\r
- IN OUT UINT32 *VariableMtrrCount,\r
OUT VARIABLE_MTRR *VariableMtrr\r
);\r
\r
This function prints all MTRRs for debugging.\r
**/\r
VOID\r
+EFIAPI\r
MtrrDebugPrintAllMtrrs (\r
+ VOID\r
+ );\r
+\r
+/**\r
+ Checks if MTRR is supported.\r
+\r
+ @retval TRUE MTRR is supported.\r
+ @retval FALSE MTRR is not supported.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+IsMtrrSupported (\r
+ VOID\r
+ );\r
+\r
+/**\r
+ Returns the default MTRR cache type for the system.\r
+\r
+ @return The default MTRR cache type.\r
+\r
+**/\r
+MTRR_MEMORY_CACHE_TYPE\r
+EFIAPI\r
+MtrrGetDefaultMemoryType (\r
+ VOID\r
+ );\r
+\r
+/**\r
+ This function attempts to set the attributes into MTRR setting buffer for a memory range.\r
+\r
+ @param[in, out] MtrrSetting MTRR setting buffer to be set.\r
+ @param[in] BaseAddress The physical address that is the start address\r
+ of a memory region.\r
+ @param[in] Length The size in bytes of the memory region.\r
+ @param[in] Attribute The bit mask of attributes to set for the\r
+ memory region.\r
+\r
+ @retval RETURN_SUCCESS The attributes were set for the memory region.\r
+ @retval RETURN_INVALID_PARAMETER Length is zero.\r
+ @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the\r
+ memory resource range specified by BaseAddress and Length.\r
+ @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource\r
+ range specified by BaseAddress and Length.\r
+ @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by\r
+ BaseAddress and Length cannot be modified.\r
+ @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of\r
+ the memory resource range.\r
+ Multiple memory range attributes setting by calling this API multiple\r
+ times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean\r
+ the number of CPU MTRRs are too small to set such memory attributes.\r
+ Pass the multiple memory range attributes to one call of\r
+ MtrrSetMemoryAttributesInMtrrSettings() may succeed.\r
+ @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.\r
+ Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify\r
+ external scratch buffer.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+MtrrSetMemoryAttributeInMtrrSettings (\r
+ IN OUT MTRR_SETTINGS *MtrrSetting,\r
+ IN PHYSICAL_ADDRESS BaseAddress,\r
+ IN UINT64 Length,\r
+ IN MTRR_MEMORY_CACHE_TYPE Attribute\r
);\r
\r
+/**\r
+ This function attempts to set the attributes into MTRR setting buffer for multiple memory ranges.\r
+\r
+ @param[in, out] MtrrSetting MTRR setting buffer to be set.\r
+ @param[in] Scratch A temporary scratch buffer that is used to perform the calculation.\r
+ @param[in, out] ScratchSize Pointer to the size in bytes of the scratch buffer.\r
+ It may be updated to the actual required size when the calculation\r
+ needs more scratch buffer.\r
+ @param[in] Ranges Pointer to an array of MTRR_MEMORY_RANGE.\r
+ When range overlap happens, the last one takes higher priority.\r
+ When the function returns, either all the attributes are set successfully,\r
+ or none of them is set.\r
+ @param[in] RangeCount Count of MTRR_MEMORY_RANGE.\r
+\r
+ @retval RETURN_SUCCESS The attributes were set for all the memory ranges.\r
+ @retval RETURN_INVALID_PARAMETER Length in any range is zero.\r
+ @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the\r
+ memory resource range specified by BaseAddress and Length in any range.\r
+ @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource\r
+ range specified by BaseAddress and Length in any range.\r
+ @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of\r
+ the memory resource ranges.\r
+ @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by\r
+ BaseAddress and Length cannot be modified.\r
+ @retval RETURN_BUFFER_TOO_SMALL The scratch buffer is too small for MTRR calculation.\r
+**/\r
+RETURN_STATUS\r
+EFIAPI\r
+MtrrSetMemoryAttributesInMtrrSettings (\r
+ IN OUT MTRR_SETTINGS *MtrrSetting,\r
+ IN VOID *Scratch,\r
+ IN OUT UINTN *ScratchSize,\r
+ IN CONST MTRR_MEMORY_RANGE *Ranges,\r
+ IN UINTN RangeCount\r
+ );\r
#endif // _MTRR_LIB_H_\r
projects / mirror_edk2.git / blobdiff