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