[PATCH v2 15/27] Documentation: x86: convert pti.txt to reST

Changbin Du
2019-05-02T07:11:05Z

Documentation/x86/{pti.txt => pti.rst} | 17 +++++++++++++----
2 files changed, 14 insertions(+), 4 deletions(-)
rename Documentation/x86/{pti.txt => pti.rst} (96%)

diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index 85f1f44cc8ac..6719defc16f8 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -21,3 +21,4 @@ x86-specific Documentation
protection-keys
intel_mpx
amd-memory-encryption
+ pti
diff --git a/Documentation/x86/pti.txt b/Documentation/x86/pti.rst
similarity index 96%
rename from Documentation/x86/pti.txt
rename to Documentation/x86/pti.rst
index 5cd58439ad2d..4b858a9bad8d 100644
--- a/Documentation/x86/pti.txt
+++ b/Documentation/x86/pti.rst
@@ -1,9 +1,15 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+Page Table Isolation (PTI)
+==========================
+
Overview
========

-Page Table Isolation (pti, previously known as KAISER[1]) is a
+Page Table Isolation (pti, previously known as KAISER [1]_) is a
countermeasure against attacks on the shared user/kernel address
-space such as the "Meltdown" approach[2].
+space such as the "Meltdown" approach [2]_.

To mitigate this class of attacks, we create an independent set of
page tables for use only when running userspace applications. When
@@ -60,6 +66,7 @@ Protection against side-channel attacks is important. But,
this protection comes at a cost:

1. Increased Memory Use
+
a. Each process now needs an order-1 PGD instead of order-0.
(Consumes an additional 4k per process).
b. The 'cpu_entry_area' structure must be 2MB in size and 2MB
@@ -68,6 +75,7 @@ this protection comes at a cost:
is decompressed, but no space in the kernel image itself.

2. Runtime Cost
+
a. CR3 manipulation to switch between the page table copies
must be done at interrupt, syscall, and exception entry
and exit (it can be skipped when the kernel is interrupted,
@@ -142,6 +150,7 @@ ideally doing all of these in parallel:
interrupted, including nested NMIs. Using "-c" boosts the rate of
NMIs, and using two -c with separate counters encourages nested NMIs
and less deterministic behavior.
+ ::

while true; do perf record -c 10000 -e instructions,cycles -a sleep 10; done

@@ -182,5 +191,5 @@ that are worth noting here.
tended to be TLB invalidation issues. Usually invalidating
the wrong PCID, or otherwise missing an invalidation.

-1. https://gruss.cc/files/kaiser.pdf
-2. https://meltdownattack.com/meltdown.pdf
+.. [1] https://gruss.cc/files/kaiser.pdf
+.. [2] https://meltdownattack.com/meltdown.pdf
--
2.20.1