13.1.PAT APIs¶

There are many different APIs in the kernel that allows setting of memoryattributes at the page level. In order to avoid aliasing, these interfacesshould be used thoughtfully. Below is a table of interfaces available,their intended usage and their memory attribute relationships. Internally,these APIs use areserve_memtype()/free_memtype() interface on the physicaladdress range to avoid any aliasing.

13.2.Advanced APIs for drivers¶

A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range,vmf_insert_pfn.

Drivers wanting to export some pages to userspace do it by using mmapinterface and a combination of:

1. pgprot_noncached()

2. io_remap_pfn_range() orremap_pfn_range() orvmf_insert_pfn()

With PAT support, a new API pgprot_writecombine is being added. So, drivers cancontinue to use the above sequence, with eitherpgprot_noncached() orpgprot_writecombine() in step 1, followed by step 2.

In addition, step 2 internally tracks the region as UC or WC in memtypelist in order to ensure no conflicting mapping.

Note that this set of APIs only works with IO (non RAM) regions. If driverwants to export a RAM region, it has to doset_memory_uc() orset_memory_wc()as step 0 above and also track the usage of those pages and useset_memory_wb()before the page is freed to free pool.

13.3.MTRR effects on PAT / non-PAT systems¶

The following table provides the effects of using write-combining MTRRs whenusing ioremap*() calls on x86 for both non-PAT and PAT systems. Ideallymtrr_add() usage will be phased out in favor ofarch_phys_wc_add() which willbe a no-op on PAT enabled systems. The region over which aarch_phys_wc_add()is made, should already have been ioremapped with WC attributes or PAT entries,this can be done by usingioremap_wc() /set_memory_wc(). Devices whichcombine areas of IO memory desired to remain uncacheable with areas wherewrite-combining is desirable should consider use ofioremap_uc() followed byset_memory_wc() to white-list effective write-combined areas. Such use isnevertheless discouraged as the effective memory type is consideredimplementation defined, yet this strategy can be used as last resort on deviceswith size-constrained regions where otherwise MTRR write-combining wouldotherwise not be effective.

====  =======  ===  =========================  =====================MTRR  Non-PAT  PAT  Linux ioremap value        Effective memory type====  =======  ===  =========================  =====================      PAT                                        Non-PAT |  PAT      |PCD                                               |      ||PWT                                              |      |||                                                |WC    000      WB   _PAGE_CACHE_MODE_WB             WC   |   WCWC    001      WC   _PAGE_CACHE_MODE_WC             WC*  |   WCWC    010      UC-  _PAGE_CACHE_MODE_UC_MINUS       WC*  |   UCWC    011      UC   _PAGE_CACHE_MODE_UC             UC   |   UC====  =======  ===  =========================  =====================(*) denotes implementation defined and is discouraged

For ioremap and pci access through /sys or /proc - The actual type returnedcan be more restrictive, in case of any existing aliasing for that address.For example: If there is an existing uncached mapping, a new ioremap_wc canreturn uncached mapping in place of write-combine requested.

set_memory_[uc|wc|wt] and set_memory_wb should be used in pairs, where driverwill first make a region uc, wc or wt and switch it back to wb after use.

Over time writes to /proc/mtrr will be deprecated in favor of using PAT basedinterfaces. Users writing to /proc/mtrr are suggested to use above interfaces.

Drivers should use ioremap_[uc|wc] to access PCI BARs with [uc|wc] accesstypes.

Drivers should use set_memory_[uc|wc|wt] to set access type for RAM ranges.

13.4.PAT debugging¶

With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by:

# mount -t debugfs debugfs /sys/kernel/debug# cat /sys/kernel/debug/x86/pat_memtype_listPAT memtype list:uncached-minus @ 0x7fadf000-0x7fae0000uncached-minus @ 0x7fb19000-0x7fb1a000uncached-minus @ 0x7fb1a000-0x7fb1b000uncached-minus @ 0x7fb1b000-0x7fb1c000uncached-minus @ 0x7fb1c000-0x7fb1d000uncached-minus @ 0x7fb1d000-0x7fb1e000uncached-minus @ 0x7fb1e000-0x7fb25000uncached-minus @ 0x7fb25000-0x7fb26000uncached-minus @ 0x7fb26000-0x7fb27000uncached-minus @ 0x7fb27000-0x7fb28000uncached-minus @ 0x7fb28000-0x7fb2e000uncached-minus @ 0x7fb2e000-0x7fb2f000uncached-minus @ 0x7fb2f000-0x7fb30000uncached-minus @ 0x7fb31000-0x7fb32000uncached-minus @ 0x80000000-0x90000000

This list shows physical address ranges and various PAT settings used toaccess those physical address ranges.

Another, more verbose way of getting PAT related debug messages is with“debugpat” boot parameter. With this parameter, various debug messages areprinted to dmesg log.

13.5.PAT Initialization¶

The following table describes how PAT is initialized under variousconfigurations. The PAT MSR must be updated by Linux in order to support WCand WT attributes. Otherwise, the PAT MSR has the value programmed in itby the firmware. Note, Xen enables WC attribute in the PAT MSR for guests.

MTRR	PAT	Call Sequence	PAT State	PAT MSR
E	E	MTRR -> PAT init	Enabled	OS
E	D	MTRR -> PAT init	Disabled
D	E	MTRR -> PAT disable	Disabled	BIOS
D	D	MTRR -> PAT disable	Disabled
	np/E	PAT -> PAT disable	Disabled	BIOS
	np/D	PAT -> PAT disable	Disabled
E	!P/E	MTRR -> PAT init	Disabled	BIOS
D	!P/E	MTRR -> PAT disable	Disabled	BIOS
!M	!P/E	MTRR stub -> PAT disable	Disabled	BIOS

Legend

E	Feature enabled in CPU
D	Feature disabled/unsupported in CPU
np	“nopat” boot option specified
!P	CONFIG_X86_PAT option unset
!M	CONFIG_MTRR option unset
Enabled	PAT state set to enabled
Disabled	PAT state set to disabled
OS	PAT initializes PAT MSR with OS setting
BIOS	PAT keeps PAT MSR with BIOS setting