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  BaseAddress            The physical address that is the start address of a memory region.
 160   @param  Length                 The size in bytes of the memory region.
 161   @param  Attributes             The bit mask of attributes to set for the memory region.
 162
 163   @retval RETURN_SUCCESS            The attributes were set for the memory region.
 164   @retval RETURN_INVALID_PARAMETER  Length is zero.
 165   @retval RETURN_UNSUPPORTED        The processor does not support one or more bytes of the
 166                                  memory resource range specified by BaseAddress and Length.
 167   @retval RETURN_UNSUPPORTED        The bit mask of attributes is not support for the memory resource
 168                                  range specified by BaseAddress and Length.
 169   @retval RETURN_ACCESS_DENIED      The attributes for the memory resource range specified by
 170                                  BaseAddress and Length cannot be modified.
 171   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to modify the attributes of
 172                                  the memory resource range.
 173
 174 **/
 175 RETURN_STATUS
 176 EFIAPI
 177 MtrrSetMemoryAttribute (
 178   IN PHYSICAL_ADDRESS        BaseAddress,
 179   IN UINT64                  Length,
 180   IN MTRR_MEMORY_CACHE_TYPE  Attribute
 181   );
 182
 183
 184 /**
 185   This function will get the memory cache type of the specific address.
 186   This function is mainly for debugging purposes.
 187
 188   @param  Address            The specific address
 189
 190   @return The memory cache type of the specific address
 191
 192 **/
 193 MTRR_MEMORY_CACHE_TYPE
 194 EFIAPI
 195 MtrrGetMemoryAttribute (
 196   IN PHYSICAL_ADDRESS   Address
 197   );
 198
 199
 200 /**
 201   This function will get the raw value in variable MTRRs
 202
 203   @param  VariableSettings   A buffer to hold variable MTRRs content.
 204
 205   @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable mtrr
 206
 207 **/
 208 MTRR_VARIABLE_SETTINGS*
 209 EFIAPI
 210 MtrrGetVariableMtrr (
 211   OUT MTRR_VARIABLE_SETTINGS         *VariableSettings
 212   );
 213
 214
 215 /**
 216   This function sets fixed MTRRs
 217
 218   @param  VariableSettings   A buffer to hold variable MTRRs content.
 219
 220   @return The pointer of VariableSettings
 221
 222 **/
 223 MTRR_VARIABLE_SETTINGS*
 224 EFIAPI
 225 MtrrSetVariableMtrr (
 226   IN MTRR_VARIABLE_SETTINGS         *VariableSettings
 227   );
 228
 229
 230 /**
 231   This function gets the content in fixed MTRRs
 232
 233   @param  FixedSettings      A buffer to hold fixed MTRRs content.
 234
 235   @return The pointer of FixedSettings
 236
 237 **/
 238 MTRR_FIXED_SETTINGS*
 239 EFIAPI
 240 MtrrGetFixedMtrr (
 241   OUT MTRR_FIXED_SETTINGS         *FixedSettings
 242   );
 243
 244
 245 /**
 246   This function sets fixed MTRRs
 247
 248   @param   FixedSettings      A buffer holding fixed MTRRs content.
 249
 250   @return  The pointer of FixedSettings
 251
 252 **/
 253 MTRR_FIXED_SETTINGS*
 254 EFIAPI
 255 MtrrSetFixedMtrr (
 256   IN MTRR_FIXED_SETTINGS          *FixedSettings
 257   );
 258
 259
 260 /**
 261   This function gets the content in all MTRRs (variable and fixed)
 262
 263   @param  MtrrSetting   A buffer to hold all MTRRs content.
 264
 265   @return The pointer of MtrrSetting
 266
 267 **/
 268 MTRR_SETTINGS *
 269 EFIAPI
 270 MtrrGetAllMtrrs (
 271   OUT MTRR_SETTINGS                *MtrrSetting
 272   );
 273
 274
 275 /**
 276   This function sets all MTRRs (variable and fixed)
 277
 278   @param  MtrrSetting   A buffer to hold all MTRRs content.
 279
 280   @return The pointer of MtrrSetting
 281
 282 **/
 283 MTRR_SETTINGS *
 284 EFIAPI
 285 MtrrSetAllMtrrs (
 286   IN MTRR_SETTINGS                *MtrrSetting
 287   );
 288
 289
 290 /**
 291   Get the attribute of variable MTRRs.
 292
 293   This function shadows the content of variable MTRRs into
 294   an internal array: VariableMtrr
 295
 296   @param  MtrrValidBitsMask     The mask for the valid bit of the MTRR
 297   @param  MtrrValidAddressMask  The valid address mask for MTRR since the base address in
 298                                 MTRR must align to 4K, so valid address mask equal to
 299                                 MtrrValidBitsMask & 0xfffffffffffff000ULL
 300   @param  VariableMtrr          The array to shadow variable MTRRs content
 301   @return                       The ruturn value of this paramter indicates the number of
 302                                 MTRRs which has been used.
 303 **/
 304 UINT32
 305 EFIAPI
 306 MtrrGetMemoryAttributeInVariableMtrr (
 307   IN  UINT64                    MtrrValidBitsMask,
 308   IN  UINT64                    MtrrValidAddressMask,
 309   OUT VARIABLE_MTRR             *VariableMtrr
 310   );
 311
 312
 313 /**
 314   This function prints all MTRRs for debugging.
 315 **/
 316 VOID
 317 EFIAPI
 318 MtrrDebugPrintAllMtrrs (
 319   VOID
 320   );
 321
 322 /**
 323   Checks if MTRR is supported.
 324
 325   @retval TRUE  MTRR is supported.
 326   @retval FALSE MTRR is not supported.
 327
 328 **/
 329 BOOLEAN
 330 EFIAPI
 331 IsMtrrSupported (
 332   VOID
 333   );
 334
 335 /**
 336   Returns the default MTRR cache type for the system.
 337
 338   @return  The default MTRR cache type.
 339
 340 **/
 341 MTRR_MEMORY_CACHE_TYPE
 342 EFIAPI
 343 MtrrGetDefaultMemoryType (
 344   VOID
 345   );
 346
 347 #endif // _MTRR_LIB_H_