Documentation/x86/pat.rst

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