Skip to content

Commit 46201d4

Browse files
Harinder SinghJonathan Corbet
Harinder Singh
authored and
Jonathan Corbet
committed
Documentation: kunit: Reorganize documentation related to running tests
Consolidate documentation running tests into two pages: "run tests with kunit_tool" and "run tests without kunit_tool". Signed-off-by: Harinder Singh <[email protected]> Reviewed-by: Tim Bird <[email protected]> Reviewed-by: Brendan Higgins <[email protected]> Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Jonathan Corbet <[email protected]>
1 parent bc145b3 commit 46201d4

File tree

4 files changed

+311
-1
lines changed

4 files changed

+311
-1
lines changed

‎Documentation/dev-tools/kunit/index.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ KUnit - Linux Kernel Unit Testing
1010

1111
start
1212
architecture
13+
run_wrapper
14+
run_manual
1315
usage
1416
kunit-tool
1517
api/index
@@ -98,6 +100,8 @@ How do I use it?
98100

99101
* Documentation/dev-tools/kunit/start.rst - for KUnit new users.
100102
* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
103+
* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
104+
* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
101105
* Documentation/dev-tools/kunit/usage.rst - KUnit features.
102106
* Documentation/dev-tools/kunit/tips.rst - best practices with
103107
examples.

‎Documentation/dev-tools/kunit/run_manual.rst

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
============================
4+
Run Tests without kunit_tool
5+
============================
6+
7+
If we do not want to use kunit_tool (For example: we want to integrate
8+
with other systems, or run tests on real hardware), we can
9+
include KUnit in any kernel, read out results, and parse manually.
10+
11+
.. note:: KUnit is not designed for use in a production system. It is
12+
possible that tests may reduce the stability or security of
13+
the system.
14+
15+
Configure the Kernel
16+
====================
17+
18+
KUnit tests can run without kunit_tool. This can be useful, if:
19+
20+
- We have an existing kernel configuration to test.
21+
- Need to run on real hardware (or using an emulator/VM kunit_tool
22+
does not support).
23+
- Wish to integrate with some existing testing systems.
24+
25+
KUnit is configured with the ``CONFIG_KUNIT`` option, and individual
26+
tests can also be built by enabling their config options in our
27+
``.config``. KUnit tests usually (but don't always) have config options
28+
ending in ``_KUNIT_TEST``. Most tests can either be built as a module,
29+
or be built into the kernel.
30+
31+
.. note ::
32+
33+
We can enable the ``KUNIT_ALL_TESTS`` config option to
34+
automatically enable all tests with satisfied dependencies. This is
35+
a good way of quickly testing everything applicable to the current
36+
config.
37+
38+
Once we have built our kernel (and/or modules), it is simple to run
39+
the tests. If the tests are built-in, they will run automatically on the
40+
kernel boot. The results will be written to the kernel log (``dmesg``)
41+
in TAP format.
42+
43+
If the tests are built as modules, they will run when the module is
44+
loaded.
45+
46+
.. code-block :: bash
47+
48+
# modprobe example-test
49+
50+
The results will appear in TAP format in ``dmesg``.
51+
52+
.. note ::
53+
54+
If ``CONFIG_KUNIT_DEBUGFS`` is enabled, KUnit test results will
55+
be accessible from the ``debugfs`` filesystem (if mounted).
56+
They will be in ``/sys/kernel/debug/kunit/<test_suite>/results``, in
57+
TAP format.

‎Documentation/dev-tools/kunit/run_wrapper.rst

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
=========================
4+
Run Tests with kunit_tool
5+
=========================
6+
7+
We can either run KUnit tests using kunit_tool or can run tests
8+
manually, and then use kunit_tool to parse the results. To run tests
9+
manually, see: Documentation/dev-tools/kunit/run_manual.rst.
10+
As long as we can build the kernel, we can run KUnit.
11+
12+
kunit_tool is a Python script which configures and builds a kernel, runs
13+
tests, and formats the test results.
14+
15+
Run command:
16+
17+
.. code-block::
18+
19+
./tools/testing/kunit/kunit.py run
20+
21+
We should see the following:
22+
23+
.. code-block::
24+
25+
Generating .config...
26+
Building KUnit kernel...
27+
Starting KUnit kernel...
28+
29+
We may want to use the following options:
30+
31+
.. code-block::
32+
33+
./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all
34+
35+
- ``--timeout`` sets a maximum amount of time for tests to run.
36+
- ``--jobs`` sets the number of threads to build the kernel.
37+
38+
kunit_tool will generate a ``.kunitconfig`` with a default
39+
configuration, if no other ``.kunitconfig`` file exists
40+
(in the build directory). In addition, it verifies that the
41+
generated ``.config`` file contains the ``CONFIG`` options in the
42+
``.kunitconfig``.
43+
It is also possible to pass a separate ``.kunitconfig`` fragment to
44+
kunit_tool. This is useful if we have several different groups of
45+
tests we want to run independently, or if we want to use pre-defined
46+
test configs for certain subsystems.
47+
48+
To use a different ``.kunitconfig`` file (such as one
49+
provided to test a particular subsystem), pass it as an option:
50+
51+
.. code-block::
52+
53+
./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig
54+
55+
To view kunit_tool flags (optional command-line arguments), run:
56+
57+
.. code-block::
58+
59+
./tools/testing/kunit/kunit.py run --help
60+
61+
Create a ``.kunitconfig`` File
62+
===============================
63+
64+
If we want to run a specific set of tests (rather than those listed
65+
in the KUnit ``defconfig``), we can provide Kconfig options in the
66+
``.kunitconfig`` file. For default .kunitconfig, see:
67+
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config.
68+
A ``.kunitconfig`` is a ``minconfig`` (a .config
69+
generated by running ``make savedefconfig``), used for running a
70+
specific set of tests. This file contains the regular Kernel configs
71+
with specific test targets. The ``.kunitconfig`` also
72+
contains any other config options required by the tests (For example:
73+
dependencies for features under tests, configs that enable/disable
74+
certain code blocks, arch configs and so on).
75+
76+
To create a ``.kunitconfig``, using the KUnit ``defconfig``:
77+
78+
.. code-block::
79+
80+
cd $PATH_TO_LINUX_REPO
81+
cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig
82+
83+
We can then add any other Kconfig options. For example:
84+
85+
.. code-block::
86+
87+
CONFIG_LIST_KUNIT_TEST=y
88+
89+
kunit_tool ensures that all config options in ``.kunitconfig`` are
90+
set in the kernel ``.config`` before running the tests. It warns if we
91+
have not included the options dependencies.
92+
93+
.. note:: Removing something from the ``.kunitconfig`` will
94+
not rebuild the ``.config file``. The configuration is only
95+
updated if the ``.kunitconfig`` is not a subset of ``.config``.
96+
This means that we can use other tools
97+
(For example: ``make menuconfig``) to adjust other config options.
98+
The build dir needs to be set for ``make menuconfig`` to
99+
work, therefore by default use ``make O=.kunit menuconfig``.
100+
101+
Configure, Build, and Run Tests
102+
===============================
103+
104+
If we want to make manual changes to the KUnit build process, we
105+
can run part of the KUnit build process independently.
106+
When running kunit_tool, from a ``.kunitconfig``, we can generate a
107+
``.config`` by using the ``config`` argument:
108+
109+
.. code-block::
110+
111+
./tools/testing/kunit/kunit.py config
112+
113+
To build a KUnit kernel from the current ``.config``, we can use the
114+
``build`` argument:
115+
116+
.. code-block::
117+
118+
./tools/testing/kunit/kunit.py build
119+
120+
If we already have built UML kernel with built-in KUnit tests, we
121+
can run the kernel, and display the test results with the ``exec``
122+
argument:
123+
124+
.. code-block::
125+
126+
./tools/testing/kunit/kunit.py exec
127+
128+
The ``run`` command discussed in section: **Run Tests with kunit_tool**,
129+
is equivalent to running the above three commands in sequence.
130+
131+
Parse Test Results
132+
==================
133+
134+
KUnit tests output displays results in TAP (Test Anything Protocol)
135+
format. When running tests, kunit_tool parses this output and prints
136+
a summary. To see the raw test results in TAP format, we can pass the
137+
``--raw_output`` argument:
138+
139+
.. code-block::
140+
141+
./tools/testing/kunit/kunit.py run --raw_output
142+
143+
If we have KUnit results in the raw TAP format, we can parse them and
144+
print the human-readable summary with the ``parse`` command for
145+
kunit_tool. This accepts a filename for an argument, or will read from
146+
standard input.
147+
148+
.. code-block:: bash
149+
150+
# Reading from a file
151+
./tools/testing/kunit/kunit.py parse /var/log/dmesg
152+
# Reading from stdin
153+
dmesg | ./tools/testing/kunit/kunit.py parse
154+
155+
Run Selected Test Suites
156+
========================
157+
158+
By passing a bash style glob filter to the ``exec`` or ``run``
159+
commands, we can run a subset of the tests built into a kernel . For
160+
example: if we only want to run KUnit resource tests, use:
161+
162+
.. code-block::
163+
164+
./tools/testing/kunit/kunit.py run 'kunit-resource*'
165+
166+
This uses the standard glob format with wildcard characters.
167+
168+
Run Tests on qemu
169+
=================
170+
171+
kunit_tool supports running tests on qemu as well as
172+
via UML. To run tests on qemu, by default it requires two flags:
173+
174+
- ``--arch``: Selects a configs collection (Kconfig, qemu config options
175+
and so on), that allow KUnit tests to be run on the specified
176+
architecture in a minimal way. The architecture argument is same as
177+
the option name passed to the ``ARCH`` variable used by Kbuild.
178+
Not all architectures currently support this flag, but we can use
179+
``--qemu_config`` to handle it. If ``um`` is passed (or this flag
180+
is ignored), the tests will run via UML. Non-UML architectures,
181+
for example: i386, x86_64, arm and so on; run on qemu.
182+
183+
- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the
184+
same argument as passed to the ``CROSS_COMPILE`` variable used by
185+
Kbuild. As a reminder, this will be the prefix for the toolchain
186+
binaries such as GCC. For example:
187+
188+
- ``sparc64-linux-gnu`` if we have the sparc toolchain installed on
189+
our system.
190+
191+
- ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux``
192+
if we have downloaded the microblaze toolchain from the 0-day
193+
website to a directory in our home directory called toolchains.
194+
195+
If we want to run KUnit tests on an architecture not supported by
196+
the ``--arch`` flag, or want to run KUnit tests on qemu using a
197+
non-default configuration; then we can write our own``QemuConfig``.
198+
These ``QemuConfigs`` are written in Python. They have an import line
199+
``from..qemu_config import QemuArchParams`` at the top of the file.
200+
The file must contain a variable called ``QEMU_ARCH`` that has an
201+
instance of ``QemuArchParams`` assigned to it. See example in:
202+
``tools/testing/kunit/qemu_configs/x86_64.py``.
203+
204+
Once we have a ``QemuConfig``, we can pass it into kunit_tool,
205+
using the ``--qemu_config`` flag. When used, this flag replaces the
206+
``--arch`` flag. For example: using
207+
``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear
208+
as
209+
210+
.. code-block:: bash
211+
212+
./tools/testing/kunit/kunit.py run \
213+
--timeout=60 \
214+
--jobs=12 \
215+
--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
216+
217+
To run existing KUnit tests on non-UML architectures, see:
218+
Documentation/dev-tools/kunit/non_uml.rst.
219+
220+
Command-Line Arguments
221+
======================
222+
223+
kunit_tool has a number of other command-line arguments which can
224+
be useful for our test environment. Below the most commonly used
225+
command line arguments:
226+
227+
- ``--help``: Lists all available options. To list common options,
228+
place ``--help`` before the command. To list options specific to that
229+
command, place ``--help`` after the command.
230+
231+
.. note:: Different commands (``config``, ``build``, ``run``, etc)
232+
have different supported options.
233+
- ``--build_dir``: Specifies kunit_tool build directory. It includes
234+
the ``.kunitconfig``, ``.config`` files and compiled kernel.
235+
236+
- ``--make_options``: Specifies additional options to pass to make, when
237+
compiling a kernel (using ``build`` or ``run`` commands). For example:
238+
to enable compiler warnings, we can pass ``--make_options W=1``.
239+
240+
- ``--alltests``: Builds a UML kernel with all config options enabled
241+
using ``make allyesconfig``. This allows us to run as many tests as
242+
possible.
243+
244+
.. note:: It is slow and prone to breakage as new options are
245+
added or modified. Instead, enable all tests
246+
which have satisfied dependencies by adding
247+
``CONFIG_KUNIT_ALL_TESTS=y`` to your ``.kunitconfig``.

‎Documentation/dev-tools/kunit/start.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ can run kunit_tool:
2020
./tools/testing/kunit/kunit.py run
2121
2222
For more information on this wrapper, see:
23-
Documentation/dev-tools/kunit/kunit-tool.rst.
23+
Documentation/dev-tools/kunit/run_wrapper.rst.
2424

2525
Creating a ``.kunitconfig``
2626
---------------------------
@@ -241,6 +241,8 @@ Next Steps
241241
==========
242242

243243
* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
244+
* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
245+
* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
244246
* Documentation/dev-tools/kunit/usage.rst - KUnit features.
245247
* Documentation/dev-tools/kunit/tips.rst - best practices with
246248
examples.

0 commit comments

Comments
 (0)