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

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