4 Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 // According to IA32 SDM, MTRRs number and MSR offset are always consistent
20 // for IA32 processor family
24 // The semantics of below macro is MAX_MTRR_NUMBER_OF_VARIABLE_MTRR, the real number can be read out from MTRR_CAP register.
26 #define MTRR_NUMBER_OF_VARIABLE_MTRR 32
28 // Firmware need reserve 2 MTRR for OS
29 // Note: It is replaced by PCD PcdCpuNumberOfReservedVariableMtrrs
31 #define RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER 2
33 #define MTRR_NUMBER_OF_FIXED_MTRR 11
36 // Structure to describe a fixed MTRR
45 // Structure to describe a variable MTRR
57 // Structure to hold base and mask pair for variable MTRR register
59 typedef struct _MTRR_VARIABLE_SETTING_
{
62 } MTRR_VARIABLE_SETTING
;
65 // Array for variable MTRRs
67 typedef struct _MTRR_VARIABLE_SETTINGS_
{
68 MTRR_VARIABLE_SETTING Mtrr
[MTRR_NUMBER_OF_VARIABLE_MTRR
];
69 } MTRR_VARIABLE_SETTINGS
;
72 // Array for fixed MTRRs
74 typedef struct _MTRR_FIXED_SETTINGS_
{
75 UINT64 Mtrr
[MTRR_NUMBER_OF_FIXED_MTRR
];
76 } MTRR_FIXED_SETTINGS
;
79 // Structure to hold all MTRRs
81 typedef struct _MTRR_SETTINGS_
{
82 MTRR_FIXED_SETTINGS Fixed
;
83 MTRR_VARIABLE_SETTINGS Variables
;
92 CacheWriteCombining
= 1,
93 CacheWriteThrough
= 4,
94 CacheWriteProtected
= 5,
97 } MTRR_MEMORY_CACHE_TYPE
;
99 #define MTRR_CACHE_UNCACHEABLE 0
100 #define MTRR_CACHE_WRITE_COMBINING 1
101 #define MTRR_CACHE_WRITE_THROUGH 4
102 #define MTRR_CACHE_WRITE_PROTECTED 5
103 #define MTRR_CACHE_WRITE_BACK 6
104 #define MTRR_CACHE_INVALID_TYPE 7
109 MTRR_MEMORY_CACHE_TYPE Type
;
113 Returns the variable MTRR count for the CPU.
115 @return Variable MTRR count
120 GetVariableMtrrCount (
125 Returns the firmware usable variable MTRR count for the CPU.
127 @return Firmware usable variable MTRR count
132 GetFirmwareVariableMtrrCount (
137 This function attempts to set the attributes for a memory range.
139 @param[in] BaseAddress The physical address that is the start
140 address of a memory region.
141 @param[in] Length The size in bytes of the memory region.
142 @param[in] Attribute The bit mask of attributes to set for the
145 @retval RETURN_SUCCESS The attributes were set for the memory
147 @retval RETURN_INVALID_PARAMETER Length is zero.
148 @retval RETURN_UNSUPPORTED The processor does not support one or
149 more bytes of the memory resource range
150 specified by BaseAddress and Length.
151 @retval RETURN_UNSUPPORTED The bit mask of attributes is not support
152 for the memory resource range specified
153 by BaseAddress and Length.
154 @retval RETURN_ACCESS_DENIED The attributes for the memory resource
155 range specified by BaseAddress and Length
157 @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to
158 modify the attributes of the memory
160 Multiple memory range attributes setting by calling this API multiple
161 times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean
162 the number of CPU MTRRs are too small to set such memory attributes.
163 Pass the multiple memory range attributes to one call of
164 MtrrSetMemoryAttributesInMtrrSettings() may succeed.
165 @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.
166 Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify
167 external scratch buffer.
171 MtrrSetMemoryAttribute (
172 IN PHYSICAL_ADDRESS BaseAddress
,
174 IN MTRR_MEMORY_CACHE_TYPE Attribute
179 This function will get the memory cache type of the specific address.
180 This function is mainly for debugging purposes.
182 @param[in] Address The specific address
184 @return The memory cache type of the specific address
187 MTRR_MEMORY_CACHE_TYPE
189 MtrrGetMemoryAttribute (
190 IN PHYSICAL_ADDRESS Address
195 This function will get the raw value in variable MTRRs
197 @param[out] VariableSettings A buffer to hold variable MTRRs content.
199 @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable MTRR
202 MTRR_VARIABLE_SETTINGS
*
204 MtrrGetVariableMtrr (
205 OUT MTRR_VARIABLE_SETTINGS
*VariableSettings
210 This function sets variable MTRRs
212 @param[in] VariableSettings A buffer to hold variable MTRRs content.
214 @return The pointer of VariableSettings
217 MTRR_VARIABLE_SETTINGS
*
219 MtrrSetVariableMtrr (
220 IN MTRR_VARIABLE_SETTINGS
*VariableSettings
225 This function gets the content in fixed MTRRs
227 @param[out] FixedSettings A buffer to hold fixed MTRRs content.
229 @return The pointer of FixedSettings
235 OUT MTRR_FIXED_SETTINGS
*FixedSettings
240 This function sets fixed MTRRs
242 @param[in] FixedSettings A buffer holding fixed MTRRs content.
244 @return The pointer of FixedSettings
250 IN MTRR_FIXED_SETTINGS
*FixedSettings
255 This function gets the content in all MTRRs (variable and fixed)
257 @param[out] MtrrSetting A buffer to hold all MTRRs content.
259 @return The pointer of MtrrSetting
265 OUT MTRR_SETTINGS
*MtrrSetting
270 This function sets all MTRRs (variable and fixed)
272 @param[in] MtrrSetting A buffer to hold all MTRRs content.
274 @return The pointer of MtrrSetting
280 IN MTRR_SETTINGS
*MtrrSetting
285 Get the attribute of variable MTRRs.
287 This function shadows the content of variable MTRRs into
288 an internal array: VariableMtrr
290 @param[in] MtrrValidBitsMask The mask for the valid bit of the MTRR
291 @param[in] MtrrValidAddressMask The valid address mask for MTRR since the base address in
292 MTRR must align to 4K, so valid address mask equal to
293 MtrrValidBitsMask & 0xfffffffffffff000ULL
294 @param[out] VariableMtrr The array to shadow variable MTRRs content
296 @return The return value of this parameter indicates the number of
297 MTRRs which has been used.
301 MtrrGetMemoryAttributeInVariableMtrr (
302 IN UINT64 MtrrValidBitsMask
,
303 IN UINT64 MtrrValidAddressMask
,
304 OUT VARIABLE_MTRR
*VariableMtrr
309 This function prints all MTRRs for debugging.
313 MtrrDebugPrintAllMtrrs (
318 Checks if MTRR is supported.
320 @retval TRUE MTRR is supported.
321 @retval FALSE MTRR is not supported.
331 Returns the default MTRR cache type for the system.
333 @return The default MTRR cache type.
336 MTRR_MEMORY_CACHE_TYPE
338 MtrrGetDefaultMemoryType (
343 This function attempts to set the attributes into MTRR setting buffer for a memory range.
345 @param[in, out] MtrrSetting MTRR setting buffer to be set.
346 @param[in] BaseAddress The physical address that is the start address
348 @param[in] Length The size in bytes of the memory region.
349 @param[in] Attribute The bit mask of attributes to set for the
352 @retval RETURN_SUCCESS The attributes were set for the memory region.
353 @retval RETURN_INVALID_PARAMETER Length is zero.
354 @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the
355 memory resource range specified by BaseAddress and Length.
356 @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource
357 range specified by BaseAddress and Length.
358 @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by
359 BaseAddress and Length cannot be modified.
360 @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of
361 the memory resource range.
362 Multiple memory range attributes setting by calling this API multiple
363 times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean
364 the number of CPU MTRRs are too small to set such memory attributes.
365 Pass the multiple memory range attributes to one call of
366 MtrrSetMemoryAttributesInMtrrSettings() may succeed.
367 @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.
368 Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify
369 external scratch buffer.
373 MtrrSetMemoryAttributeInMtrrSettings (
374 IN OUT MTRR_SETTINGS
*MtrrSetting
,
375 IN PHYSICAL_ADDRESS BaseAddress
,
377 IN MTRR_MEMORY_CACHE_TYPE Attribute
381 This function attempts to set the attributes into MTRR setting buffer for multiple memory ranges.
383 @param[in, out] MtrrSetting MTRR setting buffer to be set.
384 @param[in] Scratch A temporary scratch buffer that is used to perform the calculation.
385 @param[in, out] ScratchSize Pointer to the size in bytes of the scratch buffer.
386 It may be updated to the actual required size when the calculation
387 needs more scratch buffer.
388 @param[in] Ranges Pointer to an array of MTRR_MEMORY_RANGE.
389 When range overlap happens, the last one takes higher priority.
390 When the function returns, either all the attributes are set successfully,
391 or none of them is set.
392 @param[in] RangeCount Count of MTRR_MEMORY_RANGE.
394 @retval RETURN_SUCCESS The attributes were set for all the memory ranges.
395 @retval RETURN_INVALID_PARAMETER Length in any range is zero.
396 @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the
397 memory resource range specified by BaseAddress and Length in any range.
398 @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource
399 range specified by BaseAddress and Length in any range.
400 @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of
401 the memory resource ranges.
402 @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by
403 BaseAddress and Length cannot be modified.
404 @retval RETURN_BUFFER_TOO_SMALL The scratch buffer is too small for MTRR calculation.
408 MtrrSetMemoryAttributesInMtrrSettings (
409 IN OUT MTRR_SETTINGS
*MtrrSetting
,
411 IN OUT UINTN
*ScratchSize
,
412 IN CONST MTRR_MEMORY_RANGE
*Ranges
,
415 #endif // _MTRR_LIB_H_