pat.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240
  1. .. SPDX-License-Identifier: GPL-2.0
  2. ==========================
  3. PAT (Page Attribute Table)
  4. ==========================
  5. x86 Page Attribute Table (PAT) allows for setting the memory attribute at the
  6. page level granularity. PAT is complementary to the MTRR settings which allows
  7. for setting of memory types over physical address ranges. However, PAT is
  8. more flexible than MTRR due to its capability to set attributes at page level
  9. and also due to the fact that there are no hardware limitations on number of
  10. such attribute settings allowed. Added flexibility comes with guidelines for
  11. not having memory type aliasing for the same physical memory with multiple
  12. virtual addresses.
  13. PAT allows for different types of memory attributes. The most commonly used
  14. ones that will be supported at this time are:
  15. === ==============
  16. WB Write-back
  17. UC Uncached
  18. WC Write-combined
  19. WT Write-through
  20. UC- Uncached Minus
  21. === ==============
  22. PAT APIs
  23. ========
  24. There are many different APIs in the kernel that allows setting of memory
  25. attributes at the page level. In order to avoid aliasing, these interfaces
  26. should be used thoughtfully. Below is a table of interfaces available,
  27. their intended usage and their memory attribute relationships. Internally,
  28. these APIs use a reserve_memtype()/free_memtype() interface on the physical
  29. address range to avoid any aliasing.
  30. +------------------------+----------+--------------+------------------+
  31. | API | RAM | ACPI,... | Reserved/Holes |
  32. +------------------------+----------+--------------+------------------+
  33. | ioremap | -- | UC- | UC- |
  34. +------------------------+----------+--------------+------------------+
  35. | ioremap_cache | -- | WB | WB |
  36. +------------------------+----------+--------------+------------------+
  37. | ioremap_uc | -- | UC | UC |
  38. +------------------------+----------+--------------+------------------+
  39. | ioremap_wc | -- | -- | WC |
  40. +------------------------+----------+--------------+------------------+
  41. | ioremap_wt | -- | -- | WT |
  42. +------------------------+----------+--------------+------------------+
  43. | set_memory_uc, | UC- | -- | -- |
  44. | set_memory_wb | | | |
  45. +------------------------+----------+--------------+------------------+
  46. | set_memory_wc, | WC | -- | -- |
  47. | set_memory_wb | | | |
  48. +------------------------+----------+--------------+------------------+
  49. | set_memory_wt, | WT | -- | -- |
  50. | set_memory_wb | | | |
  51. +------------------------+----------+--------------+------------------+
  52. | pci sysfs resource | -- | -- | UC- |
  53. +------------------------+----------+--------------+------------------+
  54. | pci sysfs resource_wc | -- | -- | WC |
  55. | is IORESOURCE_PREFETCH | | | |
  56. +------------------------+----------+--------------+------------------+
  57. | pci proc | -- | -- | UC- |
  58. | !PCIIOC_WRITE_COMBINE | | | |
  59. +------------------------+----------+--------------+------------------+
  60. | pci proc | -- | -- | WC |
  61. | PCIIOC_WRITE_COMBINE | | | |
  62. +------------------------+----------+--------------+------------------+
  63. | /dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
  64. | read-write | | | |
  65. +------------------------+----------+--------------+------------------+
  66. | /dev/mem | -- | UC- | UC- |
  67. | mmap SYNC flag | | | |
  68. +------------------------+----------+--------------+------------------+
  69. | /dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
  70. | mmap !SYNC flag | | | |
  71. | and | |(from existing| (from existing |
  72. | any alias to this area | |alias) | alias) |
  73. +------------------------+----------+--------------+------------------+
  74. | /dev/mem | -- | WB | WB |
  75. | mmap !SYNC flag | | | |
  76. | no alias to this area | | | |
  77. | and | | | |
  78. | MTRR says WB | | | |
  79. +------------------------+----------+--------------+------------------+
  80. | /dev/mem | -- | -- | UC- |
  81. | mmap !SYNC flag | | | |
  82. | no alias to this area | | | |
  83. | and | | | |
  84. | MTRR says !WB | | | |
  85. +------------------------+----------+--------------+------------------+
  86. Advanced APIs for drivers
  87. =========================
  88. A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range,
  89. vmf_insert_pfn.
  90. Drivers wanting to export some pages to userspace do it by using mmap
  91. interface and a combination of:
  92. 1) pgprot_noncached()
  93. 2) io_remap_pfn_range() or remap_pfn_range() or vmf_insert_pfn()
  94. With PAT support, a new API pgprot_writecombine is being added. So, drivers can
  95. continue to use the above sequence, with either pgprot_noncached() or
  96. pgprot_writecombine() in step 1, followed by step 2.
  97. In addition, step 2 internally tracks the region as UC or WC in memtype
  98. list in order to ensure no conflicting mapping.
  99. Note that this set of APIs only works with IO (non RAM) regions. If driver
  100. wants to export a RAM region, it has to do set_memory_uc() or set_memory_wc()
  101. as step 0 above and also track the usage of those pages and use set_memory_wb()
  102. before the page is freed to free pool.
  103. MTRR effects on PAT / non-PAT systems
  104. =====================================
  105. The following table provides the effects of using write-combining MTRRs when
  106. using ioremap*() calls on x86 for both non-PAT and PAT systems. Ideally
  107. mtrr_add() usage will be phased out in favor of arch_phys_wc_add() which will
  108. be a no-op on PAT enabled systems. The region over which a arch_phys_wc_add()
  109. is made, should already have been ioremapped with WC attributes or PAT entries,
  110. this can be done by using ioremap_wc() / set_memory_wc(). Devices which
  111. combine areas of IO memory desired to remain uncacheable with areas where
  112. write-combining is desirable should consider use of ioremap_uc() followed by
  113. set_memory_wc() to white-list effective write-combined areas. Such use is
  114. nevertheless discouraged as the effective memory type is considered
  115. implementation defined, yet this strategy can be used as last resort on devices
  116. with size-constrained regions where otherwise MTRR write-combining would
  117. otherwise not be effective.
  118. ::
  119. ==== ======= === ========================= =====================
  120. MTRR Non-PAT PAT Linux ioremap value Effective memory type
  121. ==== ======= === ========================= =====================
  122. PAT Non-PAT | PAT
  123. |PCD |
  124. ||PWT |
  125. ||| |
  126. WC 000 WB _PAGE_CACHE_MODE_WB WC | WC
  127. WC 001 WC _PAGE_CACHE_MODE_WC WC* | WC
  128. WC 010 UC- _PAGE_CACHE_MODE_UC_MINUS WC* | UC
  129. WC 011 UC _PAGE_CACHE_MODE_UC UC | UC
  130. ==== ======= === ========================= =====================
  131. (*) denotes implementation defined and is discouraged
  132. .. note:: -- in the above table mean "Not suggested usage for the API". Some
  133. of the --'s are strictly enforced by the kernel. Some others are not really
  134. enforced today, but may be enforced in future.
  135. For ioremap and pci access through /sys or /proc - The actual type returned
  136. can be more restrictive, in case of any existing aliasing for that address.
  137. For example: If there is an existing uncached mapping, a new ioremap_wc can
  138. return uncached mapping in place of write-combine requested.
  139. set_memory_[uc|wc|wt] and set_memory_wb should be used in pairs, where driver
  140. will first make a region uc, wc or wt and switch it back to wb after use.
  141. Over time writes to /proc/mtrr will be deprecated in favor of using PAT based
  142. interfaces. Users writing to /proc/mtrr are suggested to use above interfaces.
  143. Drivers should use ioremap_[uc|wc] to access PCI BARs with [uc|wc] access
  144. types.
  145. Drivers should use set_memory_[uc|wc|wt] to set access type for RAM ranges.
  146. PAT debugging
  147. =============
  148. With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by::
  149. # mount -t debugfs debugfs /sys/kernel/debug
  150. # cat /sys/kernel/debug/x86/pat_memtype_list
  151. PAT memtype list:
  152. uncached-minus @ 0x7fadf000-0x7fae0000
  153. uncached-minus @ 0x7fb19000-0x7fb1a000
  154. uncached-minus @ 0x7fb1a000-0x7fb1b000
  155. uncached-minus @ 0x7fb1b000-0x7fb1c000
  156. uncached-minus @ 0x7fb1c000-0x7fb1d000
  157. uncached-minus @ 0x7fb1d000-0x7fb1e000
  158. uncached-minus @ 0x7fb1e000-0x7fb25000
  159. uncached-minus @ 0x7fb25000-0x7fb26000
  160. uncached-minus @ 0x7fb26000-0x7fb27000
  161. uncached-minus @ 0x7fb27000-0x7fb28000
  162. uncached-minus @ 0x7fb28000-0x7fb2e000
  163. uncached-minus @ 0x7fb2e000-0x7fb2f000
  164. uncached-minus @ 0x7fb2f000-0x7fb30000
  165. uncached-minus @ 0x7fb31000-0x7fb32000
  166. uncached-minus @ 0x80000000-0x90000000
  167. This list shows physical address ranges and various PAT settings used to
  168. access those physical address ranges.
  169. Another, more verbose way of getting PAT related debug messages is with
  170. "debugpat" boot parameter. With this parameter, various debug messages are
  171. printed to dmesg log.
  172. PAT Initialization
  173. ==================
  174. The following table describes how PAT is initialized under various
  175. configurations. The PAT MSR must be updated by Linux in order to support WC
  176. and WT attributes. Otherwise, the PAT MSR has the value programmed in it
  177. by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests.
  178. ==== ===== ========================== ========= =======
  179. MTRR PAT Call Sequence PAT State PAT MSR
  180. ==== ===== ========================== ========= =======
  181. E E MTRR -> PAT init Enabled OS
  182. E D MTRR -> PAT init Disabled -
  183. D E MTRR -> PAT disable Disabled BIOS
  184. D D MTRR -> PAT disable Disabled -
  185. - np/E PAT -> PAT disable Disabled BIOS
  186. - np/D PAT -> PAT disable Disabled -
  187. E !P/E MTRR -> PAT init Disabled BIOS
  188. D !P/E MTRR -> PAT disable Disabled BIOS
  189. !M !P/E MTRR stub -> PAT disable Disabled BIOS
  190. ==== ===== ========================== ========= =======
  191. Legend
  192. ========= =======================================
  193. E Feature enabled in CPU
  194. D Feature disabled/unsupported in CPU
  195. np "nopat" boot option specified
  196. !P CONFIG_X86_PAT option unset
  197. !M CONFIG_MTRR option unset
  198. Enabled PAT state set to enabled
  199. Disabled PAT state set to disabled
  200. OS PAT initializes PAT MSR with OS setting
  201. BIOS PAT keeps PAT MSR with BIOS setting
  202. ========= =======================================