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