182 строки
6.4 KiB
ReStructuredText
182 строки
6.4 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
=================
|
|
kunit_tool How-To
|
|
=================
|
|
|
|
What is kunit_tool?
|
|
===================
|
|
|
|
kunit_tool is a script (``tools/testing/kunit/kunit.py``) that aids in building
|
|
the Linux kernel as UML (`User Mode Linux
|
|
<http://user-mode-linux.sourceforge.net/>`_), running KUnit tests, parsing
|
|
the test results and displaying them in a user friendly manner.
|
|
|
|
kunit_tool addresses the problem of being able to run tests without needing a
|
|
virtual machine or actual hardware with User Mode Linux. User Mode Linux is a
|
|
Linux architecture, like ARM or x86; however, unlike other architectures it
|
|
compiles the kernel as a standalone Linux executable that can be run like any
|
|
other program directly inside of a host operating system. To be clear, it does
|
|
not require any virtualization support: it is just a regular program.
|
|
|
|
What is a .kunitconfig?
|
|
=======================
|
|
|
|
It's just a defconfig that kunit_tool looks for in the build directory
|
|
(``.kunit`` by default). kunit_tool uses it to generate a .config as you might
|
|
expect. In addition, it verifies that the generated .config contains the CONFIG
|
|
options in the .kunitconfig; the reason it does this is so that it is easy to
|
|
be sure that a CONFIG that enables a test actually ends up in the .config.
|
|
|
|
It's also possible to pass a separate .kunitconfig fragment to kunit_tool,
|
|
which is useful if you have several different groups of tests you wish
|
|
to run independently, or if you want to use pre-defined test configs for
|
|
certain subsystems.
|
|
|
|
Getting Started with kunit_tool
|
|
===============================
|
|
|
|
If a kunitconfig is present at the root directory, all you have to do is:
|
|
|
|
.. code-block:: bash
|
|
|
|
./tools/testing/kunit/kunit.py run
|
|
|
|
However, you most likely want to use it with the following options:
|
|
|
|
.. code-block:: bash
|
|
|
|
./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all`
|
|
|
|
- ``--timeout`` sets a maximum amount of time to allow tests to run.
|
|
- ``--jobs`` sets the number of threads to use to build the kernel.
|
|
|
|
.. note::
|
|
This command will work even without a .kunitconfig file: if no
|
|
.kunitconfig is present, a default one will be used instead.
|
|
|
|
If you wish to use a different .kunitconfig file (such as one provided for
|
|
testing a particular subsystem), you can pass it as an option.
|
|
|
|
.. code-block:: bash
|
|
|
|
./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig
|
|
|
|
For a list of all the flags supported by kunit_tool, you can run:
|
|
|
|
.. code-block:: bash
|
|
|
|
./tools/testing/kunit/kunit.py run --help
|
|
|
|
Configuring, Building, and Running Tests
|
|
========================================
|
|
|
|
It's also possible to run just parts of the KUnit build process independently,
|
|
which is useful if you want to make manual changes to part of the process.
|
|
|
|
A .config can be generated from a .kunitconfig by using the ``config`` argument
|
|
when running kunit_tool:
|
|
|
|
.. code-block:: bash
|
|
|
|
./tools/testing/kunit/kunit.py config
|
|
|
|
Similarly, if you just want to build a KUnit kernel from the current .config,
|
|
you can use the ``build`` argument:
|
|
|
|
.. code-block:: bash
|
|
|
|
./tools/testing/kunit/kunit.py build
|
|
|
|
And, if you already have a built UML kernel with built-in KUnit tests, you can
|
|
run the kernel and display the test results with the ``exec`` argument:
|
|
|
|
.. code-block:: bash
|
|
|
|
./tools/testing/kunit/kunit.py exec
|
|
|
|
The ``run`` command which is discussed above is equivalent to running all three
|
|
of these in sequence.
|
|
|
|
All of these commands accept a number of optional command-line arguments. The
|
|
``--help`` flag will give a complete list of these, or keep reading this page
|
|
for a guide to some of the more useful ones.
|
|
|
|
Parsing Test Results
|
|
====================
|
|
|
|
KUnit tests output their results in TAP (Test Anything Protocol) format.
|
|
kunit_tool will, when running tests, parse this output and print a summary
|
|
which is much more pleasant to read. If you wish to look at the raw test
|
|
results in TAP format, you can pass the ``--raw_output`` argument.
|
|
|
|
.. code-block:: bash
|
|
|
|
./tools/testing/kunit/kunit.py run --raw_output
|
|
|
|
.. note::
|
|
The raw output from test runs may contain other, non-KUnit kernel log
|
|
lines.
|
|
|
|
If you have KUnit results in their raw TAP format, you can parse them and print
|
|
the human-readable summary with the ``parse`` command for kunit_tool. This
|
|
accepts a filename for an argument, or will read from standard input.
|
|
|
|
.. code-block:: bash
|
|
|
|
# Reading from a file
|
|
./tools/testing/kunit/kunit.py parse /var/log/dmesg
|
|
# Reading from stdin
|
|
dmesg | ./tools/testing/kunit/kunit.py parse
|
|
|
|
This is very useful if you wish to run tests in a configuration not supported
|
|
by kunit_tool (such as on real hardware, or an unsupported architecture).
|
|
|
|
Filtering Tests
|
|
===============
|
|
|
|
It's possible to run only a subset of the tests built into a kernel by passing
|
|
a filter to the ``exec`` or ``run`` commands. For example, if you only wanted
|
|
to run KUnit resource tests, you could use:
|
|
|
|
.. code-block:: bash
|
|
|
|
./tools/testing/kunit/kunit.py run 'kunit-resource*'
|
|
|
|
This uses the standard glob format for wildcards.
|
|
|
|
Other Useful Options
|
|
====================
|
|
|
|
kunit_tool has a number of other command-line arguments which can be useful
|
|
when adapting it to fit your environment or needs.
|
|
|
|
Some of the more useful ones are:
|
|
|
|
``--help``
|
|
Lists all of the available options. Note that different commands
|
|
(``config``, ``build``, ``run``, etc) will have different supported
|
|
options. Place ``--help`` before the command to list common options,
|
|
and after the command for options specific to that command.
|
|
|
|
``--build_dir``
|
|
Specifies the build directory that kunit_tool will use. This is where
|
|
the .kunitconfig file is located, as well as where the .config and
|
|
compiled kernel will be placed. Defaults to ``.kunit``.
|
|
|
|
``--make_options``
|
|
Specifies additional options to pass to ``make`` when compiling a
|
|
kernel (with the ``build`` or ``run`` commands). For example, to enable
|
|
compiler warnings, you can pass ``--make_options W=1``.
|
|
|
|
``--alltests``
|
|
Builds a UML kernel with all config options enabled using ``make
|
|
allyesconfig``. This allows you to run as many tests as is possible,
|
|
but is very slow and prone to breakage as new options are added or
|
|
modified. In most cases, enabling all tests which have satisfied
|
|
dependencies by adding ``CONFIG_KUNIT_ALL_TESTS=1`` to your
|
|
.kunitconfig is preferable.
|
|
|
|
There are several other options (and new ones are often added), so do check
|
|
``--help`` if you're looking for something not mentioned here.
|