241 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3==========================4PAT (Page Attribute Table)5==========================6 7x86 Page Attribute Table (PAT) allows for setting the memory attribute at the8page level granularity. PAT is complementary to the MTRR settings which allows9for setting of memory types over physical address ranges. However, PAT is10more flexible than MTRR due to its capability to set attributes at page level11and also due to the fact that there are no hardware limitations on number of12such attribute settings allowed. Added flexibility comes with guidelines for13not having memory type aliasing for the same physical memory with multiple14virtual addresses.15 16PAT allows for different types of memory attributes. The most commonly used17ones that will be supported at this time are:18 19=== ==============20WB Write-back21UC Uncached22WC Write-combined23WT Write-through24UC- Uncached Minus25=== ==============26 27 28PAT APIs29========30 31There are many different APIs in the kernel that allows setting of memory32attributes at the page level. In order to avoid aliasing, these interfaces33should 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 physical36address 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 96Advanced APIs for drivers97=========================98 99A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range,100vmf_insert_pfn.101 102Drivers wanting to export some pages to userspace do it by using mmap103interface and a combination of:104 105 1) pgprot_noncached()106 2) io_remap_pfn_range() or remap_pfn_range() or vmf_insert_pfn()107 108With PAT support, a new API pgprot_writecombine is being added. So, drivers can109continue to use the above sequence, with either pgprot_noncached() or110pgprot_writecombine() in step 1, followed by step 2.111 112In addition, step 2 internally tracks the region as UC or WC in memtype113list in order to ensure no conflicting mapping.114 115Note that this set of APIs only works with IO (non RAM) regions. If driver116wants to export a RAM region, it has to do set_memory_uc() or set_memory_wc()117as step 0 above and also track the usage of those pages and use set_memory_wb()118before the page is freed to free pool.119 120MTRR effects on PAT / non-PAT systems121=====================================122 123The following table provides the effects of using write-combining MTRRs when124using ioremap*() calls on x86 for both non-PAT and PAT systems. Ideally125mtrr_add() usage will be phased out in favor of arch_phys_wc_add() which will126be a no-op on PAT enabled systems. The region over which a arch_phys_wc_add()127is made, should already have been ioremapped with WC attributes or PAT entries,128this can be done by using ioremap_wc() / set_memory_wc(). Devices which129combine areas of IO memory desired to remain uncacheable with areas where130write-combining is desirable should consider use of ioremap_uc() followed by131set_memory_wc() to white-list effective write-combined areas. Such use is132nevertheless discouraged as the effective memory type is considered133implementation defined, yet this strategy can be used as last resort on devices134with size-constrained regions where otherwise MTRR write-combining would135otherwise not be effective.136::137 138 ==== ======= === ========================= =====================139 MTRR Non-PAT PAT Linux ioremap value Effective memory type140 ==== ======= === ========================= =====================141 PAT Non-PAT | PAT142 |PCD |143 ||PWT |144 ||| |145 WC 000 WB _PAGE_CACHE_MODE_WB WC | WC146 WC 001 WC _PAGE_CACHE_MODE_WC WC* | WC147 WC 010 UC- _PAGE_CACHE_MODE_UC_MINUS WC* | UC148 WC 011 UC _PAGE_CACHE_MODE_UC UC | UC149 ==== ======= === ========================= =====================150 151 (*) denotes implementation defined and is discouraged152 153.. note:: -- in the above table mean "Not suggested usage for the API". Some154 of the --'s are strictly enforced by the kernel. Some others are not really155 enforced today, but may be enforced in future.156 157For ioremap and pci access through /sys or /proc - The actual type returned158can be more restrictive, in case of any existing aliasing for that address.159For example: If there is an existing uncached mapping, a new ioremap_wc can160return uncached mapping in place of write-combine requested.161 162set_memory_[uc|wc|wt] and set_memory_wb should be used in pairs, where driver163will first make a region uc, wc or wt and switch it back to wb after use.164 165Over time writes to /proc/mtrr will be deprecated in favor of using PAT based166interfaces. Users writing to /proc/mtrr are suggested to use above interfaces.167 168Drivers should use ioremap_[uc|wc] to access PCI BARs with [uc|wc] access169types.170 171Drivers should use set_memory_[uc|wc|wt] to set access type for RAM ranges.172 173 174PAT debugging175=============176 177With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by::178 179 # mount -t debugfs debugfs /sys/kernel/debug180 # cat /sys/kernel/debug/x86/pat_memtype_list181 PAT memtype list:182 uncached-minus @ 0x7fadf000-0x7fae0000183 uncached-minus @ 0x7fb19000-0x7fb1a000184 uncached-minus @ 0x7fb1a000-0x7fb1b000185 uncached-minus @ 0x7fb1b000-0x7fb1c000186 uncached-minus @ 0x7fb1c000-0x7fb1d000187 uncached-minus @ 0x7fb1d000-0x7fb1e000188 uncached-minus @ 0x7fb1e000-0x7fb25000189 uncached-minus @ 0x7fb25000-0x7fb26000190 uncached-minus @ 0x7fb26000-0x7fb27000191 uncached-minus @ 0x7fb27000-0x7fb28000192 uncached-minus @ 0x7fb28000-0x7fb2e000193 uncached-minus @ 0x7fb2e000-0x7fb2f000194 uncached-minus @ 0x7fb2f000-0x7fb30000195 uncached-minus @ 0x7fb31000-0x7fb32000196 uncached-minus @ 0x80000000-0x90000000197 198This list shows physical address ranges and various PAT settings used to199access those physical address ranges.200 201Another, more verbose way of getting PAT related debug messages is with202"debugpat" boot parameter. With this parameter, various debug messages are203printed to dmesg log.204 205PAT Initialization206==================207 208The following table describes how PAT is initialized under various209configurations. The PAT MSR must be updated by Linux in order to support WC210and WT attributes. Otherwise, the PAT MSR has the value programmed in it211by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests.212 213 ==== ===== ========================== ========= =======214 MTRR PAT Call Sequence PAT State PAT MSR215 ==== ===== ========================== ========= =======216 E E MTRR -> PAT init Enabled OS217 E D MTRR -> PAT init Disabled -218 D E MTRR -> PAT disable Disabled BIOS219 D D MTRR -> PAT disable Disabled -220 - np/E PAT -> PAT disable Disabled BIOS221 - np/D PAT -> PAT disable Disabled -222 E !P/E MTRR -> PAT init Disabled BIOS223 D !P/E MTRR -> PAT disable Disabled BIOS224 !M !P/E MTRR stub -> PAT disable Disabled BIOS225 ==== ===== ========================== ========= =======226 227 Legend228 229 ========= =======================================230 E Feature enabled in CPU231 D Feature disabled/unsupported in CPU232 np "nopat" boot option specified233 !P CONFIG_X86_PAT option unset234 !M CONFIG_MTRR option unset235 Enabled PAT state set to enabled236 Disabled PAT state set to disabled237 OS PAT initializes PAT MSR with OS setting238 BIOS PAT keeps PAT MSR with BIOS setting239 ========= =======================================240 241