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 #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   This function attempts to set the attributes for a memory range.
 116
 117   @param  BaseAddress            The physical address that is the start address of a memory region.
 118   @param  Length                 The size in bytes of the memory region.
 119   @param  Attributes             The bit mask of attributes to set for the memory region.
 120
 121   @retval RETURN_SUCCESS            The attributes were set for the memory region.
 122   @retval RETURN_INVALID_PARAMETER  Length is zero.
 123   @retval RETURN_UNSUPPORTED        The processor does not support one or more bytes of the
 124                                  memory resource range specified by BaseAddress and Length.
 125   @retval RETURN_UNSUPPORTED        The bit mask of attributes is not support for the memory resource
 126                                  range specified by BaseAddress and Length.
 127   @retval RETURN_ACCESS_DENIED      The attributes for the memory resource range specified by
 128                                  BaseAddress and Length cannot be modified.
 129   @retval RETURN_OUT_OF_RESOURCES   There are not enough system resources to modify the attributes of
 130                                  the memory resource range.
 131
 132 **/
 133 RETURN_STATUS
 134 EFIAPI
 135 MtrrSetMemoryAttribute (
 136   IN PHYSICAL_ADDRESS        BaseAddress,
 137   IN UINT64                  Length,
 138   IN MTRR_MEMORY_CACHE_TYPE  Attribute
 139   );
 140
 141
 142 /**
 143   This function will get the memory cache type of the specific address.
 144   This function is mainly for debugging purposes.
 145
 146   @param  Address            The specific address
 147
 148   @return The memory cache type of the specific address
 149
 150 **/
 151 MTRR_MEMORY_CACHE_TYPE
 152 EFIAPI
 153 MtrrGetMemoryAttribute (
 154   IN PHYSICAL_ADDRESS   Address
 155   );
 156
 157
 158 /**
 159   This function will get the raw value in variable MTRRs
 160
 161   @param  VariableSettings   A buffer to hold variable MTRRs content.
 162
 163   @return The buffer point to MTRR_VARIABLE_SETTINGS in which holds the content of the variable mtrr
 164
 165 **/
 166 MTRR_VARIABLE_SETTINGS*
 167 EFIAPI
 168 MtrrGetVariableMtrr (
 169   OUT MTRR_VARIABLE_SETTINGS         *VariableSettings
 170   );
 171
 172
 173 /**
 174   This function sets fixed MTRRs
 175
 176   @param  VariableSettings   A buffer to hold variable MTRRs content.
 177
 178   @return The pointer of VariableSettings
 179
 180 **/
 181 MTRR_VARIABLE_SETTINGS*
 182 EFIAPI
 183 MtrrSetVariableMtrr (
 184   IN MTRR_VARIABLE_SETTINGS         *VariableSettings
 185   );
 186
 187
 188 /**
 189   This function gets the content in fixed MTRRs
 190
 191   @param  FixedSettings      A buffer to hold fixed MTRRs content.
 192
 193   @return The pointer of FixedSettings
 194
 195 **/
 196 MTRR_FIXED_SETTINGS*
 197 EFIAPI
 198 MtrrGetFixedMtrr (
 199   OUT MTRR_FIXED_SETTINGS         *FixedSettings
 200   );
 201
 202
 203 /**
 204   This function sets fixed MTRRs
 205
 206   @param   FixedSettings      A buffer holding fixed MTRRs content.
 207
 208   @return  The pointer of FixedSettings
 209
 210 **/
 211 MTRR_FIXED_SETTINGS*
 212 EFIAPI
 213 MtrrSetFixedMtrr (
 214   IN MTRR_FIXED_SETTINGS          *FixedSettings
 215   );
 216
 217
 218 /**
 219   This function gets the content in all MTRRs (variable and fixed)
 220
 221   @param  MtrrSetting   A buffer to hold all MTRRs content.
 222
 223   @return The pointer of MtrrSetting
 224
 225 **/
 226 MTRR_SETTINGS *
 227 EFIAPI
 228 MtrrGetAllMtrrs (
 229   OUT MTRR_SETTINGS                *MtrrSetting
 230   );
 231
 232
 233 /**
 234   This function sets all MTRRs (variable and fixed)
 235
 236   @param  MtrrSetting   A buffer to hold all MTRRs content.
 237
 238   @return The pointer of MtrrSetting
 239
 240 **/
 241 MTRR_SETTINGS *
 242 EFIAPI
 243 MtrrSetAllMtrrs (
 244   IN MTRR_SETTINGS                *MtrrSetting
 245   );
 246
 247
 248 /**
 249   Get the attribute of variable MTRRs.
 250
 251   This function shadows the content of variable MTRRs into
 252   an internal array: VariableMtrr
 253
 254   @param  MtrrValidBitsMask     The mask for the valid bit of the MTRR
 255   @param  MtrrValidAddressMask  The valid address mask for MTRR since the base address in
 256                                 MTRR must align to 4K, so valid address mask equal to
 257                                 MtrrValidBitsMask & 0xfffffffffffff000ULL
 258   @param  VariableMtrr          The array to shadow variable MTRRs content
 259   @return                       The ruturn value of this paramter indicates the number of
 260                                 MTRRs which has been used.
 261 **/
 262 UINT32
 263 EFIAPI
 264 MtrrGetMemoryAttributeInVariableMtrr (
 265   IN  UINT64                    MtrrValidBitsMask,
 266   IN  UINT64                    MtrrValidAddressMask,
 267   OUT VARIABLE_MTRR             *VariableMtrr
 268   );
 269
 270
 271 /**
 272   This function prints all MTRRs for debugging.
 273 **/
 274 VOID
 275 MtrrDebugPrintAllMtrrs (
 276   );
 277
 278 #endif // _MTRR_LIB_H_