Skip to content

L
linux
Commit 2f6eae47 authored by Changbin Du's avatar Changbin Du Committed by Jonathan Corbet
Browse files
Options

Documentation: x86: convert pat.txt to reST 

This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.
Signed-off-by: default avatarChangbin Du <changbin.du@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 26d14a20
Hide whitespace changes
Inline Side-by-side
Showing with 243 additions and 0 deletions
Documentation/x86/index.rst
View file @ 2f6eae47
...@@ -17,3 +17,4 @@ x86-specific Documentation ...@@ -17,3 +17,4 @@ x86-specific Documentation
zero-page zero-page
tlb tlb
mtrr mtrr
pat
Documentation/x86/pat.txt → Documentation/x86/pat.rst
View file @ 2f6eae47
.. SPDX-License-Identifier: GPL-2.0
==========================
PAT (Page Attribute Table) PAT (Page Attribute Table)
==========================
x86 Page Attribute Table (PAT) allows for setting the memory attribute at the x86 Page Attribute Table (PAT) allows for setting the memory attribute at the
page level granularity. PAT is complementary to the MTRR settings which allows page level granularity. PAT is complementary to the MTRR settings which allows
...@@ -11,12 +14,19 @@ not having memory type aliasing for the same physical memory with multiple ...@@ -11,12 +14,19 @@ not having memory type aliasing for the same physical memory with multiple
virtual addresses. virtual addresses.
PAT allows for different types of memory attributes. The most commonly used PAT allows for different types of memory attributes. The most commonly used
ones that will be supported at this time are Write-back, Uncached, ones that will be supported at this time are:
Write-combined, Write-through and Uncached Minus.
=== ==============
WB Write-back
UC Uncached
WC Write-combined
WT Write-through
UC- Uncached Minus
=== ==============
PAT APIs PAT APIs
-------- ========
There are many different APIs in the kernel that allows setting of memory There are many different APIs in the kernel that allows setting of memory
attributes at the page level. In order to avoid aliasing, these interfaces attributes at the page level. In order to avoid aliasing, these interfaces
...@@ -25,77 +35,77 @@ their intended usage and their memory attribute relationships. Internally, ...@@ -25,77 +35,77 @@ their intended usage and their memory attribute relationships. Internally,
these APIs use a reserve_memtype()/free_memtype() interface on the physical these APIs use a reserve_memtype()/free_memtype() interface on the physical
address range to avoid any aliasing. address range to avoid any aliasing.
+------------------------+----------+--------------+------------------+
| API | RAM | ACPI,... | Reserved/Holes |
+------------------------+----------+--------------+------------------+
| ioremap | -- | UC- | UC- |
+------------------------+----------+--------------+------------------+
| ioremap_cache | -- | WB | WB |
+------------------------+----------+--------------+------------------+
| ioremap_uc | -- | UC | UC |
+------------------------+----------+--------------+------------------+
| ioremap_nocache | -- | UC- | UC- |
+------------------------+----------+--------------+------------------+
| ioremap_wc | -- | -- | WC |
+------------------------+----------+--------------+------------------+
| ioremap_wt | -- | -- | WT |
+------------------------+----------+--------------+------------------+
| set_memory_uc, | UC- | -- | -- |
| set_memory_wb | | | |
+------------------------+----------+--------------+------------------+
| set_memory_wc, | WC | -- | -- |
| set_memory_wb | | | |
+------------------------+----------+--------------+------------------+
| set_memory_wt, | WT | -- | -- |
| set_memory_wb | | | |
+------------------------+----------+--------------+------------------+
| pci sysfs resource | -- | -- | UC- |
+------------------------+----------+--------------+------------------+
| pci sysfs resource_wc | -- | -- | WC |
| is IORESOURCE_PREFETCH | | | |
+------------------------+----------+--------------+------------------+
| pci proc | -- | -- | UC- |
| !PCIIOC_WRITE_COMBINE | | | |
+------------------------+----------+--------------+------------------+
| pci proc | -- | -- | WC |
| PCIIOC_WRITE_COMBINE | | | |
+------------------------+----------+--------------+------------------+
| /dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
| read-write | | | |
+------------------------+----------+--------------+------------------+
| /dev/mem | -- | UC- | UC- |
| mmap SYNC flag | | | |
+------------------------+----------+--------------+------------------+
| /dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
| mmap !SYNC flag | | | |
| and | |(from existing| (from existing |
| any alias to this area | |alias) | alias) |
+------------------------+----------+--------------+------------------+
| /dev/mem | -- | WB | WB |
| mmap !SYNC flag | | | |
| no alias to this area | | | |
| and | | | |
| MTRR says WB | | | |
+------------------------+----------+--------------+------------------+
| /dev/mem | -- | -- | UC- |
| mmap !SYNC flag | | | |
| no alias to this area | | | |
| and | | | |
| MTRR says !WB | | | |
+------------------------+----------+--------------+------------------+
-------------------------------------------------------------------
API | RAM | ACPI,... | Reserved/Holes |
-----------------------|----------|------------|------------------|
| | | |
ioremap | -- | UC- | UC- |
| | | |
ioremap_cache | -- | WB | WB |
| | | |
ioremap_uc | -- | UC | UC |
| | | |
ioremap_nocache | -- | UC- | UC- |
| | | |
ioremap_wc | -- | -- | WC |
| | | |
ioremap_wt | -- | -- | WT |
| | | |
set_memory_uc | UC- | -- | -- |
set_memory_wb | | | |
| | | |
set_memory_wc | WC | -- | -- |
set_memory_wb | | | |
| | | |
set_memory_wt | WT | -- | -- |
set_memory_wb | | | |
| | | |
pci sysfs resource | -- | -- | UC- |
| | | |
pci sysfs resource_wc | -- | -- | WC |
is IORESOURCE_PREFETCH| | | |
| | | |
pci proc | -- | -- | UC- |
!PCIIOC_WRITE_COMBINE | | | |
| | | |
pci proc | -- | -- | WC |
PCIIOC_WRITE_COMBINE | | | |
| | | |
/dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
read-write | | | |
| | | |
/dev/mem | -- | UC- | UC- |
mmap SYNC flag | | | |
| | | |
/dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
mmap !SYNC flag | |(from exist-| (from exist- |
and | | ing alias)| ing alias) |
any alias to this area| | | |
| | | |
/dev/mem | -- | WB | WB |
mmap !SYNC flag | | | |
no alias to this area | | | |
and | | | |
MTRR says WB | | | |
| | | |
/dev/mem | -- | -- | UC- |
mmap !SYNC flag | | | |
no alias to this area | | | |
and | | | |
MTRR says !WB | | | |
| | | |
-------------------------------------------------------------------
Advanced APIs for drivers Advanced APIs for drivers
------------------------- =========================
A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range, A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range,
vmf_insert_pfn vmf_insert_pfn.
Drivers wanting to export some pages to userspace do it by using mmap Drivers wanting to export some pages to userspace do it by using mmap
interface and a combination of interface and a combination of:
1) pgprot_noncached()
2) io_remap_pfn_range() or remap_pfn_range() or vmf_insert_pfn() 1) pgprot_noncached()
2) io_remap_pfn_range() or remap_pfn_range() or vmf_insert_pfn()
With PAT support, a new API pgprot_writecombine is being added. So, drivers can With PAT support, a new API pgprot_writecombine is being added. So, drivers can
continue to use the above sequence, with either pgprot_noncached() or continue to use the above sequence, with either pgprot_noncached() or
...@@ -110,7 +120,7 @@ as step 0 above and also track the usage of those pages and use set_memory_wb() ...@@ -110,7 +120,7 @@ as step 0 above and also track the usage of those pages and use set_memory_wb()
before the page is freed to free pool. before the page is freed to free pool.
MTRR effects on PAT / non-PAT systems MTRR effects on PAT / non-PAT systems
------------------------------------- =====================================
The following table provides the effects of using write-combining MTRRs when The following table provides the effects of using write-combining MTRRs when
using ioremap*() calls on x86 for both non-PAT and PAT systems. Ideally using ioremap*() calls on x86 for both non-PAT and PAT systems. Ideally
...@@ -125,28 +135,26 @@ nevertheless discouraged as the effective memory type is considered ...@@ -125,28 +135,26 @@ nevertheless discouraged as the effective memory type is considered
implementation defined, yet this strategy can be used as last resort on devices implementation defined, yet this strategy can be used as last resort on devices
with size-constrained regions where otherwise MTRR write-combining would with size-constrained regions where otherwise MTRR write-combining would
otherwise not be effective. otherwise not be effective.
::
----------------------------------------------------------------------
MTRR Non-PAT PAT Linux ioremap value Effective memory type ==== ======= === ========================= =====================
---------------------------------------------------------------------- MTRR Non-PAT PAT Linux ioremap value Effective memory type
Non-PAT | PAT ==== ======= === ========================= =====================
PAT PAT Non-PAT | PAT
|PCD |PCD |
||PWT ||PWT |
||| ||| |
WC 000 WB _PAGE_CACHE_MODE_WB WC | WC WC 000 WB _PAGE_CACHE_MODE_WB WC | WC
WC 001 WC _PAGE_CACHE_MODE_WC WC* | WC WC 001 WC _PAGE_CACHE_MODE_WC WC* | WC
WC 010 UC- _PAGE_CACHE_MODE_UC_MINUS WC* | UC WC 010 UC- _PAGE_CACHE_MODE_UC_MINUS WC* | UC
WC 011 UC _PAGE_CACHE_MODE_UC UC | UC WC 011 UC _PAGE_CACHE_MODE_UC UC | UC
---------------------------------------------------------------------- ==== ======= === ========================= =====================
(*) denotes implementation defined and is discouraged (*) denotes implementation defined and is discouraged
Notes: .. note:: -- in the above table mean "Not suggested usage for the API". Some
of the --'s are strictly enforced by the kernel. Some others are not really
-- in the above table mean "Not suggested usage for the API". Some of the --'s enforced today, but may be enforced in future.
are strictly enforced by the kernel. Some others are not really enforced
today, but may be enforced in future.
For ioremap and pci access through /sys or /proc - The actual type returned For ioremap and pci access through /sys or /proc - The actual type returned
can be more restrictive, in case of any existing aliasing for that address. can be more restrictive, in case of any existing aliasing for that address.
...@@ -166,28 +174,28 @@ Drivers should use set_memory_[uc|wc|wt] to set access type for RAM ranges. ...@@ -166,28 +174,28 @@ Drivers should use set_memory_[uc|wc|wt] to set access type for RAM ranges.
PAT debugging PAT debugging
------------- =============
With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by::
# mount -t debugfs debugfs /sys/kernel/debug # mount -t debugfs debugfs /sys/kernel/debug
# cat /sys/kernel/debug/x86/pat_memtype_list # cat /sys/kernel/debug/x86/pat_memtype_list
PAT memtype list: PAT memtype list:
uncached-minus @ 0x7fadf000-0x7fae0000 uncached-minus @ 0x7fadf000-0x7fae0000
uncached-minus @ 0x7fb19000-0x7fb1a000 uncached-minus @ 0x7fb19000-0x7fb1a000
uncached-minus @ 0x7fb1a000-0x7fb1b000 uncached-minus @ 0x7fb1a000-0x7fb1b000
uncached-minus @ 0x7fb1b000-0x7fb1c000 uncached-minus @ 0x7fb1b000-0x7fb1c000
uncached-minus @ 0x7fb1c000-0x7fb1d000 uncached-minus @ 0x7fb1c000-0x7fb1d000
uncached-minus @ 0x7fb1d000-0x7fb1e000 uncached-minus @ 0x7fb1d000-0x7fb1e000
uncached-minus @ 0x7fb1e000-0x7fb25000 uncached-minus @ 0x7fb1e000-0x7fb25000
uncached-minus @ 0x7fb25000-0x7fb26000 uncached-minus @ 0x7fb25000-0x7fb26000
uncached-minus @ 0x7fb26000-0x7fb27000 uncached-minus @ 0x7fb26000-0x7fb27000
uncached-minus @ 0x7fb27000-0x7fb28000 uncached-minus @ 0x7fb27000-0x7fb28000
uncached-minus @ 0x7fb28000-0x7fb2e000 uncached-minus @ 0x7fb28000-0x7fb2e000
uncached-minus @ 0x7fb2e000-0x7fb2f000 uncached-minus @ 0x7fb2e000-0x7fb2f000
uncached-minus @ 0x7fb2f000-0x7fb30000 uncached-minus @ 0x7fb2f000-0x7fb30000
uncached-minus @ 0x7fb31000-0x7fb32000 uncached-minus @ 0x7fb31000-0x7fb32000
uncached-minus @ 0x80000000-0x90000000 uncached-minus @ 0x80000000-0x90000000
This list shows physical address ranges and various PAT settings used to This list shows physical address ranges and various PAT settings used to
access those physical address ranges. access those physical address ranges.
...@@ -197,15 +205,16 @@ Another, more verbose way of getting PAT related debug messages is with ...@@ -197,15 +205,16 @@ Another, more verbose way of getting PAT related debug messages is with
printed to dmesg log. printed to dmesg log.
PAT Initialization PAT Initialization
------------------ ==================
The following table describes how PAT is initialized under various The following table describes how PAT is initialized under various
configurations. The PAT MSR must be updated by Linux in order to support WC configurations. The PAT MSR must be updated by Linux in order to support WC
and WT attributes. Otherwise, the PAT MSR has the value programmed in it and WT attributes. Otherwise, the PAT MSR has the value programmed in it
by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests. by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests.
==== ===== ========================== ========= =======
MTRR PAT Call Sequence PAT State PAT MSR MTRR PAT Call Sequence PAT State PAT MSR
========================================================= ==== ===== ========================== ========= =======
E E MTRR -> PAT init Enabled OS E E MTRR -> PAT init Enabled OS
E D MTRR -> PAT init Disabled - E D MTRR -> PAT init Disabled -
D E MTRR -> PAT disable Disabled BIOS D E MTRR -> PAT disable Disabled BIOS
...@@ -215,9 +224,11 @@ by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests. ...@@ -215,9 +224,11 @@ by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests.
E !P/E MTRR -> PAT init Disabled BIOS E !P/E MTRR -> PAT init Disabled BIOS
D !P/E MTRR -> PAT disable Disabled BIOS D !P/E MTRR -> PAT disable Disabled BIOS
!M !P/E MTRR stub -> PAT disable Disabled BIOS !M !P/E MTRR stub -> PAT disable Disabled BIOS
==== ===== ========================== ========= =======
Legend
Legend ========= =======================================
------------------------------------------------
E Feature enabled in CPU E Feature enabled in CPU
D Feature disabled/unsupported in CPU D Feature disabled/unsupported in CPU
np "nopat" boot option specified np "nopat" boot option specified
...@@ -227,4 +238,5 @@ by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests. ...@@ -227,4 +238,5 @@ by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests.
Disabled PAT state set to disabled Disabled PAT state set to disabled
OS PAT initializes PAT MSR with OS setting OS PAT initializes PAT MSR with OS setting
BIOS PAT keeps PAT MSR with BIOS setting BIOS PAT keeps PAT MSR with BIOS setting
========= =======================================
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7