UefiCpuPkg/Include/Library/MtrrLib.h

   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 return value of this parameter 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_