336 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=============================4Running tests with kunit_tool5=============================6 7We can either run KUnit tests using kunit_tool or can run tests8manually, and then use kunit_tool to parse the results. To run tests9manually, 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, runs13tests, and formats the test results.14 15Run command:16 17.. code-block::18 19 ./tools/testing/kunit/kunit.py run20 21We should see the following:22 23.. code-block::24 25 Configuring KUnit Kernel ...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 default39configuration, if no other ``.kunitconfig`` file exists40(in the build directory). In addition, it verifies that the41generated ``.config`` file contains the ``CONFIG`` options in the42``.kunitconfig``.43It is also possible to pass a separate ``.kunitconfig`` fragment to44kunit_tool. This is useful if we have several different groups of45tests we want to run independently, or if we want to use pre-defined46test configs for certain subsystems.47 48To use a different ``.kunitconfig`` file (such as one49provided 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/.kunitconfig54 55To view kunit_tool flags (optional command-line arguments), run:56 57.. code-block::58 59 ./tools/testing/kunit/kunit.py run --help60 61Creating a ``.kunitconfig`` file62================================63 64If we want to run a specific set of tests (rather than those listed65in the KUnit ``defconfig``), we can provide Kconfig options in the66``.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 .config69generated by running ``make savedefconfig``), used for running a70specific set of tests. This file contains the regular Kernel configs71with specific test targets. The ``.kunitconfig`` also72contains any other config options required by the tests (For example:73dependencies for features under tests, configs that enable/disable74certain 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_REPO81 cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig82 83We can then add any other Kconfig options. For example:84 85.. code-block::86 87 CONFIG_LIST_KUNIT_TEST=y88 89kunit_tool ensures that all config options in ``.kunitconfig`` are90set in the kernel ``.config`` before running the tests. It warns if we91have not included the options dependencies.92 93.. note:: Removing something from the ``.kunitconfig`` will94 not rebuild the ``.config file``. The configuration is only95 updated if the ``.kunitconfig`` is not a subset of ``.config``.96 This means that we can use other tools97 (For example: ``make menuconfig``) to adjust other config options.98 The build dir needs to be set for ``make menuconfig`` to99 work, therefore by default use ``make O=.kunit menuconfig``.100 101Configuring, building, and running tests102========================================103 104If we want to make manual changes to the KUnit build process, we105can run part of the KUnit build process independently.106When running kunit_tool, from a ``.kunitconfig``, we can generate a107``.config`` by using the ``config`` argument:108 109.. code-block::110 111 ./tools/testing/kunit/kunit.py config112 113To build a KUnit kernel from the current ``.config``, we can use the114``build`` argument:115 116.. code-block::117 118 ./tools/testing/kunit/kunit.py build119 120If we already have built UML kernel with built-in KUnit tests, we121can run the kernel, and display the test results with the ``exec``122argument:123 124.. code-block::125 126 ./tools/testing/kunit/kunit.py exec127 128The ``run`` command discussed in section: **Running tests with kunit_tool**,129is equivalent to running the above three commands in sequence.130 131Parsing test results132====================133 134KUnit tests output displays results in TAP (Test Anything Protocol)135format. When running tests, kunit_tool parses this output and prints136a summary. To see the raw test results in TAP format, we can pass the137``--raw_output`` argument:138 139.. code-block::140 141 ./tools/testing/kunit/kunit.py run --raw_output142 143If we have KUnit results in the raw TAP format, we can parse them and144print the human-readable summary with the ``parse`` command for145kunit_tool. This accepts a filename for an argument, or will read from146standard input.147 148.. code-block:: bash149 150 # Reading from a file151 ./tools/testing/kunit/kunit.py parse /var/log/dmesg152 # Reading from stdin153 dmesg | ./tools/testing/kunit/kunit.py parse154 155Filtering tests156===============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 . For160example: 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 168.. _kunit-on-qemu:169 170Running tests on QEMU171=====================172 173kunit_tool supports running tests on qemu as well as174via UML. To run tests on qemu, by default it requires two flags:175 176- ``--arch``: Selects a configs collection (Kconfig, qemu config options177 and so on), that allow KUnit tests to be run on the specified178 architecture in a minimal way. The architecture argument is same as179 the option name passed to the ``ARCH`` variable used by Kbuild.180 Not all architectures currently support this flag, but we can use181 ``--qemu_config`` to handle it. If ``um`` is passed (or this flag182 is ignored), the tests will run via UML. Non-UML architectures,183 for example: i386, x86_64, arm and so on; run on qemu.184 185- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the186 same argument as passed to the ``CROSS_COMPILE`` variable used by187 Kbuild. As a reminder, this will be the prefix for the toolchain188 binaries such as GCC. For example:189 190 - ``sparc64-linux-gnu`` if we have the sparc toolchain installed on191 our system.192 193 - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux``194 if we have downloaded the microblaze toolchain from the 0-day195 website to a directory in our home directory called toolchains.196 197This means that for most architectures, running under qemu is as simple as:198 199.. code-block:: bash200 201 ./tools/testing/kunit/kunit.py run --arch=x86_64202 203When cross-compiling, we'll likely need to specify a different toolchain, for204example:205 206.. code-block:: bash207 208 ./tools/testing/kunit/kunit.py run \209 --arch=s390 \210 --cross_compile=s390x-linux-gnu-211 212If we want to run KUnit tests on an architecture not supported by213the ``--arch`` flag, or want to run KUnit tests on qemu using a214non-default configuration; then we can write our own``QemuConfig``.215These ``QemuConfigs`` are written in Python. They have an import line216``from..qemu_config import QemuArchParams`` at the top of the file.217The file must contain a variable called ``QEMU_ARCH`` that has an218instance of ``QemuArchParams`` assigned to it. See example in:219``tools/testing/kunit/qemu_configs/x86_64.py``.220 221Once we have a ``QemuConfig``, we can pass it into kunit_tool,222using the ``--qemu_config`` flag. When used, this flag replaces the223``--arch`` flag. For example: using224``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear225as226 227.. code-block:: bash228 229 ./tools/testing/kunit/kunit.py run \230 --timeout=60 \231 --jobs=12 \232 --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py233 234Running command-line arguments235==============================236 237kunit_tool has a number of other command-line arguments which can238be useful for our test environment. Below are the most commonly used239command line arguments:240 241- ``--help``: Lists all available options. To list common options,242 place ``--help`` before the command. To list options specific to that243 command, place ``--help`` after the command.244 245 .. note:: Different commands (``config``, ``build``, ``run``, etc)246 have different supported options.247- ``--build_dir``: Specifies kunit_tool build directory. It includes248 the ``.kunitconfig``, ``.config`` files and compiled kernel.249 250- ``--make_options``: Specifies additional options to pass to make, when251 compiling a kernel (using ``build`` or ``run`` commands). For example:252 to enable compiler warnings, we can pass ``--make_options W=1``.253 254- ``--alltests``: Enable a predefined set of options in order to build255 as many tests as possible.256 257 .. note:: The list of enabled options can be found in258 ``tools/testing/kunit/configs/all_tests.config``.259 260 If you only want to enable all tests with otherwise satisfied261 dependencies, instead add ``CONFIG_KUNIT_ALL_TESTS=y`` to your262 ``.kunitconfig``.263 264- ``--kunitconfig``: Specifies the path or the directory of the ``.kunitconfig``265 file. For example:266 267 - ``lib/kunit/.kunitconfig`` can be the path of the file.268 269 - ``lib/kunit`` can be the directory in which the file is located.270 271 This file is used to build and run with a predefined set of tests272 and their dependencies. For example, to run tests for a given subsystem.273 274- ``--kconfig_add``: Specifies additional configuration options to be275 appended to the ``.kunitconfig`` file. For example:276 277 .. code-block::278 279 ./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_KASAN=y280 281- ``--arch``: Runs tests on the specified architecture. The architecture282 argument is same as the Kbuild ARCH environment variable.283 For example, i386, x86_64, arm, um, etc. Non-UML architectures run on qemu.284 Default is `um`.285 286- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the287 same argument as passed to the ``CROSS_COMPILE`` variable used by288 Kbuild. This will be the prefix for the toolchain289 binaries such as GCC. For example:290 291 - ``sparc64-linux-gnu-`` if we have the sparc toolchain installed on292 our system.293 294 - ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux``295 if we have downloaded the microblaze toolchain from the 0-day296 website to a specified path in our home directory called toolchains.297 298- ``--qemu_config``: Specifies the path to a file containing a299 custom qemu architecture definition. This should be a python file300 containing a `QemuArchParams` object.301 302- ``--qemu_args``: Specifies additional qemu arguments, for example, ``-smp 8``.303 304- ``--jobs``: Specifies the number of jobs (commands) to run simultaneously.305 By default, this is set to the number of cores on your system.306 307- ``--timeout``: Specifies the maximum number of seconds allowed for all tests to run.308 This does not include the time taken to build the tests.309 310- ``--kernel_args``: Specifies additional kernel command-line arguments. May be repeated.311 312- ``--run_isolated``: If set, boots the kernel for each individual suite/test.313 This is useful for debugging a non-hermetic test, one that314 might pass/fail based on what ran before it.315 316- ``--raw_output``: If set, generates unformatted output from kernel. Possible options are:317 318 - ``all``: To view the full kernel output, use ``--raw_output=all``.319 320 - ``kunit``: This is the default option and filters to KUnit output. Use ``--raw_output`` or ``--raw_output=kunit``.321 322- ``--json``: If set, stores the test results in a JSON format and prints to `stdout` or323 saves to a file if a filename is specified.324 325- ``--filter``: Specifies filters on test attributes, for example, ``speed!=slow``.326 Multiple filters can be used by wrapping input in quotes and separating filters327 by commas. Example: ``--filter "speed>slow, module=example"``.328 329- ``--filter_action``: If set to ``skip``, filtered tests will be shown as skipped330 in the output rather than showing no output.331 332- ``--list_tests``: If set, lists all tests that will be run.333 334- ``--list_tests_attr``: If set, lists all tests that will be run and all of their335 attributes.336