0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==========================
0004 PAT (Page Attribute Table)
0005 ==========================
0006
0007 x86 Page Attribute Table (PAT) allows for setting the memory attribute at the
0008 page level granularity. PAT is complementary to the MTRR settings which allows
0009 for setting of memory types over physical address ranges. However, PAT is
0010 more flexible than MTRR due to its capability to set attributes at page level
0011 and also due to the fact that there are no hardware limitations on number of
0012 such attribute settings allowed. Added flexibility comes with guidelines for
0013 not having memory type aliasing for the same physical memory with multiple
0014 virtual addresses.
0015
0016 PAT allows for different types of memory attributes. The most commonly used
0017 ones that will be supported at this time are:
0018
0019 === ==============
0020 WB Write-back
0021 UC Uncached
0022 WC Write-combined
0023 WT Write-through
0024 UC- Uncached Minus
0025 === ==============
0026
0027
0028 PAT APIs
0029 ========
0030
0031 There are many different APIs in the kernel that allows setting of memory
0032 attributes at the page level. In order to avoid aliasing, these interfaces
0033 should be used thoughtfully. Below is a table of interfaces available,
0034 their intended usage and their memory attribute relationships. Internally,
0035 these APIs use a reserve_memtype()/free_memtype() interface on the physical
0036 address range to avoid any aliasing.
0037
0038 +------------------------+----------+--------------+------------------+
0039 | API | RAM | ACPI,... | Reserved/Holes |
0040 +------------------------+----------+--------------+------------------+
0041 | ioremap | -- | UC- | UC- |
0042 +------------------------+----------+--------------+------------------+
0043 | ioremap_cache | -- | WB | WB |
0044 +------------------------+----------+--------------+------------------+
0045 | ioremap_uc | -- | UC | UC |
0046 +------------------------+----------+--------------+------------------+
0047 | ioremap_wc | -- | -- | WC |
0048 +------------------------+----------+--------------+------------------+
0049 | ioremap_wt | -- | -- | WT |
0050 +------------------------+----------+--------------+------------------+
0051 | set_memory_uc, | UC- | -- | -- |
0052 | set_memory_wb | | | |
0053 +------------------------+----------+--------------+------------------+
0054 | set_memory_wc, | WC | -- | -- |
0055 | set_memory_wb | | | |
0056 +------------------------+----------+--------------+------------------+
0057 | set_memory_wt, | WT | -- | -- |
0058 | set_memory_wb | | | |
0059 +------------------------+----------+--------------+------------------+
0060 | pci sysfs resource | -- | -- | UC- |
0061 +------------------------+----------+--------------+------------------+
0062 | pci sysfs resource_wc | -- | -- | WC |
0063 | is IORESOURCE_PREFETCH | | | |
0064 +------------------------+----------+--------------+------------------+
0065 | pci proc | -- | -- | UC- |
0066 | !PCIIOC_WRITE_COMBINE | | | |
0067 +------------------------+----------+--------------+------------------+
0068 | pci proc | -- | -- | WC |
0069 | PCIIOC_WRITE_COMBINE | | | |
0070 +------------------------+----------+--------------+------------------+
0071 | /dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
0072 | read-write | | | |
0073 +------------------------+----------+--------------+------------------+
0074 | /dev/mem | -- | UC- | UC- |
0075 | mmap SYNC flag | | | |
0076 +------------------------+----------+--------------+------------------+
0077 | /dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
0078 | mmap !SYNC flag | | | |
0079 | and | |(from existing| (from existing |
0080 | any alias to this area | |alias) | alias) |
0081 +------------------------+----------+--------------+------------------+
0082 | /dev/mem | -- | WB | WB |
0083 | mmap !SYNC flag | | | |
0084 | no alias to this area | | | |
0085 | and | | | |
0086 | MTRR says WB | | | |
0087 +------------------------+----------+--------------+------------------+
0088 | /dev/mem | -- | -- | UC- |
0089 | mmap !SYNC flag | | | |
0090 | no alias to this area | | | |
0091 | and | | | |
0092 | MTRR says !WB | | | |
0093 +------------------------+----------+--------------+------------------+
0094
0095
0096 Advanced APIs for drivers
0097 =========================
0098
0099 A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range,
0100 vmf_insert_pfn.
0101
0102 Drivers wanting to export some pages to userspace do it by using mmap
0103 interface and a combination of:
0104
0105 1) pgprot_noncached()
0106 2) io_remap_pfn_range() or remap_pfn_range() or vmf_insert_pfn()
0107
0108 With PAT support, a new API pgprot_writecombine is being added. So, drivers can
0109 continue to use the above sequence, with either pgprot_noncached() or
0110 pgprot_writecombine() in step 1, followed by step 2.
0111
0112 In addition, step 2 internally tracks the region as UC or WC in memtype
0113 list in order to ensure no conflicting mapping.
0114
0115 Note that this set of APIs only works with IO (non RAM) regions. If driver
0116 wants to export a RAM region, it has to do set_memory_uc() or set_memory_wc()
0117 as step 0 above and also track the usage of those pages and use set_memory_wb()
0118 before the page is freed to free pool.
0119
0120 MTRR effects on PAT / non-PAT systems
0121 =====================================
0122
0123 The following table provides the effects of using write-combining MTRRs when
0124 using ioremap*() calls on x86 for both non-PAT and PAT systems. Ideally
0125 mtrr_add() usage will be phased out in favor of arch_phys_wc_add() which will
0126 be a no-op on PAT enabled systems. The region over which a arch_phys_wc_add()
0127 is made, should already have been ioremapped with WC attributes or PAT entries,
0128 this can be done by using ioremap_wc() / set_memory_wc(). Devices which
0129 combine areas of IO memory desired to remain uncacheable with areas where
0130 write-combining is desirable should consider use of ioremap_uc() followed by
0131 set_memory_wc() to white-list effective write-combined areas. Such use is
0132 nevertheless discouraged as the effective memory type is considered
0133 implementation defined, yet this strategy can be used as last resort on devices
0134 with size-constrained regions where otherwise MTRR write-combining would
0135 otherwise not be effective.
0136 ::
0137
0138 ==== ======= === ========================= =====================
0139 MTRR Non-PAT PAT Linux ioremap value Effective memory type
0140 ==== ======= === ========================= =====================
0141 PAT Non-PAT | PAT
0142 |PCD |
0143 ||PWT |
0144 ||| |
0145 WC 000 WB _PAGE_CACHE_MODE_WB WC | WC
0146 WC 001 WC _PAGE_CACHE_MODE_WC WC* | WC
0147 WC 010 UC- _PAGE_CACHE_MODE_UC_MINUS WC* | UC
0148 WC 011 UC _PAGE_CACHE_MODE_UC UC | UC
0149 ==== ======= === ========================= =====================
0150
0151 (*) denotes implementation defined and is discouraged
0152
0153 .. note:: -- in the above table mean "Not suggested usage for the API". Some
0154 of the --'s are strictly enforced by the kernel. Some others are not really
0155 enforced today, but may be enforced in future.
0156
0157 For ioremap and pci access through /sys or /proc - The actual type returned
0158 can be more restrictive, in case of any existing aliasing for that address.
0159 For example: If there is an existing uncached mapping, a new ioremap_wc can
0160 return uncached mapping in place of write-combine requested.
0161
0162 set_memory_[uc|wc|wt] and set_memory_wb should be used in pairs, where driver
0163 will first make a region uc, wc or wt and switch it back to wb after use.
0164
0165 Over time writes to /proc/mtrr will be deprecated in favor of using PAT based
0166 interfaces. Users writing to /proc/mtrr are suggested to use above interfaces.
0167
0168 Drivers should use ioremap_[uc|wc] to access PCI BARs with [uc|wc] access
0169 types.
0170
0171 Drivers should use set_memory_[uc|wc|wt] to set access type for RAM ranges.
0172
0173
0174 PAT debugging
0175 =============
0176
0177 With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by::
0178
0179 # mount -t debugfs debugfs /sys/kernel/debug
0180 # cat /sys/kernel/debug/x86/pat_memtype_list
0181 PAT memtype list:
0182 uncached-minus @ 0x7fadf000-0x7fae0000
0183 uncached-minus @ 0x7fb19000-0x7fb1a000
0184 uncached-minus @ 0x7fb1a000-0x7fb1b000
0185 uncached-minus @ 0x7fb1b000-0x7fb1c000
0186 uncached-minus @ 0x7fb1c000-0x7fb1d000
0187 uncached-minus @ 0x7fb1d000-0x7fb1e000
0188 uncached-minus @ 0x7fb1e000-0x7fb25000
0189 uncached-minus @ 0x7fb25000-0x7fb26000
0190 uncached-minus @ 0x7fb26000-0x7fb27000
0191 uncached-minus @ 0x7fb27000-0x7fb28000
0192 uncached-minus @ 0x7fb28000-0x7fb2e000
0193 uncached-minus @ 0x7fb2e000-0x7fb2f000
0194 uncached-minus @ 0x7fb2f000-0x7fb30000
0195 uncached-minus @ 0x7fb31000-0x7fb32000
0196 uncached-minus @ 0x80000000-0x90000000
0197
0198 This list shows physical address ranges and various PAT settings used to
0199 access those physical address ranges.
0200
0201 Another, more verbose way of getting PAT related debug messages is with
0202 "debugpat" boot parameter. With this parameter, various debug messages are
0203 printed to dmesg log.
0204
0205 PAT Initialization
0206 ==================
0207
0208 The following table describes how PAT is initialized under various
0209 configurations. The PAT MSR must be updated by Linux in order to support WC
0210 and WT attributes. Otherwise, the PAT MSR has the value programmed in it
0211 by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests.
0212
0213 ==== ===== ========================== ========= =======
0214 MTRR PAT Call Sequence PAT State PAT MSR
0215 ==== ===== ========================== ========= =======
0216 E E MTRR -> PAT init Enabled OS
0217 E D MTRR -> PAT init Disabled -
0218 D E MTRR -> PAT disable Disabled BIOS
0219 D D MTRR -> PAT disable Disabled -
0220 - np/E PAT -> PAT disable Disabled BIOS
0221 - np/D PAT -> PAT disable Disabled -
0222 E !P/E MTRR -> PAT init Disabled BIOS
0223 D !P/E MTRR -> PAT disable Disabled BIOS
0224 !M !P/E MTRR stub -> PAT disable Disabled BIOS
0225 ==== ===== ========================== ========= =======
0226
0227 Legend
0228
0229 ========= =======================================
0230 E Feature enabled in CPU
0231 D Feature disabled/unsupported in CPU
0232 np "nopat" boot option specified
0233 !P CONFIG_X86_PAT option unset
0234 !M CONFIG_MTRR option unset
0235 Enabled PAT state set to enabled
0236 Disabled PAT state set to disabled
0237 OS PAT initializes PAT MSR with OS setting
0238 BIOS PAT keeps PAT MSR with BIOS setting
0239 ========= =======================================
0240
