UefiCpuPkg/Include/Library/MtrrLib.h

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