Documentation/dev-tools/kunit/kunit-tool.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =================
   4 kunit_tool How-To
   5 =================
   6
   7 What is kunit_tool?
   8 ===================
   9
  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.
  14
  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.
  21
  22 What is a .kunitconfig?
  23 =======================
  24
  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.
  30
  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
  34 certain subsystems.
  35
  36 Getting Started with kunit_tool
  37 ===============================
  38
  39 If a kunitconfig is present at the root directory, all you have to do is:
  40
  41 .. code-block:: bash
  42
  43         ./tools/testing/kunit/kunit.py run
  44
  45 However, you most likely want to use it with the following options:
  46
  47 .. code-block:: bash
  48
  49         ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all`
  50
  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.
  53
  54 .. note::
  55         This command will work even without a .kunitconfig file: if no
  56         .kunitconfig is present, a default one will be used instead.
  57
  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.
  60
  61 .. code-block:: bash
  62
  63         ./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig
  64
  65 For a list of all the flags supported by kunit_tool, you can run:
  66
  67 .. code-block:: bash
  68
  69         ./tools/testing/kunit/kunit.py run --help
  70
  71 Configuring, Building, and Running Tests
  72 ========================================
  73
  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.
  76
  77 A .config can be generated from a .kunitconfig by using the ``config`` argument
  78 when running kunit_tool:
  79
  80 .. code-block:: bash
  81
  82         ./tools/testing/kunit/kunit.py config
  83
  84 Similarly, if you just want to build a KUnit kernel from the current .config,
  85 you can use the ``build`` argument:
  86
  87 .. code-block:: bash
  88
  89         ./tools/testing/kunit/kunit.py build
  90
  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:
  93
  94 .. code-block:: bash
  95
  96         ./tools/testing/kunit/kunit.py exec
  97
  98 The ``run`` command which is discussed above is equivalent to running all three
  99 of these in sequence.
 100
 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.
 104
 105 Parsing Test Results
 106 ====================
 107
 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.
 112
 113 .. code-block:: bash
 114
 115         ./tools/testing/kunit/kunit.py run --raw_output
 116
 117 .. note::
 118         The raw output from test runs may contain other, non-KUnit kernel log
 119         lines.
 120
 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.
 124
 125 .. code-block:: bash
 126
 127         # Reading from a file
 128         ./tools/testing/kunit/kunit.py parse /var/log/dmesg
 129         # Reading from stdin
 130         dmesg | ./tools/testing/kunit/kunit.py parse
 131
 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).
 134
 135 Filtering Tests
 136 ===============
 137
 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:
 141
 142 .. code-block:: bash
 143
 144         ./tools/testing/kunit/kunit.py run 'kunit-resource*'
 145
 146 This uses the standard glob format for wildcards.
 147
 148 Running Tests on QEMU
 149 =====================
 150
 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:
 153
 154 ``--arch``
 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.
 164
 165 ``--cross_compile``
 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``.
 174
 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``.
 183
 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:
 188
 189 .. code-block:: bash
 190
 191         ./tools/testing/kunit/kunit.py run \
 192                 --timeout=60 \
 193                 --jobs=12 \
 194                 --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
 195
 196 Other Useful Options
 197 ====================
 198
 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.
 201
 202 Some of the more useful ones are:
 203
 204 ``--help``
 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.
 209
 210 ``--build_dir``
 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``.
 214
 215 ``--make_options``
 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``.
 219
 220 ``--alltests``
 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.
 227
 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.