#include <Register/Intel/ArchitecturalMsr.h>

Data Structures
struct	FIXED_MTRR

struct	VARIABLE_MTRR

struct	_MTRR_VARIABLE_SETTING_

struct	_MTRR_VARIABLE_SETTINGS_

struct	_MTRR_FIXED_SETTINGS_

struct	_MTRR_SETTINGS_

struct	MTRR_MEMORY_RANGE

Macros
#define	MTRR_NUMBER_OF_VARIABLE_MTRR 32

#define	RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER 2

#define	MTRR_NUMBER_OF_FIXED_MTRR 11

#define	MTRR_CACHE_UNCACHEABLE MSR_IA32_MTRR_CACHE_UNCACHEABLE

#define	MTRR_CACHE_WRITE_COMBINING MSR_IA32_MTRR_CACHE_WRITE_COMBINING

#define	MTRR_CACHE_WRITE_THROUGH MSR_IA32_MTRR_CACHE_WRITE_THROUGH

#define	MTRR_CACHE_WRITE_PROTECTED MSR_IA32_MTRR_CACHE_WRITE_PROTECTED

#define	MTRR_CACHE_WRITE_BACK MSR_IA32_MTRR_CACHE_WRITE_BACK

#define	MTRR_CACHE_INVALID_TYPE MSR_IA32_MTRR_CACHE_INVALID_TYPE

Typedefs
typedef struct _MTRR_VARIABLE_SETTING_	MTRR_VARIABLE_SETTING

typedef struct _MTRR_VARIABLE_SETTINGS_	MTRR_VARIABLE_SETTINGS

typedef struct _MTRR_FIXED_SETTINGS_	MTRR_FIXED_SETTINGS

typedef struct _MTRR_SETTINGS_	MTRR_SETTINGS

Enumerations
enum	MTRR_MEMORY_CACHE_TYPE { CacheUncacheable = MSR_IA32_MTRR_CACHE_UNCACHEABLE , CacheWriteCombining = MSR_IA32_MTRR_CACHE_WRITE_COMBINING , CacheWriteThrough = MSR_IA32_MTRR_CACHE_WRITE_THROUGH , CacheWriteProtected = MSR_IA32_MTRR_CACHE_WRITE_PROTECTED , CacheWriteBack = MSR_IA32_MTRR_CACHE_WRITE_BACK , CacheInvalid = MSR_IA32_MTRR_CACHE_INVALID_TYPE }

Functions
UINT32 EFIAPI	GetVariableMtrrCount (VOID)

UINT32 EFIAPI	GetFirmwareVariableMtrrCount (VOID)

RETURN_STATUS EFIAPI	MtrrSetMemoryAttribute (IN PHYSICAL_ADDRESS BaseAddress, IN UINT64 Length, IN MTRR_MEMORY_CACHE_TYPE Attribute)

MTRR_MEMORY_CACHE_TYPE EFIAPI	MtrrGetMemoryAttribute (IN PHYSICAL_ADDRESS Address)

MTRR_FIXED_SETTINGS *EFIAPI	MtrrGetFixedMtrr (OUT MTRR_FIXED_SETTINGS *FixedSettings)

MTRR_SETTINGS *EFIAPI	MtrrGetAllMtrrs (OUT MTRR_SETTINGS *MtrrSetting)

MTRR_SETTINGS *EFIAPI	MtrrSetAllMtrrs (IN MTRR_SETTINGS *MtrrSetting)

UINT32 EFIAPI	MtrrGetMemoryAttributeInVariableMtrr (IN UINT64 MtrrValidBitsMask, IN UINT64 MtrrValidAddressMask, OUT VARIABLE_MTRR *VariableMtrr)

VOID EFIAPI	MtrrDebugPrintAllMtrrs (VOID)

BOOLEAN EFIAPI	IsMtrrSupported (VOID)

MTRR_MEMORY_CACHE_TYPE EFIAPI	MtrrGetDefaultMemoryType (VOID)

RETURN_STATUS EFIAPI	MtrrSetMemoryAttributeInMtrrSettings (IN OUT MTRR_SETTINGS *MtrrSetting, IN PHYSICAL_ADDRESS BaseAddress, IN UINT64 Length, IN MTRR_MEMORY_CACHE_TYPE Attribute)

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)

RETURN_STATUS EFIAPI	MtrrGetMemoryAttributesInMtrrSettings (IN CONST MTRR_SETTINGS MtrrSetting OPTIONAL, OUT MTRR_MEMORY_RANGE Ranges, IN OUT UINTN *RangeCount)

Detailed Description

MTRR setting library

Copyright (c) 2008 - 2023, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file MtrrLib.h.

Macro Definition Documentation

◆ MTRR_CACHE_INVALID_TYPE

#define MTRR_CACHE_INVALID_TYPE MSR_IA32_MTRR_CACHE_INVALID_TYPE

Definition at line 100 of file MtrrLib.h.

◆ MTRR_CACHE_UNCACHEABLE

#define MTRR_CACHE_UNCACHEABLE MSR_IA32_MTRR_CACHE_UNCACHEABLE

Definition at line 95 of file MtrrLib.h.

◆ MTRR_CACHE_WRITE_BACK

#define MTRR_CACHE_WRITE_BACK MSR_IA32_MTRR_CACHE_WRITE_BACK

Definition at line 99 of file MtrrLib.h.

◆ MTRR_CACHE_WRITE_COMBINING

#define MTRR_CACHE_WRITE_COMBINING MSR_IA32_MTRR_CACHE_WRITE_COMBINING

Definition at line 96 of file MtrrLib.h.

◆ MTRR_CACHE_WRITE_PROTECTED

#define MTRR_CACHE_WRITE_PROTECTED MSR_IA32_MTRR_CACHE_WRITE_PROTECTED

Definition at line 98 of file MtrrLib.h.

◆ MTRR_CACHE_WRITE_THROUGH

#define MTRR_CACHE_WRITE_THROUGH MSR_IA32_MTRR_CACHE_WRITE_THROUGH

Definition at line 97 of file MtrrLib.h.

◆ MTRR_NUMBER_OF_FIXED_MTRR

#define MTRR_NUMBER_OF_FIXED_MTRR 11

Definition at line 29 of file MtrrLib.h.

◆ MTRR_NUMBER_OF_VARIABLE_MTRR

#define MTRR_NUMBER_OF_VARIABLE_MTRR 32

Definition at line 22 of file MtrrLib.h.

◆ RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER

#define RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER 2

Definition at line 27 of file MtrrLib.h.

Enumeration Type Documentation

◆ MTRR_MEMORY_CACHE_TYPE

enum MTRR_MEMORY_CACHE_TYPE

Definition at line 86 of file MtrrLib.h.

Function Documentation

◆ GetFirmwareVariableMtrrCount()

UINT32 EFIAPI GetFirmwareVariableMtrrCount ( VOID )

Returns the firmware usable variable MTRR count for the CPU.

Returns: Firmware usable variable MTRR count

Definition at line 277 of file MtrrLib.c.

◆ GetVariableMtrrCount()

UINT32 EFIAPI GetVariableMtrrCount ( VOID )

Returns the variable MTRR count for the CPU.

Returns: Variable MTRR count

Definition at line 235 of file MtrrLib.c.

◆ IsMtrrSupported()

BOOLEAN EFIAPI IsMtrrSupported ( VOID )

Checks if MTRR is supported.

Return values

TRUE	MTRR is supported.
FALSE	MTRR is not supported.

Definition at line 2960 of file MtrrLib.c.

◆ MtrrDebugPrintAllMtrrs()

VOID EFIAPI MtrrDebugPrintAllMtrrs ( VOID )

This function prints all MTRRs for debugging.

Definition at line 3161 of file MtrrLib.c.

◆ MtrrGetAllMtrrs()

MTRR_SETTINGS *EFIAPI MtrrGetAllMtrrs ( OUT MTRR_SETTINGS * MtrrSetting )

This function gets the content in all MTRRs (variable and fixed)

Parameters

[out] MtrrSetting A buffer to hold all MTRRs content.

Returns: The pointer of MtrrSetting

This function gets the content in all MTRRs (variable and fixed)

Parameters

[out] MtrrSetting A buffer to hold all MTRRs content.

Return values

the	pointer of MtrrSetting

Definition at line 2851 of file MtrrLib.c.

◆ MtrrGetDefaultMemoryType()

MTRR_MEMORY_CACHE_TYPE EFIAPI MtrrGetDefaultMemoryType ( VOID )

Returns the default MTRR cache type for the system.

Returns: The default MTRR cache type.

Definition at line 324 of file MtrrLib.c.

◆ MtrrGetFixedMtrr()

MTRR_FIXED_SETTINGS *EFIAPI MtrrGetFixedMtrr ( OUT MTRR_FIXED_SETTINGS * FixedSettings )

This function gets the content in fixed MTRRs

Parameters

[out] FixedSettings A buffer to hold fixed MTRRs content.

Returns: The pointer of FixedSettings

This function gets the content in fixed MTRRs

Parameters

[out] FixedSettings A buffer to hold fixed MTRRs content.

Return values

The	pointer of FixedSettings

Definition at line 474 of file MtrrLib.c.

◆ MtrrGetMemoryAttribute()

MTRR_MEMORY_CACHE_TYPE EFIAPI MtrrGetMemoryAttribute ( IN PHYSICAL_ADDRESS Address )

This function will get the memory cache type of the specific address. This function is mainly for debugging purposes.

Parameters

[in] Address The specific address

Returns: The memory cache type of the specific address

This function will get the memory cache type of the specific address.

This function is mainly for debug purpose.

Parameters

[in] Address The specific address

Returns: Memory cache type of the specific address

Definition at line 1021 of file MtrrLib.c.

◆ MtrrGetMemoryAttributeInVariableMtrr()

UINT32 EFIAPI MtrrGetMemoryAttributeInVariableMtrr	(	IN UINT64	MtrrValidBitsMask,
		IN UINT64	MtrrValidAddressMask,
		OUT VARIABLE_MTRR *	VariableMtrr
	)

Get the attribute of variable MTRRs.

This function shadows the content of variable MTRRs into an internal array: VariableMtrr

Parameters

[in]	MtrrValidBitsMask	The mask for the valid bit of the MTRR
[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
[out]	VariableMtrr	The array to shadow variable MTRRs content

Returns: The return value of this parameter indicates the number of MTRRs which has been used.

Gets the attribute of variable MTRRs.

This function shadows the content of variable MTRRs into an internal array: VariableMtrr.

Parameters

[in]	MtrrValidBitsMask	The mask for the valid bit of the MTRR
[in]	MtrrValidAddressMask	The valid address mask for MTRR
[out]	VariableMtrr	The array to shadow variable MTRRs content

Returns: The return value of this parameter indicates the number of MTRRs which has been used.

Definition at line 740 of file MtrrLib.c.

◆ MtrrGetMemoryAttributesInMtrrSettings()

RETURN_STATUS EFIAPI MtrrGetMemoryAttributesInMtrrSettings	(	IN CONST MTRR_SETTINGS *MtrrSetting	OPTIONAL,
		OUT MTRR_MEMORY_RANGE *	Ranges,
		IN OUT UINTN *	RangeCount
	)

This function returns a Ranges array containing the memory cache types of all memory addresses.

Parameters

[in]	MtrrSetting	MTRR setting buffer to parse.
[out]	Ranges	Pointer to an array of MTRR_MEMORY_RANGE.
[in,out]	RangeCount	Count of MTRR_MEMORY_RANGE. On input, the maximum entries the Ranges can hold. On output, the actual entries that the function returns.

Return values

RETURN_INVALID_PARAMETER	RangeCount is NULL.
RETURN_INVALID_PARAMETER	*RangeCount is not 0 but Ranges is NULL.
RETURN_BUFFER_TOO_SMALL	*RangeCount is too small.
RETURN_SUCCESS	Ranges are successfully returned.

Definition at line 2984 of file MtrrLib.c.

◆ MtrrSetAllMtrrs()

MTRR_SETTINGS *EFIAPI MtrrSetAllMtrrs ( IN MTRR_SETTINGS * MtrrSetting )

This function sets all MTRRs (variable and fixed)

Note: The behavior of this function is to program everything in MtrrSetting to hardware. MTRR might not be enabled due to enable bit is clear in MtrrSetting->MtrrDefType.

Parameters

[in] MtrrSetting A buffer holding all MTRRs content.

Return values

The	pointer of MtrrSetting

This function sets all MTRRs includes Variable and Fixed.

The behavior of this function is to program everything in MtrrSetting to hardware. MTRRs might not be enabled because the enable bit is clear in MtrrSetting->MtrrDefType.

Parameters

[in] MtrrSetting A buffer holding all MTRRs content.

Return values

The	pointer of MtrrSetting

Definition at line 2908 of file MtrrLib.c.

◆ MtrrSetMemoryAttribute()

RETURN_STATUS EFIAPI MtrrSetMemoryAttribute	(	IN PHYSICAL_ADDRESS	BaseAddress,
		IN UINT64	Length,
		IN MTRR_MEMORY_CACHE_TYPE	Attribute
	)

This function attempts to set the attributes for a memory range.

Parameters

[in]	BaseAddress	The physical address that is the start address of a memory region.
[in]	Length	The size in bytes of the memory region.
[in]	Attribute	The bit mask of attributes to set for the memory region.

Return values

RETURN_SUCCESS	The attributes were set for the memory region.
RETURN_INVALID_PARAMETER	Length is zero.
RETURN_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
RETURN_UNSUPPORTED	The bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length.
RETURN_ACCESS_DENIED	The attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
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.
RETURN_BUFFER_TOO_SMALL	The fixed internal scratch buffer is too small for MTRR calculation. Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify external scratch buffer.

This function attempts to set the attributes for a memory range.

Parameters

[in]	BaseAddress	The physical address that is the start address of a memory range.
[in]	Length	The size in bytes of the memory range.
[in]	Attributes	The bit mask of attributes to set for the memory range.

Return values

RETURN_SUCCESS	The attributes were set for the memory range.
RETURN_INVALID_PARAMETER	Length is zero.
RETURN_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
RETURN_UNSUPPORTED	The bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length.
RETURN_ACCESS_DENIED	The attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
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.
RETURN_BUFFER_TOO_SMALL	The fixed internal scratch buffer is too small for MTRR calculation. Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify external scratch buffer.

Definition at line 2782 of file MtrrLib.c.

◆ MtrrSetMemoryAttributeInMtrrSettings()

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 a memory range.

Parameters

[in,out]	MtrrSetting	MTRR setting buffer to be set.
[in]	BaseAddress	The physical address that is the start address of a memory region.
[in]	Length	The size in bytes of the memory region.
[in]	Attribute	The bit mask of attributes to set for the memory region.

Return values

RETURN_SUCCESS	The attributes were set for the memory region.
RETURN_INVALID_PARAMETER	Length is zero.
RETURN_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
RETURN_UNSUPPORTED	The bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length.
RETURN_ACCESS_DENIED	The attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
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.
RETURN_BUFFER_TOO_SMALL	The fixed internal scratch buffer is too small for MTRR calculation. Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify external scratch buffer.

This function attempts to set the attributes into MTRR setting buffer for a memory range.

Parameters

[in,out]	MtrrSetting	MTRR setting buffer to be set.
[in]	BaseAddress	The physical address that is the start address of a memory range.
[in]	Length	The size in bytes of the memory range.
[in]	Attribute	The bit mask of attributes to set for the memory range.

Return values

RETURN_SUCCESS	The attributes were set for the memory range.
RETURN_INVALID_PARAMETER	Length is zero.
RETURN_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
RETURN_UNSUPPORTED	The bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length.
RETURN_ACCESS_DENIED	The attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
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.
RETURN_BUFFER_TOO_SMALL	The fixed internal scratch buffer is too small for MTRR calculation. Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify external scratch buffer.

Definition at line 2729 of file MtrrLib.c.

◆ MtrrSetMemoryAttributesInMtrrSettings()

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
	)

This function attempts to set the attributes into MTRR setting buffer for multiple memory ranges.

Parameters

[in,out]	MtrrSetting	MTRR setting buffer to be set.
[in]	Scratch	A temporary scratch buffer that is used to perform the calculation.
[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.
[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.
[in]	RangeCount	Count of MTRR_MEMORY_RANGE.

Return values

RETURN_SUCCESS	The attributes were set for all the memory ranges.
RETURN_INVALID_PARAMETER	Length in any range is zero.
RETURN_UNSUPPORTED	The processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length in any range.
RETURN_UNSUPPORTED	The bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length in any range.
RETURN_OUT_OF_RESOURCES	There are not enough system resources to modify the attributes of the memory resource ranges.
RETURN_ACCESS_DENIED	The attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
RETURN_BUFFER_TOO_SMALL	The scratch buffer is too small for MTRR calculation.

Definition at line 2336 of file MtrrLib.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MTRR_CACHE_INVALID_TYPE

◆ MTRR_CACHE_UNCACHEABLE

◆ MTRR_CACHE_WRITE_BACK

◆ MTRR_CACHE_WRITE_COMBINING

◆ MTRR_CACHE_WRITE_PROTECTED

◆ MTRR_CACHE_WRITE_THROUGH

◆ MTRR_NUMBER_OF_FIXED_MTRR

◆ MTRR_NUMBER_OF_VARIABLE_MTRR

◆ RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER

Enumeration Type Documentation

◆ MTRR_MEMORY_CACHE_TYPE

Function Documentation

◆ GetFirmwareVariableMtrrCount()

◆ GetVariableMtrrCount()

◆ IsMtrrSupported()

◆ MtrrDebugPrintAllMtrrs()

◆ MtrrGetAllMtrrs()

◆ MtrrGetDefaultMemoryType()

◆ MtrrGetFixedMtrr()

◆ MtrrGetMemoryAttribute()

◆ MtrrGetMemoryAttributeInVariableMtrr()

◆ MtrrGetMemoryAttributesInMtrrSettings()

◆ MtrrSetAllMtrrs()

◆ MtrrSetMemoryAttribute()

◆ MtrrSetMemoryAttributeInMtrrSettings()

◆ MtrrSetMemoryAttributesInMtrrSettings()