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