From: Maciej Wieczor-Retman <[email protected]> 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 <[email protected]> --- 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
