TianoCore EDK2 master
MtrrLib.h File Reference

Go to the source code of this file.

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   0
 
#define MTRR_CACHE_WRITE_COMBINING   1
 
#define MTRR_CACHE_WRITE_THROUGH   4
 
#define MTRR_CACHE_WRITE_PROTECTED   5
 
#define MTRR_CACHE_WRITE_BACK   6
 
#define MTRR_CACHE_INVALID_TYPE   7
 

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 = 0 , CacheWriteCombining = 1 , CacheWriteThrough = 4 , CacheWriteProtected = 5 ,
  CacheWriteBack = 6 , CacheInvalid = 7
}
 

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)
 

Detailed Description

MTRR setting library

Copyright (c) 2008 - 2020, 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   7

Definition at line 98 of file MtrrLib.h.

◆ MTRR_CACHE_UNCACHEABLE

#define MTRR_CACHE_UNCACHEABLE   0

Definition at line 93 of file MtrrLib.h.

◆ MTRR_CACHE_WRITE_BACK

#define MTRR_CACHE_WRITE_BACK   6

Definition at line 97 of file MtrrLib.h.

◆ MTRR_CACHE_WRITE_COMBINING

#define MTRR_CACHE_WRITE_COMBINING   1

Definition at line 94 of file MtrrLib.h.

◆ MTRR_CACHE_WRITE_PROTECTED

#define MTRR_CACHE_WRITE_PROTECTED   5

Definition at line 96 of file MtrrLib.h.

◆ MTRR_CACHE_WRITE_THROUGH

#define MTRR_CACHE_WRITE_THROUGH   4

Definition at line 95 of file MtrrLib.h.

◆ MTRR_NUMBER_OF_FIXED_MTRR

#define MTRR_NUMBER_OF_FIXED_MTRR   11

Definition at line 27 of file MtrrLib.h.

◆ MTRR_NUMBER_OF_VARIABLE_MTRR

#define MTRR_NUMBER_OF_VARIABLE_MTRR   32

Definition at line 20 of file MtrrLib.h.

◆ RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER

#define RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER   2

Definition at line 25 of file MtrrLib.h.

Enumeration Type Documentation

◆ MTRR_MEMORY_CACHE_TYPE

enum MTRR_MEMORY_CACHE_TYPE

Definition at line 84 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 211 of file MtrrLib.c.

◆ GetVariableMtrrCount()

UINT32 EFIAPI GetVariableMtrrCount ( VOID  )

Returns the variable MTRR count for the CPU.

Returns
Variable MTRR count

Definition at line 169 of file MtrrLib.c.

◆ IsMtrrSupported()

BOOLEAN EFIAPI IsMtrrSupported ( VOID  )

Checks if MTRR is supported.

Return values
TRUEMTRR is supported.
FALSEMTRR is not supported.

Definition at line 2841 of file MtrrLib.c.

◆ MtrrDebugPrintAllMtrrs()

VOID EFIAPI MtrrDebugPrintAllMtrrs ( VOID  )

This function prints all MTRRs for debugging.

Definition at line 2991 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]MtrrSettingA buffer to hold all MTRRs content.
Returns
The pointer of MtrrSetting

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

Parameters
[out]MtrrSettingA buffer to hold all MTRRs content.
Return values
thepointer of MtrrSetting

Definition at line 2760 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 258 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]FixedSettingsA buffer to hold fixed MTRRs content.
Returns
The pointer of FixedSettings

This function gets the content in fixed MTRRs

Parameters
[out]FixedSettingsA buffer to hold fixed MTRRs content.
Return values
Thepointer of FixedSettings

Definition at line 409 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]AddressThe 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]AddressThe specific address
Returns
Memory cache type of the specific address

Definition at line 932 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]MtrrValidBitsMaskThe mask for the valid bit of the MTRR
[in]MtrrValidAddressMaskThe valid address mask for MTRR since the base address in MTRR must align to 4K, so valid address mask equal to MtrrValidBitsMask & 0xfffffffffffff000ULL
[out]VariableMtrrThe 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]MtrrValidBitsMaskThe mask for the valid bit of the MTRR
[in]MtrrValidAddressMaskThe valid address mask for MTRR
[out]VariableMtrrThe 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 671 of file MtrrLib.c.

◆ MtrrSetAllMtrrs()

MTRR_SETTINGS *EFIAPI MtrrSetAllMtrrs ( IN MTRR_SETTINGS MtrrSetting)

This function sets all MTRRs (variable and fixed)

Parameters
[in]MtrrSettingA buffer to hold all MTRRs content.
Returns
The pointer of MtrrSetting

This function sets all MTRRs (variable and fixed)

Parameters
[in]MtrrSettingA buffer holding all MTRRs content.
Return values
Thepointer of MtrrSetting

Definition at line 2800 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]BaseAddressThe physical address that is the start address of a memory region.
[in]LengthThe size in bytes of the memory region.
[in]AttributeThe bit mask of attributes to set for the memory region.
Return values
RETURN_SUCCESSThe attributes were set for the memory region.
RETURN_INVALID_PARAMETERLength is zero.
RETURN_UNSUPPORTEDThe processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
RETURN_UNSUPPORTEDThe bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length.
RETURN_ACCESS_DENIEDThe attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
RETURN_OUT_OF_RESOURCESThere 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_SMALLThe 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]BaseAddressThe physical address that is the start address of a memory range.
[in]LengthThe size in bytes of the memory range.
[in]AttributesThe bit mask of attributes to set for the memory range.
Return values
RETURN_SUCCESSThe attributes were set for the memory range.
RETURN_INVALID_PARAMETERLength is zero.
RETURN_UNSUPPORTEDThe processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
RETURN_UNSUPPORTEDThe bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length.
RETURN_ACCESS_DENIEDThe attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
RETURN_OUT_OF_RESOURCESThere 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_SMALLThe fixed internal scratch buffer is too small for MTRR calculation. Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify external scratch buffer.

Definition at line 2691 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]MtrrSettingMTRR setting buffer to be set.
[in]BaseAddressThe physical address that is the start address of a memory region.
[in]LengthThe size in bytes of the memory region.
[in]AttributeThe bit mask of attributes to set for the memory region.
Return values
RETURN_SUCCESSThe attributes were set for the memory region.
RETURN_INVALID_PARAMETERLength is zero.
RETURN_UNSUPPORTEDThe processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
RETURN_UNSUPPORTEDThe bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length.
RETURN_ACCESS_DENIEDThe attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
RETURN_OUT_OF_RESOURCESThere 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_SMALLThe 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]MtrrSettingMTRR setting buffer to be set.
[in]BaseAddressThe physical address that is the start address of a memory range.
[in]LengthThe size in bytes of the memory range.
[in]AttributeThe bit mask of attributes to set for the memory range.
Return values
RETURN_SUCCESSThe attributes were set for the memory range.
RETURN_INVALID_PARAMETERLength is zero.
RETURN_UNSUPPORTEDThe processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length.
RETURN_UNSUPPORTEDThe bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length.
RETURN_ACCESS_DENIEDThe attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
RETURN_OUT_OF_RESOURCESThere 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_SMALLThe fixed internal scratch buffer is too small for MTRR calculation. Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify external scratch buffer.

Definition at line 2638 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]MtrrSettingMTRR setting buffer to be set.
[in]ScratchA temporary scratch buffer that is used to perform the calculation.
[in,out]ScratchSizePointer 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]RangesPointer 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]RangeCountCount of MTRR_MEMORY_RANGE.
Return values
RETURN_SUCCESSThe attributes were set for all the memory ranges.
RETURN_INVALID_PARAMETERLength in any range is zero.
RETURN_UNSUPPORTEDThe processor does not support one or more bytes of the memory resource range specified by BaseAddress and Length in any range.
RETURN_UNSUPPORTEDThe bit mask of attributes is not support for the memory resource range specified by BaseAddress and Length in any range.
RETURN_OUT_OF_RESOURCESThere are not enough system resources to modify the attributes of the memory resource ranges.
RETURN_ACCESS_DENIEDThe attributes for the memory resource range specified by BaseAddress and Length cannot be modified.
RETURN_BUFFER_TOO_SMALLThe scratch buffer is too small for MTRR calculation.

Definition at line 2260 of file MtrrLib.c.