by Marco Elver

[permalink] [raw]

Subject: Re: [PATCH v2 10/11] kasan: docs: update ignoring accesses section

On Fri, Mar 12, 2021 at 03:24PM +0100, Andrey Konovalov wrote:
> Update the "Ignoring accesses" section in KASAN documentation:
>
> - Mention __no_sanitize_address/noinstr.
> - Mention kasan_disable/enable_current().
> - Mention kasan_reset_tag()/page_kasan_tag_reset().
> - Readability and punctuation clean-ups.
>
> Signed-off-by: Andrey Konovalov <[email protected]>

Reviewed-by: Marco Elver <[email protected]>

> ---
>
> Changes in v1->v2:
> - Mention __no_sanitize_address/noinstr.
> - Reword the whole section to make it clear which method works for which
> mode.
> ---
> Documentation/dev-tools/kasan.rst | 34 +++++++++++++++++++++++++++----
> 1 file changed, 30 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
> index d0c1796122df..5749c14b38d0 100644
> --- a/Documentation/dev-tools/kasan.rst
> +++ b/Documentation/dev-tools/kasan.rst
> @@ -368,12 +368,18 @@ 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
> +Such instrumentation might be incompatible with some parts of the kernel, and
> +therefore needs to be disabled.
> +
> +Other parts of the kernel might access metadata for allocated objects.
> +Normally, KASAN detects and reports such accesses, but in some cases (e.g.,
> +in memory allocators), these accesses are valid.
> +
> +For software KASAN modes, to disable instrumentation for a specific file or
> +directory, add a ``KASAN_SANITIZE`` annotation to the respective kernel
> Makefile:
>
> -- For a single file (e.g. main.o)::
> +- For a single file (e.g., main.o)::
>
> KASAN_SANITIZE_main.o := n
>
> @@ -381,6 +387,26 @@ Makefile:
>
> KASAN_SANITIZE := n
>
> +For software KASAN modes, to disable instrumentation on a per-function basis,
> +use the KASAN-specific ``__no_sanitize_address`` function attribute or the
> +generic ``noinstr`` one.
> +
> +Note that disabling compiler instrumentation (either on a per-file or a
> +per-function basis) makes KASAN ignore the accesses that happen directly in
> +that code for software KASAN modes. It does not help when the accesses happen
> +indirectly (through calls to instrumented functions) or with the hardware
> +tag-based mode that does not use compiler instrumentation.
> +
> +For software KASAN modes, to disable KASAN reports in a part of the kernel code
> +for the current task, annotate this part of the code with a
> +``kasan_disable_current()``/``kasan_enable_current()`` section. This also
> +disables the reports for indirect accesses that happen through function calls.
> +
> +For tag-based KASAN modes (include the hardware one), to disable access
> +checking, use ``kasan_reset_tag()`` or ``page_kasan_tag_reset()``. Note that
> +temporarily disabling access checking via ``page_kasan_tag_reset()`` requires
> +saving and restoring the per-page KASAN tag via
> +``page_kasan_tag``/``page_kasan_tag_set``.
>
> Tests
> ~~~~~
> --
> 2.31.0.rc2.261.g7f71774620-goog
>

2021-03-12 15:13:30

by Marco Elver

[permalink] [raw]

Subject: Re: [PATCH v2 11/11] kasan: docs: update tests section

On Fri, Mar 12, 2021 at 03:24PM +0100, Andrey Konovalov wrote:
> Update the "Tests" section in KASAN documentation:
>
> - Add an introductory sentence.
> - Add proper indentation for the list of ways to run KUnit tests.
> - Punctuation, readability, and other minor clean-ups.
>
> Signed-off-by: Andrey Konovalov <[email protected]>

Reviewed-by: Marco Elver <[email protected]>

> ---
>
> Changes v1->v2:
> - Fix missing snippet delimeter around "test_kasan.ko".
> - Drop "the" before "test_kasan.ko".
> ---
> Documentation/dev-tools/kasan.rst | 32 +++++++++++++++----------------
> 1 file changed, 15 insertions(+), 17 deletions(-)
>
> diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
> index 5749c14b38d0..a8c3e0cff88d 100644
> --- a/Documentation/dev-tools/kasan.rst
> +++ b/Documentation/dev-tools/kasan.rst
> @@ -411,19 +411,20 @@ saving and restoring the per-page KASAN tag via
> Tests
> ~~~~~
>
> -KASAN tests consist of two parts:
> +There are KASAN tests that allow verifying that KASAN works and can detect
> +certain types of memory corruptions. The tests consist of two parts:
>
> 1. Tests that are integrated with the KUnit Test Framework. Enabled with
> ``CONFIG_KASAN_KUNIT_TEST``. These tests can be run and partially verified
> -automatically in a few different ways, see the instructions below.
> +automatically in a few different ways; see the instructions below.
>
> 2. Tests that are currently incompatible with KUnit. Enabled with
> ``CONFIG_KASAN_MODULE_TEST`` and can only be run as a module. These tests can
> -only be verified manually, by loading the kernel module and inspecting the
> +only be verified manually by loading the kernel module and inspecting the
> kernel log for KASAN reports.
>
> -Each KUnit-compatible KASAN test prints a KASAN report if an error is detected.
> -Then the test prints its number and status.
> +Each KUnit-compatible KASAN test prints one of multiple KASAN reports if an
> +error is detected. Then the test prints its number and status.
>
> When a test passes::
>
> @@ -451,27 +452,24 @@ Or, if one of the tests failed::
>
> not ok 1 - kasan
>
> -
> 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``.
> + With ``CONFIG_KUNIT`` enabled, KASAN-KUnit tests can be built as a loadable
> + module and run by loading ``test_kasan.ko`` with ``insmod`` or ``modprobe``.
>
> 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.
> + With ``CONFIG_KUNIT`` built-in, KASAN-KUnit tests can be built-in as well.
> + In this case, the tests will run 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
> -in a more readable way. This will not print the KASAN reports of the tests that
> -passed. Use `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_
> -for more up-to-date information on ``kunit_tool``.
> + With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, it is also
> + possible to use ``kunit_tool`` to see the results of KUnit tests in a more
> + readable way. This will not print the KASAN reports of the tests that passed.
> + See `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_
> + for more up-to-date information on ``kunit_tool``.
>
> .. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html
> --
> 2.31.0.rc2.261.g7f71774620-goog
>