Documentation/x86/pat.txt

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