Creating a.kunitconfig file¶

If we want to run a specific set of tests (rather than those listedin the KUnitdefconfig), we can provide Kconfig options in the.kunitconfig file. For default .kunitconfig, see:https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config.A.kunitconfig is aminconfig (a .configgenerated by runningmakesavedefconfig), used for running aspecific set of tests. This file contains the regular Kernel configswith specific test targets. The.kunitconfig alsocontains any other config options required by the tests (For example:dependencies for features under tests, configs that enable/disablecertain code blocks, arch configs and so on).

To create a.kunitconfig, using the KUnitdefconfig:

cd $PATH_TO_LINUX_REPOcp tools/testing/kunit/configs/default.config .kunit/.kunitconfig

We can then add any other Kconfig options. For example:

CONFIG_LIST_KUNIT_TEST=y

kunit_tool ensures that all config options in.kunitconfig areset in the kernel.config before running the tests. It warns if wehave not included the options dependencies.

Configuring, building, and running tests¶

If we want to make manual changes to the KUnit build process, wecan run part of the KUnit build process independently.When running kunit_tool, from a.kunitconfig, we can generate a.config by using theconfig argument:

./tools/testing/kunit/kunit.py config

To build a KUnit kernel from the current.config, we can use thebuild argument:

./tools/testing/kunit/kunit.py build

If we already have built UML kernel with built-in KUnit tests, wecan run the kernel, and display the test results with theexecargument:

./tools/testing/kunit/kunit.py exec

Therun command discussed in section:Running tests with kunit_tool,is equivalent to running the above three commands in sequence.

Parsing test results¶

KUnit tests output displays results in TAP (Test Anything Protocol)format. When running tests, kunit_tool parses this output and printsa summary. To see the raw test results in TAP format, we can pass the--raw_output argument:

./tools/testing/kunit/kunit.py run --raw_output

If we have KUnit results in the raw TAP format, we can parse them andprint the human-readable summary with theparse command forkunit_tool. This accepts a filename for an argument, or will read fromstandard input.

# Reading from a file./tools/testing/kunit/kunit.pyparse/var/log/dmesg# Reading from stdindmesg|./tools/testing/kunit/kunit.pyparse

Filtering tests¶

By passing a bash style glob filter to theexec orruncommands, we can run a subset of the tests built into a kernel . Forexample: if we only want to run KUnit resource tests, use:

./tools/testing/kunit/kunit.py run 'kunit-resource*'

This uses the standard glob format with wildcard characters.

Running tests on QEMU¶

kunit_tool supports running tests on qemu as well asvia UML. To run tests on qemu, by default it requires two flags:

• --arch: Selects a configs collection (Kconfig, qemu config optionsand so on), that allow KUnit tests to be run on the specifiedarchitecture in a minimal way. The architecture argument is same asthe option name passed to theARCH variable used by Kbuild.Not all architectures currently support this flag, but we can use--qemu_config to handle it. Ifum is passed (or this flagis ignored), the tests will run via UML. Non-UML architectures,for example: i386, x86_64, arm and so on; run on qemu.

  --archhelp lists all valid--arch values.

• --cross_compile: Specifies the Kbuild toolchain. It passes thesame argument as passed to theCROSS_COMPILE variable used byKbuild. As a reminder, this will be the prefix for the toolchainbinaries such as GCC. For example:

  • sparc64-linux-gnu if we have the sparc toolchain installed onour system.

  • $HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linuxif we have downloaded the microblaze toolchain from the 0-daywebsite to a directory in our home directory called toolchains.

This means that for most architectures, running under qemu is as simple as:

./tools/testing/kunit/kunit.pyrun--arch=x86_64

When cross-compiling, we’ll likely need to specify a different toolchain, forexample:

./tools/testing/kunit/kunit.pyrun\--arch=s390\--cross_compile=s390x-linux-gnu-

If we want to run KUnit tests on an architecture not supported bythe--arch flag, or want to run KUnit tests on qemu using anon-default configuration; then we can write our own``QemuConfig``.TheseQemuConfigs are written in Python. They have an import linefrom..qemu_configimportQemuArchParams at the top of the file.The file must contain a variable calledQEMU_ARCH that has aninstance ofQemuArchParams assigned to it. See example in:tools/testing/kunit/qemu_configs/x86_64.py.

Once we have aQemuConfig, we can pass it into kunit_tool,using the--qemu_config flag. When used, this flag replaces the--arch flag. For example: usingtools/testing/kunit/qemu_configs/x86_64.py, the invocation appearas

./tools/testing/kunit/kunit.pyrun\--timeout=60\--jobs=12\--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py

Running command-line arguments¶

kunit_tool has a number of other command-line arguments which canbe useful for our test environment. Below are the most commonly usedcommand line arguments:

• --help: Lists all available options. To list common options,place--help before the command. To list options specific to thatcommand, place--help after the command.

  Note

  Different commands (config,build,run, etc)have different supported options.

• --build_dir: Specifies kunit_tool build directory. It includesthe.kunitconfig,.config files and compiled kernel.

• --make_options: Specifies additional options to pass to make, whencompiling a kernel (usingbuild orrun commands). For example:to enable compiler warnings, we can pass--make_optionsW=1.

• --alltests: Enable a predefined set of options in order to buildas many tests as possible.

  Note

  The list of enabled options can be found intools/testing/kunit/configs/all_tests.config.

  If you only want to enable all tests with otherwise satisfieddependencies, instead addCONFIG_KUNIT_ALL_TESTS=y to your.kunitconfig.

• --kunitconfig: Specifies the path or the directory of the.kunitconfigfile. For example:

  • lib/kunit/.kunitconfig can be the path of the file.

  • lib/kunit can be the directory in which the file is located.

  This file is used to build and run with a predefined set of testsand their dependencies. For example, to run tests for a given subsystem.

• --kconfig_add: Specifies additional configuration options to beappended to the.kunitconfig file. For example:

  ./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_KASAN=y

• --arch: Runs tests on the specified architecture. The architectureargument is same as the Kbuild ARCH environment variable.For example, i386, x86_64, arm, um, etc. Non-UML architectures run on qemu.Default isum.

• --cross_compile: Specifies the Kbuild toolchain. It passes thesame argument as passed to theCROSS_COMPILE variable used byKbuild. This will be the prefix for the toolchainbinaries such as GCC. For example:

  • sparc64-linux-gnu- if we have the sparc toolchain installed onour system.

  • $HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linuxif we have downloaded the microblaze toolchain from the 0-daywebsite to a specified path in our home directory called toolchains.

• --qemu_config: Specifies the path to a file containing acustom qemu architecture definition. This should be a python filecontaining aQemuArchParams object.

• --qemu_args: Specifies additional qemu arguments, for example,-smp8.

• --jobs: Specifies the number of jobs (commands) to run simultaneously.By default, this is set to the number of cores on your system.

• --timeout: Specifies the maximum number of seconds allowed for all tests to run.This does not include the time taken to build the tests.

• --kernel_args: Specifies additional kernel command-line arguments. May be repeated.

• --run_isolated: If set, boots the kernel for each individual suite/test.This is useful for debugging a non-hermetic test, one thatmight pass/fail based on what ran before it.

• --raw_output: If set, generates unformatted output from kernel. Possible options are:

  • all: To view the full kernel output, use--raw_output=all.

  • kunit: This is the default option and filters to KUnit output. Use--raw_output or--raw_output=kunit.

• --json: If set, stores the test results in a JSON format and prints tostdout orsaves to a file if a filename is specified.

• --filter: Specifies filters on test attributes, for example,speed!=slow.Multiple filters can be used by wrapping input in quotes and separating filtersby commas. Example:--filter"speed>slow,module=example".

• --filter_action: If set toskip, filtered tests will be shown as skippedin the output rather than showing no output.

• --list_tests: If set, lists all tests that will be run.

• --list_tests_attr: If set, lists all tests that will be run and all of theirattributes.