MtrrLib.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359
  1. /** @file
  2. MTRR setting library
  3. Copyright (c) 2008 - 2020, Intel Corporation. All rights reserved.<BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. **/
  6. #ifndef _MTRR_LIB_H_
  7. #define _MTRR_LIB_H_
  8. //
  9. // According to IA32 SDM, MTRRs number and MSR offset are always consistent
  10. // for IA32 processor family
  11. //
  12. //
  13. // The semantics of below macro is MAX_MTRR_NUMBER_OF_VARIABLE_MTRR, the real number can be read out from MTRR_CAP register.
  14. //
  15. #define MTRR_NUMBER_OF_VARIABLE_MTRR 32
  16. //
  17. // Firmware need reserve 2 MTRR for OS
  18. // Note: It is replaced by PCD PcdCpuNumberOfReservedVariableMtrrs
  19. //
  20. #define RESERVED_FIRMWARE_VARIABLE_MTRR_NUMBER 2
  21. #define MTRR_NUMBER_OF_FIXED_MTRR 11
  22. //
  23. // Structure to describe a fixed MTRR
  24. //
  25. typedef struct {
  26. UINT32 Msr;
  27. UINT32 BaseAddress;
  28. UINT32 Length;
  29. } FIXED_MTRR;
  30. //
  31. // Structure to describe a variable MTRR
  32. //
  33. typedef struct {
  34. UINT64 BaseAddress;
  35. UINT64 Length;
  36. UINT64 Type;
  37. UINT32 Msr;
  38. BOOLEAN Valid;
  39. BOOLEAN Used;
  40. } VARIABLE_MTRR;
  41. //
  42. // Structure to hold base and mask pair for variable MTRR register
  43. //
  44. typedef struct _MTRR_VARIABLE_SETTING_ {
  45. UINT64 Base;
  46. UINT64 Mask;
  47. } MTRR_VARIABLE_SETTING;
  48. //
  49. // Array for variable MTRRs
  50. //
  51. typedef struct _MTRR_VARIABLE_SETTINGS_ {
  52. MTRR_VARIABLE_SETTING Mtrr[MTRR_NUMBER_OF_VARIABLE_MTRR];
  53. } MTRR_VARIABLE_SETTINGS;
  54. //
  55. // Array for fixed MTRRs
  56. //
  57. typedef struct _MTRR_FIXED_SETTINGS_ {
  58. UINT64 Mtrr[MTRR_NUMBER_OF_FIXED_MTRR];
  59. } MTRR_FIXED_SETTINGS;
  60. //
  61. // Structure to hold all MTRRs
  62. //
  63. typedef struct _MTRR_SETTINGS_ {
  64. MTRR_FIXED_SETTINGS Fixed;
  65. MTRR_VARIABLE_SETTINGS Variables;
  66. UINT64 MtrrDefType;
  67. } MTRR_SETTINGS;
  68. //
  69. // Memory cache types
  70. //
  71. typedef enum {
  72. CacheUncacheable = 0,
  73. CacheWriteCombining = 1,
  74. CacheWriteThrough = 4,
  75. CacheWriteProtected = 5,
  76. CacheWriteBack = 6,
  77. CacheInvalid = 7
  78. } MTRR_MEMORY_CACHE_TYPE;
  79. #define MTRR_CACHE_UNCACHEABLE 0
  80. #define MTRR_CACHE_WRITE_COMBINING 1
  81. #define MTRR_CACHE_WRITE_THROUGH 4
  82. #define MTRR_CACHE_WRITE_PROTECTED 5
  83. #define MTRR_CACHE_WRITE_BACK 6
  84. #define MTRR_CACHE_INVALID_TYPE 7
  85. typedef struct {
  86. UINT64 BaseAddress;
  87. UINT64 Length;
  88. MTRR_MEMORY_CACHE_TYPE Type;
  89. } MTRR_MEMORY_RANGE;
  90. /**
  91. Returns the variable MTRR count for the CPU.
  92. @return Variable MTRR count
  93. **/
  94. UINT32
  95. EFIAPI
  96. GetVariableMtrrCount (
  97. VOID
  98. );
  99. /**
  100. Returns the firmware usable variable MTRR count for the CPU.
  101. @return Firmware usable variable MTRR count
  102. **/
  103. UINT32
  104. EFIAPI
  105. GetFirmwareVariableMtrrCount (
  106. VOID
  107. );
  108. /**
  109. This function attempts to set the attributes for a memory range.
  110. @param[in] BaseAddress The physical address that is the start
  111. address of a memory region.
  112. @param[in] Length The size in bytes of the memory region.
  113. @param[in] Attribute The bit mask of attributes to set for the
  114. memory region.
  115. @retval RETURN_SUCCESS The attributes were set for the memory
  116. region.
  117. @retval RETURN_INVALID_PARAMETER Length is zero.
  118. @retval RETURN_UNSUPPORTED The processor does not support one or
  119. more bytes of the memory resource range
  120. specified by BaseAddress and Length.
  121. @retval RETURN_UNSUPPORTED The bit mask of attributes is not support
  122. for the memory resource range specified
  123. by BaseAddress and Length.
  124. @retval RETURN_ACCESS_DENIED The attributes for the memory resource
  125. range specified by BaseAddress and Length
  126. cannot be modified.
  127. @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to
  128. modify the attributes of the memory
  129. resource range.
  130. Multiple memory range attributes setting by calling this API multiple
  131. times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean
  132. the number of CPU MTRRs are too small to set such memory attributes.
  133. Pass the multiple memory range attributes to one call of
  134. MtrrSetMemoryAttributesInMtrrSettings() may succeed.
  135. @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.
  136. Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify
  137. external scratch buffer.
  138. **/
  139. RETURN_STATUS
  140. EFIAPI
  141. MtrrSetMemoryAttribute (
  142. IN PHYSICAL_ADDRESS BaseAddress,
  143. IN UINT64 Length,
  144. IN MTRR_MEMORY_CACHE_TYPE Attribute
  145. );
  146. /**
  147. This function will get the memory cache type of the specific address.
  148. This function is mainly for debugging purposes.
  149. @param[in] Address The specific address
  150. @return The memory cache type of the specific address
  151. **/
  152. MTRR_MEMORY_CACHE_TYPE
  153. EFIAPI
  154. MtrrGetMemoryAttribute (
  155. IN PHYSICAL_ADDRESS Address
  156. );
  157. /**
  158. This function gets the content in fixed MTRRs
  159. @param[out] FixedSettings A buffer to hold fixed MTRRs content.
  160. @return The pointer of FixedSettings
  161. **/
  162. MTRR_FIXED_SETTINGS *
  163. EFIAPI
  164. MtrrGetFixedMtrr (
  165. OUT MTRR_FIXED_SETTINGS *FixedSettings
  166. );
  167. /**
  168. This function gets the content in all MTRRs (variable and fixed)
  169. @param[out] MtrrSetting A buffer to hold all MTRRs content.
  170. @return The pointer of MtrrSetting
  171. **/
  172. MTRR_SETTINGS *
  173. EFIAPI
  174. MtrrGetAllMtrrs (
  175. OUT MTRR_SETTINGS *MtrrSetting
  176. );
  177. /**
  178. This function sets all MTRRs (variable and fixed)
  179. @param[in] MtrrSetting A buffer to hold all MTRRs content.
  180. @return The pointer of MtrrSetting
  181. **/
  182. MTRR_SETTINGS *
  183. EFIAPI
  184. MtrrSetAllMtrrs (
  185. IN MTRR_SETTINGS *MtrrSetting
  186. );
  187. /**
  188. Get the attribute of variable MTRRs.
  189. This function shadows the content of variable MTRRs into
  190. an internal array: VariableMtrr
  191. @param[in] MtrrValidBitsMask The mask for the valid bit of the MTRR
  192. @param[in] MtrrValidAddressMask The valid address mask for MTRR since the base address in
  193. MTRR must align to 4K, so valid address mask equal to
  194. MtrrValidBitsMask & 0xfffffffffffff000ULL
  195. @param[out] VariableMtrr The array to shadow variable MTRRs content
  196. @return The return value of this parameter indicates the number of
  197. MTRRs which has been used.
  198. **/
  199. UINT32
  200. EFIAPI
  201. MtrrGetMemoryAttributeInVariableMtrr (
  202. IN UINT64 MtrrValidBitsMask,
  203. IN UINT64 MtrrValidAddressMask,
  204. OUT VARIABLE_MTRR *VariableMtrr
  205. );
  206. /**
  207. This function prints all MTRRs for debugging.
  208. **/
  209. VOID
  210. EFIAPI
  211. MtrrDebugPrintAllMtrrs (
  212. VOID
  213. );
  214. /**
  215. Checks if MTRR is supported.
  216. @retval TRUE MTRR is supported.
  217. @retval FALSE MTRR is not supported.
  218. **/
  219. BOOLEAN
  220. EFIAPI
  221. IsMtrrSupported (
  222. VOID
  223. );
  224. /**
  225. Returns the default MTRR cache type for the system.
  226. @return The default MTRR cache type.
  227. **/
  228. MTRR_MEMORY_CACHE_TYPE
  229. EFIAPI
  230. MtrrGetDefaultMemoryType (
  231. VOID
  232. );
  233. /**
  234. This function attempts to set the attributes into MTRR setting buffer for a memory range.
  235. @param[in, out] MtrrSetting MTRR setting buffer to be set.
  236. @param[in] BaseAddress The physical address that is the start address
  237. of a memory region.
  238. @param[in] Length The size in bytes of the memory region.
  239. @param[in] Attribute The bit mask of attributes to set for the
  240. memory region.
  241. @retval RETURN_SUCCESS The attributes were set for the memory region.
  242. @retval RETURN_INVALID_PARAMETER Length is zero.
  243. @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the
  244. memory resource range specified by BaseAddress and Length.
  245. @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource
  246. range specified by BaseAddress and Length.
  247. @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by
  248. BaseAddress and Length cannot be modified.
  249. @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of
  250. the memory resource range.
  251. Multiple memory range attributes setting by calling this API multiple
  252. times may fail with status RETURN_OUT_OF_RESOURCES. It may not mean
  253. the number of CPU MTRRs are too small to set such memory attributes.
  254. Pass the multiple memory range attributes to one call of
  255. MtrrSetMemoryAttributesInMtrrSettings() may succeed.
  256. @retval RETURN_BUFFER_TOO_SMALL The fixed internal scratch buffer is too small for MTRR calculation.
  257. Caller should use MtrrSetMemoryAttributesInMtrrSettings() to specify
  258. external scratch buffer.
  259. **/
  260. RETURN_STATUS
  261. EFIAPI
  262. MtrrSetMemoryAttributeInMtrrSettings (
  263. IN OUT MTRR_SETTINGS *MtrrSetting,
  264. IN PHYSICAL_ADDRESS BaseAddress,
  265. IN UINT64 Length,
  266. IN MTRR_MEMORY_CACHE_TYPE Attribute
  267. );
  268. /**
  269. This function attempts to set the attributes into MTRR setting buffer for multiple memory ranges.
  270. @param[in, out] MtrrSetting MTRR setting buffer to be set.
  271. @param[in] Scratch A temporary scratch buffer that is used to perform the calculation.
  272. @param[in, out] ScratchSize Pointer to the size in bytes of the scratch buffer.
  273. It may be updated to the actual required size when the calculation
  274. needs more scratch buffer.
  275. @param[in] Ranges Pointer to an array of MTRR_MEMORY_RANGE.
  276. When range overlap happens, the last one takes higher priority.
  277. When the function returns, either all the attributes are set successfully,
  278. or none of them is set.
  279. @param[in] RangeCount Count of MTRR_MEMORY_RANGE.
  280. @retval RETURN_SUCCESS The attributes were set for all the memory ranges.
  281. @retval RETURN_INVALID_PARAMETER Length in any range is zero.
  282. @retval RETURN_UNSUPPORTED The processor does not support one or more bytes of the
  283. memory resource range specified by BaseAddress and Length in any range.
  284. @retval RETURN_UNSUPPORTED The bit mask of attributes is not support for the memory resource
  285. range specified by BaseAddress and Length in any range.
  286. @retval RETURN_OUT_OF_RESOURCES There are not enough system resources to modify the attributes of
  287. the memory resource ranges.
  288. @retval RETURN_ACCESS_DENIED The attributes for the memory resource range specified by
  289. BaseAddress and Length cannot be modified.
  290. @retval RETURN_BUFFER_TOO_SMALL The scratch buffer is too small for MTRR calculation.
  291. **/
  292. RETURN_STATUS
  293. EFIAPI
  294. MtrrSetMemoryAttributesInMtrrSettings (
  295. IN OUT MTRR_SETTINGS *MtrrSetting,
  296. IN VOID *Scratch,
  297. IN OUT UINTN *ScratchSize,
  298. IN CONST MTRR_MEMORY_RANGE *Ranges,
  299. IN UINTN RangeCount
  300. );
  301. #endif // _MTRR_LIB_H_