[PATCH v11 15/15] docs: Update KASAN and x86 memory map documentations

[Maciej Wieczor-Retman]

From: Maciej Wieczor-Retman <maciej.wieczor-retman@xxxxxxxxx>

Update the documentation concerning changes to x86's memory address
space and new architecture addition to KASAN's software tag-based mode.

Redo paragraphs in KASAN's documentation on hardware and software
implementation details to allow better extensibility.

Signed-off-by: Maciej Wieczor-Retman <maciej.wieczor-retman@xxxxxxxxx>
---
Changelog v11:
- Split off the documentation portion of v10's patch 13.
- Apply Dave's suggestions to reformat the footer explaining alternate
  ranges for KASAN shadow memory, put arch hardware implementation in a
  separate paragraph and make a table to hold various implementation
  details.

 Documentation/arch/x86/x86_64/mm.rst | 21 +++++++++-
 Documentation/dev-tools/kasan.rst    | 61 ++++++++++++++++++++--------
 2 files changed, 62 insertions(+), 20 deletions(-)

diff --git a/Documentation/arch/x86/x86_64/mm.rst b/Documentation/arch/x86/x86_64/mm.rst
index a6cf05d51bd8..3c78ab1afd8d 100644
--- a/Documentation/arch/x86/x86_64/mm.rst
+++ b/Documentation/arch/x86/x86_64/mm.rst
@@ -60,7 +60,7 @@ Complete virtual memory map with 4-level page tables
    ffffe90000000000 |  -23    TB | ffffe9ffffffffff |    1 TB | ... unused hole
    ffffea0000000000 |  -22    TB | ffffeaffffffffff |    1 TB | virtual memory map (vmemmap_base)
    ffffeb0000000000 |  -21    TB | ffffebffffffffff |    1 TB | ... unused hole
-   ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory
+   ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory[1]
   __________________|____________|__________________|_________|____________________________________________________________
                                                               |
                                                               | Identical layout to the 56-bit one from here on:
@@ -130,7 +130,7 @@ Complete virtual memory map with 5-level page tables
    ffd2000000000000 |  -11.5  PB | ffd3ffffffffffff |  0.5 PB | ... unused hole
    ffd4000000000000 |  -11    PB | ffd5ffffffffffff |  0.5 PB | virtual memory map (vmemmap_base)
    ffd6000000000000 |  -10.5  PB | ffdeffffffffffff | 2.25 PB | ... unused hole
-   ffdf000000000000 |   -8.25 PB | fffffbffffffffff |   ~8 PB | KASAN shadow memory
+   ffdf000000000000 |   -8.25 PB | fffffbffffffffff |   ~8 PB | KASAN shadow memory[1]
   __________________|____________|__________________|_________|____________________________________________________________
                                                               |
                                                               | Identical layout to the 47-bit one from here on:
@@ -178,3 +178,20 @@ correct as KASAN disables KASLR.
 
 For both 4- and 5-level layouts, the KSTACK_ERASE_POISON value in the last 2MB
 hole: ffffffffffff4111
+
+1. The range is different based on what KASAN mode is used and what paging level
+   is used:
+
+::
+
+  ============================================================================================================
+      Start addr    |   Offset   |     End addr     |  Size   | VM area description
+  ============================================================================================================
+                    |            |                  |         | 4-level paging:
+   ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory (generic mode)
+   fffff40000000000 |   -8    TB | fffffbffffffffff |    8 TB | KASAN shadow memory (software tag-based mode)
+  __________________|____________|__________________|_________|_______________________________________________
+                    |            |                  |         | 5-level paging:
+   ffdf000000000000 |   -8.25 PB | fffffbffffffffff |   ~8 PB | KASAN shadow memory (generic mode)
+   ffeffc0000000000 |   -6    PB | fffffbffffffffff |    4 PB | KASAN shadow memory (software tag-based mode)
+  __________________|____________|__________________|_________|_______________________________________________
diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
index b11c1be8dff4..d42d80e9fcf1 100644
--- a/Documentation/dev-tools/kasan.rst
+++ b/Documentation/dev-tools/kasan.rst
@@ -22,8 +22,8 @@ architectures, but it has significant performance and memory overheads.
 
 Software Tag-Based KASAN or SW_TAGS KASAN, enabled with CONFIG_KASAN_SW_TAGS,
 can be used for both debugging and dogfood testing, similar to userspace HWASan.
-This mode is only supported for arm64, but its moderate memory overhead allows
-using it for testing on memory-restricted devices with real workloads.
+This mode is only supported for arm64 and x86, but its moderate memory overhead
+allows using it for testing on memory-restricted devices with real workloads.
 
 Hardware Tag-Based KASAN or HW_TAGS KASAN, enabled with CONFIG_KASAN_HW_TAGS,
 is the mode intended to be used as an in-field memory bug detector or as a
@@ -346,16 +346,21 @@ Software Tag-Based KASAN
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 Software Tag-Based KASAN uses a software memory tagging approach to checking
-access validity. It is currently only implemented for the arm64 architecture.
-
-Software Tag-Based KASAN uses the Top Byte Ignore (TBI) feature of arm64 CPUs
-to store a pointer tag in the top byte of kernel pointers. It uses shadow memory
-to store memory tags associated with each 16-byte memory cell (therefore, it
-dedicates 1/16th of the kernel memory for shadow memory).
-
-On each memory allocation, Software Tag-Based KASAN generates a random tag, tags
-the allocated memory with this tag, and embeds the same tag into the returned
-pointer.
+access validity. It is currently only implemented for the arm64 and x86
+architectures. To function, special hardware CPU features* are needed for
+repurposing space inside the kernel pointers to store pointer tags.
+
+Software Tag-Based mode uses shadow memory to store memory tags associated with
+each 16-byte memory cell (therefore, it dedicates 1/16th of the kernel memory
+for shadow memory). On each memory allocation, Software Tag-Based KASAN
+generates a random tag, tags the allocated memory with this tag, and embeds the
+same tag into the returned pointer.
+
+Two special tag values can be distinguished. A match-all pointer tag (otherwise
+called the 'kernel tag' because it's supposed to be equal to the value normally
+present in the same bits of the linear address when KASAN is disabled) -
+accesses through such pointers are not checked. Another value is also reserved
+to tag freed memory regions.
 
 Software Tag-Based KASAN uses compile-time instrumentation to insert checks
 before each memory access. These checks make sure that the tag of the memory
@@ -367,12 +372,32 @@ Software Tag-Based KASAN also has two instrumentation modes (outline, which
 emits callbacks to check memory accesses; and inline, which performs the shadow
 memory checks inline). With outline instrumentation mode, a bug report is
 printed from the function that performs the access check. With inline
-instrumentation, a ``brk`` instruction is emitted by the compiler, and a
-dedicated ``brk`` handler is used to print bug reports.
-
-Software Tag-Based KASAN uses 0xFF as a match-all pointer tag (accesses through
-pointers with the 0xFF pointer tag are not checked). The value 0xFE is currently
-reserved to tag freed memory regions.
+instrumentation, the compiler emits a specific arch-dependent instruction with a
+dedicated handler to print bug reports.
+
+Architecture specific details:
+
+::
+
+  +-----------------------+--------+---------------------+
+  | detail \ architecture | arm64  | x86                 |
+  +=======================+========+=====================+
+  | Hardware feature      | TBI    | LAM                 |
+  +-----------------------+--------+---------------------+
+  | Kernel tag            | 0xFF   | 0x0F                |
+  +-----------------------+--------+---------------------+
+  | Freed memory tag      | 0xFE   | 0x0E                |
+  +-----------------------+--------+---------------------+
+  | Tag width             | 8 bits | 4 bits              |
+  +-----------------------+--------+---------------------+
+  | Inline instruction    | brk    | no compiler support |
+  +-----------------------+--------+---------------------+
+
+* Different architectures implement different hardware features to mask and
+  repurpose linear address bits. arm64 utilizes Top Byte Ignore (TBI) to mask
+  out and allow storing tags in the top byte of the pointer. x86 uses Linear
+  Address Masking (LAM) to store tags in the four bits of the kernel pointer's
+  top byte.
 
 Hardware Tag-Based KASAN
 ~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.53.0