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

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

Documentation/x86/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -17,3 +17,4 @@ x86-specific Documentation 
   zero-page

   tlb

   mtrr

   pat

Documentation/x86/pat.txt→Documentation/x86/pat.rst

+242 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



==========================

PAT (Page Attribute Table)

==========================



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
@@ -11,12 +14,19 @@ not having memory type aliasing for the same physical memory with multiple 
virtual addresses.



PAT allows for different types of memory attributes. The most commonly used

ones that will be supported at this time are Write-back, Uncached,

Write-combined, Write-through and Uncached Minus.

ones that will be supported at this time are:



===  ==============

WB   Write-back

UC   Uncached

WC   Write-combined

WT   Write-through

UC-  Uncached Minus

===  ==============





PAT APIs

--------

========



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
@@ -25,75 +35,75 @@ their intended usage and their memory attribute relationships. Internally, 
these APIs use a reserve_memtype()/free_memtype() interface on the physical

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

-------------------------

=========================



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

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()
@@ -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.



MTRR effects on PAT / non-PAT systems

-------------------------------------

=====================================



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
@@ -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

with size-constrained regions where otherwise MTRR write-combining would

otherwise not be effective.

::



----------------------------------------------------------------------

  ====  =======  ===  =========================  =====================

  MTRR  Non-PAT  PAT  Linux ioremap value        Effective memory type

----------------------------------------------------------------------

                                                  Non-PAT |  PAT

     PAT

     |PCD

     ||PWT

     |||

  ====  =======  ===  =========================  =====================

        PAT                                        Non-PAT |  PAT

        |PCD                                               |

        ||PWT                                              |

        |||                                                |

  WC    000      WB   _PAGE_CACHE_MODE_WB             WC   |   WC

  WC    001      WC   _PAGE_CACHE_MODE_WC             WC*  |   WC

  WC    010      UC-  _PAGE_CACHE_MODE_UC_MINUS       WC*  |   UC

  WC    011      UC   _PAGE_CACHE_MODE_UC             UC   |   UC

----------------------------------------------------------------------

  ====  =======  ===  =========================  =====================



  (*) denotes implementation defined and is discouraged



Notes:



-- 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 enforced

today, but may be enforced in future.

.. 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

  enforced today, but may be enforced in future.



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.
@@ -166,9 +174,9 @@ Drivers should use set_memory_[uc|wc|wt] to set access type for RAM ranges. 




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

  # cat /sys/kernel/debug/x86/pat_memtype_list
@@ -197,15 +205,16 @@ Another, more verbose way of getting PAT related debug messages is with 
printed to dmesg log.



PAT Initialization

------------------

==================



The following table describes how PAT is initialized under various

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

by 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
@@ -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

 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
@@ -227,4 +238,5 @@ by the firmware. Note, Xen enables WC attribute in the PAT MSR for guests. 
 Disabled  PAT state set to disabled

 OS        PAT initializes PAT MSR with OS setting

 BIOS      PAT keeps PAT MSR with BIOS setting

 ========= =======================================