UefiCpuPkg/Include/Library/MtrrLib.h

   1 /** @file
   2   MTRR setting library
   3
   4   Copyright (c) 2008 - 2018, 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 typedef struct {
 107   UINT64                 BaseAddress;
 108   UINT64                 Length;
 109   MTRR_MEMORY_CACHE_TYPE Type;
 110 } MTRR_MEMORY_RANGE;
 111
 112 /**
 113   Returns the variable MTRR count for the CPU.
 114
 115   @return Variable MTRR count
 116
 117 **/
 118 UINT32
 119 EFIAPI
 120 GetVariableMtrrCount (
 121   VOID
 122   );
 123
 124 /**
 125   Returns the firmware usable variable MTRR count for the CPU.
 126
 127   @return Firmware usable variable MTRR count
 128
 129 **/
 130 UINT32
 131 EFIAPI
 132 GetFirmwareVariableMtrrCount (
 133   VOID
 134   );
 135
 136 /**
 137   This function attempts to set the attributes for a memory range.
 138
 139   @param[in]       BaseAddress       The physical address that is the start
 140                                      address of a memory region.
 141   @param[in]       Length            The size in bytes of the memory region.
 142   @param[in]       Attribute         The bit mask of attributes to set for the
 143                                      memory region.
 144
 145   @retval RETURN_SUCCESS            The attributes were set for the memory
 146                                     region.
 147   @retval RETURN_INVALID_PARAMETER  Length is zero.
 148   @retval RETURN_UNSUPPORTED        The processor does not support one or
 149                                     more bytes of the memory resource range
 150                                     specified by BaseAddress and Length.
 151   @retval RETURN_UNSUPPORTED        The bit mask of attributes is not support
 152                                     for the memory resource range specified
 153                                     by BaseAddress and Length.
 154   @retval RETURN_ACCESS_DENIED      The attributes for the memory resource
 155                                     range specified by BaseAddress and Length
 156                                     cannot be modified.
 157   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to
 158                                     modify the attributes of the memory
 159                                     resource range.
 160                                     Multiple memory range attributes setting by calling this API multiple
 161                                     times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean
 162                                     the number of CPU MTRRs are too small to set such memory attributes.
 163                                     Pass the multiple memory range attributes to one call of
 164                                     MtrrSetMemoryAttributesInMtrrSettings() may succeed.
 165   @retval RETURN_BUFFER_TOO_SMALL   The fixed internal scratch buffer is too small for MTRR calculation.
 166                                     Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify
 167                                     external scratch buffer.
 168 **/
 169 RETURN_STATUS
 170 EFIAPI
 171 MtrrSetMemoryAttribute (
 172   IN PHYSICAL_ADDRESS        BaseAddress,
 173   IN UINT64                  Length,
 174   IN MTRR_MEMORY_CACHE_TYPE  Attribute
 175   );
 176
 177
 178 /**
 179   This function will get the memory cache type of the specific address.
 180   This function is mainly for debugging purposes.
 181
 182   @param[in]  Address            The specific address
 183
 184   @return The memory cache type of the specific address
 185
 186 **/
 187 MTRR_MEMORY_CACHE_TYPE
 188 EFIAPI
 189 MtrrGetMemoryAttribute (
 190   IN PHYSICAL_ADDRESS   Address
 191   );
 192
 193
 194 /**
 195   This function will get the raw value in variable MTRRs
 196
 197   @param[out]  VariableSettings   A buffer to hold variable MTRRs content.
 198
 199   @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable MTRR
 200
 201 **/
 202 MTRR_VARIABLE_SETTINGS*
 203 EFIAPI
 204 MtrrGetVariableMtrr (
 205   OUT MTRR_VARIABLE_SETTINGS         *VariableSettings
 206   );
 207
 208
 209 /**
 210   This function sets variable MTRRs
 211
 212   @param[in]  VariableSettings   A buffer to hold variable MTRRs content.
 213
 214   @return The pointer of VariableSettings
 215
 216 **/
 217 MTRR_VARIABLE_SETTINGS*
 218 EFIAPI
 219 MtrrSetVariableMtrr (
 220   IN MTRR_VARIABLE_SETTINGS         *VariableSettings
 221   );
 222
 223
 224 /**
 225   This function gets the content in fixed MTRRs
 226
 227   @param[out]  FixedSettings      A buffer to hold fixed MTRRs content.
 228
 229   @return The pointer of FixedSettings
 230
 231 **/
 232 MTRR_FIXED_SETTINGS*
 233 EFIAPI
 234 MtrrGetFixedMtrr (
 235   OUT MTRR_FIXED_SETTINGS         *FixedSettings
 236   );
 237
 238
 239 /**
 240   This function sets fixed MTRRs
 241
 242   @param[in]   FixedSettings      A buffer holding fixed MTRRs content.
 243
 244   @return  The pointer of FixedSettings
 245
 246 **/
 247 MTRR_FIXED_SETTINGS*
 248 EFIAPI
 249 MtrrSetFixedMtrr (
 250   IN MTRR_FIXED_SETTINGS          *FixedSettings
 251   );
 252
 253
 254 /**
 255   This function gets the content in all MTRRs (variable and fixed)
 256
 257   @param[out]  MtrrSetting   A buffer to hold all MTRRs content.
 258
 259   @return The pointer of MtrrSetting
 260
 261 **/
 262 MTRR_SETTINGS *
 263 EFIAPI
 264 MtrrGetAllMtrrs (
 265   OUT MTRR_SETTINGS                *MtrrSetting
 266   );
 267
 268
 269 /**
 270   This function sets all MTRRs (variable and fixed)
 271
 272   @param[in]  MtrrSetting   A buffer to hold all MTRRs content.
 273
 274   @return The pointer of MtrrSetting
 275
 276 **/
 277 MTRR_SETTINGS *
 278 EFIAPI
 279 MtrrSetAllMtrrs (
 280   IN MTRR_SETTINGS                *MtrrSetting
 281   );
 282
 283
 284 /**
 285   Get the attribute of variable MTRRs.
 286
 287   This function shadows the content of variable MTRRs into
 288   an internal array: VariableMtrr
 289
 290   @param[in]   MtrrValidBitsMask    The mask for the valid bit of the MTRR
 291   @param[in]   MtrrValidAddressMask The valid address mask for MTRR since the base address in
 292                                     MTRR must align to 4K, so valid address mask equal to
 293                                     MtrrValidBitsMask & 0xfffffffffffff000ULL
 294   @param[out]  VariableMtrr         The array to shadow variable MTRRs content
 295
 296   @return                       The return value of this parameter indicates the number of
 297                                 MTRRs which has been used.
 298 **/
 299 UINT32
 300 EFIAPI
 301 MtrrGetMemoryAttributeInVariableMtrr (
 302   IN  UINT64                    MtrrValidBitsMask,
 303   IN  UINT64                    MtrrValidAddressMask,
 304   OUT VARIABLE_MTRR             *VariableMtrr
 305   );
 306
 307
 308 /**
 309   This function prints all MTRRs for debugging.
 310 **/
 311 VOID
 312 EFIAPI
 313 MtrrDebugPrintAllMtrrs (
 314   VOID
 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 EFIAPI
 326 IsMtrrSupported (
 327   VOID
 328   );
 329
 330 /**
 331   Returns the default MTRR cache type for the system.
 332
 333   @return  The default MTRR cache type.
 334
 335 **/
 336 MTRR_MEMORY_CACHE_TYPE
 337 EFIAPI
 338 MtrrGetDefaultMemoryType (
 339   VOID
 340   );
 341
 342 /**
 343   This function attempts to set the attributes into MTRR setting buffer for a memory range.
 344
 345   @param[in, out]  MtrrSetting  MTRR setting buffer to be set.
 346   @param[in]       BaseAddress  The physical address that is the start address
 347                                 of a memory region.
 348   @param[in]       Length       The size in bytes of the memory region.
 349   @param[in]       Attribute    The bit mask of attributes to set for the
 350                                 memory region.
 351
 352   @retval RETURN_SUCCESS            The attributes were set for the memory region.
 353   @retval RETURN_INVALID_PARAMETER  Length is zero.
 354   @retval RETURN_UNSUPPORTED        The processor does not support one or more bytes of the
 355                                     memory resource range specified by BaseAddress and Length.
 356   @retval RETURN_UNSUPPORTED        The bit mask of attributes is not support for the memory resource
 357                                     range specified by BaseAddress and Length.
 358   @retval RETURN_ACCESS_DENIED      The attributes for the memory resource range specified by
 359                                     BaseAddress and Length cannot be modified.
 360   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to modify the attributes of
 361                                     the memory resource range.
 362                                     Multiple memory range attributes setting by calling this API multiple
 363                                     times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean
 364                                     the number of CPU MTRRs are too small to set such memory attributes.
 365                                     Pass the multiple memory range attributes to one call of
 366                                     MtrrSetMemoryAttributesInMtrrSettings() may succeed.
 367   @retval RETURN_BUFFER_TOO_SMALL   The fixed internal scratch buffer is too small for MTRR calculation.
 368                                     Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify
 369                                     external scratch buffer.
 370 **/
 371 RETURN_STATUS
 372 EFIAPI
 373 MtrrSetMemoryAttributeInMtrrSettings (
 374   IN OUT MTRR_SETTINGS       *MtrrSetting,
 375   IN PHYSICAL_ADDRESS        BaseAddress,
 376   IN UINT64                  Length,
 377   IN MTRR_MEMORY_CACHE_TYPE  Attribute
 378   );
 379
 380 /**
 381   This function attempts to set the attributes into MTRR setting buffer for multiple memory ranges.
 382
 383   @param[in, out]  MtrrSetting  MTRR setting buffer to be set.
 384   @param[in]       Scratch      A temporary scratch buffer that is used to perform the calculation.
 385   @param[in, out]  ScratchSize  Pointer to the size in bytes of the scratch buffer.
 386                                 It may be updated to the actual required size when the calculation
 387                                 needs more scratch buffer.
 388   @param[in]       Ranges       Pointer to an array of MTRR_MEMORY_RANGE.
 389                                 When range overlap happens, the last one takes higher priority.
 390                                 When the function returns, either all the attributes are set successfully,
 391                                 or none of them is set.
 392   @param[in]      RangeCount    Count of MTRR_MEMORY_RANGE.
 393
 394   @retval RETURN_SUCCESS            The attributes were set for all the memory ranges.
 395   @retval RETURN_INVALID_PARAMETER  Length in any range is zero.
 396   @retval RETURN_UNSUPPORTED        The processor does not support one or more bytes of the
 397                                     memory resource range specified by BaseAddress and Length in any range.
 398   @retval RETURN_UNSUPPORTED        The bit mask of attributes is not support for the memory resource
 399                                     range specified by BaseAddress and Length in any range.
 400   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to modify the attributes of
 401                                     the memory resource ranges.
 402   @retval RETURN_ACCESS_DENIED      The attributes for the memory resource range specified by
 403                                     BaseAddress and Length cannot be modified.
 404   @retval RETURN_BUFFER_TOO_SMALL   The scratch buffer is too small for MTRR calculation.
 405 **/
 406 RETURN_STATUS
 407 EFIAPI
 408 MtrrSetMemoryAttributesInMtrrSettings (
 409   IN OUT MTRR_SETTINGS           *MtrrSetting,
 410   IN     VOID                    *Scratch,
 411   IN OUT UINTN                   *ScratchSize,
 412   IN     CONST MTRR_MEMORY_RANGE *Ranges,
 413   IN     UINTN                   RangeCount
 414   );
 415 #endif // _MTRR_LIB_H_