hc
2023-12-11 d2ccde1c8e90d38cee87a1b0309ad2827f3fd30d
kernel/Documentation/dev-tools/kselftest.rst
....@@ -7,12 +7,21 @@
77 paths in the kernel. Tests are intended to be run after building, installing
88 and booting a kernel.
99
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
+
1015 On some systems, hot-plug tests could hang forever waiting for cpu and
1116 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
1318 in safe mode with a limited scope. In limited mode, cpu-hotplug test is
1419 run on a single cpu as opposed to all hotplug capable cpus, and memory
1520 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`_.
1625
1726 Running the selftests (hotplug tests are run in limited mode)
1827 =============================================================
....@@ -31,17 +40,32 @@
3140
3241 Note that some tests will require root privileges.
3342
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= ::
3550
3651 $ make O=/tmp/kselftest kselftest
3752
38
-Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
53
+To build, save output files in a separate directory with KBUILD_OUTPUT ::
3954
40
- $ make KBUILD_OUTPUT=/tmp/kselftest kselftest
55
+ $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
4156
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
4569
4670 Running a subset of selftests
4771 =============================
....@@ -57,17 +81,29 @@
5781
5882 $ make TARGETS="size timers" kselftest
5983
60
-Build and run from user specific object directory (make O=dir)::
84
+To build, save output files in a separate directory with O= ::
6185
6286 $ make O=/tmp/kselftest TARGETS="size timers" kselftest
6387
64
-Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
88
+To build, save output files in a separate directory with KBUILD_OUTPUT ::
6589
66
- $ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest
90
+ $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest
6791
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
71107
72108 See the top-level tools/testing/selftests/Makefile for the list of all
73109 possible targets.
....@@ -89,31 +125,63 @@
89125 Install selftests
90126 =================
91127
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.
95131
96132 To install selftests in default location::
97133
98
- $ cd tools/testing/selftests
99
- $ ./kselftest_install.sh
134
+ $ make -C tools/testing/selftests install
100135
101136 To install selftests in a user specified location::
102137
103
- $ cd tools/testing/selftests
104
- $ ./kselftest_install.sh install_dir
138
+ $ make -C tools/testing/selftests install INSTALL_PATH=/some/other/path
105139
106140 Running installed selftests
107141 ===========================
108142
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.
111145
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
113147 note some tests will require root privileges::
114148
115
- $ cd kselftest
149
+ $ cd kselftest_install
116150 $ ./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
117185
118186 Contributing new tests
119187 ======================
....@@ -139,7 +207,7 @@
139207 default.
140208
141209 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.
143211
144212 TEST_PROGS are for test shell scripts. Please ensure shell script has
145213 its exec bit set. Otherwise, lib.mk run_tests will generate a warning.
....@@ -159,13 +227,99 @@
159227 * If a test needs specific kernel config options enabled, add a config file in
160228 the test directory to enable them.
161229
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
+
163313
164314 Test Harness
165315 ============
166316
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.
169323
170324 Example
171325 -------
....@@ -179,7 +333,8 @@
179333
180334 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
181335 :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
183338
184339 Operators
185340 ---------