TianoCore EDK2 master
MtrrLib.c File Reference
#include <Uefi.h>
#include <Register/Intel/Cpuid.h>
#include <Register/Intel/Msr.h>
#include <Library/MtrrLib.h>
#include <Library/BaseLib.h>
#include <Library/CpuLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/DebugLib.h>

Go to the source code of this file.

Data Structures

struct  MTRR_CONTEXT
 
struct  MTRR_LIB_ADDRESS
 

Macros

#define OR_SEED   0x0101010101010101ull
 
#define CLEAR_SEED   0xFFFFFFFFFFFFFFFFull
 
#define MAX_WEIGHT   MAX_UINT8
 
#define SCRATCH_BUFFER_SIZE   (4 * SIZE_4KB)
 
#define MTRR_LIB_ASSERT_ALIGNED(B, L)   ASSERT ((B & ~(L - 1)) == B);
 
#define M(x, y)   ((x) * VertexCount + (y))
 
#define O(x, y)   ((y) * VertexCount + (x))
 

Functions

VOID MtrrDebugPrintAllMtrrsWorker (IN MTRR_SETTINGS *MtrrSetting)
 
UINT32 GetVariableMtrrCountWorker (VOID)
 
UINT32 EFIAPI GetVariableMtrrCount (VOID)
 
UINT32 GetFirmwareVariableMtrrCountWorker (VOID)
 
UINT32 EFIAPI GetFirmwareVariableMtrrCount (VOID)
 
MTRR_MEMORY_CACHE_TYPE MtrrGetDefaultMemoryTypeWorker (IN MTRR_SETTINGS *MtrrSetting)
 
MTRR_MEMORY_CACHE_TYPE EFIAPI MtrrGetDefaultMemoryType (VOID)
 
VOID MtrrLibPreMtrrChange (OUT MTRR_CONTEXT *MtrrContext)
 
VOID MtrrLibPostMtrrChangeEnableCache (IN MTRR_CONTEXT *MtrrContext)
 
VOID MtrrLibPostMtrrChange (IN MTRR_CONTEXT *MtrrContext)
 
MTRR_FIXED_SETTINGSMtrrGetFixedMtrrWorker (OUT MTRR_FIXED_SETTINGS *FixedSettings)
 
MTRR_FIXED_SETTINGS *EFIAPI MtrrGetFixedMtrr (OUT MTRR_FIXED_SETTINGS *FixedSettings)
 
MTRR_VARIABLE_SETTINGSMtrrGetVariableMtrrWorker (IN MTRR_SETTINGS *MtrrSetting, IN UINT32 VariableMtrrCount, OUT MTRR_VARIABLE_SETTINGS *VariableSettings)
 
RETURN_STATUS MtrrLibProgramFixedMtrr (IN MTRR_MEMORY_CACHE_TYPE Type, IN OUT UINT64 *Base, IN OUT UINT64 *Length, IN OUT UINT32 *LastMsrIndex, OUT UINT64 *ClearMask, OUT UINT64 *OrMask)
 
UINT32 MtrrGetMemoryAttributeInVariableMtrrWorker (IN MTRR_VARIABLE_SETTINGS *VariableSettings, IN UINTN VariableMtrrCount, IN UINT64 MtrrValidBitsMask, IN UINT64 MtrrValidAddressMask, OUT VARIABLE_MTRR *VariableMtrr)
 
UINT32 MtrrLibGetRawVariableRanges (IN MTRR_VARIABLE_SETTINGS *VariableSettings, IN UINTN VariableMtrrCount, IN UINT64 MtrrValidBitsMask, IN UINT64 MtrrValidAddressMask, OUT MTRR_MEMORY_RANGE *VariableMtrr)
 
UINT32 EFIAPI MtrrGetMemoryAttributeInVariableMtrr (IN UINT64 MtrrValidBitsMask, IN UINT64 MtrrValidAddressMask, OUT VARIABLE_MTRR *VariableMtrr)
 
UINT64 MtrrLibBiggestAlignment (UINT64 Address, UINT64 Alignment0)
 
BOOLEAN MtrrLibTypeLeftPrecedeRight (IN MTRR_MEMORY_CACHE_TYPE Left, IN MTRR_MEMORY_CACHE_TYPE Right)
 
VOID MtrrLibInitializeMtrrMask (OUT UINT64 *MtrrValidBitsMask, OUT UINT64 *MtrrValidAddressMask)
 
MTRR_MEMORY_CACHE_TYPE MtrrLibPrecedence (IN MTRR_MEMORY_CACHE_TYPE MtrrType1, IN MTRR_MEMORY_CACHE_TYPE MtrrType2)
 
MTRR_MEMORY_CACHE_TYPE MtrrGetMemoryAttributeByAddressWorker (IN MTRR_SETTINGS *MtrrSetting, IN PHYSICAL_ADDRESS Address)
 
MTRR_MEMORY_CACHE_TYPE EFIAPI MtrrGetMemoryAttribute (IN PHYSICAL_ADDRESS Address)
 
RETURN_STATUS MtrrLibSetMemoryType (IN MTRR_MEMORY_RANGE *Ranges, IN UINTN Capacity, IN OUT UINTN *Count, IN UINT64 BaseAddress, IN UINT64 Length, IN MTRR_MEMORY_CACHE_TYPE Type)
 
UINT8 MtrrLibGetNumberOfTypes (IN CONST MTRR_MEMORY_RANGE *Ranges, IN UINTN RangeCount, IN UINT64 BaseAddress, IN UINT64 Length, IN OUT UINT8 *Types OPTIONAL)
 
VOID MtrrLibCalculateLeastMtrrs (IN UINT16 VertexCount, IN MTRR_LIB_ADDRESS *Vertices, IN OUT CONST UINT8 *Weight, IN UINT16 Start, IN UINT16 Stop, IN BOOLEAN IncludeOptional)
 
RETURN_STATUS MtrrLibAppendVariableMtrr (IN OUT MTRR_MEMORY_RANGE *Mtrrs, IN UINT32 MtrrCapacity, IN OUT UINT32 *MtrrCount, IN UINT64 BaseAddress, IN UINT64 Length, IN MTRR_MEMORY_CACHE_TYPE Type)
 
MTRR_MEMORY_CACHE_TYPE MtrrLibLowestType (IN UINT8 TypeBits)
 
BOOLEAN MtrrLibIsPowerOfTwo (IN UINT64 Operand)
 
RETURN_STATUS MtrrLibCalculateSubtractivePath (IN MTRR_MEMORY_CACHE_TYPE DefaultType, IN UINT64 A0, IN CONST MTRR_MEMORY_RANGE *Ranges, IN UINTN RangeCount, IN UINT16 VertexCount, IN MTRR_LIB_ADDRESS *Vertices, IN OUT UINT8 *Weight, IN UINT16 Start, IN UINT16 Stop, IN UINT8 Types, IN UINT8 TypeCount, IN OUT MTRR_MEMORY_RANGE *Mtrrs OPTIONAL, IN UINT32 MtrrCapacity OPTIONAL, IN OUT UINT32 *MtrrCount OPTIONAL)
 
RETURN_STATUS MtrrLibCalculateMtrrs (IN MTRR_MEMORY_CACHE_TYPE DefaultType, IN UINT64 A0, IN CONST MTRR_MEMORY_RANGE *Ranges, IN UINTN RangeCount, IN VOID *Scratch, IN OUT UINTN *ScratchSize, IN OUT MTRR_MEMORY_RANGE *Mtrrs, IN UINT32 MtrrCapacity, IN OUT UINT32 *MtrrCount)
 
RETURN_STATUS MtrrLibApplyFixedMtrrs (IN MTRR_FIXED_SETTINGS *Fixed, IN OUT MTRR_MEMORY_RANGE *Ranges, IN UINTN RangeCapacity, IN OUT UINTN *RangeCount)
 
RETURN_STATUS MtrrLibApplyVariableMtrrs (IN CONST MTRR_MEMORY_RANGE *VariableMtrr, IN UINT32 VariableMtrrCount, IN OUT MTRR_MEMORY_RANGE *Ranges, IN UINTN RangeCapacity, IN OUT UINTN *RangeCount)
 
UINT8 MtrrLibGetCompatibleTypes (IN CONST MTRR_MEMORY_RANGE *Ranges, IN UINTN RangeCount)
 
VOID MtrrLibMergeVariableMtrr (MTRR_MEMORY_RANGE *DstMtrrs, UINT32 DstMtrrCount, MTRR_MEMORY_RANGE *SrcMtrrs, UINT32 SrcMtrrCount, BOOLEAN *Modified)
 
RETURN_STATUS MtrrLibSetMemoryRanges (IN MTRR_MEMORY_CACHE_TYPE DefaultType, IN UINT64 A0, IN MTRR_MEMORY_RANGE *Ranges, IN UINTN RangeCount, IN VOID *Scratch, IN OUT UINTN *ScratchSize, OUT MTRR_MEMORY_RANGE *VariableMtrr, IN UINT32 VariableMtrrCapacity, OUT UINT32 *VariableMtrrCount)
 
RETURN_STATUS MtrrLibSetBelow1MBMemoryAttribute (IN OUT UINT64 *ClearMasks, IN OUT UINT64 *OrMasks, IN PHYSICAL_ADDRESS BaseAddress, IN UINT64 Length, IN MTRR_MEMORY_CACHE_TYPE Type)
 
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 MtrrSetMemoryAttributeInMtrrSettings (IN OUT MTRR_SETTINGS *MtrrSetting, IN PHYSICAL_ADDRESS BaseAddress, IN UINT64 Length, IN MTRR_MEMORY_CACHE_TYPE Attribute)
 
RETURN_STATUS EFIAPI MtrrSetMemoryAttribute (IN PHYSICAL_ADDRESS BaseAddress, IN UINT64 Length, IN MTRR_MEMORY_CACHE_TYPE Attribute)
 
VOID MtrrSetVariableMtrrWorker (IN MTRR_VARIABLE_SETTINGS *VariableSettings)
 
VOID MtrrSetFixedMtrrWorker (IN MTRR_FIXED_SETTINGS *FixedSettings)
 
MTRR_SETTINGS *EFIAPI MtrrGetAllMtrrs (OUT MTRR_SETTINGS *MtrrSetting)
 
MTRR_SETTINGS *EFIAPI MtrrSetAllMtrrs (IN MTRR_SETTINGS *MtrrSetting)
 
BOOLEAN EFIAPI IsMtrrSupported (VOID)
 
VOID EFIAPI MtrrDebugPrintAllMtrrs (VOID)
 

Variables

CONST FIXED_MTRR mMtrrLibFixedMtrrTable []
 
GLOBAL_REMOVE_IF_UNREFERENCED CONST CHAR8mMtrrMemoryCacheTypeShortName []
 

Detailed Description

MTRR setting library

Note:
Most of services in this library instance are suggested to be invoked by BSP only, except for MtrrSetAllMtrrs() which is used to sync BSP's MTRR setting to APs.

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

Definition in file MtrrLib.c.

Macro Definition Documentation

◆ CLEAR_SEED

#define CLEAR_SEED   0xFFFFFFFFFFFFFFFFull

Definition at line 24 of file MtrrLib.c.

◆ M

#define M (   x,
 
)    ((x) * VertexCount + (y))

Definition at line 29 of file MtrrLib.c.

◆ MAX_WEIGHT

#define MAX_WEIGHT   MAX_UINT8

Definition at line 25 of file MtrrLib.c.

◆ MTRR_LIB_ASSERT_ALIGNED

#define MTRR_LIB_ASSERT_ALIGNED (   B,
 
)    ASSERT ((B & ~(L - 1)) == B);

Definition at line 27 of file MtrrLib.c.

◆ O

#define O (   x,
 
)    ((y) * VertexCount + (x))

Definition at line 30 of file MtrrLib.c.

◆ OR_SEED

#define OR_SEED   0x0101010101010101ull

Definition at line 23 of file MtrrLib.c.

◆ SCRATCH_BUFFER_SIZE

#define SCRATCH_BUFFER_SIZE   (4 * SIZE_4KB)

Definition at line 26 of file MtrrLib.c.

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.

◆ GetFirmwareVariableMtrrCountWorker()

UINT32 GetFirmwareVariableMtrrCountWorker ( VOID  )

Worker function returns the firmware usable variable MTRR count for the CPU.

Returns
Firmware usable variable MTRR count

Definition at line 187 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.

◆ GetVariableMtrrCountWorker()

UINT32 GetVariableMtrrCountWorker ( VOID  )

Worker function returns the variable MTRR count for the CPU.

Returns
Variable MTRR count

Definition at line 150 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.

◆ MtrrDebugPrintAllMtrrsWorker()

VOID MtrrDebugPrintAllMtrrsWorker ( IN MTRR_SETTINGS MtrrSetting)

Worker function prints all MTRRs for debugging.

If MtrrSetting is not NULL, print MTRR settings from input MTRR settings buffer. If MtrrSetting is NULL, print MTRR settings from MTRRs.

Parameters
MtrrSettingA buffer holding all MTRRs content.

Definition at line 2879 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.
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.

◆ MtrrGetDefaultMemoryTypeWorker()

MTRR_MEMORY_CACHE_TYPE MtrrGetDefaultMemoryTypeWorker ( IN MTRR_SETTINGS MtrrSetting)

Worker function returns the default MTRR cache type for the system.

If MtrrSetting is not NULL, returns the default MTRR cache type from input MTRR settings buffer. If MtrrSetting is NULL, returns the default MTRR cache type from MSR.

Parameters
[in]MtrrSettingA buffer holding all MTRRs content.
Returns
The default MTRR cache type.

Definition at line 235 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.
Return values
Thepointer of FixedSettings

Definition at line 409 of file MtrrLib.c.

◆ MtrrGetFixedMtrrWorker()

MTRR_FIXED_SETTINGS * MtrrGetFixedMtrrWorker ( OUT MTRR_FIXED_SETTINGS FixedSettings)

Worker function gets the content in fixed MTRRs

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

Definition at line 385 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 debug purpose.

Parameters
[in]AddressThe specific address
Returns
Memory cache type of the specific address

Definition at line 932 of file MtrrLib.c.

◆ MtrrGetMemoryAttributeByAddressWorker()

MTRR_MEMORY_CACHE_TYPE MtrrGetMemoryAttributeByAddressWorker ( IN MTRR_SETTINGS MtrrSetting,
IN PHYSICAL_ADDRESS  Address 
)

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

If MtrrSetting is not NULL, gets the memory cache type from input MTRR settings buffer. If MtrrSetting is NULL, gets the memory cache type from MTRRs.

Parameters
[in]MtrrSettingA buffer holding all MTRRs content.
[in]AddressThe specific address
Returns
Memory cache type of the specific address

Definition at line 822 of file MtrrLib.c.

◆ MtrrGetMemoryAttributeInVariableMtrr()

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

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.

◆ MtrrGetMemoryAttributeInVariableMtrrWorker()

UINT32 MtrrGetMemoryAttributeInVariableMtrrWorker ( IN MTRR_VARIABLE_SETTINGS VariableSettings,
IN UINTN  VariableMtrrCount,
IN UINT64  MtrrValidBitsMask,
IN UINT64  MtrrValidAddressMask,
OUT VARIABLE_MTRR VariableMtrr 
)

Worker function gets the attribute of variable MTRRs.

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

Parameters
[in]VariableSettingsThe variable MTRR values to shadow
[in]VariableMtrrCountThe number of variable MTRRs
[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
Number of MTRRs which has been used.

Definition at line 587 of file MtrrLib.c.

◆ MtrrGetVariableMtrrWorker()

MTRR_VARIABLE_SETTINGS * MtrrGetVariableMtrrWorker ( IN MTRR_SETTINGS MtrrSetting,
IN UINT32  VariableMtrrCount,
OUT MTRR_VARIABLE_SETTINGS VariableSettings 
)

Worker function will get the raw value in variable MTRRs

If MtrrSetting is not NULL, gets the variable MTRRs raw value from input MTRR settings buffer. If MtrrSetting is NULL, gets the variable MTRRs raw value from MTRRs.

Parameters
[in]MtrrSettingA buffer holding all MTRRs content.
[in]VariableMtrrCountNumber of variable MTRRs.
[out]VariableSettingsA buffer to hold variable MTRRs content.
Returns
The VariableSettings input pointer

Definition at line 435 of file MtrrLib.c.

◆ MtrrLibAppendVariableMtrr()

RETURN_STATUS MtrrLibAppendVariableMtrr ( IN OUT MTRR_MEMORY_RANGE Mtrrs,
IN UINT32  MtrrCapacity,
IN OUT UINT32 MtrrCount,
IN UINT64  BaseAddress,
IN UINT64  Length,
IN MTRR_MEMORY_CACHE_TYPE  Type 
)

Append the MTRR setting to MTRR setting array.

Parameters
MtrrsArray holding all MTRR settings.
MtrrCapacityCapacity of the MTRR array.
MtrrCountThe count of MTRR settings in array.
BaseAddressBase address.
LengthLength.
TypeMemory type.
Return values
RETURN_SUCCESSMTRR setting is appended to array.
RETURN_OUT_OF_RESOURCESArray is full.

Definition at line 1215 of file MtrrLib.c.

◆ MtrrLibApplyFixedMtrrs()

RETURN_STATUS MtrrLibApplyFixedMtrrs ( IN MTRR_FIXED_SETTINGS Fixed,
IN OUT MTRR_MEMORY_RANGE Ranges,
IN UINTN  RangeCapacity,
IN OUT UINTN RangeCount 
)

Apply the fixed MTRR settings to memory range array.

Parameters
FixedThe fixed MTRR settings.
RangesReturn the memory range array holding memory type settings for all memory address.
RangeCapacityThe capacity of memory range array.
RangeCountReturn the count of memory range.
Return values
RETURN_SUCCESSThe memory range array is returned successfully.
RETURN_OUT_OF_RESOURCESThe count of memory ranges exceeds capacity.

Definition at line 1757 of file MtrrLib.c.

◆ MtrrLibApplyVariableMtrrs()

RETURN_STATUS MtrrLibApplyVariableMtrrs ( IN CONST MTRR_MEMORY_RANGE VariableMtrr,
IN UINT32  VariableMtrrCount,
IN OUT MTRR_MEMORY_RANGE Ranges,
IN UINTN  RangeCapacity,
IN OUT UINTN RangeCount 
)

Apply the variable MTRR settings to memory range array.

Parameters
VariableMtrrThe variable MTRR array.
VariableMtrrCountThe count of variable MTRRs.
RangesReturn the memory range array with new MTRR settings applied.
RangeCapacityThe capacity of memory range array.
RangeCountReturn the count of memory range.
Return values
RETURN_SUCCESSThe memory range array is returned successfully.
RETURN_OUT_OF_RESOURCESThe count of memory ranges exceeds capacity.

Definition at line 1808 of file MtrrLib.c.

◆ MtrrLibBiggestAlignment()

UINT64 MtrrLibBiggestAlignment ( UINT64  Address,
UINT64  Alignment0 
)

Return the biggest alignment (lowest set bit) of address. The function is equivalent to: 1 << LowBitSet64 (Address).

Parameters
AddressThe address to return the alignment.
Alignment0The alignment to return when Address is 0.
Returns
The least alignment of the Address.

Definition at line 708 of file MtrrLib.c.

◆ MtrrLibCalculateLeastMtrrs()

VOID MtrrLibCalculateLeastMtrrs ( IN UINT16  VertexCount,
IN MTRR_LIB_ADDRESS Vertices,
IN OUT CONST UINT8 Weight,
IN UINT16  Start,
IN UINT16  Stop,
IN BOOLEAN  IncludeOptional 
)

Calculate the least MTRR number from vertex Start to Stop and update the Previous of all vertices from Start to Stop is updated to reflect how the memory range is covered by MTRR.

Parameters
VertexCountThe count of vertices in the graph.
VerticesArray holding all vertices.
Weight2-dimention array holding weights between vertices.
StartStart vertex.
StopStop vertex.
IncludeOptionalTRUE to count the optional weight.

Definition at line 1137 of file MtrrLib.c.

◆ MtrrLibCalculateMtrrs()

RETURN_STATUS MtrrLibCalculateMtrrs ( IN MTRR_MEMORY_CACHE_TYPE  DefaultType,
IN UINT64  A0,
IN CONST MTRR_MEMORY_RANGE Ranges,
IN UINTN  RangeCount,
IN VOID Scratch,
IN OUT UINTN ScratchSize,
IN OUT MTRR_MEMORY_RANGE Mtrrs,
IN UINT32  MtrrCapacity,
IN OUT UINT32 MtrrCount 
)

Calculate MTRR settings to cover the specified memory ranges.

Parameters
DefaultTypeDefault memory type.
A0Alignment to use when base address is 0.
RangesMemory range array holding the memory type settings for all memory address.
RangeCountCount of memory ranges.
ScratchA temporary scratch buffer that is used to perform the calculation. This is an optional parameter that may be NULL.
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.
MtrrsArray holding all MTRR settings.
MtrrCapacityCapacity of the MTRR array.
MtrrCountThe count of MTRR settings in array.
Return values
RETURN_SUCCESSVariable MTRRs are allocated successfully.
RETURN_OUT_OF_RESOURCESCount of variable MTRRs exceeds capacity.
RETURN_BUFFER_TOO_SMALLThe scratch buffer is too small for MTRR calculation.

Definition at line 1516 of file MtrrLib.c.

◆ MtrrLibCalculateSubtractivePath()

RETURN_STATUS MtrrLibCalculateSubtractivePath ( IN MTRR_MEMORY_CACHE_TYPE  DefaultType,
IN UINT64  A0,
IN CONST MTRR_MEMORY_RANGE Ranges,
IN UINTN  RangeCount,
IN UINT16  VertexCount,
IN MTRR_LIB_ADDRESS Vertices,
IN OUT UINT8 Weight,
IN UINT16  Start,
IN UINT16  Stop,
IN UINT8  Types,
IN UINT8  TypeCount,
IN OUT MTRR_MEMORY_RANGE *Mtrrs  OPTIONAL,
IN UINT32 MtrrCapacity  OPTIONAL,
IN OUT UINT32 *MtrrCount  OPTIONAL 
)

Calculate the subtractive path from vertex Start to Stop.

Parameters
DefaultTypeDefault memory type.
A0Alignment to use when base address is 0.
RangesArray holding memory type settings for all memory regions.
RangeCountThe count of memory ranges the array holds.
VertexCountThe count of vertices in the graph.
VerticesArray holding all vertices.
Weight2-dimention array holding weights between vertices.
StartStart vertex.
StopStop vertex.
TypesType bit mask of memory range from Start to Stop.
TypeCountNumber of different memory types from Start to Stop.
MtrrsArray holding all MTRR settings.
MtrrCapacityCapacity of the MTRR array.
MtrrCountThe count of MTRR settings in array.
Return values
RETURN_SUCCESSThe subtractive path is calculated successfully.
RETURN_OUT_OF_RESOURCESThe MTRR setting array is full.

Definition at line 1294 of file MtrrLib.c.

◆ MtrrLibGetCompatibleTypes()

UINT8 MtrrLibGetCompatibleTypes ( IN CONST MTRR_MEMORY_RANGE Ranges,
IN UINTN  RangeCount 
)

Return the memory type bit mask that's compatible to first type in the Ranges.

Parameters
RangesMemory range array holding the memory type settings for all memory address.
RangeCountCount of memory ranges.
Returns
Compatible memory type bit mask.

Definition at line 1897 of file MtrrLib.c.

◆ MtrrLibGetNumberOfTypes()

UINT8 MtrrLibGetNumberOfTypes ( IN CONST MTRR_MEMORY_RANGE Ranges,
IN UINTN  RangeCount,
IN UINT64  BaseAddress,
IN UINT64  Length,
IN OUT UINT8 *Types  OPTIONAL 
)

Return the number of memory types in range [BaseAddress, BaseAddress + Length).

Parameters
RangesArray holding memory type settings for all memory regions.
RangeCountThe count of memory ranges the array holds.
BaseAddressBase address.
LengthLength.
TypesReturn bit mask to indicate all memory types in the specified range.
Return values
Numberof memory types.

Definition at line 1084 of file MtrrLib.c.

◆ MtrrLibGetRawVariableRanges()

UINT32 MtrrLibGetRawVariableRanges ( IN MTRR_VARIABLE_SETTINGS VariableSettings,
IN UINTN  VariableMtrrCount,
IN UINT64  MtrrValidBitsMask,
IN UINT64  MtrrValidAddressMask,
OUT MTRR_MEMORY_RANGE VariableMtrr 
)

Convert variable MTRRs to a RAW MTRR_MEMORY_RANGE array. One MTRR_MEMORY_RANGE element is created for each MTRR setting. The routine doesn't remove the overlap or combine the near-by region.

Parameters
[in]VariableSettingsThe variable MTRR values to shadow
[in]VariableMtrrCountThe number of variable MTRRs
[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
Number of MTRRs which has been used.

Definition at line 630 of file MtrrLib.c.

◆ MtrrLibInitializeMtrrMask()

VOID MtrrLibInitializeMtrrMask ( OUT UINT64 MtrrValidBitsMask,
OUT UINT64 MtrrValidAddressMask 
)

Initializes the valid bits mask and valid address mask for MTRRs.

This function initializes the valid bits mask and valid address mask for MTRRs.

Parameters
[out]MtrrValidBitsMaskThe mask for the valid bit of the MTRR
[out]MtrrValidAddressMaskThe valid address mask for the MTRR

Definition at line 754 of file MtrrLib.c.

◆ MtrrLibIsPowerOfTwo()

BOOLEAN MtrrLibIsPowerOfTwo ( IN UINT64  Operand)

Return TRUE when the Operand is exactly power of 2.

Return values
TRUEOperand is exactly power of 2.
FALSEOperand is not power of 2.

Definition at line 1263 of file MtrrLib.c.

◆ MtrrLibLowestType()

MTRR_MEMORY_CACHE_TYPE MtrrLibLowestType ( IN UINT8  TypeBits)

Return the memory type that has the least precedence.

Parameters
TypeBitsBit mask of memory type.
Return values
Memorytype that has the least precedence.

Definition at line 1243 of file MtrrLib.c.

◆ MtrrLibMergeVariableMtrr()

VOID MtrrLibMergeVariableMtrr ( MTRR_MEMORY_RANGE DstMtrrs,
UINT32  DstMtrrCount,
MTRR_MEMORY_RANGE SrcMtrrs,
UINT32  SrcMtrrCount,
BOOLEAN Modified 
)

Overwrite the destination MTRR settings with the source MTRR settings. This routine is to make sure the modification to destination MTRR settings is as small as possible.

Parameters
DstMtrrsDestination MTRR settings.
DstMtrrCountCount of destination MTRR settings.
SrcMtrrsSource MTRR settings.
SrcMtrrCountCount of source MTRR settings.
ModifiedFlag array to indicate which destination MTRR setting is modified.

Definition at line 1944 of file MtrrLib.c.

◆ MtrrLibPostMtrrChange()

VOID MtrrLibPostMtrrChange ( IN MTRR_CONTEXT MtrrContext)

Cleaning up after programming MTRRs.

This function will do some clean up after programming MTRRs: enable MTRR caching functionality, and enable cache

Parameters
[in]MtrrContextPointer to context to restore

Definition at line 359 of file MtrrLib.c.

◆ MtrrLibPostMtrrChangeEnableCache()

VOID MtrrLibPostMtrrChangeEnableCache ( IN MTRR_CONTEXT MtrrContext)

Cleaning up after programming MTRRs.

This function will do some clean up after programming MTRRs: Flush all TLBs, re-enable caching, restore CR4.

Parameters
[in]MtrrContextPointer to context to restore

Definition at line 324 of file MtrrLib.c.

◆ MtrrLibPrecedence()

MTRR_MEMORY_CACHE_TYPE MtrrLibPrecedence ( IN MTRR_MEMORY_CACHE_TYPE  MtrrType1,
IN MTRR_MEMORY_CACHE_TYPE  MtrrType2 
)

Determines the real attribute of a memory range.

This function is to arbitrate the real attribute of the memory when there are 2 MTRRs covers the same memory range. For further details, please refer the IA32 Software Developer's Manual, Volume 3, Section "MTRR Precedences".

Parameters
[in]MtrrType1The first kind of Memory type
[in]MtrrType2The second kind of memory type

Definition at line 787 of file MtrrLib.c.

◆ MtrrLibPreMtrrChange()

VOID MtrrLibPreMtrrChange ( OUT MTRR_CONTEXT MtrrContext)

Preparation before programming MTRR.

This function will do some preparation for programming MTRRs: disable cache, invalid cache and disable MTRR caching functionality

Parameters
[out]MtrrContextPointer to context to save

Definition at line 279 of file MtrrLib.c.

◆ MtrrLibProgramFixedMtrr()

RETURN_STATUS MtrrLibProgramFixedMtrr ( IN MTRR_MEMORY_CACHE_TYPE  Type,
IN OUT UINT64 Base,
IN OUT UINT64 Length,
IN OUT UINT32 LastMsrIndex,
OUT UINT64 ClearMask,
OUT UINT64 OrMask 
)

Programs fixed MTRRs registers.

Parameters
[in]TypeThe memory type to set.
[in,out]BaseThe base address of memory range.
[in,out]LengthThe length of memory range.
[in,out]LastMsrIndexOn input, the last index of the fixed MTRR MSR to program. On return, the current index of the fixed MTRR MSR to program.
[out]ClearMaskThe bits to clear in the fixed MTRR MSR.
[out]OrMaskThe bits to set in the fixed MTRR MSR.
Return values
RETURN_SUCCESSThe cache type was updated successfully
RETURN_UNSUPPORTEDThe requested range or cache type was invalid for the fixed MTRRs.

Definition at line 477 of file MtrrLib.c.

◆ MtrrLibSetBelow1MBMemoryAttribute()

RETURN_STATUS MtrrLibSetBelow1MBMemoryAttribute ( IN OUT UINT64 ClearMasks,
IN OUT UINT64 OrMasks,
IN PHYSICAL_ADDRESS  BaseAddress,
IN UINT64  Length,
IN MTRR_MEMORY_CACHE_TYPE  Type 
)

Set the below-1MB memory attribute to fixed MTRR buffer. Modified flag array indicates which fixed MTRR is modified.

Parameters
[in,out]ClearMasksThe bits (when set) to clear in the fixed MTRR MSR.
[in,out]OrMasksThe bits to set in the fixed MTRR MSR.
[in]BaseAddressBase address.
[in]LengthLength.
[in]TypeMemory type.
Return values
RETURN_SUCCESSThe memory attribute is set successfully.
RETURN_UNSUPPORTEDThe requested range or cache type was invalid for the fixed MTRRs.

Definition at line 2203 of file MtrrLib.c.

◆ MtrrLibSetMemoryRanges()

RETURN_STATUS MtrrLibSetMemoryRanges ( IN MTRR_MEMORY_CACHE_TYPE  DefaultType,
IN UINT64  A0,
IN MTRR_MEMORY_RANGE Ranges,
IN UINTN  RangeCount,
IN VOID Scratch,
IN OUT UINTN ScratchSize,
OUT MTRR_MEMORY_RANGE VariableMtrr,
IN UINT32  VariableMtrrCapacity,
OUT UINT32 VariableMtrrCount 
)

Calculate the variable MTRR settings for all memory ranges.

Parameters
DefaultTypeDefault memory type.
A0Alignment to use when base address is 0.
RangesMemory range array holding the memory type settings for all memory address.
RangeCountCount of memory ranges.
ScratchScratch buffer to be used in MTRR calculation.
ScratchSizePointer to the size of scratch buffer.
VariableMtrrArray holding all MTRR settings.
VariableMtrrCapacityCapacity of the MTRR array.
VariableMtrrCountThe count of MTRR settings in array.
Return values
RETURN_SUCCESSVariable MTRRs are allocated successfully.
RETURN_OUT_OF_RESOURCESCount of variable MTRRs exceeds capacity.
RETURN_BUFFER_TOO_SMALLThe scratch buffer is too small for MTRR calculation. The required scratch buffer size is returned through ScratchSize.

Definition at line 2032 of file MtrrLib.c.

◆ MtrrLibSetMemoryType()

RETURN_STATUS MtrrLibSetMemoryType ( IN MTRR_MEMORY_RANGE Ranges,
IN UINTN  Capacity,
IN OUT UINTN Count,
IN UINT64  BaseAddress,
IN UINT64  Length,
IN MTRR_MEMORY_CACHE_TYPE  Type 
)

Update the Ranges array to change the specified range identified by BaseAddress and Length to Type.

Parameters
RangesArray holding memory type settings for all memory regions.
CapacityThe maximum count of memory ranges the array can hold.
CountReturn the new memory range count in the array.
BaseAddressThe base address of the memory range to change type.
LengthThe length of the memory range to change type.
TypeThe new type of the specified memory range.
Return values
RETURN_SUCCESSThe type of the specified memory range is changed successfully.
RETURN_ALREADY_STARTEDThe type of the specified memory range equals to the desired type.
RETURN_OUT_OF_RESOURCESThe new type set causes the count of memory range exceeds capacity.

Definition at line 962 of file MtrrLib.c.

◆ MtrrLibTypeLeftPrecedeRight()

BOOLEAN MtrrLibTypeLeftPrecedeRight ( IN MTRR_MEMORY_CACHE_TYPE  Left,
IN MTRR_MEMORY_CACHE_TYPE  Right 
)

Return whether the left MTRR type precedes the right MTRR type.

The MTRR type precedence rules are:

  1. UC precedes any other type
  2. WT precedes WB For further details, please refer the IA32 Software Developer's Manual, Volume 3, Section "MTRR Precedences".
Parameters
LeftThe left MTRR type.
RightThe right MTRR type.
Return values
TRUELeft precedes Right.
FALSELeft doesn't precede Right.

Definition at line 736 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 holding all MTRRs content.
Return values
Thepointer of MtrrSetting

Definition at line 2800 of file MtrrLib.c.

◆ MtrrSetFixedMtrrWorker()

VOID MtrrSetFixedMtrrWorker ( IN MTRR_FIXED_SETTINGS FixedSettings)

Worker function setting fixed MTRRs

Parameters
[in]FixedSettingsA buffer to hold fixed MTRRs content.

Definition at line 2736 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 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 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.

◆ MtrrSetVariableMtrrWorker()

VOID MtrrSetVariableMtrrWorker ( IN MTRR_VARIABLE_SETTINGS VariableSettings)

Worker function setting variable MTRRs

Parameters
[in]VariableSettingsA buffer to hold variable MTRRs content.

Definition at line 2707 of file MtrrLib.c.

Variable Documentation

◆ mMtrrLibFixedMtrrTable

CONST FIXED_MTRR mMtrrLibFixedMtrrTable[]

Definition at line 57 of file MtrrLib.c.

◆ mMtrrMemoryCacheTypeShortName

GLOBAL_REMOVE_IF_UNREFERENCED CONST CHAR8* mMtrrMemoryCacheTypeShortName[]
Initial value:
= {
"UC",
"WC",
"R*",
"R*",
"WT",
"WP",
"WB",
"R*"
}

Definition at line 118 of file MtrrLib.c.