/** @file\r
MTRR setting library\r
\r
- Copyright (c) 2008 - 2010, Intel Corporation\r
- All rights reserved. This program and the accompanying materials\r
+ Copyright (c) 2008 - 2017, Intel Corporation. All rights reserved.<BR>\r
+ 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
#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
-#define MTRR_NUMBER_OF_VARIABLE_MTRR 8\r
+\r
+//\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 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 FIRMWARE_VARIABLE_MTRR_NUMBER 6\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_VARIABLE_MTRR_END 0x20F\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[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
+ @return Variable MTRR count\r
+\r
+**/\r
+UINT32\r
+EFIAPI\r
+GetVariableMtrrCount (\r
+ VOID\r
+ );\r
+\r
+/**\r
+ Returns the firmware usable variable MTRR count for the CPU.\r
+\r
+ @return Firmware usable variable MTRR count\r
+\r
+**/\r
+UINT32\r
+EFIAPI\r
+GetFirmwareVariableMtrrCount (\r
+ VOID\r
+ );\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
+ @retval RETURN_BUFFER_TOO_SMALL The scratch buffer is too small for MTRR calculation.\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 VariableMtrr The array to shadow variable MTRRs content\r
- @return The ruturn value of this paramter indicates the number of\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
UINT32\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
+ @retval RETURN_BUFFER_TOO_SMALL The scratch buffer is too small for MTRR calculation.\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] 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