Re: [PATCH v2 01/11] kasan: docs: clean up sections

[Marco Elver <elver@google.com>]

On Fri, Mar 12, 2021 at 03:24PM +0100, Andrey Konovalov wrote:
> Update KASAN documentation:
> 
> - Give some sections clearer names.
> - Remove unneeded subsections in the "Tests" section.
> - Move the "For developers" section and split into subsections.
> 
> Signed-off-by: Andrey Konovalov <andreyknvl@google.com>

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

> ---
> 
> Changes v1->v2:
> - Rename "By default" section to "Default behaviour".
> ---
>  Documentation/dev-tools/kasan.rst | 54 +++++++++++++++----------------
>  1 file changed, 27 insertions(+), 27 deletions(-)
> 
> diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
> index ddf4239a5890..b3b2c517db55 100644
> --- a/Documentation/dev-tools/kasan.rst
> +++ b/Documentation/dev-tools/kasan.rst
> @@ -168,24 +168,6 @@ particular KASAN features.
>    report or also panic the kernel (default: ``report``). Note, that tag
>    checking gets disabled after the first reported bug.
>  
> -For developers
> -~~~~~~~~~~~~~~
> -
> -Software KASAN modes use compiler instrumentation to insert validity checks.
> -Such instrumentation might be incompatible with some part of the kernel, and
> -therefore needs to be disabled. To disable instrumentation for specific files
> -or directories, add a line similar to the following to the respective kernel
> -Makefile:
> -
> -- For a single file (e.g. main.o)::
> -
> -    KASAN_SANITIZE_main.o := n
> -
> -- For all files in one directory::
> -
> -    KASAN_SANITIZE := n
> -
> -
>  Implementation details
>  ----------------------
>  
> @@ -299,8 +281,8 @@ support MTE (but supports TBI).
>  Hardware tag-based KASAN only reports the first found bug. After that MTE tag
>  checking gets disabled.
>  
> -What memory accesses are sanitised by KASAN?
> ---------------------------------------------
> +Shadow memory
> +-------------
>  
>  The kernel maps memory in a number of different parts of the address
>  space. This poses something of a problem for KASAN, which requires
> @@ -311,8 +293,8 @@ The range of kernel virtual addresses is large: there is not enough
>  real memory to support a real shadow region for every address that
>  could be accessed by the kernel.
>  
> -By default
> -~~~~~~~~~~
> +Default behaviour
> +~~~~~~~~~~~~~~~~~
>  
>  By default, architectures only map real memory over the shadow region
>  for the linear mapping (and potentially other small areas). For all
> @@ -362,8 +344,29 @@ unmapped. This will require changes in arch-specific code.
>  This allows ``VMAP_STACK`` support on x86, and can simplify support of
>  architectures that do not have a fixed module region.
>  
> -CONFIG_KASAN_KUNIT_TEST and CONFIG_KASAN_MODULE_TEST
> -----------------------------------------------------
> +For developers
> +--------------
> +
> +Ignoring accesses
> +~~~~~~~~~~~~~~~~~
> +
> +Software KASAN modes use compiler instrumentation to insert validity checks.
> +Such instrumentation might be incompatible with some part of the kernel, and
> +therefore needs to be disabled. To disable instrumentation for specific files
> +or directories, add a line similar to the following to the respective kernel
> +Makefile:
> +
> +- For a single file (e.g. main.o)::
> +
> +    KASAN_SANITIZE_main.o := n
> +
> +- For all files in one directory::
> +
> +    KASAN_SANITIZE := n
> +
> +
> +Tests
> +~~~~~
>  
>  KASAN tests consist of two parts:
>  
> @@ -409,21 +412,18 @@ Or, if one of the tests failed::
>  There are a few ways to run KUnit-compatible KASAN tests.
>  
>  1. Loadable module
> -~~~~~~~~~~~~~~~~~~
>  
>  With ``CONFIG_KUNIT`` enabled, ``CONFIG_KASAN_KUNIT_TEST`` can be built as
>  a loadable module and run on any architecture that supports KASAN by loading
>  the module with insmod or modprobe. The module is called ``test_kasan``.
>  
>  2. Built-In
> -~~~~~~~~~~~
>  
>  With ``CONFIG_KUNIT`` built-in, ``CONFIG_KASAN_KUNIT_TEST`` can be built-in
>  on any architecure that supports KASAN. These and any other KUnit tests enabled
>  will run and print the results at boot as a late-init call.
>  
>  3. Using kunit_tool
> -~~~~~~~~~~~~~~~~~~~
>  
>  With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, it's also
>  possible use ``kunit_tool`` to see the results of these and other KUnit tests
> -- 
> 2.31.0.rc2.261.g7f71774620-goog
>