Documentation/dev-tools/kselftest.rst

8 and booting a kernel.
15 On some systems, hot-plug tests could hang forever waiting for cpu and
16 memory to be ready to be offlined. A special hot-plug target is created
17 to run the full range of hot-plug tests. In default mode, hot-plug tests run
18 in safe mode with a limited scope. In limited mode, cpu-hotplug test is
19 run on a single cpu as opposed to all hotplug capable cpus, and memory
20 hotplug test is run on 2% of hotplug capable memory instead of 10%.
23 userspace may wish to use the `Test Harness`_.  Tests that need to be
24 run in kernel space may wish to use a `Test Module`_.
29 To build the tests::
31   $ make -C tools/testing/selftests
35   $ make -C tools/testing/selftests run_tests
37 To build and run the tests with a single command, use::
43 Kselftest supports saving output files in a separate directory and then
49 To build, save output files in a separate directory with O= ::
53 To build, save output files in a separate directory with KBUILD_OUTPUT ::
60 The above commands by default run the tests and print full pass/fail report.
61 Kselftest supports "summary" option to make it easier to understand the test
62 results. Please find the detailed individual test results for each test in
74 single test to run, or a list of tests to run.
78   $ make -C tools/testing/selftests TARGETS=ptrace run_tests
80 You can specify multiple tests to build and run::
84 To build, save output files in a separate directory with O= ::
88 To build, save output files in a separate directory with KBUILD_OUTPUT ::
97   $ make -C tools/testing/selftests SKIP_TARGETS=ptrace run_tests
108 See the top-level tools/testing/selftests/Makefile for the list of all
114 To build the hotplug tests::
116   $ make -C tools/testing/selftests hotplug
120   $ make -C tools/testing/selftests run_hotplug
134    $ make -C tools/testing/selftests install
138    $ make -C tools/testing/selftests install INSTALL_PATH=/some/other/path
152 To see the list of available tests, the `-l` option can be used::
154    $ ./run_kselftest.sh -l
156 The `-c` option can be used to run all the tests from a test collection, or
157 the `-t` option for specific single tests. Either can be used multiple times::
159    $ ./run_kselftest.sh -c bpf -c seccomp -t timers:posix_timers -t timer:nanosleep
161 For other features see the script usage output, seen with the `-h` option.
169    $ make -C tools/testing/selftests gen_tar
171 This generates a tarball in the `INSTALL_PATH/kselftest-packages` directory. By
173 specifying a `FORMAT` make variable. Any value recognized by `tar's auto-compress`_
176     $ make -C tools/testing/selftests gen_tar FORMAT=.xz
182     $ make -C tools/testing/selftests gen_tar TARGETS="bpf" FORMAT=.xz
184 .. _tar's auto-compress: https://www.gnu.org/software/tar/manual/html_node/gzip.html#auto_002dcompr…
195  * Don't break the build on any architecture, and
197  * Don't cause the top-level "make run_tests" to fail if your feature is
209    TEST_CUSTOM_PROGS should be used by tests that require custom build
210    rules and prevent common build rule use.
212    TEST_PROGS are for test shell scripts. Please ensure shell script has
215    TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests.
220    test.
222  * First use the headers inside the kernel source and/or git repo, and then the
227  * If a test needs specific kernel config options enabled, add a config file in
228    the test directory to enable them.
232 Test Module
237 test module.  We can tie the module into the kselftest framework by
238 using a shell script test runner.  ``kselftest/module.sh`` is designed
242 - ``tools/testing/kselftest/kselftest_module.h``
243 - ``tools/testing/kselftest/kselftest/module.sh``
246 ----------
248 Here we show the typical steps to create a test module and tie it into
251 1. Create the test module
253 2. Create the test script that will run (load/unload) the module
258 4. Add test script to makefile  e.g. ``tools/testing/selftests/lib/Makefile``
262 .. code-block:: sh
264    # Assumes you have booted a fresh build of this kernel tree
266    make kselftest-merge
272 --------------
274 A bare bones test module might look like this:
276 .. code-block:: c
278    // SPDX-License-Identifier: GPL-2.0+
304 Example test script
305 -------------------
307 .. code-block:: sh
310     # SPDX-License-Identifier: GPL-2.0+
314 Test Harness
317 The kselftest_harness.h file contains useful helpers to build tests.  The
318 test harness is for userspace testing, for kernel space testing see `Test
325 -------
327 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
332 -------
334 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
335     :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP
340 ---------
342 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
345 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h