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