[mirror_edk2.git] / UefiCpuPkg / Include / Library / MtrrLib.h

/** @file\r
  MTRR setting library\r
\r
  Copyright (c) 2008 - 2018, 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
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef  _MTRR_LIB_H_\r
#define  _MTRR_LIB_H_\r
\r
//\r
// According to IA32 SDM, MTRRs number and MSR offset are always consistent\r
// for IA32 processor family\r
//\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
\r
//\r
// Structure to describe a fixed MTRR\r
//\r
typedef struct {\r
  UINT32  Msr;\r
  UINT32  BaseAddress;\r
  UINT32  Length;\r
} FIXED_MTRR;\r
\r
//\r
// Structure to describe a variable MTRR\r
//\r
typedef struct {\r
  UINT64  BaseAddress;\r
  UINT64  Length;\r
  UINT64  Type;\r
  UINT32  Msr;\r
  BOOLEAN Valid;\r
  BOOLEAN Used;\r
} VARIABLE_MTRR;\r
\r
//\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
} 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
\r
//\r
// Array for fixed MTRRs\r
//\r
typedef  struct  _MTRR_FIXED_SETTINGS_ {\r
  UINT64       Mtrr[MTRR_NUMBER_OF_FIXED_MTRR];\r
} MTRR_FIXED_SETTINGS;\r
\r
//\r
// Structure to hold all MTRRs\r
//\r
typedef struct _MTRR_SETTINGS_ {\r
  MTRR_FIXED_SETTINGS       Fixed;\r
  MTRR_VARIABLE_SETTINGS    Variables;\r
  UINT64                    MtrrDefType;\r
} MTRR_SETTINGS;\r
\r
//\r
// Memory cache types\r
//\r
typedef enum {\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_COMBINING  1\r
#define  MTRR_CACHE_WRITE_THROUGH    4\r
#define  MTRR_CACHE_WRITE_PROTECTED  5\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[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\r
                                    region.\r
  @retval RETURN_INVALID_PARAMETER  Length is zero.\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
MtrrSetMemoryAttribute (\r
  IN PHYSICAL_ADDRESS        BaseAddress,\r
  IN UINT64                  Length,\r
  IN MTRR_MEMORY_CACHE_TYPE  Attribute\r
  );\r
\r
\r
/**\r
  This function will get the memory cache type of the specific address.\r
  This function is mainly for debugging purposes.\r
\r
  @param[in]  Address            The specific address\r
\r
  @return The memory cache type of the specific address\r
\r
**/\r
MTRR_MEMORY_CACHE_TYPE\r
EFIAPI\r
MtrrGetMemoryAttribute (\r
  IN PHYSICAL_ADDRESS   Address\r
  );\r
\r
\r
/**\r
  This function will get the raw value in variable MTRRs\r
\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
\r
**/\r
MTRR_VARIABLE_SETTINGS*\r
EFIAPI\r
MtrrGetVariableMtrr (\r
  OUT MTRR_VARIABLE_SETTINGS         *VariableSettings\r
  );\r
\r
\r
/**\r
  This function sets variable MTRRs\r
\r
  @param[in]  VariableSettings   A buffer to hold variable MTRRs content.\r
\r
  @return The pointer of VariableSettings\r
\r
**/\r
MTRR_VARIABLE_SETTINGS*\r
EFIAPI\r
MtrrSetVariableMtrr (\r
  IN MTRR_VARIABLE_SETTINGS         *VariableSettings\r
  );\r
\r
\r
/**\r
  This function gets the content in fixed MTRRs\r
\r
  @param[out]  FixedSettings      A buffer to hold fixed MTRRs content.\r
\r
  @return The pointer of FixedSettings\r
\r
**/\r
MTRR_FIXED_SETTINGS*\r
EFIAPI\r
MtrrGetFixedMtrr (\r
  OUT MTRR_FIXED_SETTINGS         *FixedSettings\r
  );\r
\r
\r
/**\r
  This function sets fixed MTRRs\r
\r
  @param[in]   FixedSettings      A buffer holding fixed MTRRs content.\r
\r
  @return  The pointer of FixedSettings\r
\r
**/\r
MTRR_FIXED_SETTINGS*\r
EFIAPI\r
MtrrSetFixedMtrr (\r
  IN MTRR_FIXED_SETTINGS          *FixedSettings\r
  );\r
\r
\r
/**\r
  This function gets the content in all MTRRs (variable and fixed)\r
\r
  @param[out]  MtrrSetting   A buffer to hold all MTRRs content.\r
\r
  @return The pointer of MtrrSetting\r
\r
**/\r
MTRR_SETTINGS *\r
EFIAPI\r
MtrrGetAllMtrrs (\r
  OUT MTRR_SETTINGS                *MtrrSetting\r
  );\r
\r
\r
/**\r
  This function sets all MTRRs (variable and fixed)\r
\r
  @param[in]  MtrrSetting   A buffer to hold all MTRRs content.\r
\r
  @return The pointer of MtrrSetting\r
\r
**/\r
MTRR_SETTINGS *\r
EFIAPI\r
MtrrSetAllMtrrs (\r
  IN MTRR_SETTINGS                *MtrrSetting\r
  );\r
\r
\r
/**\r
  Get the attribute of variable MTRRs.\r
\r
  This function shadows the content of variable MTRRs into\r
  an internal array: VariableMtrr\r
\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
EFIAPI\r
MtrrGetMemoryAttributeInVariableMtrr (\r
  IN  UINT64                    MtrrValidBitsMask,\r
  IN  UINT64                    MtrrValidAddressMask,\r
  OUT VARIABLE_MTRR             *VariableMtrr\r
  );\r
\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
Commit	Line	Data
e50466da	1	/** @file\r
	2	MTRR setting library\r
	3	\r
8b2eb7b3	4	Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR>\r
01a1c0fc	5	This program and the accompanying materials\r
e50466da	6	are licensed and made available under the terms and conditions of the BSD License\r
	7	which accompanies this distribution. The full text of the license may be found at\r
	8	http://opensource.org/licenses/bsd-license.php\r
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	12	\r
	13	**/\r
	14	\r
	15	#ifndef _MTRR_LIB_H_\r
	16	#define _MTRR_LIB_H_\r
	17	\r
	18	//\r
341fea64	19	// According to IA32 SDM, MTRRs number and MSR offset are always consistent\r
e50466da	20	// for IA32 processor family\r
e50466da	21	//\r
3b9be416 JY	22	\r
3b9be416 JY	23	//\r
3ba736f3	24	// The semantics of below macro is MAX_MTRR_NUMBER_OF_VARIABLE_MTRR, the real number can be read out from MTRR_CAP register.\r
3b9be416	25	//\r
3ba736f3	26	#define MTRR_NUMBER_OF_VARIABLE_MTRR 32\r
3b9be416 JY	27	//\r
3b9be416 JY	28	// Firmware need reserve 2 MTRR for OS\r
46309b11	29	// Note: It is replaced by PCD PcdCpuNumberOfReservedVariableMtrrs\r
3b9be416 JY	30	//\r
	31	#define RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER 2\r
	32	\r
e50466da	33	#define MTRR_NUMBER_OF_FIXED_MTRR 11\r
e50466da	34	\r
	35	//\r
	36	// Structure to describe a fixed MTRR\r
	37	//\r
	38	typedef struct {\r
	39	UINT32 Msr;\r
	40	UINT32 BaseAddress;\r
	41	UINT32 Length;\r
	42	} FIXED_MTRR;\r
	43	\r
	44	//\r
	45	// Structure to describe a variable MTRR\r
	46	//\r
	47	typedef struct {\r
	48	UINT64 BaseAddress;\r
	49	UINT64 Length;\r
	50	UINT64 Type;\r
	51	UINT32 Msr;\r
	52	BOOLEAN Valid;\r
	53	BOOLEAN Used;\r
	54	} VARIABLE_MTRR;\r
	55	\r
	56	//\r
	57	// Structure to hold base and mask pair for variable MTRR register\r
	58	//\r
	59	typedef struct _MTRR_VARIABLE_SETTING_ {\r
76b4cae3 MK	60	UINT64 Base;\r
76b4cae3 MK	61	UINT64 Mask;\r
e50466da	62	} MTRR_VARIABLE_SETTING;\r
	63	\r
	64	//\r
	65	// Array for variable MTRRs\r
	66	//\r
	67	typedef struct _MTRR_VARIABLE_SETTINGS_ {\r
341fea64 RN	68	MTRR_VARIABLE_SETTING Mtrr[MTRR_NUMBER_OF_VARIABLE_MTRR];\r
341fea64 RN	69	} MTRR_VARIABLE_SETTINGS;\r
e50466da	70	\r
e50466da	71	//\r
341fea64	72	// Array for fixed MTRRs\r
e50466da	73	//\r
	74	typedef struct _MTRR_FIXED_SETTINGS_ {\r
	75	UINT64 Mtrr[MTRR_NUMBER_OF_FIXED_MTRR];\r
	76	} MTRR_FIXED_SETTINGS;\r
	77	\r
	78	//\r
	79	// Structure to hold all MTRRs\r
	80	//\r
	81	typedef struct _MTRR_SETTINGS_ {\r
	82	MTRR_FIXED_SETTINGS Fixed;\r
	83	MTRR_VARIABLE_SETTINGS Variables;\r
	84	UINT64 MtrrDefType;\r
	85	} MTRR_SETTINGS;\r
	86	\r
	87	//\r
	88	// Memory cache types\r
	89	//\r
	90	typedef enum {\r
76b4cae3 MK	91	CacheUncacheable = 0,\r
	92	CacheWriteCombining = 1,\r
	93	CacheWriteThrough = 4,\r
	94	CacheWriteProtected = 5,\r
78c49925 RN	95	CacheWriteBack = 6,\r
78c49925 RN	96	CacheInvalid = 7\r
e50466da	97	} MTRR_MEMORY_CACHE_TYPE;\r
	98	\r
	99	#define MTRR_CACHE_UNCACHEABLE 0\r
	100	#define MTRR_CACHE_WRITE_COMBINING 1\r
	101	#define MTRR_CACHE_WRITE_THROUGH 4\r
	102	#define MTRR_CACHE_WRITE_PROTECTED 5\r
	103	#define MTRR_CACHE_WRITE_BACK 6\r
	104	#define MTRR_CACHE_INVALID_TYPE 7\r
	105	\r
2bbd7e2f RN	106	typedef struct {\r
	107	UINT64 BaseAddress;\r
	108	UINT64 Length;\r
	109	MTRR_MEMORY_CACHE_TYPE Type;\r
	110	} MTRR_MEMORY_RANGE;\r
	111	\r
3b9be416 JY	112	/**\r
	113	Returns the variable MTRR count for the CPU.\r
	114	\r
	115	@return Variable MTRR count\r
	116	\r
	117	**/\r
	118	UINT32\r
ed8dfd7b	119	EFIAPI\r
3b9be416 JY	120	GetVariableMtrrCount (\r
	121	VOID\r
	122	);\r
	123	\r
	124	/**\r
	125	Returns the firmware usable variable MTRR count for the CPU.\r
	126	\r
	127	@return Firmware usable variable MTRR count\r
	128	\r
	129	**/\r
	130	UINT32\r
ed8dfd7b	131	EFIAPI\r
3b9be416 JY	132	GetFirmwareVariableMtrrCount (\r
	133	VOID\r
	134	);\r
	135	\r
e50466da	136	/**\r
	137	This function attempts to set the attributes for a memory range.\r
	138	\r
76b4cae3 MK	139	@param[in] BaseAddress The physical address that is the start\r
	140	address of a memory region.\r
	141	@param[in] Length The size in bytes of the memory region.\r
	142	@param[in] Attribute The bit mask of attributes to set for the\r
	143	memory region.\r
e50466da	144	\r
76b4cae3 MK	145	@retval RETURN_SUCCESS The attributes were set for the memory\r
76b4cae3 MK	146	region.\r
e50466da	147	@retval RETURN_INVALID_PARAMETER Length is zero.\r
76b4cae3 MK	148	@retval RETURN_UNSUPPORTED The processor does not support one or\r
	149	more bytes of the memory resource range\r
	150	specified by BaseAddress and Length.\r
	151	@retval RETURN_UNSUPPORTED The bit mask of attributes is not support\r
	152	for the memory resource range specified\r
	153	by BaseAddress and Length.\r
	154	@retval RETURN_ACCESS_DENIED The attributes for the memory resource\r
	155	range specified by BaseAddress and Length\r
	156	cannot be modified.\r
	157	@retval RETURN_OUT_OF_RESOURCES There are not enough system resources to\r
	158	modify the attributes of the memory\r
	159	resource range.\r
bc6a8b78 RN	160	Multiple memory range attributes setting by calling this API multiple\r
	161	times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean\r
	162	the number of CPU MTRRs are too small to set such memory attributes.\r
	163	Pass the multiple memory range attributes to one call of\r
	164	MtrrSetMemoryAttributesInMtrrSettings() may succeed.\r
8b2eb7b3 RN	165	@retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.\r
	166	Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify\r
	167	external scratch buffer.\r
e50466da	168	**/\r
	169	RETURN_STATUS\r
	170	EFIAPI\r
	171	MtrrSetMemoryAttribute (\r
	172	IN PHYSICAL_ADDRESS BaseAddress,\r
	173	IN UINT64 Length,\r
	174	IN MTRR_MEMORY_CACHE_TYPE Attribute\r
	175	);\r
	176	\r
	177	\r
	178	/**\r
	179	This function will get the memory cache type of the specific address.\r
	180	This function is mainly for debugging purposes.\r
	181	\r
76b4cae3	182	@param[in] Address The specific address\r
e50466da	183	\r
	184	@return The memory cache type of the specific address\r
	185	\r
	186	**/\r
	187	MTRR_MEMORY_CACHE_TYPE\r
	188	EFIAPI\r
	189	MtrrGetMemoryAttribute (\r
	190	IN PHYSICAL_ADDRESS Address\r
	191	);\r
	192	\r
	193	\r
	194	/**\r
	195	This function will get the raw value in variable MTRRs\r
	196	\r
76b4cae3	197	@param[out] VariableSettings A buffer to hold variable MTRRs content.\r
e50466da	198	\r
341fea64	199	@return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable MTRR\r
e50466da	200	\r
	201	**/\r
	202	MTRR_VARIABLE_SETTINGS*\r
	203	EFIAPI\r
	204	MtrrGetVariableMtrr (\r
	205	OUT MTRR_VARIABLE_SETTINGS *VariableSettings\r
	206	);\r
	207	\r
	208	\r
	209	/**\r
341fea64	210	This function sets variable MTRRs\r
e50466da	211	\r
76b4cae3	212	@param[in] VariableSettings A buffer to hold variable MTRRs content.\r
e50466da	213	\r
	214	@return The pointer of VariableSettings\r
	215	\r
	216	**/\r
	217	MTRR_VARIABLE_SETTINGS*\r
	218	EFIAPI\r
	219	MtrrSetVariableMtrr (\r
	220	IN MTRR_VARIABLE_SETTINGS *VariableSettings\r
	221	);\r
	222	\r
	223	\r
	224	/**\r
	225	This function gets the content in fixed MTRRs\r
	226	\r
76b4cae3	227	@param[out] FixedSettings A buffer to hold fixed MTRRs content.\r
e50466da	228	\r
	229	@return The pointer of FixedSettings\r
	230	\r
	231	**/\r
	232	MTRR_FIXED_SETTINGS*\r
	233	EFIAPI\r
	234	MtrrGetFixedMtrr (\r
	235	OUT MTRR_FIXED_SETTINGS *FixedSettings\r
	236	);\r
	237	\r
	238	\r
	239	/**\r
	240	This function sets fixed MTRRs\r
	241	\r
76b4cae3	242	@param[in] FixedSettings A buffer holding fixed MTRRs content.\r
e50466da	243	\r
	244	@return The pointer of FixedSettings\r
	245	\r
	246	**/\r
	247	MTRR_FIXED_SETTINGS*\r
	248	EFIAPI\r
	249	MtrrSetFixedMtrr (\r
	250	IN MTRR_FIXED_SETTINGS *FixedSettings\r
	251	);\r
	252	\r
	253	\r
	254	/**\r
	255	This function gets the content in all MTRRs (variable and fixed)\r
	256	\r
76b4cae3	257	@param[out] MtrrSetting A buffer to hold all MTRRs content.\r
e50466da	258	\r
	259	@return The pointer of MtrrSetting\r
	260	\r
	261	**/\r
	262	MTRR_SETTINGS *\r
	263	EFIAPI\r
	264	MtrrGetAllMtrrs (\r
	265	OUT MTRR_SETTINGS *MtrrSetting\r
	266	);\r
	267	\r
	268	\r
	269	/**\r
	270	This function sets all MTRRs (variable and fixed)\r
	271	\r
76b4cae3	272	@param[in] MtrrSetting A buffer to hold all MTRRs content.\r
e50466da	273	\r
	274	@return The pointer of MtrrSetting\r
	275	\r
	276	**/\r
	277	MTRR_SETTINGS *\r
	278	EFIAPI\r
	279	MtrrSetAllMtrrs (\r
	280	IN MTRR_SETTINGS *MtrrSetting\r
	281	);\r
	282	\r
	283	\r
	284	/**\r
	285	Get the attribute of variable MTRRs.\r
	286	\r
	287	This function shadows the content of variable MTRRs into\r
	288	an internal array: VariableMtrr\r
	289	\r
76b4cae3 MK	290	@param[in] MtrrValidBitsMask The mask for the valid bit of the MTRR\r
	291	@param[in] MtrrValidAddressMask The valid address mask for MTRR since the base address in\r
	292	MTRR must align to 4K, so valid address mask equal to\r
	293	MtrrValidBitsMask & 0xfffffffffffff000ULL\r
	294	@param[out] VariableMtrr The array to shadow variable MTRRs content\r
	295	\r
438f1766	296	@return The return value of this parameter indicates the number of\r
3ba736f3	297	MTRRs which has been used.\r
e50466da	298	**/\r
3ba736f3	299	UINT32\r
e50466da	300	EFIAPI\r
	301	MtrrGetMemoryAttributeInVariableMtrr (\r
	302	IN UINT64 MtrrValidBitsMask,\r
	303	IN UINT64 MtrrValidAddressMask,\r
	304	OUT VARIABLE_MTRR *VariableMtrr\r
	305	);\r
	306	\r
	307	\r
	308	/**\r
	309	This function prints all MTRRs for debugging.\r
	310	**/\r
	311	VOID\r
ed8dfd7b	312	EFIAPI\r
e50466da	313	MtrrDebugPrintAllMtrrs (\r
430fbbe0	314	VOID\r
e50466da	315	);\r
e50466da	316	\r
947a573a	317	/**\r
	318	Checks if MTRR is supported.\r
	319	\r
	320	@retval TRUE MTRR is supported.\r
	321	@retval FALSE MTRR is not supported.\r
	322	\r
	323	**/\r
	324	BOOLEAN\r
ed8dfd7b	325	EFIAPI\r
947a573a	326	IsMtrrSupported (\r
	327	VOID\r
	328	);\r
	329	\r
91ec7824	330	/**\r
	331	Returns the default MTRR cache type for the system.\r
	332	\r
	333	@return The default MTRR cache type.\r
	334	\r
	335	**/\r
	336	MTRR_MEMORY_CACHE_TYPE\r
	337	EFIAPI\r
	338	MtrrGetDefaultMemoryType (\r
	339	VOID\r
	340	);\r
	341	\r
b970ed68 MK	342	/**\r
	343	This function attempts to set the attributes into MTRR setting buffer for a memory range.\r
	344	\r
	345	@param[in, out] MtrrSetting MTRR setting buffer to be set.\r
	346	@param[in] BaseAddress The physical address that is the start address\r
	347	of a memory region.\r
	348	@param[in] Length The size in bytes of the memory region.\r
	349	@param[in] Attribute The bit mask of attributes to set for the\r
	350	memory region.\r
	351	\r
	352	@retval RETURN_SUCCESS The attributes were set for the memory region.\r
	353	@retval RETURN_INVALID_PARAMETER Length is zero.\r
	354	@retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the\r
	355	memory resource range specified by BaseAddress and Length.\r
	356	@retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource\r
	357	range specified by BaseAddress and Length.\r
	358	@retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by\r
	359	BaseAddress and Length cannot be modified.\r
	360	@retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of\r
	361	the memory resource range.\r
bc6a8b78 RN	362	Multiple memory range attributes setting by calling this API multiple\r
	363	times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean\r
	364	the number of CPU MTRRs are too small to set such memory attributes.\r
	365	Pass the multiple memory range attributes to one call of\r
	366	MtrrSetMemoryAttributesInMtrrSettings() may succeed.\r
8b2eb7b3 RN	367	@retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.\r
	368	Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify\r
	369	external scratch buffer.\r
b970ed68 MK	370	**/\r
	371	RETURN_STATUS\r
	372	EFIAPI\r
	373	MtrrSetMemoryAttributeInMtrrSettings (\r
	374	IN OUT MTRR_SETTINGS *MtrrSetting,\r
	375	IN PHYSICAL_ADDRESS BaseAddress,\r
	376	IN UINT64 Length,\r
	377	IN MTRR_MEMORY_CACHE_TYPE Attribute\r
	378	);\r
	379	\r
2bbd7e2f RN	380	/**\r
	381	This function attempts to set the attributes into MTRR setting buffer for multiple memory ranges.\r
	382	\r
	383	@param[in, out] MtrrSetting MTRR setting buffer to be set.\r
	384	@param[in] Scratch A temporary scratch buffer that is used to perform the calculation.\r
	385	@param[in, out] ScratchSize Pointer to the size in bytes of the scratch buffer.\r
	386	It may be updated to the actual required size when the calculation\r
	387	needs more scratch buffer.\r
	388	@param[in] Ranges Pointer to an array of MTRR_MEMORY_RANGE.\r
	389	When range overlap happens, the last one takes higher priority.\r
	390	When the function returns, either all the attributes are set successfully,\r
	391	or none of them is set.\r
f6194f5a	392	@param[in] RangeCount Count of MTRR_MEMORY_RANGE.\r
2bbd7e2f RN	393	\r
	394	@retval RETURN_SUCCESS The attributes were set for all the memory ranges.\r
	395	@retval RETURN_INVALID_PARAMETER Length in any range is zero.\r
	396	@retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the\r
	397	memory resource range specified by BaseAddress and Length in any range.\r
	398	@retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource\r
	399	range specified by BaseAddress and Length in any range.\r
	400	@retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of\r
	401	the memory resource ranges.\r
	402	@retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by\r
	403	BaseAddress and Length cannot be modified.\r
	404	@retval RETURN_BUFFER_TOO_SMALL The scratch buffer is too small for MTRR calculation.\r
	405	**/\r
	406	RETURN_STATUS\r
	407	EFIAPI\r
	408	MtrrSetMemoryAttributesInMtrrSettings (\r
	409	IN OUT MTRR_SETTINGS *MtrrSetting,\r
	410	IN VOID *Scratch,\r
	411	IN OUT UINTN *ScratchSize,\r
	412	IN CONST MTRR_MEMORY_RANGE *Ranges,\r
	413	IN UINTN RangeCount\r
	414	);\r
e50466da	415	#endif // _MTRR_LIB_H_\r