linux/Documentation/x86/pat.txt
<<
>>
Prefs
   1
   2PAT (Page Attribute Table)
   3
   4x86 Page Attribute Table (PAT) allows for setting the memory attribute at the
   5page level granularity. PAT is complementary to the MTRR settings which allows
   6for setting of memory types over physical address ranges. However, PAT is
   7more flexible than MTRR due to its capability to set attributes at page level
   8and also due to the fact that there are no hardware limitations on number of
   9such attribute settings allowed. Added flexibility comes with guidelines for
  10not having memory type aliasing for the same physical memory with multiple
  11virtual addresses.
  12
  13PAT allows for different types of memory attributes. The most commonly used
  14ones that will be supported at this time are Write-back, Uncached,
  15Write-combined and Uncached Minus.
  16
  17
  18PAT APIs
  19--------
  20
  21There are many different APIs in the kernel that allows setting of memory
  22attributes at the page level. In order to avoid aliasing, these interfaces
  23should be used thoughtfully. Below is a table of interfaces available,
  24their intended usage and their memory attribute relationships. Internally,
  25these APIs use a reserve_memtype()/free_memtype() interface on the physical
  26address range to avoid any aliasing.
  27
  28
  29-------------------------------------------------------------------
  30API                    |    RAM   |  ACPI,...  |  Reserved/Holes  |
  31-----------------------|----------|------------|------------------|
  32                       |          |            |                  |
  33ioremap                |    --    |    UC-     |       UC-        |
  34                       |          |            |                  |
  35ioremap_cache          |    --    |    WB      |       WB         |
  36                       |          |            |                  |
  37ioremap_nocache        |    --    |    UC-     |       UC-        |
  38                       |          |            |                  |
  39ioremap_wc             |    --    |    --      |       WC         |
  40                       |          |            |                  |
  41set_memory_uc          |    UC-   |    --      |       --         |
  42 set_memory_wb         |          |            |                  |
  43                       |          |            |                  |
  44set_memory_wc          |    WC    |    --      |       --         |
  45 set_memory_wb         |          |            |                  |
  46                       |          |            |                  |
  47pci sysfs resource     |    --    |    --      |       UC-        |
  48                       |          |            |                  |
  49pci sysfs resource_wc  |    --    |    --      |       WC         |
  50 is IORESOURCE_PREFETCH|          |            |                  |
  51                       |          |            |                  |
  52pci proc               |    --    |    --      |       UC-        |
  53 !PCIIOC_WRITE_COMBINE |          |            |                  |
  54                       |          |            |                  |
  55pci 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
  83Advanced APIs for drivers
  84-------------------------
  85A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range,
  86vm_insert_pfn
  87
  88Drivers wanting to export some pages to userspace do it by using mmap
  89interface and a combination of
  901) pgprot_noncached()
  912) io_remap_pfn_range() or remap_pfn_range() or vm_insert_pfn()
  92
  93With PAT support, a new API pgprot_writecombine is being added. So, drivers can
  94continue to use the above sequence, with either pgprot_noncached() or
  95pgprot_writecombine() in step 1, followed by step 2.
  96
  97In addition, step 2 internally tracks the region as UC or WC in memtype
  98list in order to ensure no conflicting mapping.
  99
 100Note that this set of APIs only works with IO (non RAM) regions. If driver
 101wants to export a RAM region, it has to do set_memory_uc() or set_memory_wc()
 102as step 0 above and also track the usage of those pages and use set_memory_wb()
 103before the page is freed to free pool.
 104
 105
 106
 107Notes:
 108
 109-- in the above table mean "Not suggested usage for the API". Some of the --'s
 110are strictly enforced by the kernel. Some others are not really enforced
 111today, but may be enforced in future.
 112
 113For ioremap and pci access through /sys or /proc - The actual type returned
 114can be more restrictive, in case of any existing aliasing for that address.
 115For example: If there is an existing uncached mapping, a new ioremap_wc can
 116return uncached mapping in place of write-combine requested.
 117
 118set_memory_[uc|wc] and set_memory_wb should be used in pairs, where driver will
 119first make a region uc or wc and switch it back to wb after use.
 120
 121Over time writes to /proc/mtrr will be deprecated in favor of using PAT based
 122interfaces. Users writing to /proc/mtrr are suggested to use above interfaces.
 123
 124Drivers should use ioremap_[uc|wc] to access PCI BARs with [uc|wc] access
 125types.
 126
 127Drivers should use set_memory_[uc|wc] to set access type for RAM ranges.
 128
 129
 130PAT debugging
 131-------------
 132
 133With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by
 134
 135# mount -t debugfs debugfs /sys/kernel/debug
 136# cat /sys/kernel/debug/x86/pat_memtype_list
 137PAT memtype list:
 138uncached-minus @ 0x7fadf000-0x7fae0000
 139uncached-minus @ 0x7fb19000-0x7fb1a000
 140uncached-minus @ 0x7fb1a000-0x7fb1b000
 141uncached-minus @ 0x7fb1b000-0x7fb1c000
 142uncached-minus @ 0x7fb1c000-0x7fb1d000
 143uncached-minus @ 0x7fb1d000-0x7fb1e000
 144uncached-minus @ 0x7fb1e000-0x7fb25000
 145uncached-minus @ 0x7fb25000-0x7fb26000
 146uncached-minus @ 0x7fb26000-0x7fb27000
 147uncached-minus @ 0x7fb27000-0x7fb28000
 148uncached-minus @ 0x7fb28000-0x7fb2e000
 149uncached-minus @ 0x7fb2e000-0x7fb2f000
 150uncached-minus @ 0x7fb2f000-0x7fb30000
 151uncached-minus @ 0x7fb31000-0x7fb32000
 152uncached-minus @ 0x80000000-0x90000000
 153
 154This list shows physical address ranges and various PAT settings used to
 155access those physical address ranges.
 156
 157Another, more verbose way of getting PAT related debug messages is with
 158"debugpat" boot parameter. With this parameter, various debug messages are
 159printed to dmesg log.
 160
 161
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.