Re: [PATCH v2 06/11] kasan: docs: update GENERIC implementation details section

[Marco Elver <elver@google.com>]

On Fri, Mar 12, 2021 at 03:24PM +0100, Andrey Konovalov wrote:
> Update the "Implementation details" section for generic KASAN:
> 
> - Don't mention kmemcheck, it's not present in the kernel anymore.
> - Don't mention GCC as the only supported compiler.
> - Update kasan_mem_to_shadow() definition to match actual code.
> - Punctuation, readability, and other minor clean-ups.
> 
> Signed-off-by: Andrey Konovalov <andreyknvl@google.com>

Reviewed-by: Marco Elver <elver@google.com>

> ---
>  Documentation/dev-tools/kasan.rst | 27 +++++++++++++--------------
>  1 file changed, 13 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
> index 1189be9b4cb5..986410bf269f 100644
> --- a/Documentation/dev-tools/kasan.rst
> +++ b/Documentation/dev-tools/kasan.rst
> @@ -200,12 +200,11 @@ Implementation details
>  Generic KASAN
>  ~~~~~~~~~~~~~
>  
> -From a high level perspective, KASAN's approach to memory error detection is
> -similar to that of kmemcheck: use shadow memory to record whether each byte of
> -memory is safe to access, and use compile-time instrumentation to insert checks
> -of shadow memory on each memory access.
> +Software KASAN modes use shadow memory to record whether each byte of memory is
> +safe to access and use compile-time instrumentation to insert shadow memory
> +checks before each memory access.
>  
> -Generic KASAN dedicates 1/8th of kernel memory to its shadow memory (e.g. 16TB
> +Generic KASAN dedicates 1/8th of kernel memory to its shadow memory (16TB
>  to cover 128TB on x86_64) and uses direct mapping with a scale and offset to
>  translate a memory address to its corresponding shadow address.
>  
> @@ -214,23 +213,23 @@ address::
>  
>      static inline void *kasan_mem_to_shadow(const void *addr)
>      {
> -	return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT)
> +	return (void *)((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT)
>  		+ KASAN_SHADOW_OFFSET;
>      }
>  
>  where ``KASAN_SHADOW_SCALE_SHIFT = 3``.
>  
>  Compile-time instrumentation is used to insert memory access checks. Compiler
> -inserts function calls (__asan_load*(addr), __asan_store*(addr)) before each
> -memory access of size 1, 2, 4, 8 or 16. These functions check whether memory
> -access is valid or not by checking corresponding shadow memory.
> +inserts function calls (``__asan_load*(addr)``, ``__asan_store*(addr)``) before
> +each memory access of size 1, 2, 4, 8, or 16. These functions check whether
> +memory accesses are valid or not by checking corresponding shadow memory.
>  
> -GCC 5.0 has possibility to perform inline instrumentation. Instead of making
> -function calls GCC directly inserts the code to check the shadow memory.
> -This option significantly enlarges kernel but it gives x1.1-x2 performance
> -boost over outline instrumented kernel.
> +With inline instrumentation, instead of making function calls, the compiler
> +directly inserts the code to check shadow memory. This option significantly
> +enlarges the kernel, but it gives an x1.1-x2 performance boost over the
> +outline-instrumented kernel.
>  
> -Generic KASAN is the only mode that delays the reuse of freed object via
> +Generic KASAN is the only mode that delays the reuse of freed objects via
>  quarantine (see mm/kasan/quarantine.c for implementation).
>  
>  Software tag-based KASAN
> -- 
> 2.31.0.rc2.261.g7f71774620-goog
>