Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Fri, 12 Mar 2021 16:08:55 +0100
From:   Marco Elver <elver@google.com>
To:     Andrey Konovalov <andreyknvl@google.com>
Cc:     Andrew Morton <akpm@linux-foundation.org>,
        Alexander Potapenko <glider@google.com>,
        Andrey Ryabinin <aryabinin@virtuozzo.com>,
        Dmitry Vyukov <dvyukov@google.com>, kasan-dev@googlegroups.com,
        linux-mm@kvack.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 06/11] kasan: docs: update GENERIC implementation
 details section
Message-ID: <YEuEB3IhoXdixgiP@elver.google.com>
References: <c2bbb56eaea80ad484f0ee85bb71959a3a63f1d7.1615559068.git.andreyknvl@google.com>
 <f2f35fdab701f8c709f63d328f98aec2982c8acc.1615559068.git.andreyknvl@google.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <f2f35fdab701f8c709f63d328f98aec2982c8acc.1615559068.git.andreyknvl@google.com>
User-Agent: Mutt/2.0.5 (2021-01-21)
Precedence: bulk

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
>