UefiCpuPkg/Include/Library/MtrrLib.h

   1 /** @file
   2   MTRR setting library
   3
   4   Copyright (c) 2008 - 2017, 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   CacheInvalid        = 7
 124 } MTRR_MEMORY_CACHE_TYPE;
 125
 126 #define  MTRR_CACHE_UNCACHEABLE      0
 127 #define  MTRR_CACHE_WRITE_COMBINING  1
 128 #define  MTRR_CACHE_WRITE_THROUGH    4
 129 #define  MTRR_CACHE_WRITE_PROTECTED  5
 130 #define  MTRR_CACHE_WRITE_BACK       6
 131 #define  MTRR_CACHE_INVALID_TYPE     7
 132
 133 /**
 134   Returns the variable MTRR count for the CPU.
 135
 136   @return Variable MTRR count
 137
 138 **/
 139 UINT32
 140 EFIAPI
 141 GetVariableMtrrCount (
 142   VOID
 143   );
 144
 145 /**
 146   Returns the firmware usable variable MTRR count for the CPU.
 147
 148   @return Firmware usable variable MTRR count
 149
 150 **/
 151 UINT32
 152 EFIAPI
 153 GetFirmwareVariableMtrrCount (
 154   VOID
 155   );
 156
 157 /**
 158   This function attempts to set the attributes for a memory range.
 159
 160   @param[in]       BaseAddress       The physical address that is the start
 161                                      address of a memory region.
 162   @param[in]       Length            The size in bytes of the memory region.
 163   @param[in]       Attribute         The bit mask of attributes to set for the
 164                                      memory region.
 165
 166   @retval RETURN_SUCCESS            The attributes were set for the memory
 167                                     region.
 168   @retval RETURN_INVALID_PARAMETER  Length is zero.
 169   @retval RETURN_UNSUPPORTED        The processor does not support one or
 170                                     more bytes of the memory resource range
 171                                     specified by BaseAddress and Length.
 172   @retval RETURN_UNSUPPORTED        The bit mask of attributes is not support
 173                                     for the memory resource range specified
 174                                     by BaseAddress and Length.
 175   @retval RETURN_ACCESS_DENIED      The attributes for the memory resource
 176                                     range specified by BaseAddress and Length
 177                                     cannot be modified.
 178   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to
 179                                     modify the attributes of the memory
 180                                     resource range.
 181
 182 **/
 183 RETURN_STATUS
 184 EFIAPI
 185 MtrrSetMemoryAttribute (
 186   IN PHYSICAL_ADDRESS        BaseAddress,
 187   IN UINT64                  Length,
 188   IN MTRR_MEMORY_CACHE_TYPE  Attribute
 189   );
 190
 191
 192 /**
 193   This function will get the memory cache type of the specific address.
 194   This function is mainly for debugging purposes.
 195
 196   @param[in]  Address            The specific address
 197
 198   @return The memory cache type of the specific address
 199
 200 **/
 201 MTRR_MEMORY_CACHE_TYPE
 202 EFIAPI
 203 MtrrGetMemoryAttribute (
 204   IN PHYSICAL_ADDRESS   Address
 205   );
 206
 207
 208 /**
 209   This function will get the raw value in variable MTRRs
 210
 211   @param[out]  VariableSettings   A buffer to hold variable MTRRs content.
 212
 213   @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable MTRR
 214
 215 **/
 216 MTRR_VARIABLE_SETTINGS*
 217 EFIAPI
 218 MtrrGetVariableMtrr (
 219   OUT MTRR_VARIABLE_SETTINGS         *VariableSettings
 220   );
 221
 222
 223 /**
 224   This function sets variable MTRRs
 225
 226   @param[in]  VariableSettings   A buffer to hold variable MTRRs content.
 227
 228   @return The pointer of VariableSettings
 229
 230 **/
 231 MTRR_VARIABLE_SETTINGS*
 232 EFIAPI
 233 MtrrSetVariableMtrr (
 234   IN MTRR_VARIABLE_SETTINGS         *VariableSettings
 235   );
 236
 237
 238 /**
 239   This function gets the content in fixed MTRRs
 240
 241   @param[out]  FixedSettings      A buffer to hold fixed MTRRs content.
 242
 243   @return The pointer of FixedSettings
 244
 245 **/
 246 MTRR_FIXED_SETTINGS*
 247 EFIAPI
 248 MtrrGetFixedMtrr (
 249   OUT MTRR_FIXED_SETTINGS         *FixedSettings
 250   );
 251
 252
 253 /**
 254   This function sets fixed MTRRs
 255
 256   @param[in]   FixedSettings      A buffer holding fixed MTRRs content.
 257
 258   @return  The pointer of FixedSettings
 259
 260 **/
 261 MTRR_FIXED_SETTINGS*
 262 EFIAPI
 263 MtrrSetFixedMtrr (
 264   IN MTRR_FIXED_SETTINGS          *FixedSettings
 265   );
 266
 267
 268 /**
 269   This function gets the content in all MTRRs (variable and fixed)
 270
 271   @param[out]  MtrrSetting   A buffer to hold all MTRRs content.
 272
 273   @return The pointer of MtrrSetting
 274
 275 **/
 276 MTRR_SETTINGS *
 277 EFIAPI
 278 MtrrGetAllMtrrs (
 279   OUT MTRR_SETTINGS                *MtrrSetting
 280   );
 281
 282
 283 /**
 284   This function sets all MTRRs (variable and fixed)
 285
 286   @param[in]  MtrrSetting   A buffer to hold all MTRRs content.
 287
 288   @return The pointer of MtrrSetting
 289
 290 **/
 291 MTRR_SETTINGS *
 292 EFIAPI
 293 MtrrSetAllMtrrs (
 294   IN MTRR_SETTINGS                *MtrrSetting
 295   );
 296
 297
 298 /**
 299   Get the attribute of variable MTRRs.
 300
 301   This function shadows the content of variable MTRRs into
 302   an internal array: VariableMtrr
 303
 304   @param[in]   MtrrValidBitsMask    The mask for the valid bit of the MTRR
 305   @param[in]   MtrrValidAddressMask The valid address mask for MTRR since the base address in
 306                                     MTRR must align to 4K, so valid address mask equal to
 307                                     MtrrValidBitsMask & 0xfffffffffffff000ULL
 308   @param[out]  VariableMtrr         The array to shadow variable MTRRs content
 309
 310   @return                       The return value of this parameter indicates the number of
 311                                 MTRRs which has been used.
 312 **/
 313 UINT32
 314 EFIAPI
 315 MtrrGetMemoryAttributeInVariableMtrr (
 316   IN  UINT64                    MtrrValidBitsMask,
 317   IN  UINT64                    MtrrValidAddressMask,
 318   OUT VARIABLE_MTRR             *VariableMtrr
 319   );
 320
 321
 322 /**
 323   This function prints all MTRRs for debugging.
 324 **/
 325 VOID
 326 EFIAPI
 327 MtrrDebugPrintAllMtrrs (
 328   VOID
 329   );
 330
 331 /**
 332   Checks if MTRR is supported.
 333
 334   @retval TRUE  MTRR is supported.
 335   @retval FALSE MTRR is not supported.
 336
 337 **/
 338 BOOLEAN
 339 EFIAPI
 340 IsMtrrSupported (
 341   VOID
 342   );
 343
 344 /**
 345   Returns the default MTRR cache type for the system.
 346
 347   @return  The default MTRR cache type.
 348
 349 **/
 350 MTRR_MEMORY_CACHE_TYPE
 351 EFIAPI
 352 MtrrGetDefaultMemoryType (
 353   VOID
 354   );
 355
 356 /**
 357   This function attempts to set the attributes into MTRR setting buffer for a memory range.
 358
 359   @param[in, out]  MtrrSetting  MTRR setting buffer to be set.
 360   @param[in]       BaseAddress  The physical address that is the start address
 361                                 of a memory region.
 362   @param[in]       Length       The size in bytes of the memory region.
 363   @param[in]       Attribute    The bit mask of attributes to set for the
 364                                 memory region.
 365
 366   @retval RETURN_SUCCESS            The attributes were set for the memory region.
 367   @retval RETURN_INVALID_PARAMETER  Length is zero.
 368   @retval RETURN_UNSUPPORTED        The processor does not support one or more bytes of the
 369                                     memory resource range specified by BaseAddress and Length.
 370   @retval RETURN_UNSUPPORTED        The bit mask of attributes is not support for the memory resource
 371                                     range specified by BaseAddress and Length.
 372   @retval RETURN_ACCESS_DENIED      The attributes for the memory resource range specified by
 373                                     BaseAddress and Length cannot be modified.
 374   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to modify the attributes of
 375                                     the memory resource range.
 376
 377 **/
 378 RETURN_STATUS
 379 EFIAPI
 380 MtrrSetMemoryAttributeInMtrrSettings (
 381   IN OUT MTRR_SETTINGS       *MtrrSetting,
 382   IN PHYSICAL_ADDRESS        BaseAddress,
 383   IN UINT64                  Length,
 384   IN MTRR_MEMORY_CACHE_TYPE  Attribute
 385   );
 386
 387 #endif // _MTRR_LIB_H_