1.. SPDX-License-Identifier: GPL-2.0 2 3================== 4KUnit Architecture 5================== 6 7The KUnit architecture is divided into two parts: 8 9- `In-Kernel Testing Framework`_ 10- `kunit_tool (Command-line Test Harness)`_ 11 12In-Kernel Testing Framework 13=========================== 14 15The kernel testing library supports KUnit tests written in C using 16KUnit. These KUnit tests are kernel code. KUnit performs the following 17tasks: 18 19- Organizes tests 20- Reports test results 21- Provides test utilities 22 23Test Cases 24---------- 25 26The test case is the fundamental unit in KUnit. KUnit test cases are organised 27into suites. A KUnit test case is a function with type signature 28``void (*)(struct kunit *test)``. These test case functions are wrapped in a 29struct called struct kunit_case. 30 31.. note: 32 ``generate_params`` is optional for non-parameterized tests. 33 34Each KUnit test case receives a ``struct kunit`` context object that tracks a 35running 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 44Test Suites 45----------- 46 47A KUnit suite includes a collection of test cases. The KUnit suites 48are 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 67In the above example, the test suite ``example_test_suite``, runs the 68test cases ``example_test_foo``, ``example_test_bar``, and 69``example_test_baz``. Before running the test, the ``example_test_init`` 70is called and after running the test, ``example_test_exit`` is called. 71The ``kunit_test_suite(example_test_suite)`` registers the test suite 72with the KUnit test framework. 73 74Executor 75-------- 76 77The KUnit executor can list and run built-in KUnit tests on boot. 78The Test suites are stored in a linker section 79called ``.kunit_test_suites``. For the code, see ``KUNIT_TABLE()`` macro 80definition 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>`_. 82The linker section consists of an array of pointers to 83``struct kunit_suite``, and is populated by the ``kunit_test_suites()`` 84macro. The KUnit executor iterates over the linker section array in order to 85run 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 92On the kernel boot, the KUnit executor uses the start and end addresses 93of this section to iterate over and run all tests. For the implementation of the 94executor, see 95`lib/kunit/executor.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/lib/kunit/executor.c>`_. 96When built as a module, the ``kunit_test_suites()`` macro defines a 97``module_init()`` function, which runs all the tests in the compilation 98unit instead of utilizing the executor. 99 100In KUnit tests, some error classes do not affect other tests 101or parts of the kernel, each KUnit case executes in a separate thread 102context. 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 105Assertion Macros 106---------------- 107 108KUnit tests verify state using expectations/assertions. 109All 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 138Test Result Reporting 139--------------------- 140KUnit prints the test results in KTAP format. KTAP is based on TAP14, see 141Documentation/dev-tools/ktap.rst. 142KTAP works with KUnit and Kselftest. The KUnit executor prints KTAP results to 143dmesg, and debugfs (if configured). 144 145Parameterized Tests 146------------------- 147 148Each KUnit parameterized test is associated with a collection of 149parameters. The test is invoked multiple times, once for each parameter 150value and the parameter is stored in the ``param_value`` field. 151The test case includes a KUNIT_CASE_PARAM() macro that accepts a 152generator function. The generator function is passed the previous parameter 153and returns the next parameter. It also includes a macro for generating 154array-based common-case generators. 155 156kunit_tool (Command-line Test Harness) 157====================================== 158 159``kunit_tool`` is a Python script, found in ``tools/testing/kunit/kunit.py``. It 160is used to configure, build, execute, parse test results and run all of the 161previous commands in correct order (i.e., configure, build, execute and parse). 162You have two options for running KUnit tests: either build the kernel with KUnit 163enabled and manually parse the results (see 164Documentation/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. 197
