On Wed, Apr 1, 2020 at 8:09 PM Patricia Alfonso trishalfonso@google.com wrote:
Include documentation on how to test KASAN using CONFIG_TEST_KASAN and CONFIG_TEST_KASAN_USER.
Signed-off-by: Patricia Alfonso trishalfonso@google.com
Reviewed-by: Dmitry Vyukov dvyukov@google.com
Documentation/dev-tools/kasan.rst | 70 +++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+)
diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index c652d740735d..287ba063d9f6 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -281,3 +281,73 @@ 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_TEST_KASAN & CONFIG_TEST_KASAN_USER +-------------------------------------------
+``CONFIG_TEST_KASAN`` utilizes the KUnit Test Framework for testing. +This means each test focuses on a small unit of functionality and +there are a few ways these tests can be run.
+Each test will print the KASAN report if an error is detected and then +print the number of the test and the status of the test:
+pass::
ok 28 - kmalloc_double_kzfree
+or, if kmalloc failed::
# kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163
Expected ptr is not null, but is
not ok 4 - kmalloc_large_oob_right
+or, if a KASAN report was expected, but not found::
# kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629
Expected kasan_data->report_expected == kasan_data->report_found, but
kasan_data->report_expected == 1
kasan_data->report_found == 0
not ok 28 - kmalloc_double_kzfree
+All test statuses are tracked as they run and an overall status will +be printed at the end::
ok 1 - kasan_kunit_test
+or::
not ok 1 - kasan_kunit_test
+(1) Loadable Module +~~~~~~~~~~~~~~~~~~~~
+With ``CONFIG_KUNIT`` built-in, ``CONFIG_TEST_KASAN`` can be built as +a loadable module and run on any architecture that supports KASAN +using something like insmod or modprobe.
+(2) Built-In +~~~~~~~~~~~~~
+With ``CONFIG_KUNIT`` built-in, ``CONFIG_TEST_KASAN`` 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_TEST_KASAN`` built-in, we can also +use kunit_tool to see the results of these along with other KUnit +tests in a more readable way. This will not print the KASAN reports +of 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.
+.. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html
+``CONFIG_TEST_KASAN_USER`` is a set of KASAN tests that could not be +converted to KUnit. These tests can be run only as a module with +``CONFIG_TEST_KASAN_USER`` built as a loadable module and +``CONFIG_KASAN`` built-in. The type of error expected and the +function being run is printed before the expression expected to give +an error. Then the error is printed, if found, and that test +should be interpretted to pass only if the error was the one expected
+by the test.
2.26.0.rc2.310.g2932bb562d-goog