.. | .. |
---|
7 | 7 | paths in the kernel. Tests are intended to be run after building, installing |
---|
8 | 8 | and booting a kernel. |
---|
9 | 9 | |
---|
| 10 | +You can find additional information on Kselftest framework, how to |
---|
| 11 | +write new tests using the framework on Kselftest wiki: |
---|
| 12 | + |
---|
| 13 | +https://kselftest.wiki.kernel.org/ |
---|
| 14 | + |
---|
10 | 15 | On some systems, hot-plug tests could hang forever waiting for cpu and |
---|
11 | 16 | memory to be ready to be offlined. A special hot-plug target is created |
---|
12 | | -to run full range of hot-plug tests. In default mode, hot-plug tests run |
---|
| 17 | +to run the full range of hot-plug tests. In default mode, hot-plug tests run |
---|
13 | 18 | in safe mode with a limited scope. In limited mode, cpu-hotplug test is |
---|
14 | 19 | run on a single cpu as opposed to all hotplug capable cpus, and memory |
---|
15 | 20 | hotplug test is run on 2% of hotplug capable memory instead of 10%. |
---|
| 21 | + |
---|
| 22 | +kselftest runs as a userspace process. Tests that can be written/run in |
---|
| 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`_. |
---|
16 | 25 | |
---|
17 | 26 | Running the selftests (hotplug tests are run in limited mode) |
---|
18 | 27 | ============================================================= |
---|
.. | .. |
---|
31 | 40 | |
---|
32 | 41 | Note that some tests will require root privileges. |
---|
33 | 42 | |
---|
34 | | -Build and run from user specific object directory (make O=dir):: |
---|
| 43 | +Kselftest supports saving output files in a separate directory and then |
---|
| 44 | +running tests. To locate output files in a separate directory two syntaxes |
---|
| 45 | +are supported. In both cases the working directory must be the root of the |
---|
| 46 | +kernel src. This is applicable to "Running a subset of selftests" section |
---|
| 47 | +below. |
---|
| 48 | + |
---|
| 49 | +To build, save output files in a separate directory with O= :: |
---|
35 | 50 | |
---|
36 | 51 | $ make O=/tmp/kselftest kselftest |
---|
37 | 52 | |
---|
38 | | -Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=):: |
---|
| 53 | +To build, save output files in a separate directory with KBUILD_OUTPUT :: |
---|
39 | 54 | |
---|
40 | | - $ make KBUILD_OUTPUT=/tmp/kselftest kselftest |
---|
| 55 | + $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest |
---|
41 | 56 | |
---|
42 | | -The above commands run the tests and print pass/fail summary to make it |
---|
43 | | -easier to understand the test results. Please find the detailed individual |
---|
44 | | -test results for each test in /tmp/testname file(s). |
---|
| 57 | +The O= assignment takes precedence over the KBUILD_OUTPUT environment |
---|
| 58 | +variable. |
---|
| 59 | + |
---|
| 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 |
---|
| 63 | +/tmp/testname file(s) when summary option is specified. This is applicable |
---|
| 64 | +to "Running a subset of selftests" section below. |
---|
| 65 | + |
---|
| 66 | +To run kselftest with summary option enabled :: |
---|
| 67 | + |
---|
| 68 | + $ make summary=1 kselftest |
---|
45 | 69 | |
---|
46 | 70 | Running a subset of selftests |
---|
47 | 71 | ============================= |
---|
.. | .. |
---|
57 | 81 | |
---|
58 | 82 | $ make TARGETS="size timers" kselftest |
---|
59 | 83 | |
---|
60 | | -Build and run from user specific object directory (make O=dir):: |
---|
| 84 | +To build, save output files in a separate directory with O= :: |
---|
61 | 85 | |
---|
62 | 86 | $ make O=/tmp/kselftest TARGETS="size timers" kselftest |
---|
63 | 87 | |
---|
64 | | -Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=):: |
---|
| 88 | +To build, save output files in a separate directory with KBUILD_OUTPUT :: |
---|
65 | 89 | |
---|
66 | | - $ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest |
---|
| 90 | + $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest |
---|
67 | 91 | |
---|
68 | | -The above commands run the tests and print pass/fail summary to make it |
---|
69 | | -easier to understand the test results. Please find the detailed individual |
---|
70 | | -test results for each test in /tmp/testname file(s). |
---|
| 92 | +Additionally you can use the "SKIP_TARGETS" variable on the make command |
---|
| 93 | +line to specify one or more targets to exclude from the TARGETS list. |
---|
| 94 | + |
---|
| 95 | +To run all tests but a single subsystem:: |
---|
| 96 | + |
---|
| 97 | + $ make -C tools/testing/selftests SKIP_TARGETS=ptrace run_tests |
---|
| 98 | + |
---|
| 99 | +You can specify multiple tests to skip:: |
---|
| 100 | + |
---|
| 101 | + $ make SKIP_TARGETS="size timers" kselftest |
---|
| 102 | + |
---|
| 103 | +You can also specify a restricted list of tests to run together with a |
---|
| 104 | +dedicated skiplist:: |
---|
| 105 | + |
---|
| 106 | + $ make TARGETS="bpf breakpoints size timers" SKIP_TARGETS=bpf kselftest |
---|
71 | 107 | |
---|
72 | 108 | See the top-level tools/testing/selftests/Makefile for the list of all |
---|
73 | 109 | possible targets. |
---|
.. | .. |
---|
89 | 125 | Install selftests |
---|
90 | 126 | ================= |
---|
91 | 127 | |
---|
92 | | -You can use kselftest_install.sh tool installs selftests in default |
---|
93 | | -location which is tools/testing/selftests/kselftest or a user specified |
---|
94 | | -location. |
---|
| 128 | +You can use the "install" target of "make" (which calls the `kselftest_install.sh` |
---|
| 129 | +tool) to install selftests in the default location (`tools/testing/selftests/kselftest_install`), |
---|
| 130 | +or in a user specified location via the `INSTALL_PATH` "make" variable. |
---|
95 | 131 | |
---|
96 | 132 | To install selftests in default location:: |
---|
97 | 133 | |
---|
98 | | - $ cd tools/testing/selftests |
---|
99 | | - $ ./kselftest_install.sh |
---|
| 134 | + $ make -C tools/testing/selftests install |
---|
100 | 135 | |
---|
101 | 136 | To install selftests in a user specified location:: |
---|
102 | 137 | |
---|
103 | | - $ cd tools/testing/selftests |
---|
104 | | - $ ./kselftest_install.sh install_dir |
---|
| 138 | + $ make -C tools/testing/selftests install INSTALL_PATH=/some/other/path |
---|
105 | 139 | |
---|
106 | 140 | Running installed selftests |
---|
107 | 141 | =========================== |
---|
108 | 142 | |
---|
109 | | -Kselftest install as well as the Kselftest tarball provide a script |
---|
110 | | -named "run_kselftest.sh" to run the tests. |
---|
| 143 | +Found in the install directory, as well as in the Kselftest tarball, |
---|
| 144 | +is a script named `run_kselftest.sh` to run the tests. |
---|
111 | 145 | |
---|
112 | | -You can simply do the following to run the installed Kselftests. Please |
---|
| 146 | +You can simply do the following to run the installed Kselftests. Please |
---|
113 | 147 | note some tests will require root privileges:: |
---|
114 | 148 | |
---|
115 | | - $ cd kselftest |
---|
| 149 | + $ cd kselftest_install |
---|
116 | 150 | $ ./run_kselftest.sh |
---|
| 151 | + |
---|
| 152 | +To see the list of available tests, the `-l` option can be used:: |
---|
| 153 | + |
---|
| 154 | + $ ./run_kselftest.sh -l |
---|
| 155 | + |
---|
| 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:: |
---|
| 158 | + |
---|
| 159 | + $ ./run_kselftest.sh -c bpf -c seccomp -t timers:posix_timers -t timer:nanosleep |
---|
| 160 | + |
---|
| 161 | +For other features see the script usage output, seen with the `-h` option. |
---|
| 162 | + |
---|
| 163 | +Packaging selftests |
---|
| 164 | +=================== |
---|
| 165 | + |
---|
| 166 | +In some cases packaging is desired, such as when tests need to run on a |
---|
| 167 | +different system. To package selftests, run:: |
---|
| 168 | + |
---|
| 169 | + $ make -C tools/testing/selftests gen_tar |
---|
| 170 | + |
---|
| 171 | +This generates a tarball in the `INSTALL_PATH/kselftest-packages` directory. By |
---|
| 172 | +default, `.gz` format is used. The tar compression format can be overridden by |
---|
| 173 | +specifying a `FORMAT` make variable. Any value recognized by `tar's auto-compress`_ |
---|
| 174 | +option is supported, such as:: |
---|
| 175 | + |
---|
| 176 | + $ make -C tools/testing/selftests gen_tar FORMAT=.xz |
---|
| 177 | + |
---|
| 178 | +`make gen_tar` invokes `make install` so you can use it to package a subset of |
---|
| 179 | +tests by using variables specified in `Running a subset of selftests`_ |
---|
| 180 | +section:: |
---|
| 181 | + |
---|
| 182 | + $ make -C tools/testing/selftests gen_tar TARGETS="bpf" FORMAT=.xz |
---|
| 183 | + |
---|
| 184 | +.. _tar's auto-compress: https://www.gnu.org/software/tar/manual/html_node/gzip.html#auto_002dcompress |
---|
117 | 185 | |
---|
118 | 186 | Contributing new tests |
---|
119 | 187 | ====================== |
---|
.. | .. |
---|
139 | 207 | default. |
---|
140 | 208 | |
---|
141 | 209 | TEST_CUSTOM_PROGS should be used by tests that require custom build |
---|
142 | | - rule and prevent common build rule use. |
---|
| 210 | + rules and prevent common build rule use. |
---|
143 | 211 | |
---|
144 | 212 | TEST_PROGS are for test shell scripts. Please ensure shell script has |
---|
145 | 213 | its exec bit set. Otherwise, lib.mk run_tests will generate a warning. |
---|
.. | .. |
---|
159 | 227 | * If a test needs specific kernel config options enabled, add a config file in |
---|
160 | 228 | the test directory to enable them. |
---|
161 | 229 | |
---|
162 | | - e.g: tools/testing/selftests/android/ion/config |
---|
| 230 | + e.g: tools/testing/selftests/android/config |
---|
| 231 | + |
---|
| 232 | +Test Module |
---|
| 233 | +=========== |
---|
| 234 | + |
---|
| 235 | +Kselftest tests the kernel from userspace. Sometimes things need |
---|
| 236 | +testing from within the kernel, one method of doing this is to create a |
---|
| 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 |
---|
| 239 | +to facilitate this process. There is also a header file provided to |
---|
| 240 | +assist writing kernel modules that are for use with kselftest: |
---|
| 241 | + |
---|
| 242 | +- ``tools/testing/kselftest/kselftest_module.h`` |
---|
| 243 | +- ``tools/testing/kselftest/kselftest/module.sh`` |
---|
| 244 | + |
---|
| 245 | +How to use |
---|
| 246 | +---------- |
---|
| 247 | + |
---|
| 248 | +Here we show the typical steps to create a test module and tie it into |
---|
| 249 | +kselftest. We use kselftests for lib/ as an example. |
---|
| 250 | + |
---|
| 251 | +1. Create the test module |
---|
| 252 | + |
---|
| 253 | +2. Create the test script that will run (load/unload) the module |
---|
| 254 | + e.g. ``tools/testing/selftests/lib/printf.sh`` |
---|
| 255 | + |
---|
| 256 | +3. Add line to config file e.g. ``tools/testing/selftests/lib/config`` |
---|
| 257 | + |
---|
| 258 | +4. Add test script to makefile e.g. ``tools/testing/selftests/lib/Makefile`` |
---|
| 259 | + |
---|
| 260 | +5. Verify it works: |
---|
| 261 | + |
---|
| 262 | +.. code-block:: sh |
---|
| 263 | + |
---|
| 264 | + # Assumes you have booted a fresh build of this kernel tree |
---|
| 265 | + cd /path/to/linux/tree |
---|
| 266 | + make kselftest-merge |
---|
| 267 | + make modules |
---|
| 268 | + sudo make modules_install |
---|
| 269 | + make TARGETS=lib kselftest |
---|
| 270 | + |
---|
| 271 | +Example Module |
---|
| 272 | +-------------- |
---|
| 273 | + |
---|
| 274 | +A bare bones test module might look like this: |
---|
| 275 | + |
---|
| 276 | +.. code-block:: c |
---|
| 277 | + |
---|
| 278 | + // SPDX-License-Identifier: GPL-2.0+ |
---|
| 279 | + |
---|
| 280 | + #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt |
---|
| 281 | + |
---|
| 282 | + #include "../tools/testing/selftests/kselftest/module.h" |
---|
| 283 | + |
---|
| 284 | + KSTM_MODULE_GLOBALS(); |
---|
| 285 | + |
---|
| 286 | + /* |
---|
| 287 | + * Kernel module for testing the foobinator |
---|
| 288 | + */ |
---|
| 289 | + |
---|
| 290 | + static int __init test_function() |
---|
| 291 | + { |
---|
| 292 | + ... |
---|
| 293 | + } |
---|
| 294 | + |
---|
| 295 | + static void __init selftest(void) |
---|
| 296 | + { |
---|
| 297 | + KSTM_CHECK_ZERO(do_test_case("", 0)); |
---|
| 298 | + } |
---|
| 299 | + |
---|
| 300 | + KSTM_MODULE_LOADERS(test_foo); |
---|
| 301 | + MODULE_AUTHOR("John Developer <jd@fooman.org>"); |
---|
| 302 | + MODULE_LICENSE("GPL"); |
---|
| 303 | + |
---|
| 304 | +Example test script |
---|
| 305 | +------------------- |
---|
| 306 | + |
---|
| 307 | +.. code-block:: sh |
---|
| 308 | + |
---|
| 309 | + #!/bin/bash |
---|
| 310 | + # SPDX-License-Identifier: GPL-2.0+ |
---|
| 311 | + $(dirname $0)/../kselftest/module.sh "foo" test_foo |
---|
| 312 | + |
---|
163 | 313 | |
---|
164 | 314 | Test Harness |
---|
165 | 315 | ============ |
---|
166 | 316 | |
---|
167 | | -The kselftest_harness.h file contains useful helpers to build tests. The tests |
---|
168 | | -from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example. |
---|
| 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 |
---|
| 319 | +Module`_ above. |
---|
| 320 | + |
---|
| 321 | +The tests from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as |
---|
| 322 | +example. |
---|
169 | 323 | |
---|
170 | 324 | Example |
---|
171 | 325 | ------- |
---|
.. | .. |
---|
179 | 333 | |
---|
180 | 334 | .. kernel-doc:: tools/testing/selftests/kselftest_harness.h |
---|
181 | 335 | :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP |
---|
182 | | - FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN |
---|
| 336 | + FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN FIXTURE_VARIANT |
---|
| 337 | + FIXTURE_VARIANT_ADD |
---|
183 | 338 | |
---|
184 | 339 | Operators |
---|
185 | 340 | --------- |
---|