]> git.proxmox.com Git - mirror_edk2.git/blame - UefiCpuPkg/Include/Library/MtrrLib.h
BaseTools: Library hashing fix and optimization for --hash feature
[mirror_edk2.git] / UefiCpuPkg / Include / Library / MtrrLib.h
CommitLineData
e50466da 1/** @file\r
2 MTRR setting library\r
3\r
8b2eb7b3 4 Copyright (c) 2008 - 2018, Intel Corporation. All rights reserved.<BR>\r
0acd8697 5 SPDX-License-Identifier: BSD-2-Clause-Patent\r
e50466da 6\r
7**/\r
8\r
9#ifndef _MTRR_LIB_H_\r
10#define _MTRR_LIB_H_\r
11\r
12//\r
341fea64 13// According to IA32 SDM, MTRRs number and MSR offset are always consistent\r
e50466da 14// for IA32 processor family\r
15//\r
3b9be416
JY
16\r
17//\r
3ba736f3 18// 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 19//\r
3ba736f3 20#define MTRR_NUMBER_OF_VARIABLE_MTRR 32\r
3b9be416
JY
21//\r
22// Firmware need reserve 2 MTRR for OS\r
46309b11 23// Note: It is replaced by PCD PcdCpuNumberOfReservedVariableMtrrs\r
3b9be416
JY
24//\r
25#define RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER 2\r
26\r
e50466da 27#define MTRR_NUMBER_OF_FIXED_MTRR 11\r
e50466da 28\r
29//\r
30// Structure to describe a fixed MTRR\r
31//\r
32typedef struct {\r
33 UINT32 Msr;\r
34 UINT32 BaseAddress;\r
35 UINT32 Length;\r
36} FIXED_MTRR;\r
37\r
38//\r
39// Structure to describe a variable MTRR\r
40//\r
41typedef struct {\r
42 UINT64 BaseAddress;\r
43 UINT64 Length;\r
44 UINT64 Type;\r
45 UINT32 Msr;\r
46 BOOLEAN Valid;\r
47 BOOLEAN Used;\r
48} VARIABLE_MTRR;\r
49\r
50//\r
51// Structure to hold base and mask pair for variable MTRR register\r
52//\r
53typedef struct _MTRR_VARIABLE_SETTING_ {\r
76b4cae3
MK
54 UINT64 Base;\r
55 UINT64 Mask;\r
e50466da 56} MTRR_VARIABLE_SETTING;\r
57\r
58//\r
59// Array for variable MTRRs\r
60//\r
61typedef struct _MTRR_VARIABLE_SETTINGS_ {\r
341fea64
RN
62 MTRR_VARIABLE_SETTING Mtrr[MTRR_NUMBER_OF_VARIABLE_MTRR];\r
63} MTRR_VARIABLE_SETTINGS;\r
e50466da 64\r
65//\r
341fea64 66// Array for fixed MTRRs\r
e50466da 67//\r
68typedef struct _MTRR_FIXED_SETTINGS_ {\r
69 UINT64 Mtrr[MTRR_NUMBER_OF_FIXED_MTRR];\r
70} MTRR_FIXED_SETTINGS;\r
71\r
72//\r
73// Structure to hold all MTRRs\r
74//\r
75typedef struct _MTRR_SETTINGS_ {\r
76 MTRR_FIXED_SETTINGS Fixed;\r
77 MTRR_VARIABLE_SETTINGS Variables;\r
78 UINT64 MtrrDefType;\r
79} MTRR_SETTINGS;\r
80\r
81//\r
82// Memory cache types\r
83//\r
84typedef enum {\r
76b4cae3
MK
85 CacheUncacheable = 0,\r
86 CacheWriteCombining = 1,\r
87 CacheWriteThrough = 4,\r
88 CacheWriteProtected = 5,\r
78c49925
RN
89 CacheWriteBack = 6,\r
90 CacheInvalid = 7\r
e50466da 91} MTRR_MEMORY_CACHE_TYPE;\r
92\r
93#define MTRR_CACHE_UNCACHEABLE 0\r
94#define MTRR_CACHE_WRITE_COMBINING 1\r
95#define MTRR_CACHE_WRITE_THROUGH 4\r
96#define MTRR_CACHE_WRITE_PROTECTED 5\r
97#define MTRR_CACHE_WRITE_BACK 6\r
98#define MTRR_CACHE_INVALID_TYPE 7\r
99\r
2bbd7e2f
RN
100typedef struct {\r
101 UINT64 BaseAddress;\r
102 UINT64 Length;\r
103 MTRR_MEMORY_CACHE_TYPE Type;\r
104} MTRR_MEMORY_RANGE;\r
105\r
3b9be416
JY
106/**\r
107 Returns the variable MTRR count for the CPU.\r
108\r
109 @return Variable MTRR count\r
110\r
111**/\r
112UINT32\r
ed8dfd7b 113EFIAPI\r
3b9be416
JY
114GetVariableMtrrCount (\r
115 VOID\r
116 );\r
117\r
118/**\r
119 Returns the firmware usable variable MTRR count for the CPU.\r
120\r
121 @return Firmware usable variable MTRR count\r
122\r
123**/\r
124UINT32\r
ed8dfd7b 125EFIAPI\r
3b9be416
JY
126GetFirmwareVariableMtrrCount (\r
127 VOID\r
128 );\r
129\r
e50466da 130/**\r
131 This function attempts to set the attributes for a memory range.\r
132\r
76b4cae3
MK
133 @param[in] BaseAddress The physical address that is the start\r
134 address of a memory region.\r
135 @param[in] Length The size in bytes of the memory region.\r
136 @param[in] Attribute The bit mask of attributes to set for the\r
137 memory region.\r
e50466da 138\r
76b4cae3
MK
139 @retval RETURN_SUCCESS The attributes were set for the memory\r
140 region.\r
e50466da 141 @retval RETURN_INVALID_PARAMETER Length is zero.\r
76b4cae3
MK
142 @retval RETURN_UNSUPPORTED The processor does not support one or\r
143 more bytes of the memory resource range\r
144 specified by BaseAddress and Length.\r
145 @retval RETURN_UNSUPPORTED The bit mask of attributes is not support\r
146 for the memory resource range specified\r
147 by BaseAddress and Length.\r
148 @retval RETURN_ACCESS_DENIED The attributes for the memory resource\r
149 range specified by BaseAddress and Length\r
150 cannot be modified.\r
151 @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to\r
152 modify the attributes of the memory\r
153 resource range.\r
bc6a8b78
RN
154 Multiple memory range attributes setting by calling this API multiple\r
155 times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean\r
156 the number of CPU MTRRs are too small to set such memory attributes.\r
157 Pass the multiple memory range attributes to one call of\r
158 MtrrSetMemoryAttributesInMtrrSettings() may succeed.\r
8b2eb7b3
RN
159 @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.\r
160 Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify\r
161 external scratch buffer.\r
e50466da 162**/\r
163RETURN_STATUS\r
164EFIAPI\r
165MtrrSetMemoryAttribute (\r
166 IN PHYSICAL_ADDRESS BaseAddress,\r
167 IN UINT64 Length,\r
168 IN MTRR_MEMORY_CACHE_TYPE Attribute\r
169 );\r
170\r
171\r
172/**\r
173 This function will get the memory cache type of the specific address.\r
174 This function is mainly for debugging purposes.\r
175\r
76b4cae3 176 @param[in] Address The specific address\r
e50466da 177\r
178 @return The memory cache type of the specific address\r
179\r
180**/\r
181MTRR_MEMORY_CACHE_TYPE\r
182EFIAPI\r
183MtrrGetMemoryAttribute (\r
184 IN PHYSICAL_ADDRESS Address\r
185 );\r
186\r
187\r
188/**\r
189 This function will get the raw value in variable MTRRs\r
190\r
76b4cae3 191 @param[out] VariableSettings A buffer to hold variable MTRRs content.\r
e50466da 192\r
341fea64 193 @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable MTRR\r
e50466da 194\r
195**/\r
196MTRR_VARIABLE_SETTINGS*\r
197EFIAPI\r
198MtrrGetVariableMtrr (\r
199 OUT MTRR_VARIABLE_SETTINGS *VariableSettings\r
200 );\r
201\r
202\r
203/**\r
341fea64 204 This function sets variable MTRRs\r
e50466da 205\r
76b4cae3 206 @param[in] VariableSettings A buffer to hold variable MTRRs content.\r
e50466da 207\r
208 @return The pointer of VariableSettings\r
209\r
210**/\r
211MTRR_VARIABLE_SETTINGS*\r
212EFIAPI\r
213MtrrSetVariableMtrr (\r
214 IN MTRR_VARIABLE_SETTINGS *VariableSettings\r
215 );\r
216\r
217\r
218/**\r
219 This function gets the content in fixed MTRRs\r
220\r
76b4cae3 221 @param[out] FixedSettings A buffer to hold fixed MTRRs content.\r
e50466da 222\r
223 @return The pointer of FixedSettings\r
224\r
225**/\r
226MTRR_FIXED_SETTINGS*\r
227EFIAPI\r
228MtrrGetFixedMtrr (\r
229 OUT MTRR_FIXED_SETTINGS *FixedSettings\r
230 );\r
231\r
232\r
233/**\r
234 This function sets fixed MTRRs\r
235\r
76b4cae3 236 @param[in] FixedSettings A buffer holding fixed MTRRs content.\r
e50466da 237\r
238 @return The pointer of FixedSettings\r
239\r
240**/\r
241MTRR_FIXED_SETTINGS*\r
242EFIAPI\r
243MtrrSetFixedMtrr (\r
244 IN MTRR_FIXED_SETTINGS *FixedSettings\r
245 );\r
246\r
247\r
248/**\r
249 This function gets the content in all MTRRs (variable and fixed)\r
250\r
76b4cae3 251 @param[out] MtrrSetting A buffer to hold all MTRRs content.\r
e50466da 252\r
253 @return The pointer of MtrrSetting\r
254\r
255**/\r
256MTRR_SETTINGS *\r
257EFIAPI\r
258MtrrGetAllMtrrs (\r
259 OUT MTRR_SETTINGS *MtrrSetting\r
260 );\r
261\r
262\r
263/**\r
264 This function sets all MTRRs (variable and fixed)\r
265\r
76b4cae3 266 @param[in] MtrrSetting A buffer to hold all MTRRs content.\r
e50466da 267\r
268 @return The pointer of MtrrSetting\r
269\r
270**/\r
271MTRR_SETTINGS *\r
272EFIAPI\r
273MtrrSetAllMtrrs (\r
274 IN MTRR_SETTINGS *MtrrSetting\r
275 );\r
276\r
277\r
278/**\r
279 Get the attribute of variable MTRRs.\r
280\r
281 This function shadows the content of variable MTRRs into\r
282 an internal array: VariableMtrr\r
283\r
76b4cae3
MK
284 @param[in] MtrrValidBitsMask The mask for the valid bit of the MTRR\r
285 @param[in] MtrrValidAddressMask The valid address mask for MTRR since the base address in\r
286 MTRR must align to 4K, so valid address mask equal to\r
287 MtrrValidBitsMask & 0xfffffffffffff000ULL\r
288 @param[out] VariableMtrr The array to shadow variable MTRRs content\r
289\r
438f1766 290 @return The return value of this parameter indicates the number of\r
3ba736f3 291 MTRRs which has been used.\r
e50466da 292**/\r
3ba736f3 293UINT32\r
e50466da 294EFIAPI\r
295MtrrGetMemoryAttributeInVariableMtrr (\r
296 IN UINT64 MtrrValidBitsMask,\r
297 IN UINT64 MtrrValidAddressMask,\r
298 OUT VARIABLE_MTRR *VariableMtrr\r
299 );\r
300\r
301\r
302/**\r
303 This function prints all MTRRs for debugging.\r
304**/\r
305VOID\r
ed8dfd7b 306EFIAPI\r
e50466da 307MtrrDebugPrintAllMtrrs (\r
430fbbe0 308 VOID\r
e50466da 309 );\r
310\r
947a573a 311/**\r
312 Checks if MTRR is supported.\r
313\r
314 @retval TRUE MTRR is supported.\r
315 @retval FALSE MTRR is not supported.\r
316\r
317**/\r
318BOOLEAN\r
ed8dfd7b 319EFIAPI\r
947a573a 320IsMtrrSupported (\r
321 VOID\r
322 );\r
323\r
91ec7824 324/**\r
325 Returns the default MTRR cache type for the system.\r
326\r
327 @return The default MTRR cache type.\r
328\r
329**/\r
330MTRR_MEMORY_CACHE_TYPE\r
331EFIAPI\r
332MtrrGetDefaultMemoryType (\r
333 VOID\r
334 );\r
335\r
b970ed68
MK
336/**\r
337 This function attempts to set the attributes into MTRR setting buffer for a memory range.\r
338\r
339 @param[in, out] MtrrSetting MTRR setting buffer to be set.\r
340 @param[in] BaseAddress The physical address that is the start address\r
341 of a memory region.\r
342 @param[in] Length The size in bytes of the memory region.\r
343 @param[in] Attribute The bit mask of attributes to set for the\r
344 memory region.\r
345\r
346 @retval RETURN_SUCCESS The attributes were set for the memory region.\r
347 @retval RETURN_INVALID_PARAMETER Length is zero.\r
348 @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the\r
349 memory resource range specified by BaseAddress and Length.\r
350 @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource\r
351 range specified by BaseAddress and Length.\r
352 @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by\r
353 BaseAddress and Length cannot be modified.\r
354 @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of\r
355 the memory resource range.\r
bc6a8b78
RN
356 Multiple memory range attributes setting by calling this API multiple\r
357 times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean\r
358 the number of CPU MTRRs are too small to set such memory attributes.\r
359 Pass the multiple memory range attributes to one call of\r
360 MtrrSetMemoryAttributesInMtrrSettings() may succeed.\r
8b2eb7b3
RN
361 @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.\r
362 Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify\r
363 external scratch buffer.\r
b970ed68
MK
364**/\r
365RETURN_STATUS\r
366EFIAPI\r
367MtrrSetMemoryAttributeInMtrrSettings (\r
368 IN OUT MTRR_SETTINGS *MtrrSetting,\r
369 IN PHYSICAL_ADDRESS BaseAddress,\r
370 IN UINT64 Length,\r
371 IN MTRR_MEMORY_CACHE_TYPE Attribute\r
372 );\r
373\r
2bbd7e2f
RN
374/**\r
375 This function attempts to set the attributes into MTRR setting buffer for multiple memory ranges.\r
376\r
377 @param[in, out] MtrrSetting MTRR setting buffer to be set.\r
378 @param[in] Scratch A temporary scratch buffer that is used to perform the calculation.\r
379 @param[in, out] ScratchSize Pointer to the size in bytes of the scratch buffer.\r
380 It may be updated to the actual required size when the calculation\r
381 needs more scratch buffer.\r
382 @param[in] Ranges Pointer to an array of MTRR_MEMORY_RANGE.\r
383 When range overlap happens, the last one takes higher priority.\r
384 When the function returns, either all the attributes are set successfully,\r
385 or none of them is set.\r
f6194f5a 386 @param[in] RangeCount Count of MTRR_MEMORY_RANGE.\r
2bbd7e2f
RN
387\r
388 @retval RETURN_SUCCESS The attributes were set for all the memory ranges.\r
389 @retval RETURN_INVALID_PARAMETER Length in any range is zero.\r
390 @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the\r
391 memory resource range specified by BaseAddress and Length in any range.\r
392 @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource\r
393 range specified by BaseAddress and Length in any range.\r
394 @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of\r
395 the memory resource ranges.\r
396 @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by\r
397 BaseAddress and Length cannot be modified.\r
398 @retval RETURN_BUFFER_TOO_SMALL The scratch buffer is too small for MTRR calculation.\r
399**/\r
400RETURN_STATUS\r
401EFIAPI\r
402MtrrSetMemoryAttributesInMtrrSettings (\r
403 IN OUT MTRR_SETTINGS *MtrrSetting,\r
404 IN VOID *Scratch,\r
405 IN OUT UINTN *ScratchSize,\r
406 IN CONST MTRR_MEMORY_RANGE *Ranges,\r
407 IN UINTN RangeCount\r
408 );\r
e50466da 409#endif // _MTRR_LIB_H_\r