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