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