UefiCpuPkg/Include/Library/MtrrLib.h

   1 /** @file
   2   MTRR setting library
   3
   4   Copyright (c) 2008 - 2009, 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 #define  MTRR_NUMBER_OF_VARIABLE_MTRR   8
  23 #define  MTRR_NUMBER_OF_FIXED_MTRR      11
  24 #define  FIRMWARE_VARIABLE_MTRR_NUMBER  6
  25 #define  MTRR_LIB_IA32_MTRR_FIX64K_00000             0x250
  26 #define  MTRR_LIB_IA32_MTRR_FIX16K_80000             0x258
  27 #define  MTRR_LIB_IA32_MTRR_FIX16K_A0000             0x259
  28 #define  MTRR_LIB_IA32_MTRR_FIX4K_C0000              0x268
  29 #define  MTRR_LIB_IA32_MTRR_FIX4K_C8000              0x269
  30 #define  MTRR_LIB_IA32_MTRR_FIX4K_D0000              0x26A
  31 #define  MTRR_LIB_IA32_MTRR_FIX4K_D8000              0x26B
  32 #define  MTRR_LIB_IA32_MTRR_FIX4K_E0000              0x26C
  33 #define  MTRR_LIB_IA32_MTRR_FIX4K_E8000              0x26D
  34 #define  MTRR_LIB_IA32_MTRR_FIX4K_F0000              0x26E
  35 #define  MTRR_LIB_IA32_MTRR_FIX4K_F8000              0x26F
  36 #define  MTRR_LIB_IA32_VARIABLE_MTRR_BASE            0x200
  37 #define  MTRR_LIB_IA32_VARIABLE_MTRR_END             0x20F
  38 #define  MTRR_LIB_IA32_MTRR_DEF_TYPE                 0x2FF
  39 #define  MTRR_LIB_MSR_VALID_MASK                     0xFFFFFFFFFULL
  40 #define  MTRR_LIB_CACHE_VALID_ADDRESS                0xFFFFFF000ULL
  41 #define  MTRR_LIB_CACHE_MTRR_ENABLED                 0x800
  42 #define  MTRR_LIB_CACHE_FIXED_MTRR_ENABLED           0x400
  43
  44 //
  45 // Structure to describe a fixed MTRR
  46 //
  47 typedef struct {
  48   UINT32  Msr;
  49   UINT32  BaseAddress;
  50   UINT32  Length;
  51 } FIXED_MTRR;
  52
  53 //
  54 // Structure to describe a variable MTRR
  55 //
  56 typedef struct {
  57   UINT64  BaseAddress;
  58   UINT64  Length;
  59   UINT64  Type;
  60   UINT32  Msr;
  61   BOOLEAN Valid;
  62   BOOLEAN Used;
  63 } VARIABLE_MTRR;
  64
  65 //
  66 // Structure to hold base and mask pair for variable MTRR register
  67 //
  68 typedef struct _MTRR_VARIABLE_SETTING_ {
  69         UINT64    Base;
  70         UINT64    Mask;
  71 } MTRR_VARIABLE_SETTING;
  72
  73 //
  74 // Array for variable MTRRs
  75 //
  76 typedef struct _MTRR_VARIABLE_SETTINGS_ {
  77         MTRR_VARIABLE_SETTING   Mtrr[MTRR_NUMBER_OF_VARIABLE_MTRR];
  78 }       MTRR_VARIABLE_SETTINGS;
  79
  80 //
  81 // Array for fixed mtrrs
  82 //
  83 typedef  struct  _MTRR_FIXED_SETTINGS_ {
  84   UINT64       Mtrr[MTRR_NUMBER_OF_FIXED_MTRR];
  85 } MTRR_FIXED_SETTINGS;
  86
  87 //
  88 // Structure to hold all MTRRs
  89 //
  90 typedef struct _MTRR_SETTINGS_ {
  91   MTRR_FIXED_SETTINGS       Fixed;
  92   MTRR_VARIABLE_SETTINGS    Variables;
  93   UINT64                    MtrrDefType;
  94 } MTRR_SETTINGS;
  95
  96 //
  97 // Memory cache types
  98 //
  99 typedef enum {
 100         CacheUncacheable    = 0,
 101         CacheWriteCombining = 1,
 102         CacheWriteThrough   = 4,
 103         CacheWriteProtected = 5,
 104         CacheWriteBack      = 6
 105 } MTRR_MEMORY_CACHE_TYPE;
 106
 107 #define  MTRR_CACHE_UNCACHEABLE      0
 108 #define  MTRR_CACHE_WRITE_COMBINING  1
 109 #define  MTRR_CACHE_WRITE_THROUGH    4
 110 #define  MTRR_CACHE_WRITE_PROTECTED  5
 111 #define  MTRR_CACHE_WRITE_BACK       6
 112 #define  MTRR_CACHE_INVALID_TYPE     7
 113
 114 //
 115 // structure for memory attribute descriptor according MTRR setting
 116 //
 117 typedef struct _MTRR_MEMORY_ATTRIBUTE_MAP_ {
 118         PHYSICAL_ADDRESS       StartAddress;
 119         PHYSICAL_ADDRESS       EndAddress;
 120         MTRR_MEMORY_CACHE_TYPE Attribute;
 121 } MTRR_MEMORY_ATTRIBUTE_MAP;
 122
 123
 124 /**
 125   This function attempts to set the attributes for a memory range.
 126
 127   @param  BaseAddress            The physical address that is the start address of a memory region.
 128   @param  Length                 The size in bytes of the memory region.
 129   @param  Attributes             The bit mask of attributes to set for the memory region.
 130
 131   @retval RETURN_SUCCESS            The attributes were set for the memory region.
 132   @retval RETURN_INVALID_PARAMETER  Length is zero.
 133   @retval RETURN_UNSUPPORTED        The processor does not support one or more bytes of the
 134                                  memory resource range specified by BaseAddress and Length.
 135   @retval RETURN_UNSUPPORTED        The bit mask of attributes is not support for the memory resource
 136                                  range specified by BaseAddress and Length.
 137   @retval RETURN_ACCESS_DENIED      The attributes for the memory resource range specified by
 138                                  BaseAddress and Length cannot be modified.
 139   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to modify the attributes of
 140                                  the memory resource range.
 141
 142 **/
 143 RETURN_STATUS
 144 EFIAPI
 145 MtrrSetMemoryAttribute (
 146   IN PHYSICAL_ADDRESS        BaseAddress,
 147   IN UINT64                  Length,
 148   IN MTRR_MEMORY_CACHE_TYPE  Attribute
 149   );
 150
 151
 152 /**
 153   This function will get the memory cache type of the specific address.
 154   This function is mainly for debugging purposes.
 155
 156   @param  Address            The specific address
 157
 158   @return The memory cache type of the specific address
 159
 160 **/
 161 MTRR_MEMORY_CACHE_TYPE
 162 EFIAPI
 163 MtrrGetMemoryAttribute (
 164   IN PHYSICAL_ADDRESS   Address
 165   );
 166
 167
 168 /**
 169   This function will get the raw value in variable MTRRs
 170
 171   @param  VariableSettings   A buffer to hold variable MTRRs content.
 172
 173   @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable mtrr
 174
 175 **/
 176 MTRR_VARIABLE_SETTINGS*
 177 EFIAPI
 178 MtrrGetVariableMtrr (
 179   OUT MTRR_VARIABLE_SETTINGS         *VariableSettings
 180   );
 181
 182
 183 /**
 184   This function sets fixed MTRRs
 185
 186   @param  VariableSettings   A buffer to hold variable MTRRs content.
 187
 188   @return The pointer of VariableSettings
 189
 190 **/
 191 MTRR_VARIABLE_SETTINGS*
 192 EFIAPI
 193 MtrrSetVariableMtrr (
 194   IN MTRR_VARIABLE_SETTINGS         *VariableSettings
 195   );
 196
 197
 198 /**
 199   This function gets the content in fixed MTRRs
 200
 201   @param  FixedSettings      A buffer to hold fixed MTRRs content.
 202
 203   @return The pointer of FixedSettings
 204
 205 **/
 206 MTRR_FIXED_SETTINGS*
 207 EFIAPI
 208 MtrrGetFixedMtrr (
 209   OUT MTRR_FIXED_SETTINGS         *FixedSettings
 210   );
 211
 212
 213 /**
 214   This function sets fixed MTRRs
 215
 216   @param   FixedSettings      A buffer holding fixed MTRRs content.
 217
 218   @return  The pointer of FixedSettings
 219
 220 **/
 221 MTRR_FIXED_SETTINGS*
 222 EFIAPI
 223 MtrrSetFixedMtrr (
 224   IN MTRR_FIXED_SETTINGS          *FixedSettings
 225   );
 226
 227
 228 /**
 229   This function gets the content in all MTRRs (variable and fixed)
 230
 231   @param  MtrrSetting   A buffer to hold all MTRRs content.
 232
 233   @return The pointer of MtrrSetting
 234
 235 **/
 236 MTRR_SETTINGS *
 237 EFIAPI
 238 MtrrGetAllMtrrs (
 239   OUT MTRR_SETTINGS                *MtrrSetting
 240   );
 241
 242
 243 /**
 244   This function sets all MTRRs (variable and fixed)
 245
 246   @param  MtrrSetting   A buffer to hold all MTRRs content.
 247
 248   @return The pointer of MtrrSetting
 249
 250 **/
 251 MTRR_SETTINGS *
 252 EFIAPI
 253 MtrrSetAllMtrrs (
 254   IN MTRR_SETTINGS                *MtrrSetting
 255   );
 256
 257
 258 /**
 259   Get the attribute of variable MTRRs.
 260
 261   This function shadows the content of variable MTRRs into
 262   an internal array: VariableMtrr
 263
 264   @param  MtrrValidBitsMask     The mask for the valid bit of the MTRR
 265   @param  MtrrValidAddressMask  The valid address mask for MTRR since the base address in
 266                                 MTRR must align to 4K, so valid address mask equal to
 267                                 MtrrValidBitsMask & 0xfffffffffffff000ULL
 268   @param  VariableMtrr          The array to shadow variable MTRRs content
 269   @return                       The ruturn value of this paramter indicates the number of
 270                                 MTRRs which has been used.
 271 **/
 272 UINT32
 273 EFIAPI
 274 MtrrGetMemoryAttributeInVariableMtrr (
 275   IN  UINT64                    MtrrValidBitsMask,
 276   IN  UINT64                    MtrrValidAddressMask,
 277   OUT VARIABLE_MTRR             *VariableMtrr
 278   );
 279
 280
 281 /**
 282   This function prints all MTRRs for debugging.
 283 **/
 284 VOID
 285 MtrrDebugPrintAllMtrrs (
 286   );
 287
 288 #endif // _MTRR_LIB_H_