1 .. SPDX-License-Identifier: GPL-2.0
10 kunit_tool is a script (``tools/testing/kunit/kunit.py``) that aids in building
11 the Linux kernel as UML (`User Mode Linux
12 <http://user-mode-linux.sourceforge.net/>`_), running KUnit tests, parsing
13 the test results and displaying them in a user friendly manner.
15 kunit_tool addresses the problem of being able to run tests without needing a
16 virtual machine or actual hardware with User Mode Linux. User Mode Linux is a
17 Linux architecture, like ARM or x86; however, unlike other architectures it
18 compiles the kernel as a standalone Linux executable that can be run like any
19 other program directly inside of a host operating system. To be clear, it does
20 not require any virtualization support: it is just a regular program.
22 What is a .kunitconfig?
23 =======================
25 It's just a defconfig that kunit_tool looks for in the build directory
26 (``.kunit`` by default). kunit_tool uses it to generate a .config as you might
27 expect. In addition, it verifies that the generated .config contains the CONFIG
28 options in the .kunitconfig; the reason it does this is so that it is easy to
29 be sure that a CONFIG that enables a test actually ends up in the .config.
31 It's also possible to pass a separate .kunitconfig fragment to kunit_tool,
32 which is useful if you have several different groups of tests you wish
33 to run independently, or if you want to use pre-defined test configs for
36 Getting Started with kunit_tool
37 ===============================
39 If a kunitconfig is present at the root directory, all you have to do is:
43 ./tools/testing/kunit/kunit.py run
45 However, you most likely want to use it with the following options:
49 ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all`
51 - ``--timeout`` sets a maximum amount of time to allow tests to run.
52 - ``--jobs`` sets the number of threads to use to build the kernel.
55 This command will work even without a .kunitconfig file: if no
56 .kunitconfig is present, a default one will be used instead.
58 If you wish to use a different .kunitconfig file (such as one provided for
59 testing a particular subsystem), you can pass it as an option.
63 ./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig
65 For a list of all the flags supported by kunit_tool, you can run:
69 ./tools/testing/kunit/kunit.py run --help
71 Configuring, Building, and Running Tests
72 ========================================
74 It's also possible to run just parts of the KUnit build process independently,
75 which is useful if you want to make manual changes to part of the process.
77 A .config can be generated from a .kunitconfig by using the ``config`` argument
78 when running kunit_tool:
82 ./tools/testing/kunit/kunit.py config
84 Similarly, if you just want to build a KUnit kernel from the current .config,
85 you can use the ``build`` argument:
89 ./tools/testing/kunit/kunit.py build
91 And, if you already have a built UML kernel with built-in KUnit tests, you can
92 run the kernel and display the test results with the ``exec`` argument:
96 ./tools/testing/kunit/kunit.py exec
98 The ``run`` command which is discussed above is equivalent to running all three
101 All of these commands accept a number of optional command-line arguments. The
102 ``--help`` flag will give a complete list of these, or keep reading this page
103 for a guide to some of the more useful ones.
108 KUnit tests output their results in TAP (Test Anything Protocol) format.
109 kunit_tool will, when running tests, parse this output and print a summary
110 which is much more pleasant to read. If you wish to look at the raw test
111 results in TAP format, you can pass the ``--raw_output`` argument.
115 ./tools/testing/kunit/kunit.py run --raw_output
118 The raw output from test runs may contain other, non-KUnit kernel log
121 If you have KUnit results in their raw TAP format, you can parse them and print
122 the human-readable summary with the ``parse`` command for kunit_tool. This
123 accepts a filename for an argument, or will read from standard input.
127 # Reading from a file
128 ./tools/testing/kunit/kunit.py parse /var/log/dmesg
130 dmesg | ./tools/testing/kunit/kunit.py parse
132 This is very useful if you wish to run tests in a configuration not supported
133 by kunit_tool (such as on real hardware, or an unsupported architecture).
138 It's possible to run only a subset of the tests built into a kernel by passing
139 a filter to the ``exec`` or ``run`` commands. For example, if you only wanted
140 to run KUnit resource tests, you could use:
144 ./tools/testing/kunit/kunit.py run 'kunit-resource*'
146 This uses the standard glob format for wildcards.
148 Running Tests on QEMU
149 =====================
151 kunit_tool supports running tests on QEMU as well as via UML (as mentioned
152 elsewhere). The default way of running tests on QEMU requires two flags:
155 Selects a collection of configs (Kconfig as well as QEMU configs
156 options, etc) that allow KUnit tests to be run on the specified
157 architecture in a minimal way; this is usually not much slower than
158 using UML. The architecture argument is the same as the name of the
159 option passed to the ``ARCH`` variable used by Kbuild. Not all
160 architectures are currently supported by this flag, but can be handled
161 by the ``--qemu_config`` discussed later. If ``um`` is passed (or this
162 this flag is ignored) the tests will run via UML. Non-UML architectures,
163 e.g. i386, x86_64, arm, um, etc. Non-UML run on QEMU.
166 Specifies the use of a toolchain by Kbuild. The argument passed here is
167 the same passed to the ``CROSS_COMPILE`` variable used by Kbuild. As a
168 reminder this will be the prefix for the toolchain binaries such as gcc
169 for example ``sparc64-linux-gnu-`` if you have the sparc toolchain
170 installed on your system, or
171 ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux-``
172 if you have downloaded the microblaze toolchain from the 0-day website
173 to a directory in your home directory called ``toolchains``.
175 In many cases it is likely that you may want to run an architecture which is
176 not supported by the ``--arch`` flag, or you may want to just run KUnit tests
177 on QEMU using a non-default configuration. For this use case, you can write
178 your own QemuConfig. These QemuConfigs are written in Python. They must have an
179 import line ``from ..qemu_config import QemuArchParams`` at the top of the file
180 and the file must contain a variable called ``QEMU_ARCH`` that has an instance
181 of ``QemuArchParams`` assigned to it. An example can be seen in
182 ``tools/testing/kunit/qemu_configs/x86_64.py``.
184 Once you have a QemuConfig you can pass it into kunit_tool using the
185 ``--qemu_config`` flag; when used this flag replaces the ``--arch`` flag. If we
186 were to do this with the ``x86_64.py`` example from above, the invocation would
187 look something like this:
191 ./tools/testing/kunit/kunit.py run \
194 --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
199 kunit_tool has a number of other command-line arguments which can be useful
200 when adapting it to fit your environment or needs.
202 Some of the more useful ones are:
205 Lists all of the available options. Note that different commands
206 (``config``, ``build``, ``run``, etc) will have different supported
207 options. Place ``--help`` before the command to list common options,
208 and after the command for options specific to that command.
211 Specifies the build directory that kunit_tool will use. This is where
212 the .kunitconfig file is located, as well as where the .config and
213 compiled kernel will be placed. Defaults to ``.kunit``.
216 Specifies additional options to pass to ``make`` when compiling a
217 kernel (with the ``build`` or ``run`` commands). For example, to enable
218 compiler warnings, you can pass ``--make_options W=1``.
221 Builds a UML kernel with all config options enabled using ``make
222 allyesconfig``. This allows you to run as many tests as is possible,
223 but is very slow and prone to breakage as new options are added or
224 modified. In most cases, enabling all tests which have satisfied
225 dependencies by adding ``CONFIG_KUNIT_ALL_TESTS=1`` to your
226 .kunitconfig is preferable.
228 There are several other options (and new ones are often added), so do check
229 ``--help`` if you're looking for something not mentioned here.