1.. SPDX-License-Identifier: GPL-2.0 2 3========================= 4Run Tests with kunit_tool 5========================= 6 7We can either run KUnit tests using kunit_tool or can run tests 8manually, and then use kunit_tool to parse the results. To run tests 9manually, see: Documentation/dev-tools/kunit/run_manual.rst. 10As long as we can build the kernel, we can run KUnit. 11 12kunit_tool is a Python script which configures and builds a kernel, runs 13tests, and formats the test results. 14 15Run command: 16 17.. code-block:: 18 19 ./tools/testing/kunit/kunit.py run 20 21We should see the following: 22 23.. code-block:: 24 25 Generating .config... 26 Building KUnit kernel... 27 Starting KUnit kernel... 28 29We 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 38kunit_tool will generate a ``.kunitconfig`` with a default 39configuration, if no other ``.kunitconfig`` file exists 40(in the build directory). In addition, it verifies that the 41generated ``.config`` file contains the ``CONFIG`` options in the 42``.kunitconfig``. 43It is also possible to pass a separate ``.kunitconfig`` fragment to 44kunit_tool. This is useful if we have several different groups of 45tests we want to run independently, or if we want to use pre-defined 46test configs for certain subsystems. 47 48To use a different ``.kunitconfig`` file (such as one 49provided 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 55To view kunit_tool flags (optional command-line arguments), run: 56 57.. code-block:: 58 59 ./tools/testing/kunit/kunit.py run --help 60 61Create a ``.kunitconfig`` File 62=============================== 63 64If we want to run a specific set of tests (rather than those listed 65in the KUnit ``defconfig``), we can provide Kconfig options in the 66``.kunitconfig`` file. For default .kunitconfig, see: 67https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config. 68A ``.kunitconfig`` is a ``minconfig`` (a .config 69generated by running ``make savedefconfig``), used for running a 70specific set of tests. This file contains the regular Kernel configs 71with specific test targets. The ``.kunitconfig`` also 72contains any other config options required by the tests (For example: 73dependencies for features under tests, configs that enable/disable 74certain code blocks, arch configs and so on). 75 76To 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 83We can then add any other Kconfig options. For example: 84 85.. code-block:: 86 87 CONFIG_LIST_KUNIT_TEST=y 88 89kunit_tool ensures that all config options in ``.kunitconfig`` are 90set in the kernel ``.config`` before running the tests. It warns if we 91have 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 101Configure, Build, and Run Tests 102=============================== 103 104If we want to make manual changes to the KUnit build process, we 105can run part of the KUnit build process independently. 106When 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 113To 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 120If we already have built UML kernel with built-in KUnit tests, we 121can run the kernel, and display the test results with the ``exec`` 122argument: 123 124.. code-block:: 125 126 ./tools/testing/kunit/kunit.py exec 127 128The ``run`` command discussed in section: **Run Tests with kunit_tool**, 129is equivalent to running the above three commands in sequence. 130 131Parse Test Results 132================== 133 134KUnit tests output displays results in TAP (Test Anything Protocol) 135format. When running tests, kunit_tool parses this output and prints 136a 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 143If we have KUnit results in the raw TAP format, we can parse them and 144print the human-readable summary with the ``parse`` command for 145kunit_tool. This accepts a filename for an argument, or will read from 146standard 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 155Run Selected Test Suites 156======================== 157 158By passing a bash style glob filter to the ``exec`` or ``run`` 159commands, we can run a subset of the tests built into a kernel . For 160example: 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 166This uses the standard glob format with wildcard characters. 167 168Run Tests on qemu 169================= 170 171kunit_tool supports running tests on qemu as well as 172via 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 195This means that for most architectures, running under qemu is as simple as: 196 197.. code-block:: bash 198 199 ./tools/testing/kunit/kunit.py run --arch=x86_64 200 201When cross-compiling, we'll likely need to specify a different toolchain, for 202example: 203 204.. code-block:: bash 205 206 ./tools/testing/kunit/kunit.py run \ 207 --arch=s390 \ 208 --cross_compile=s390x-linux-gnu- 209 210If we want to run KUnit tests on an architecture not supported by 211the ``--arch`` flag, or want to run KUnit tests on qemu using a 212non-default configuration; then we can write our own``QemuConfig``. 213These ``QemuConfigs`` are written in Python. They have an import line 214``from..qemu_config import QemuArchParams`` at the top of the file. 215The file must contain a variable called ``QEMU_ARCH`` that has an 216instance of ``QemuArchParams`` assigned to it. See example in: 217``tools/testing/kunit/qemu_configs/x86_64.py``. 218 219Once we have a ``QemuConfig``, we can pass it into kunit_tool, 220using the ``--qemu_config`` flag. When used, this flag replaces the 221``--arch`` flag. For example: using 222``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear 223as 224 225.. code-block:: bash 226 227 ./tools/testing/kunit/kunit.py run \ 228 --timeout=60 \ 229 --jobs=12 \ 230 --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py 231 232Command-Line Arguments 233====================== 234 235kunit_tool has a number of other command-line arguments which can 236be useful for our test environment. Below are the most commonly used 237command line arguments: 238 239- ``--help``: Lists all available options. To list common options, 240 place ``--help`` before the command. To list options specific to that 241 command, place ``--help`` after the command. 242 243 .. note:: Different commands (``config``, ``build``, ``run``, etc) 244 have different supported options. 245- ``--build_dir``: Specifies kunit_tool build directory. It includes 246 the ``.kunitconfig``, ``.config`` files and compiled kernel. 247 248- ``--make_options``: Specifies additional options to pass to make, when 249 compiling a kernel (using ``build`` or ``run`` commands). For example: 250 to enable compiler warnings, we can pass ``--make_options W=1``. 251 252- ``--alltests``: Builds a UML kernel with all config options enabled 253 using ``make allyesconfig``. This allows us to run as many tests as 254 possible. 255 256 .. note:: It is slow and prone to breakage as new options are 257 added or modified. Instead, enable all tests 258 which have satisfied dependencies by adding 259 ``CONFIG_KUNIT_ALL_TESTS=y`` to your ``.kunitconfig``. 260 261- ``--kunitconfig``: Specifies the path or the directory of the ``.kunitconfig`` 262 file. For example: 263 264 - ``lib/kunit/.kunitconfig`` can be the path of the file. 265 266 - ``lib/kunit`` can be the directory in which the file is located. 267 268 This file is used to build and run with a predefined set of tests 269 and their dependencies. For example, to run tests for a given subsystem. 270 271- ``--kconfig_add``: Specifies additional configuration options to be 272 appended to the ``.kunitconfig`` file. For example: 273 274 .. code-block:: 275 276 ./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_KASAN=y 277 278- ``--arch``: Runs tests on the specified architecture. The architecture 279 argument is same as the Kbuild ARCH environment variable. 280 For example, i386, x86_64, arm, um, etc. Non-UML architectures run on qemu. 281 Default is `um`. 282 283- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the 284 same argument as passed to the ``CROSS_COMPILE`` variable used by 285 Kbuild. This will be the prefix for the toolchain 286 binaries such as GCC. For example: 287 288 - ``sparc64-linux-gnu-`` if we have the sparc toolchain installed on 289 our system. 290 291 - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux`` 292 if we have downloaded the microblaze toolchain from the 0-day 293 website to a specified path in our home directory called toolchains. 294 295- ``--qemu_config``: Specifies the path to a file containing a 296 custom qemu architecture definition. This should be a python file 297 containing a `QemuArchParams` object. 298 299- ``--qemu_args``: Specifies additional qemu arguments, for example, ``-smp 8``. 300 301- ``--jobs``: Specifies the number of jobs (commands) to run simultaneously. 302 By default, this is set to the number of cores on your system. 303 304- ``--timeout``: Specifies the maximum number of seconds allowed for all tests to run. 305 This does not include the time taken to build the tests. 306 307- ``--kernel_args``: Specifies additional kernel command-line arguments. May be repeated. 308 309- ``--run_isolated``: If set, boots the kernel for each individual suite/test. 310 This is useful for debugging a non-hermetic test, one that 311 might pass/fail based on what ran before it. 312 313- ``--raw_output``: If set, generates unformatted output from kernel. Possible options are: 314 315 - ``all``: To view the full kernel output, use ``--raw_output=all``. 316 317 - ``kunit``: This is the default option and filters to KUnit output. Use ``--raw_output`` or ``--raw_output=kunit``. 318 319- ``--json``: If set, stores the test results in a JSON format and prints to `stdout` or 320 saves to a file if a filename is specified. 321