Update the copyright notice format
[mirror_edk2.git] / UefiCpuPkg / Include / Library / MtrrLib.h
CommitLineData
e50466da 1/** @file\r
2 MTRR setting library\r
3\r
01a1c0fc
HT
4 Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved.<BR>\r
5 This program and the accompanying materials\r
e50466da 6 are licensed and made available under the terms and conditions of the BSD License\r
7 which accompanies this distribution. The full text of the license may be found at\r
8 http://opensource.org/licenses/bsd-license.php\r
9\r
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
12\r
13**/\r
14\r
15#ifndef _MTRR_LIB_H_\r
16#define _MTRR_LIB_H_\r
17\r
18//\r
19// According to IA32 SDM, MTRRs number and msr offset are always consistent\r
20// for IA32 processor family\r
21//\r
3b9be416
JY
22\r
23//\r
3ba736f3 24// 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 25//\r
3ba736f3 26#define MTRR_NUMBER_OF_VARIABLE_MTRR 32\r
3b9be416
JY
27//\r
28// Firmware need reserve 2 MTRR for OS\r
29//\r
30#define RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER 2\r
31\r
e50466da 32#define MTRR_NUMBER_OF_FIXED_MTRR 11\r
3ba736f3
JY
33//\r
34// Below macro is deprecated, and should not be used.\r
35//\r
36#define FIRMWARE_VARIABLE_MTRR_NUMBER 6\r
3b9be416
JY
37#define MTRR_LIB_IA32_MTRR_CAP 0x0FE\r
38#define MTRR_LIB_IA32_MTRR_CAP_VCNT_MASK 0x0FF\r
e50466da 39#define MTRR_LIB_IA32_MTRR_FIX64K_00000 0x250\r
40#define MTRR_LIB_IA32_MTRR_FIX16K_80000 0x258\r
41#define MTRR_LIB_IA32_MTRR_FIX16K_A0000 0x259\r
42#define MTRR_LIB_IA32_MTRR_FIX4K_C0000 0x268\r
43#define MTRR_LIB_IA32_MTRR_FIX4K_C8000 0x269\r
44#define MTRR_LIB_IA32_MTRR_FIX4K_D0000 0x26A\r
45#define MTRR_LIB_IA32_MTRR_FIX4K_D8000 0x26B\r
46#define MTRR_LIB_IA32_MTRR_FIX4K_E0000 0x26C\r
47#define MTRR_LIB_IA32_MTRR_FIX4K_E8000 0x26D\r
48#define MTRR_LIB_IA32_MTRR_FIX4K_F0000 0x26E\r
49#define MTRR_LIB_IA32_MTRR_FIX4K_F8000 0x26F\r
50#define MTRR_LIB_IA32_VARIABLE_MTRR_BASE 0x200\r
3ba736f3
JY
51//\r
52// Below macro is deprecated, and should not be used.\r
53//\r
54#define MTRR_LIB_IA32_VARIABLE_MTRR_END 0x20F\r
e50466da 55#define MTRR_LIB_IA32_MTRR_DEF_TYPE 0x2FF\r
56#define MTRR_LIB_MSR_VALID_MASK 0xFFFFFFFFFULL\r
57#define MTRR_LIB_CACHE_VALID_ADDRESS 0xFFFFFF000ULL\r
58#define MTRR_LIB_CACHE_MTRR_ENABLED 0x800\r
59#define MTRR_LIB_CACHE_FIXED_MTRR_ENABLED 0x400\r
60\r
61//\r
62// Structure to describe a fixed MTRR\r
63//\r
64typedef struct {\r
65 UINT32 Msr;\r
66 UINT32 BaseAddress;\r
67 UINT32 Length;\r
68} FIXED_MTRR;\r
69\r
70//\r
71// Structure to describe a variable MTRR\r
72//\r
73typedef struct {\r
74 UINT64 BaseAddress;\r
75 UINT64 Length;\r
76 UINT64 Type;\r
77 UINT32 Msr;\r
78 BOOLEAN Valid;\r
79 BOOLEAN Used;\r
80} VARIABLE_MTRR;\r
81\r
82//\r
83// Structure to hold base and mask pair for variable MTRR register\r
84//\r
85typedef struct _MTRR_VARIABLE_SETTING_ {\r
86 UINT64 Base;\r
87 UINT64 Mask;\r
88} MTRR_VARIABLE_SETTING;\r
89\r
90//\r
91// Array for variable MTRRs\r
92//\r
93typedef struct _MTRR_VARIABLE_SETTINGS_ {\r
3ba736f3 94 MTRR_VARIABLE_SETTING Mtrr[MTRR_NUMBER_OF_VARIABLE_MTRR];\r
e50466da 95} MTRR_VARIABLE_SETTINGS;\r
96\r
97//\r
98// Array for fixed mtrrs\r
99//\r
100typedef struct _MTRR_FIXED_SETTINGS_ {\r
101 UINT64 Mtrr[MTRR_NUMBER_OF_FIXED_MTRR];\r
102} MTRR_FIXED_SETTINGS;\r
103\r
104//\r
105// Structure to hold all MTRRs\r
106//\r
107typedef struct _MTRR_SETTINGS_ {\r
108 MTRR_FIXED_SETTINGS Fixed;\r
109 MTRR_VARIABLE_SETTINGS Variables;\r
110 UINT64 MtrrDefType;\r
111} MTRR_SETTINGS;\r
112\r
113//\r
114// Memory cache types\r
115//\r
116typedef enum {\r
117 CacheUncacheable = 0,\r
118 CacheWriteCombining = 1,\r
119 CacheWriteThrough = 4,\r
120 CacheWriteProtected = 5,\r
121 CacheWriteBack = 6\r
122} MTRR_MEMORY_CACHE_TYPE;\r
123\r
124#define MTRR_CACHE_UNCACHEABLE 0\r
125#define MTRR_CACHE_WRITE_COMBINING 1\r
126#define MTRR_CACHE_WRITE_THROUGH 4\r
127#define MTRR_CACHE_WRITE_PROTECTED 5\r
128#define MTRR_CACHE_WRITE_BACK 6\r
129#define MTRR_CACHE_INVALID_TYPE 7\r
130\r
3b9be416
JY
131/**\r
132 Returns the variable MTRR count for the CPU.\r
133\r
134 @return Variable MTRR count\r
135\r
136**/\r
137UINT32\r
ed8dfd7b 138EFIAPI\r
3b9be416
JY
139GetVariableMtrrCount (\r
140 VOID\r
141 );\r
142\r
143/**\r
144 Returns the firmware usable variable MTRR count for the CPU.\r
145\r
146 @return Firmware usable variable MTRR count\r
147\r
148**/\r
149UINT32\r
ed8dfd7b 150EFIAPI\r
3b9be416
JY
151GetFirmwareVariableMtrrCount (\r
152 VOID\r
153 );\r
154\r
e50466da 155/**\r
156 This function attempts to set the attributes for a memory range.\r
157\r
158 @param BaseAddress The physical address that is the start address of a memory region.\r
159 @param Length The size in bytes of the memory region.\r
160 @param Attributes The bit mask of attributes to set for the memory region.\r
161\r
162 @retval RETURN_SUCCESS The attributes were set for the memory region.\r
163 @retval RETURN_INVALID_PARAMETER Length is zero.\r
164 @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the\r
165 memory resource range specified by BaseAddress and Length.\r
166 @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource\r
167 range specified by BaseAddress and Length.\r
168 @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by\r
169 BaseAddress and Length cannot be modified.\r
170 @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of\r
171 the memory resource range.\r
172\r
173**/\r
174RETURN_STATUS\r
175EFIAPI\r
176MtrrSetMemoryAttribute (\r
177 IN PHYSICAL_ADDRESS BaseAddress,\r
178 IN UINT64 Length,\r
179 IN MTRR_MEMORY_CACHE_TYPE Attribute\r
180 );\r
181\r
182\r
183/**\r
184 This function will get the memory cache type of the specific address.\r
185 This function is mainly for debugging purposes.\r
186\r
187 @param Address The specific address\r
188\r
189 @return The memory cache type of the specific address\r
190\r
191**/\r
192MTRR_MEMORY_CACHE_TYPE\r
193EFIAPI\r
194MtrrGetMemoryAttribute (\r
195 IN PHYSICAL_ADDRESS Address\r
196 );\r
197\r
198\r
199/**\r
200 This function will get the raw value in variable MTRRs\r
201\r
202 @param VariableSettings A buffer to hold variable MTRRs content.\r
203\r
204 @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable mtrr\r
205\r
206**/\r
207MTRR_VARIABLE_SETTINGS*\r
208EFIAPI\r
209MtrrGetVariableMtrr (\r
210 OUT MTRR_VARIABLE_SETTINGS *VariableSettings\r
211 );\r
212\r
213\r
214/**\r
215 This function sets fixed MTRRs\r
216\r
217 @param VariableSettings A buffer to hold variable MTRRs content.\r
218\r
219 @return The pointer of VariableSettings\r
220\r
221**/\r
222MTRR_VARIABLE_SETTINGS*\r
223EFIAPI\r
224MtrrSetVariableMtrr (\r
225 IN MTRR_VARIABLE_SETTINGS *VariableSettings\r
226 );\r
227\r
228\r
229/**\r
230 This function gets the content in fixed MTRRs\r
231\r
232 @param FixedSettings A buffer to hold fixed MTRRs content.\r
233\r
234 @return The pointer of FixedSettings\r
235\r
236**/\r
237MTRR_FIXED_SETTINGS*\r
238EFIAPI\r
239MtrrGetFixedMtrr (\r
240 OUT MTRR_FIXED_SETTINGS *FixedSettings\r
241 );\r
242\r
243\r
244/**\r
245 This function sets fixed MTRRs\r
246\r
247 @param FixedSettings A buffer holding fixed MTRRs content.\r
248\r
249 @return The pointer of FixedSettings\r
250\r
251**/\r
252MTRR_FIXED_SETTINGS*\r
253EFIAPI\r
254MtrrSetFixedMtrr (\r
255 IN MTRR_FIXED_SETTINGS *FixedSettings\r
256 );\r
257\r
258\r
259/**\r
260 This function gets the content in all MTRRs (variable and fixed)\r
261\r
262 @param MtrrSetting A buffer to hold all MTRRs content.\r
263\r
264 @return The pointer of MtrrSetting\r
265\r
266**/\r
267MTRR_SETTINGS *\r
268EFIAPI\r
269MtrrGetAllMtrrs (\r
270 OUT MTRR_SETTINGS *MtrrSetting\r
271 );\r
272\r
273\r
274/**\r
275 This function sets all MTRRs (variable and fixed)\r
276\r
277 @param MtrrSetting A buffer to hold all MTRRs content.\r
278\r
279 @return The pointer of MtrrSetting\r
280\r
281**/\r
282MTRR_SETTINGS *\r
283EFIAPI\r
284MtrrSetAllMtrrs (\r
285 IN MTRR_SETTINGS *MtrrSetting\r
286 );\r
287\r
288\r
289/**\r
290 Get the attribute of variable MTRRs.\r
291\r
292 This function shadows the content of variable MTRRs into\r
293 an internal array: VariableMtrr\r
294\r
3ba736f3
JY
295 @param MtrrValidBitsMask The mask for the valid bit of the MTRR\r
296 @param MtrrValidAddressMask The valid address mask for MTRR since the base address in\r
297 MTRR must align to 4K, so valid address mask equal to\r
298 MtrrValidBitsMask & 0xfffffffffffff000ULL\r
299 @param VariableMtrr The array to shadow variable MTRRs content\r
300 @return The ruturn value of this paramter indicates the number of\r
301 MTRRs which has been used.\r
e50466da 302**/\r
3ba736f3 303UINT32\r
e50466da 304EFIAPI\r
305MtrrGetMemoryAttributeInVariableMtrr (\r
306 IN UINT64 MtrrValidBitsMask,\r
307 IN UINT64 MtrrValidAddressMask,\r
308 OUT VARIABLE_MTRR *VariableMtrr\r
309 );\r
310\r
311\r
312/**\r
313 This function prints all MTRRs for debugging.\r
314**/\r
315VOID\r
ed8dfd7b 316EFIAPI\r
e50466da 317MtrrDebugPrintAllMtrrs (\r
318 );\r
319\r
947a573a 320/**\r
321 Checks if MTRR is supported.\r
322\r
323 @retval TRUE MTRR is supported.\r
324 @retval FALSE MTRR is not supported.\r
325\r
326**/\r
327BOOLEAN\r
ed8dfd7b 328EFIAPI\r
947a573a 329IsMtrrSupported (\r
330 VOID\r
331 );\r
332\r
e50466da 333#endif // _MTRR_LIB_H_\r