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

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

Em Fri, 26 Apr 2019 23:31:38 +0800
Changbin Du <changbin.du@gmail.com> escreveu:

> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
> 
> Signed-off-by: Changbin Du <changbin.du@gmail.com>

Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

> ---
>  Documentation/x86/index.rst            |  1 +
>  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 a0426ab156bd..1c675cef14d7 100644
> --- a/Documentation/x86/index.rst
> +++ b/Documentation/x86/index.rst
> @@ -21,3 +21,4 @@ Linux x86 Support
>     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



Thanks,
Mauro