Documentation/dev-tools/kunit/architecture.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==================
   4 KUnit Architecture
   5 ==================
   6
   7 The KUnit architecture is divided into two parts:
   8
   9 - `In-Kernel Testing Framework`_
  10 - `kunit_tool (Command-line Test Harness)`_
  11
  12 In-Kernel Testing Framework
  13 ===========================
  14
  15 The kernel testing library supports KUnit tests written in C using
  16 KUnit. These KUnit tests are kernel code. KUnit performs the following
  17 tasks:
  18
  19 - Organizes tests
  20 - Reports test results
  21 - Provides test utilities
  22
  23 Test Cases
  24 ----------
  25
  26 The test case is the fundamental unit in KUnit. KUnit test cases are organised
  27 into suites. A KUnit test case is a function with type signature
  28 ``void (*)(struct kunit *test)``. These test case functions are wrapped in a
  29 struct called struct kunit_case.
  30
  31 .. note:
  32         ``generate_params`` is optional for non-parameterized tests.
  33
  34 Each KUnit test case receives a ``struct kunit`` context object that tracks a
  35 running test. The KUnit assertion macros and other KUnit utilities use the
  36 ``struct kunit`` context object. As an exception, there are two fields:
  37
  38 - ``->priv``: The setup functions can use it to store arbitrary test
  39   user data.
  40
  41 - ``->param_value``: It contains the parameter value which can be
  42   retrieved in the parameterized tests.
  43
  44 Test Suites
  45 -----------
  46
  47 A KUnit suite includes a collection of test cases. The KUnit suites
  48 are represented by the ``struct kunit_suite``. For example:
  49
  50 .. code-block:: c
  51
  52         static struct kunit_case example_test_cases[] = {
  53                 KUNIT_CASE(example_test_foo),
  54                 KUNIT_CASE(example_test_bar),
  55                 KUNIT_CASE(example_test_baz),
  56                 {}
  57         };
  58
  59         static struct kunit_suite example_test_suite = {
  60                 .name = "example",
  61                 .init = example_test_init,
  62                 .exit = example_test_exit,
  63                 .test_cases = example_test_cases,
  64         };
  65         kunit_test_suite(example_test_suite);
  66
  67 In the above example, the test suite ``example_test_suite``, runs the
  68 test cases ``example_test_foo``, ``example_test_bar``, and
  69 ``example_test_baz``. Before running the test, the ``example_test_init``
  70 is called and after running the test, ``example_test_exit`` is called.
  71 The ``kunit_test_suite(example_test_suite)`` registers the test suite
  72 with the KUnit test framework.
  73
  74 Executor
  75 --------
  76
  77 The KUnit executor can list and run built-in KUnit tests on boot.
  78 The Test suites are stored in a linker section
  79 called ``.kunit_test_suites``. For the code, see ``KUNIT_TABLE()`` macro
  80 definition in
  81 `include/asm-generic/vmlinux.lds.h <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/asm-generic/vmlinux.lds.h?h=v6.0#n950>`_.
  82 The linker section consists of an array of pointers to
  83 ``struct kunit_suite``, and is populated by the ``kunit_test_suites()``
  84 macro. The KUnit executor iterates over the linker section array in order to
  85 run all the tests that are compiled into the kernel.
  86
  87 .. kernel-figure:: kunit_suitememorydiagram.svg
  88         :alt:   KUnit Suite Memory
  89
  90         KUnit Suite Memory Diagram
  91
  92 On the kernel boot, the KUnit executor uses the start and end addresses
  93 of this section to iterate over and run all tests. For the implementation of the
  94 executor, see
  95 `lib/kunit/executor.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c>`_.
  96 When built as a module, the ``kunit_test_suites()`` macro defines a
  97 ``module_init()`` function, which runs all the tests in the compilation
  98 unit instead of utilizing the executor.
  99
 100 In KUnit tests, some error classes do not affect other tests
 101 or parts of the kernel, each KUnit case executes in a separate thread
 102 context. See the ``kunit_try_catch_run()`` function in
 103 `lib/kunit/try-catch.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/try-catch.c?h=v5.15#n58>`_.
 104
 105 Assertion Macros
 106 ----------------
 107
 108 KUnit tests verify state using expectations/assertions.
 109 All expectations/assertions are formatted as:
 110 ``KUNIT_{EXPECT|ASSERT}_<op>[_MSG](kunit, property[, message])``
 111
 112 - ``{EXPECT|ASSERT}`` determines whether the check is an assertion or an
 113   expectation.
 114   In the event of a failure, the testing flow differs as follows:
 115
 116         - For expectations, the test is marked as failed and the failure is logged.
 117
 118         - Failing assertions, on the other hand, result in the test case being
 119           terminated immediately.
 120
 121                 - Assertions call the function:
 122                   ``void __noreturn __kunit_abort(struct kunit *)``.
 123
 124                 - ``__kunit_abort`` calls the function:
 125                   ``void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch)``.
 126
 127                 - ``kunit_try_catch_throw`` calls the function:
 128                   ``void kthread_complete_and_exit(struct completion *, long) __noreturn;``
 129                   and terminates the special thread context.
 130
 131 - ``<op>`` denotes a check with options: ``TRUE`` (supplied property
 132   has the boolean value "true"), ``EQ`` (two supplied properties are
 133   equal), ``NOT_ERR_OR_NULL`` (supplied pointer is not null and does not
 134   contain an "err" value).
 135
 136 - ``[_MSG]`` prints a custom message on failure.
 137
 138 Test Result Reporting
 139 ---------------------
 140 KUnit prints the test results in KTAP format. KTAP is based on TAP14, see
 141 Documentation/dev-tools/ktap.rst.
 142 KTAP works with KUnit and Kselftest. The KUnit executor prints KTAP results to
 143 dmesg, and debugfs (if configured).
 144
 145 Parameterized Tests
 146 -------------------
 147
 148 Each KUnit parameterized test is associated with a collection of
 149 parameters. The test is invoked multiple times, once for each parameter
 150 value and the parameter is stored in the ``param_value`` field.
 151 The test case includes a KUNIT_CASE_PARAM() macro that accepts a
 152 generator function. The generator function is passed the previous parameter
 153 and returns the next parameter. It also includes a macro for generating
 154 array-based common-case generators.
 155
 156 kunit_tool (Command-line Test Harness)
 157 ======================================
 158
 159 ``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It
 160 is used to configure, build, execute, parse test results and run all of the
 161 previous commands in correct order (i.e., configure, build, execute and parse).
 162 You have two options for running KUnit tests: either build the kernel with KUnit
 163 enabled and manually parse the results (see
 164 Documentation/dev-tools/kunit/run_manual.rst) or use ``kunit_tool``
 165 (see Documentation/dev-tools/kunit/run_wrapper.rst).
 166
 167 - ``configure`` command generates the kernel ``.config`` from a
 168   ``.kunitconfig`` file (and any architecture-specific options).
 169   The Python scripts available in ``qemu_configs`` folder
 170   (for example, ``tools/testing/kunit/qemu configs/powerpc.py``) contains
 171   additional configuration options for specific architectures.
 172   It parses both the existing ``.config`` and the ``.kunitconfig`` files
 173   to ensure that ``.config`` is a superset of ``.kunitconfig``.
 174   If not, it will combine the two and run ``make olddefconfig`` to regenerate
 175   the ``.config`` file. It then checks to see if ``.config`` has become a superset.
 176   This verifies that all the Kconfig dependencies are correctly specified in the
 177   file ``.kunitconfig``. The ``kunit_config.py`` script contains the code for parsing
 178   Kconfigs. The code which runs ``make olddefconfig`` is part of the
 179   ``kunit_kernel.py`` script. You can invoke this command through:
 180   ``./tools/testing/kunit/kunit.py config`` and
 181   generate a ``.config`` file.
 182 - ``build`` runs ``make`` on the kernel tree with required options
 183   (depends on the architecture and some options, for example: build_dir)
 184   and reports any errors.
 185   To build a KUnit kernel from the current ``.config``, you can use the
 186   ``build`` argument: ``./tools/testing/kunit/kunit.py build``.
 187 - ``exec`` command executes kernel results either directly (using
 188   User-mode Linux configuration), or through an emulator such
 189   as QEMU. It reads results from the log using standard
 190   output (stdout), and passes them to ``parse`` to be parsed.
 191   If you already have built a kernel with built-in KUnit tests,
 192   you can run the kernel and display the test results with the ``exec``
 193   argument: ``./tools/testing/kunit/kunit.py exec``.
 194 - ``parse`` extracts the KTAP output from a kernel log, parses
 195   the test results, and prints a summary. For failed tests, any
 196   diagnostic output will be included.