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