요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
=============================
Running tests with kunit_tool
=============================
We can either run KUnit tests using kunit_tool or can run tests
manually, and then use kunit_tool to parse the results. To run tests
manually, see: Documentation/dev-tools/kunit/run_manual.rst.
As long as we can build the kernel, we can run KUnit.
kunit_tool is a Python script which configures and builds a kernel, runs
tests, and formats the test results.
Run command:
.. code-block::
./tools/testing/kunit/kunit.py run
We should see the following:
.. code-block::
Configuring KUnit Kernel ...
Building KUnit kernel...
Starting KUnit kernel...
We may want to use the following options:
.. code-block::
./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all`
- ``--timeout`` sets a maximum amount of time for tests to run.
- ``--jobs`` sets the number of threads to build the kernel.
kunit_tool will generate a ``.kunitconfig`` with a default
configuration, if no other ``.kunitconfig`` file exists
(in the build directory). In addition, it verifies that the
generated ``.config`` file contains the ``CONFIG`` options in the
``.kunitconfig``.
It is also possible to pass a separate ``.kunitconfig`` fragment to
kunit_tool. This is useful if we have several different groups of
tests we want to run independently, or if we want to use pre-defined
test configs for certain subsystems.
To use a different ``.kunitconfig`` file (such as one
provided to test a particular subsystem), pass it as an option:
.. code-block::
./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig
To view kunit_tool flags (optional command-line arguments), run:
.. code-block::
./tools/testing/kunit/kunit.py run --help
Creating a ``.kunitconfig`` file
================================
If we want to run a specific set of tests (rather than those listed
in the KUnit ``defconfig``), 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 a ``minconfig`` (a .config
generated by running ``make savedefconfig``), used for running a
specific set of tests. This file contains the regular Kernel configs
with specific test targets. The ``.kunitconfig`` also
contains any other config options required by the tests (For example:
dependencies for features under tests, configs that enable/disable
certain code blocks, arch configs and so on).
To create a ``.kunitconfig``, using the KUnit ``defconfig``:
.. code-block::
cd $PATH_TO_LINUX_REPO
cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig
We can then add any other Kconfig options. For example:
.. code-block::
CONFIG_LIST_KUNIT_TEST=y
kunit_tool ensures that all config options in ``.kunitconfig`` are
set in the kernel ``.config`` before running the tests. It warns if we
have not included the options dependencies.
.. note:: Removing something from the ``.kunitconfig`` will
not rebuild the ``.config file``. The configuration is only
updated if the ``.kunitconfig`` is not a subset of ``.config``.
This means that we can use other tools
(For example: ``make menuconfig``) to adjust other config options.
The build dir needs to be set for ``make menuconfig`` to
work, therefore by default use ``make O=.kunit menuconfig``.
Configuring, building, and running tests
========================================
If we want to make manual changes to the KUnit build process, we
can run part of the KUnit build process independently.
When running kunit_tool, from a ``.kunitconfig``, we can generate a
``.config`` by using the ``config`` argument:
.. code-block::
./tools/testing/kunit/kunit.py config
To build a KUnit kernel from the current ``.config``, we can use the
``build`` argument:
.. code-block::
./tools/testing/kunit/kunit.py build
If we already have built UML kernel with built-in KUnit tests, we
can run the kernel, and display the test results with the ``exec``
argument:
.. code-block::
./tools/testing/kunit/kunit.py exec
The ``run`` 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 prints
a summary. To see the raw test results in TAP format, we can pass the
``--raw_output`` argument:
.. code-block::
./tools/testing/kunit/kunit.py run --raw_output
If we have KUnit results in the raw TAP format, we 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
Filtering tests
===============
By passing a bash style glob filter to the ``exec`` or ``run``
commands, we can run a subset of the tests built into a kernel . For
example: if we only want to run KUnit resource tests, use:
.. code-block::
./tools/testing/kunit/kunit.py run 'kunit-resource*'
This uses the standard glob format with wildcard characters.
.. _kunit-on-qemu:
Running tests on QEMU
=====================
kunit_tool supports running tests on qemu as well as
via UML. To run tests on qemu, by default it requires two flags:
- ``--arch``: Selects a configs collection (Kconfig, qemu config options
and so on), that allow KUnit tests to be run on the specified
architecture in a minimal way. The architecture argument is same as
the option name passed to the ``ARCH`` variable used by Kbuild.
Not all architectures currently support this flag, but we can use
``--qemu_config`` to handle it. If ``um`` is passed (or this flag
is ignored), the tests will run via UML. Non-UML architectures,
for example: i386, x86_64, arm and so on; run on qemu.
``--arch help`` lists all valid ``--arch`` values.
- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the
same argument as passed to the ``CROSS_COMPILE`` variable used by
Kbuild. As a reminder, this will be the prefix for the toolchain
binaries such as GCC. For example:
- ``sparc64-linux-gnu`` if we have the sparc toolchain installed on
our system.
- ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux``
if we have downloaded the microblaze toolchain from the 0-day
website to a directory in our home directory called toolchains.
This means that for most architectures, running under qemu is as simple as:
.. code-block:: bash
./tools/testing/kunit/kunit.py run --arch=x86_64
When cross-compiling, we'll likely need to specify a different toolchain, for
example:
.. code-block:: bash
./tools/testing/kunit/kunit.py run \
--arch=s390 \
--cross_compile=s390x-linux-gnu-
If we want to run KUnit tests on an architecture not supported by
the ``--arch`` flag, or want to run KUnit tests on qemu using a
non-default configuration; then we can write our own``QemuConfig``.
These ``QemuConfigs`` are written in Python. They have an import line
``from..qemu_config import QemuArchParams`` at the top of the file.
The file must contain a variable called ``QEMU_ARCH`` that has an
instance of ``QemuArchParams`` assigned to it. See example in:
``tools/testing/kunit/qemu_configs/x86_64.py``.
Once we have a ``QemuConfig``, we can pass it into kunit_tool,
using the ``--qemu_config`` flag. When used, this flag replaces the
``--arch`` flag. For example: using
``tools/testing/kunit/qemu_configs/x86_64.py``, the invocation appear
as
.. code-block:: bash
./tools/testing/kunit/kunit.py run \
--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 can
be useful for our test environment. Below are the most commonly used
command line arguments:
- ``--help``: Lists all available options. To list common options,
place ``--help`` before the command. To list options specific to that
command, place ``--help`` after the command.
.. note:: Different commands (``config``, ``build``, ``run``, etc)
have different supported options.
- ``--build_dir``: Specifies kunit_tool build directory. It includes
the ``.kunitconfig``, ``.config`` files and compiled kernel.
- ``--make_options``: Specifies additional options to pass to make, when
compiling a kernel (using ``build`` or ``run`` commands). For example:
to enable compiler warnings, we can pass ``--make_options W=1``.
- ``--alltests``: Enable a predefined set of options in order to build
as many tests as possible.
.. note:: The list of enabled options can be found in
``tools/testing/kunit/configs/all_tests.config``.
If you only want to enable all tests with otherwise satisfied
dependencies, instead add ``CONFIG_KUNIT_ALL_TESTS=y`` to your
``.kunitconfig``.
- ``--kunitconfig``: Specifies the path or the directory of the ``.kunitconfig``
file. 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 tests
and their dependencies. For example, to run tests for a given subsystem.
- ``--kconfig_add``: Specifies additional configuration options to be
appended to the ``.kunitconfig`` file. For example:
.. code-block::
./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_KASAN=y
- ``--arch``: Runs tests on the specified architecture. The architecture
argument is same as the Kbuild ARCH environment variable.
For example, i386, x86_64, arm, um, etc. Non-UML architectures run on qemu.
Default is `um`.
- ``--cross_compile``: Specifies the Kbuild toolchain. It passes the
same argument as passed to the ``CROSS_COMPILE`` variable used by
Kbuild. This will be the prefix for the toolchain
binaries such as GCC. For example:
- ``sparc64-linux-gnu-`` if we have the sparc toolchain installed on
our system.
- ``$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux``
if we have downloaded the microblaze toolchain from the 0-day
website to a specified path in our home directory called toolchains.
- ``--qemu_config``: Specifies the path to a file containing a
custom qemu architecture definition. This should be a python file
containing a `QemuArchParams` object.
- ``--qemu_args``: Specifies additional qemu arguments, for example, ``-smp 8``.
- ``--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 that
might 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 to `stdout` or
saves 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 filters
by commas. Example: ``--filter "speed>slow, module=example"``.
- ``--filter_action``: If set to ``skip``, filtered tests will be shown as skipped
in 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 their
attributes.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
kunit_tool 기본 실행
1-60SPDX 라이선스 식별자: GPL-2.0
kunit_tool로 테스트 실행
KUnit test는 kunit_tool로 실행하거나 수동으로 실행한 뒤 kunit_tool로 결과만 parsing할 수 있습니다. 수동 실행은 `Documentation/dev-tools/kunit/run_manual.rst`를 참조하십시오. Kernel을 build할 수 있다면 KUnit을 실행할 수 있습니다.
kunit_tool은 kernel 구성과 build, test 실행, 결과 formatting을 수행하는 Python script입니다.
실행 명령은 다음과 같습니다.
./tools/testing/kunit/kunit.py run다음 진행 message가 나타나야 합니다.
Configuring KUnit Kernel ...
Building KUnit kernel...
Starting KUnit kernel...다음 option을 사용할 수 있습니다.
./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all``--timeout`은 테스트가 실행될 최대 시간을 지정하고 `--jobs`는 kernel build에 사용할 thread 수를 지정합니다.
Build directory에 다른 `.kunitconfig`가 없으면 kunit_tool이 기본 configuration으로 새 파일을 생성합니다. 또한 생성된 `.config`가 `.kunitconfig`의 `CONFIG` option을 포함하는지 검증합니다.
별도의 `.kunitconfig` fragment를 kunit_tool에 전달할 수도 있습니다. 여러 test group을 독립적으로 실행하거나 subsystem별 미리 정의된 test config를 사용할 때 유용합니다.
다른 `.kunitconfig` file을 사용하려면 option으로 전달합니다.
./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfigkunit_tool의 선택적 command-line flag를 보려면 다음을 실행합니다.
./tools/testing/kunit/kunit.py run --help.kunitconfig 생성과 갱신 규칙
61-100`.kunitconfig` file 만들기
KUnit `defconfig`에 있는 테스트 대신 특정 test set을 실행하려면 `.kunitconfig`에 Kconfig option을 넣습니다. 기본 파일은 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config 에 있습니다.
`.kunitconfig`는 `make savedefconfig`가 생성한 `.config`인 minconfig이며 특정 test set 실행에 사용합니다. 일반 kernel config와 특정 test target을 포함하고, feature dependency, 특정 code block 활성화 또는 비활성화, architecture config처럼 테스트에 필요한 다른 option도 포함합니다.
KUnit defconfig에서 `.kunitconfig`를 만듭니다.
cd $PATH_TO_LINUX_REPO
cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig그 뒤 다른 Kconfig option을 추가할 수 있습니다.
CONFIG_LIST_KUNIT_TEST=ykunit_tool은 테스트 실행 전에 `.kunitconfig`의 모든 option이 kernel `.config`에 설정되었는지 확인하고 dependency option이 빠졌으면 warning을 냅니다.
참고: `.kunitconfig`에서 항목을 제거해도 `.config`를 다시 build하지 않습니다. `.kunitconfig`가 `.config`의 subset이 아닐 때만 configuration을 갱신합니다. 따라서 `make menuconfig` 같은 다른 tool로 나머지 option을 조정할 수 있습니다. Build directory를 지정해야 하므로 기본적으로 `make O=.kunit menuconfig`를 사용합니다.
Config, build, exec 단계 분리
101-130테스트 구성, build, 실행
KUnit build process를 수동으로 변경하려면 일부 단계를 독립적으로 실행할 수 있습니다. `.kunitconfig`에서 `.config`를 생성하려면 `config` argument를 사용합니다.
./tools/testing/kunit/kunit.py config현재 `.config`에서 KUnit kernel을 build하려면 `build`를 사용합니다.
./tools/testing/kunit/kunit.py buildBuilt-in KUnit test를 포함한 UML kernel을 이미 build했다면 `exec`로 kernel을 실행하고 결과를 표시합니다.
./tools/testing/kunit/kunit.py exec앞에서 설명한 `run` command는 위 세 command를 순서대로 실행한 것과 같습니다.
전체 run을 단계별로 분리하면 configuration, build, runtime 중 어느 지점이 실패했는지 확인할 수 있습니다.
결과 parsing과 test filter
131-169Test result parsing
KUnit test output은 TAP 형식으로 결과를 표시합니다. kunit_tool은 실행 중 이 출력을 parsing해 summary를 출력합니다. Raw TAP 결과를 보려면 `--raw_output`을 전달합니다.
./tools/testing/kunit/kunit.py run --raw_outputRaw TAP 형식의 KUnit 결과가 있다면 kunit_tool의 `parse` command로 사람이 읽을 수 있는 summary를 출력할 수 있습니다. Filename argument를 받거나 standard input에서 읽습니다.
# Reading from a file
./tools/testing/kunit/kunit.py parse /var/log/dmesg
# Reading from stdin
dmesg | ./tools/testing/kunit/kunit.py parseTest filtering
`exec` 또는 `run` command에 bash style glob filter를 전달하면 kernel에 build된 테스트 일부만 실행할 수 있습니다. KUnit resource test만 실행하는 예는 다음과 같습니다.
./tools/testing/kunit/kunit.py run 'kunit-resource*'Wildcard character를 사용하는 표준 glob 형식을 사용합니다.
QEMU와 cross compilation
170-235QEMU에서 테스트 실행
원문의 `kunit-on-qemu` anchor는 이 QEMU 실행 절을 가리킵니다.
kunit_tool은 UML뿐 아니라 QEMU에서도 테스트 실행을 지원합니다. 기본적으로 QEMU 실행에는 `--arch`와 `--cross_compile` 두 flag가 필요합니다.
`--arch`는 지정 architecture에서 KUnit test를 최소 구성으로 실행할 수 있게 하는 Kconfig와 QEMU option 등의 config collection을 선택합니다. Argument는 Kbuild의 ARCH variable에 전달하는 option 이름과 같습니다.
모든 architecture가 이 flag를 지원하는 것은 아니며 이 경우 `--qemu_config`를 사용할 수 있습니다. `um`을 전달하거나 flag를 생략하면 UML에서 실행하고 i386, x86_64, arm 같은 non-UML architecture는 QEMU에서 실행합니다. `--arch help`는 유효한 값을 나열합니다.
`--cross_compile`은 Kbuild toolchain을 지정하며 Kbuild의 CROSS_COMPILE variable과 같은 argument를 전달합니다. GCC 같은 toolchain binary의 prefix입니다. 예를 들어 설치된 sparc toolchain은 `sparc64-linux-gnu`, home의 toolchains 디렉터리에 받은 microblaze toolchain은 `$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux`를 사용할 수 있습니다.
대부분의 architecture는 QEMU에서 다음처럼 간단히 실행합니다.
./tools/testing/kunit/kunit.py run --arch=x86_64Cross-compilation에는 다른 toolchain을 지정해야 할 수 있습니다.
./tools/testing/kunit/kunit.py run \
--arch=s390 \
--cross_compile=s390x-linux-gnu-`--arch`가 지원하지 않는 architecture에서 실행하거나 non-default QEMU configuration을 쓰려면 custom `QemuConfig`를 작성합니다. Python file 맨 위에서 `from..qemu_config import QemuArchParams`를 import하고 `QemuArchParams` instance를 할당한 `QEMU_ARCH` variable을 포함해야 합니다. 예는 `tools/testing/kunit/qemu_configs/x86_64.py`입니다.
작성한 QemuConfig는 `--qemu_config` flag로 전달하며 이 flag는 `--arch`를 대체합니다.
./tools/testing/kunit/kunit.py run \
--timeout=60 \
--jobs=12 \
--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.pyArchitecture flag와 custom QemuConfig에 따라 UML 또는 QEMU 실행 경로가 결정됩니다.
주요 command-line argument
236-337Command-line argument 실행
kunit_tool은 test environment에 유용한 여러 command-line argument를 제공합니다. 주요 argument는 다음과 같습니다.
`--help`: 사용 가능한 option을 나열합니다. Command 앞에 두면 공통 option, 뒤에 두면 해당 command 전용 option을 표시합니다. `config`, `build`, `run` 등은 지원 option이 서로 다릅니다.
`--build_dir`: `.kunitconfig`, `.config`, compile된 kernel을 포함하는 kunit_tool build directory를 지정합니다.
`--make_options`: `build`나 `run`으로 kernel을 compile할 때 make에 전달할 추가 option을 지정합니다. Compiler warning을 켜려면 `--make_options W=1`을 사용합니다.
`--alltests`: 가능한 많은 테스트를 build하도록 미리 정의된 option set을 활성화합니다. Option 목록은 `tools/testing/kunit/configs/all_tests.config`에 있습니다. Dependency가 이미 충족된 모든 테스트만 켜려면 `.kunitconfig`에 `CONFIG_KUNIT_ALL_TESTS=y`를 추가합니다.
`--kunitconfig`: `.kunitconfig` file 경로나 이를 포함한 directory를 지정합니다. 예를 들어 `lib/kunit/.kunitconfig` 또는 `lib/kunit`입니다. 특정 subsystem의 test와 dependency처럼 미리 정의한 set으로 build하고 실행할 때 사용합니다.
`--kconfig_add`: `.kunitconfig`에 덧붙일 추가 configuration option을 지정합니다.
./tools/testing/kunit/kunit.py run --kconfig_add CONFIG_KASAN=y`--arch`: Kbuild ARCH environment variable과 같은 architecture를 지정합니다. 예: i386, x86_64, arm, um. Non-UML은 QEMU에서 실행하며 기본값은 `um`입니다.
`--cross_compile`: Kbuild CROSS_COMPILE과 같은 toolchain prefix를 지정합니다. 예: `sparc64-linux-gnu-` 또는 `$HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux`.
`--qemu_config`: custom QEMU architecture 정의를 담은 Python file 경로를 지정합니다. File은 `QemuArchParams` object를 포함해야 합니다.
`--qemu_args`: `-smp 8` 같은 추가 QEMU argument를 지정합니다.
`--jobs`: 동시에 실행할 job 또는 command 수입니다. 기본값은 system core 수입니다.
`--timeout`: 모든 테스트에 허용되는 최대 실행 초입니다. Test build 시간은 포함하지 않습니다.
`--kernel_args`: 추가 kernel command-line argument이며 여러 번 지정할 수 있습니다.
`--run_isolated`: 개별 suite 또는 test마다 kernel을 boot합니다. 앞서 실행된 항목에 따라 성공과 실패가 달라지는 non-hermetic test를 디버깅할 때 유용합니다.
`--raw_output`: format하지 않은 kernel output을 생성합니다. `all`은 전체 kernel output을 표시하고 기본값인 `kunit`은 KUnit output만 filtering합니다. `--raw_output`, `--raw_output=kunit`, `--raw_output=all`을 사용할 수 있습니다.
`--json`: test result를 JSON 형식으로 저장해 stdout에 출력하거나 filename을 지정했다면 file에 저장합니다.
`--filter`: `speed!=slow` 같은 test attribute filter를 지정합니다. 여러 filter는 quote 안에서 comma로 구분합니다. 예: `--filter "speed>slow, module=example"`.
`--filter_action`: `skip`이면 filter된 테스트를 출력에서 숨기지 않고 skipped로 표시합니다.
`--list_tests`: 실행할 모든 테스트를 나열합니다.
`--list_tests_attr`: 실행할 모든 테스트와 각 테스트의 모든 attribute를 나열합니다.
긴 option 목록을 구성, build, 실행, 출력과 선택이라는 작업별로 묶었습니다.
요약과 해설
run_wrapper.rst:1-337kunit_tool은 `.kunitconfig`에서 kernel config를 만들고 build한 뒤 UML 또는 QEMU에서 실행해 TAP 결과를 parsing합니다. Run을 config, build, exec로 분리할 수 있어 자동화와 문제 진단에 모두 적합합니다.
Architecture와 toolchain, custom QemuConfig, isolated boot, raw·JSON output, attribute filter까지 command-line에서 제어할 수 있습니다. `.kunitconfig`는 dependency를 포함한 최소 test configuration이며 삭제만으로 기존 `.config`가 다시 생성되지는 않는다는 갱신 규칙에 주의해야 합니다.