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 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_nocache        |    --    |    UC-     |       UC-        |
  38                        |          |            |                  |
  39 ioremap_wc             |    --    |    --      |       WC         |
  40                        |          |            |                  |
  41 set_memory_uc          |    UC-   |    --      |       --         |
  42  set_memory_wb         |          |            |                  |
  43                        |          |            |                  |
  44 set_memory_wc          |    WC    |    --      |       --         |
  45  set_memory_wb         |          |            |                  |
  46                        |          |            |                  |
  47 pci sysfs resource     |    --    |    --      |       UC-        |
  48                        |          |            |                  |
  49 pci sysfs resource_wc  |    --    |    --      |       WC         |
  50  is IORESOURCE_PREFETCH|          |            |                  |
  51                        |          |            |                  |
  52 pci proc               |    --    |    --      |       UC-        |
  53  !PCIIOC_WRITE_COMBINE |          |            |                  |
  54                        |          |            |                  |
  55 pci proc               |    --    |    --      |       WC         |
  56  PCIIOC_WRITE_COMBINE  |          |            |                  |
  57                        |          |            |                  |
  58 /dev/mem               |    --    |  WB/WC/UC- |    WB/WC/UC-     |
  59  read-write            |          |            |                  |
  60                        |          |            |                  |
  61 /dev/mem               |    --    |    UC-     |       UC-        |
  62  mmap SYNC flag        |          |            |                  |
  63                        |          |            |                  |
  64 /dev/mem               |    --    |  WB/WC/UC- |    WB/WC/UC-     |
  65  mmap !SYNC flag       |          |(from exist-|  (from exist-    |
  66  and                   |          |  ing alias)|    ing alias)    |
  67  any alias to this area|          |            |                  |
  68                        |          |            |                  |
  69 /dev/mem               |    --    |    WB      |       WB         |
  70  mmap !SYNC flag       |          |            |                  |
  71  no alias to this area |          |            |                  |
  72  and                   |          |            |                  |
  73  MTRR says WB          |          |            |                  |
  74                        |          |            |                  |
  75 /dev/mem               |    --    |    --      |       UC-        |
  76  mmap !SYNC flag       |          |            |                  |
  77  no alias to this area |          |            |                  |
  78  and                   |          |            |                  |
  79  MTRR says !WB         |          |            |                  |
  80                        |          |            |                  |
  81 -------------------------------------------------------------------
  82
  83 Notes:
  84
  85 -- in the above table mean "Not suggested usage for the API". Some of the --'s
  86 are strictly enforced by the kernel. Some others are not really enforced
  87 today, but may be enforced in future.
  88
  89 For ioremap and pci access through /sys or /proc - The actual type returned
  90 can be more restrictive, in case of any existing aliasing for that address.
  91 For example: If there is an existing uncached mapping, a new ioremap_wc can
  92 return uncached mapping in place of write-combine requested.
  93
  94 set_memory_[uc|wc] and set_memory_wb should be used in pairs, where driver will
  95 first make a region uc or wc and switch it back to wb after use.
  96
  97 Over time writes to /proc/mtrr will be deprecated in favor of using PAT based
  98 interfaces. Users writing to /proc/mtrr are suggested to use above interfaces.
  99
 100 Drivers should use ioremap_[uc|wc] to access PCI BARs with [uc|wc] access
 101 types.
 102
 103 Drivers should use set_memory_[uc|wc] to set access type for RAM ranges.
 104
 105
 106 PAT debugging
 107 -------------
 108
 109 With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by
 110
 111 # mount -t debugfs debugfs /sys/kernel/debug
 112 # cat /sys/kernel/debug/x86/pat_memtype_list
 113 PAT memtype list:
 114 uncached-minus @ 0x7fadf000-0x7fae0000
 115 uncached-minus @ 0x7fb19000-0x7fb1a000
 116 uncached-minus @ 0x7fb1a000-0x7fb1b000
 117 uncached-minus @ 0x7fb1b000-0x7fb1c000
 118 uncached-minus @ 0x7fb1c000-0x7fb1d000
 119 uncached-minus @ 0x7fb1d000-0x7fb1e000
 120 uncached-minus @ 0x7fb1e000-0x7fb25000
 121 uncached-minus @ 0x7fb25000-0x7fb26000
 122 uncached-minus @ 0x7fb26000-0x7fb27000
 123 uncached-minus @ 0x7fb27000-0x7fb28000
 124 uncached-minus @ 0x7fb28000-0x7fb2e000
 125 uncached-minus @ 0x7fb2e000-0x7fb2f000
 126 uncached-minus @ 0x7fb2f000-0x7fb30000
 127 uncached-minus @ 0x7fb31000-0x7fb32000
 128 uncached-minus @ 0x80000000-0x90000000
 129
 130 This list shows physical address ranges and various PAT settings used to
 131 access those physical address ranges.
 132
 133 Another, more verbose way of getting PAT related debug messages is with
 134 "debugpat" boot parameter. With this parameter, various debug messages are
 135 printed to dmesg log.
 136