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