Re: [PATCH 2/3] kasan: move boot parameters section in documentation

[Marco Elver <elver@google.com>]

On Mon, May 09, 2022 at 09:07PM +0200, andrey.konovalov@linux.dev wrote:
> From: Andrey Konovalov <andreyknvl@google.com>
> 
> Move the "Boot parameters" section in KASAN documentation next to the
> section that describes KASAN build options.
> 
> No content changes.
> 
> Signed-off-by: Andrey Konovalov <andreyknvl@google.com>

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

> ---
>  Documentation/dev-tools/kasan.rst | 82 +++++++++++++++----------------
>  1 file changed, 41 insertions(+), 41 deletions(-)
> 
> diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
> index aca219ed1198..7f103e975ac2 100644
> --- a/Documentation/dev-tools/kasan.rst
> +++ b/Documentation/dev-tools/kasan.rst
> @@ -94,6 +94,47 @@ To include alloc and free stack traces of affected slab objects into reports,
>  enable ``CONFIG_STACKTRACE``. To include alloc and free stack traces of affected
>  physical pages, enable ``CONFIG_PAGE_OWNER`` and boot with ``page_owner=on``.
>  
> +Boot parameters
> +~~~~~~~~~~~~~~~
> +
> +KASAN is affected by the generic ``panic_on_warn`` command line parameter.
> +When it is enabled, KASAN panics the kernel after printing a bug report.
> +
> +By default, KASAN prints a bug report only for the first invalid memory access.
> +With ``kasan_multi_shot``, KASAN prints a report on every invalid access. This
> +effectively disables ``panic_on_warn`` for KASAN reports.
> +
> +Alternatively, independent of ``panic_on_warn``, the ``kasan.fault=`` boot
> +parameter can be used to control panic and reporting behaviour:
> +
> +- ``kasan.fault=report`` or ``=panic`` controls whether to only print a KASAN
> +  report or also panic the kernel (default: ``report``). The panic happens even
> +  if ``kasan_multi_shot`` is enabled.
> +
> +Hardware Tag-Based KASAN mode (see the section about various modes below) is
> +intended for use in production as a security mitigation. Therefore, it supports
> +additional boot parameters that allow disabling KASAN or controlling features:
> +
> +- ``kasan=off`` or ``=on`` controls whether KASAN is enabled (default: ``on``).
> +
> +- ``kasan.mode=sync``, ``=async`` or ``=asymm`` controls whether KASAN
> +  is configured in synchronous, asynchronous or asymmetric mode of
> +  execution (default: ``sync``).
> +  Synchronous mode: a bad access is detected immediately when a tag
> +  check fault occurs.
> +  Asynchronous mode: a bad access detection is delayed. When a tag check
> +  fault occurs, the information is stored in hardware (in the TFSR_EL1
> +  register for arm64). The kernel periodically checks the hardware and
> +  only reports tag faults during these checks.
> +  Asymmetric mode: a bad access is detected synchronously on reads and
> +  asynchronously on writes.
> +
> +- ``kasan.vmalloc=off`` or ``=on`` disables or enables tagging of vmalloc
> +  allocations (default: ``on``).
> +
> +- ``kasan.stacktrace=off`` or ``=on`` disables or enables alloc and free stack
> +  traces collection (default: ``on``).
> +
>  Error reports
>  ~~~~~~~~~~~~~
>  
> @@ -208,47 +249,6 @@ traces point to places in code that interacted with the object but that are not
>  directly present in the bad access stack trace. Currently, this includes
>  call_rcu() and workqueue queuing.
>  
> -Boot parameters
> -~~~~~~~~~~~~~~~
> -
> -KASAN is affected by the generic ``panic_on_warn`` command line parameter.
> -When it is enabled, KASAN panics the kernel after printing a bug report.
> -
> -By default, KASAN prints a bug report only for the first invalid memory access.
> -With ``kasan_multi_shot``, KASAN prints a report on every invalid access. This
> -effectively disables ``panic_on_warn`` for KASAN reports.
> -
> -Alternatively, independent of ``panic_on_warn``, the ``kasan.fault=`` boot
> -parameter can be used to control panic and reporting behaviour:
> -
> -- ``kasan.fault=report`` or ``=panic`` controls whether to only print a KASAN
> -  report or also panic the kernel (default: ``report``). The panic happens even
> -  if ``kasan_multi_shot`` is enabled.
> -
> -Hardware Tag-Based KASAN mode (see the section about various modes below) is
> -intended for use in production as a security mitigation. Therefore, it supports
> -additional boot parameters that allow disabling KASAN or controlling features:
> -
> -- ``kasan=off`` or ``=on`` controls whether KASAN is enabled (default: ``on``).
> -
> -- ``kasan.mode=sync``, ``=async`` or ``=asymm`` controls whether KASAN
> -  is configured in synchronous, asynchronous or asymmetric mode of
> -  execution (default: ``sync``).
> -  Synchronous mode: a bad access is detected immediately when a tag
> -  check fault occurs.
> -  Asynchronous mode: a bad access detection is delayed. When a tag check
> -  fault occurs, the information is stored in hardware (in the TFSR_EL1
> -  register for arm64). The kernel periodically checks the hardware and
> -  only reports tag faults during these checks.
> -  Asymmetric mode: a bad access is detected synchronously on reads and
> -  asynchronously on writes.
> -
> -- ``kasan.vmalloc=off`` or ``=on`` disables or enables tagging of vmalloc
> -  allocations (default: ``on``).
> -
> -- ``kasan.stacktrace=off`` or ``=on`` disables or enables alloc and free stack
> -  traces collection (default: ``on``).
> -
>  Implementation details
>  ----------------------
>  
> -- 
> 2.25.1
> 
> -- 
> You received this message because you are subscribed to the Google Groups "kasan-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to kasan-dev+unsubscribe@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/kasan-dev/ec9c923f35e7c5312836c4624a7f317dc1ee2c1c.1652123204.git.andreyknvl%40google.com.