Skip to contentSkip to conversation

x86/doc: add PTI description

PATCH Superseded Dave Hansen 3 participants 3 messages Jan 5, 2018 Documentation

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 x86/doc: add PTI description

Changes from v2:
* Update some wording
* Minor typo and grammar fixes
* Further clarify what INVPCID is.

Changes from v1:
* update kernel-parameters.txt to clarify that the pti= option is not just for disabling. Also describe what 'pti=auto' does and why
* Add a note about the presence of NX in the user portion of the kernel page tables
* Clarify _additional_ 4k of PGD space
* Add a note about the runtime overhead of PCID without INVPCID

---

From: Dave Hansen <[email protected]>

Add some details about how PTI works, what some of the downsides are, and how to debug it when things go wrong.

Also document the kernel parameter: 'nopti'.

Cc Moritz Lipp <[email protected]>
Cc Daniel Gruss <[email protected]>
Cc Michael Schwarz <[email protected]>
Cc Richard Fellner <[email protected]>
Cc Andy Lutomirski <[email protected]>
Cc Linus Torvalds <[email protected]>
Cc Hugh Dickins <[email protected]>

---

 b/Documentation/admin-guide/kernel-parameters.txt |   21 +-
 b/Documentation/x86/pti.txt                       |  187 ++++++++++++++++++++++
 2 files changed, 201 insertions(+), 7 deletions(-)
Documentation/admin-guide/kernel-parameters.txt renamed from Documentation/admin-guide/kernel-parameters.txt~kpti-doc +14 -7
diff -puN Documentation/admin-guide/kernel-parameters.txt~kpti-doc Documentation/admin-guide/kernel-parameters.txt
@@ -2712,8 +2712,6 @@
 			steal time is computed, but won't influence scheduler
 			behaviour
 
-	nopti		[X86-64] Disable kernel page table isolation
-
 	nolapic		[X86-32,APIC] Do not enable or use the local APIC.
 
 	nolapic_timer	[X86-32,APIC] Do not use the local APIC timer.
@@ -3288,11 +3286,20 @@
 	pt.		[PARIDE]
 			See Documentation/blockdev/paride.txt.
 
-	pti=		[X86_64]
-			Control user/kernel address space isolation:
-			on - enable
-			off - disable
-			auto - default setting
+	pti=		[X86_64] Control Page Table Isolation of user and
+			kernel address spaces.  Disabling this feature
+			removes hardening, but improves performance of
+			system calls and interrupts.
+
+			on   - unconditionally enable
+			off  - unconditionally disable
+			auto - kernel detects whether your CPU model is
+			       vulnerable to issues that PTI mitigates
+
+			Not specifying this option is equivalent to pti=auto.
+
+	nopti		[X86_64]
+			Equivalent to pti=off
 
 	pty.legacy_count=
 			[KNL] Number of legacy pty's. Overwrites compiled-in
Documentation/x86/pti.txt new file +187 -0

187 lines not on this page · raw message

_

reviewer
#1 lore raw
Quoted 8 lines · Dave Hansen
Documentation/x86/pti.txt new file +8 -0
+Page Table Management
+=====================
+
+When PTI is enabled, the kernel manages two sets of page tables.
+The first set is very similar to the single set which is present in
+kernels without PTI.  This includes a complete mapping of userspace
+that the kernel can use for things like copy_to_user().
+

Documentation/x86/pti.txt line 44

Quoted 10 lines
Documentation/x86/pti.txt new file +10 -0
+Although _complete_, the user portion of the kernel page tables is
+crippled by setting the NX bit in the top level.  This ensures
+that any missed kernel->user CR3 switch will immediately crash
+userspace upon executing its first instruction.
+
+The userspace page tables map only the kernel data needed to enter
+and exit the kernel.  This data is entirely contained in the 'struct
+cpu_entry_area' structure which is placed in the fixmap which gives
+each CPU's copy of the area has a compile-time-fixed virtual
+address.

drop /has/ above.

Quoted 6 lines
Documentation/x86/pti.txt new file +6 -0
+
+For new userspace mappings, the kernel makes the entries in its
+page tables like normal.  The only difference is when the kernel
+makes entries in the top (PGD) level.  In addition to setting the
+entry in the main kernel PGD, a copy of the entry is made in the
+userspace page tables' PGD.
Signature · 1 line
~Randy
#2 lore raw
In reply to Dave Hansen
Quoted 4 lines · Dave Hansen

diff -puN /dev/null Documentation/x86/pti.txt

Documentation/x86/pti.txt new file +0 -0
@@ -0,0 +1,187 @@

[...]

Documentation/x86/pti.txt line 55

Quoted 4 lines
Documentation/x86/pti.txt new file +4 -0
+This sharing at the PGD level also inherently shares all the lower
+layers of the page tables.  This leaves a single, shared set of
+userspace page tables to manage.  One PTE to lock, one set set of
+accessed bits, dirty bits, etc...

one set set -> one set

[...]

Quoted 2 lines

+2. Allow PTI to enabled/disabled at runtime in addition to the
+ boot-time switching.

to -> to be

Signature · 1 line
David Taylor