Merge tag 'for-5.17-rc2-tag' of git://git.kernel.org/pub/scm/linux/kernel/git/kdave...
[linux-2.6-microblaze.git] / Documentation / dev-tools / kunit / run_wrapper.rst
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``.