1 ======================
2 Linux Kernel Selftests
3 ======================
4
5 The kernel contains a set of "self tests" unde
6 directory. These are intended to be small test
7 paths in the kernel. Tests are intended to be
8 and booting a kernel.
9
10 Kselftest from mainline can be run on older st
11 from mainline offers the best coverage. Severa
12 kselftest suite on stable releases. The reason
13 gets added to test existing code to regression
14 able to run that test on an older kernel. Henc
15 code that can still test an older kernel and m
16 gracefully on newer releases.
17
18 You can find additional information on Kselfte
19 write new tests using the framework on Kselfte
20
21 https://kselftest.wiki.kernel.org/
22
23 On some systems, hot-plug tests could hang for
24 memory to be ready to be offlined. A special h
25 to run the full range of hot-plug tests. In de
26 in safe mode with a limited scope. In limited
27 run on a single cpu as opposed to all hotplug
28 hotplug test is run on 2% of hotplug capable m
29
30 kselftest runs as a userspace process. Tests
31 userspace may wish to use the `Test Harness`_.
32 run in kernel space may wish to use a `Test Mo
33
34 Running the selftests (hotplug tests are run i
35 ==============================================
36
37 To build the tests::
38
39 $ make headers
40 $ make -C tools/testing/selftests
41
42 To run the tests::
43
44 $ make -C tools/testing/selftests run_tests
45
46 To build and run the tests with a single comma
47
48 $ make kselftest
49
50 Note that some tests will require root privile
51
52 Kselftest supports saving output files in a se
53 running tests. To locate output files in a sep
54 are supported. In both cases the working direc
55 kernel src. This is applicable to "Running a s
56 below.
57
58 To build, save output files in a separate dire
59
60 $ make O=/tmp/kselftest kselftest
61
62 To build, save output files in a separate dire
63
64 $ export KBUILD_OUTPUT=/tmp/kselftest; make
65
66 The O= assignment takes precedence over the KB
67 variable.
68
69 The above commands by default run the tests an
70 Kselftest supports "summary" option to make it
71 results. Please find the detailed individual t
72 /tmp/testname file(s) when summary option is s
73 to "Running a subset of selftests" section bel
74
75 To run kselftest with summary option enabled :
76
77 $ make summary=1 kselftest
78
79 Running a subset of selftests
80 =============================
81
82 You can use the "TARGETS" variable on the make
83 single test to run, or a list of tests to run.
84
85 To run only tests targeted for a single subsys
86
87 $ make -C tools/testing/selftests TARGETS=pt
88
89 You can specify multiple tests to build and ru
90
91 $ make TARGETS="size timers" kselftest
92
93 To build, save output files in a separate dire
94
95 $ make O=/tmp/kselftest TARGETS="size timers
96
97 To build, save output files in a separate dire
98
99 $ export KBUILD_OUTPUT=/tmp/kselftest; make
100
101 Additionally you can use the "SKIP_TARGETS" va
102 line to specify one or more targets to exclude
103
104 To run all tests but a single subsystem::
105
106 $ make -C tools/testing/selftests SKIP_TARGE
107
108 You can specify multiple tests to skip::
109
110 $ make SKIP_TARGETS="size timers" kselftest
111
112 You can also specify a restricted list of test
113 dedicated skiplist::
114
115 $ make TARGETS="breakpoints size timers" SK
116
117 See the top-level tools/testing/selftests/Make
118 possible targets.
119
120 Running the full range hotplug selftests
121 ========================================
122
123 To build the hotplug tests::
124
125 $ make -C tools/testing/selftests hotplug
126
127 To run the hotplug tests::
128
129 $ make -C tools/testing/selftests run_hotplu
130
131 Note that some tests will require root privile
132
133
134 Install selftests
135 =================
136
137 You can use the "install" target of "make" (wh
138 tool) to install selftests in the default loca
139 or in a user specified location via the `INSTA
140
141 To install selftests in default location::
142
143 $ make -C tools/testing/selftests install
144
145 To install selftests in a user specified locat
146
147 $ make -C tools/testing/selftests install I
148
149 Running installed selftests
150 ===========================
151
152 Found in the install directory, as well as in
153 is a script named `run_kselftest.sh` to run th
154
155 You can simply do the following to run the ins
156 note some tests will require root privileges::
157
158 $ cd kselftest_install
159 $ ./run_kselftest.sh
160
161 To see the list of available tests, the `-l` o
162
163 $ ./run_kselftest.sh -l
164
165 The `-c` option can be used to run all the tes
166 the `-t` option for specific single tests. Eit
167
168 $ ./run_kselftest.sh -c size -c seccomp -t
169
170 For other features see the script usage output
171
172 Timeout for selftests
173 =====================
174
175 Selftests are designed to be quick and so a de
176 seconds for each test. Tests can override the
177 a settings file in their directory and set a t
178 configured a desired upper timeout for the tes
179 the timeout with a value higher than 45 second
180 it that way. Timeouts in selftests are not con
181 system under which a test runs may change and
182 expected time it takes to run a test. If you h
183 which will run the tests you can configure a t
184 use a greater or lower timeout on the command
185 the `--override-timeout` argument. For example
186 one would use::
187
188 $ ./run_kselftest.sh --override-timeout 165
189
190 You can look at the TAP output to see if you r
191 runners which know a test must run under a spe
192 treat these timeouts then as fatal.
193
194 Packaging selftests
195 ===================
196
197 In some cases packaging is desired, such as wh
198 different system. To package selftests, run::
199
200 $ make -C tools/testing/selftests gen_tar
201
202 This generates a tarball in the `INSTALL_PATH/
203 default, `.gz` format is used. The tar compres
204 specifying a `FORMAT` make variable. Any value
205 option is supported, such as::
206
207 $ make -C tools/testing/selftests gen_tar
208
209 `make gen_tar` invokes `make install` so you c
210 tests by using variables specified in `Running
211 section::
212
213 $ make -C tools/testing/selftests gen_tar
214
215 .. _tar's auto-compress: https://www.gnu.org/s
216
217 Contributing new tests
218 ======================
219
220 In general, the rules for selftests are
221
222 * Do as much as you can if you're not root;
223
224 * Don't take too long;
225
226 * Don't break the build on any architecture,
227
228 * Don't cause the top-level "make run_tests"
229 unconfigured.
230
231 * The output of tests must conform to the TAP
232 testing quality and to capture failures/err
233 The kselftest.h and kselftest_harness.h hea
234 outputting test results. These wrappers sho
235 fail, exit, and skip messages. CI systems c
236 messages to detect test results.
237
238 Contributing new tests (details)
239 ================================
240
241 * In your Makefile, use facilities from lib.m
242 reinventing the wheel. Specify flags and bi
243 need basis before including lib.mk. ::
244
245 CFLAGS = $(KHDR_INCLUDES)
246 TEST_GEN_PROGS := close_range_test
247 include ../lib.mk
248
249 * Use TEST_GEN_XXX if such binaries or files
250 compiling.
251
252 TEST_PROGS, TEST_GEN_PROGS mean it is the e
253 default.
254
255 TEST_GEN_MODS_DIR should be used by tests t
256 before the test starts. The variable will c
257 containing the modules.
258
259 TEST_CUSTOM_PROGS should be used by tests t
260 rules and prevent common build rule use.
261
262 TEST_PROGS are for test shell scripts. Plea
263 its exec bit set. Otherwise, lib.mk run_tes
264
265 TEST_CUSTOM_PROGS and TEST_PROGS will be ru
266
267 TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDE
268 executable which is not tested by default.
269
270 TEST_FILES, TEST_GEN_FILES mean it is the f
271 test.
272
273 TEST_INCLUDES is similar to TEST_FILES, it
274 included when exporting or installing the t
275 differences:
276
277 * symlinks to files in other directories a
278 * the part of paths below tools/testing/se
279 copying the files to the output director
280
281 TEST_INCLUDES is meant to list dependencies
282 the selftests hierarchy.
283
284 * First use the headers inside the kernel sou
285 system headers. Headers for the kernel rel
286 installed by the distro on the system shoul
287 to find regressions. Use KHDR_INCLUDES in M
288 the kernel source.
289
290 * If a test needs specific kernel config opti
291 the test directory to enable them.
292
293 e.g: tools/testing/selftests/android/config
294
295 * Create a .gitignore file inside test direct
296 in it.
297
298 * Add new test name in TARGETS in selftests/M
299
300 TARGETS += android
301
302 * All changes should pass::
303
304 kselftest-{all,install,clean,gen_tar}
305 kselftest-{all,install,clean,gen_tar} O=ab
306 kselftest-{all,install,clean,gen_tar} O=re
307 make -C tools/testing/selftests {all,insta
308 make -C tools/testing/selftests {all,insta
309 make -C tools/testing/selftests {all,insta
310
311 Test Module
312 ===========
313
314 Kselftest tests the kernel from userspace. So
315 testing from within the kernel, one method of
316 test module. We can tie the module into the k
317 using a shell script test runner. ``kselftest
318 to facilitate this process. There is also a h
319 assist writing kernel modules that are for use
320
321 - ``tools/testing/selftests/kselftest_module.h
322 - ``tools/testing/selftests/kselftest/module.s
323
324 Note that test modules should taint the kernel
325 happen automatically for modules which are in
326 directory, or for modules which use the ``ksel
327 Otherwise, you'll need to add ``MODULE_INFO(te
328 source. selftests which do not load modules ty
329 kernel, but in cases where a non-test module i
330 applied from userspace by writing to ``/proc/s
331
332 How to use
333 ----------
334
335 Here we show the typical steps to create a tes
336 kselftest. We use kselftests for lib/ as an e
337
338 1. Create the test module
339
340 2. Create the test script that will run (load/
341 e.g. ``tools/testing/selftests/lib/printf.s
342
343 3. Add line to config file e.g. ``tools/testin
344
345 4. Add test script to makefile e.g. ``tools/t
346
347 5. Verify it works:
348
349 .. code-block:: sh
350
351 # Assumes you have booted a fresh build of
352 cd /path/to/linux/tree
353 make kselftest-merge
354 make modules
355 sudo make modules_install
356 make TARGETS=lib kselftest
357
358 Example Module
359 --------------
360
361 A bare bones test module might look like this:
362
363 .. code-block:: c
364
365 // SPDX-License-Identifier: GPL-2.0+
366
367 #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
368
369 #include "../tools/testing/selftests/kselft
370
371 KSTM_MODULE_GLOBALS();
372
373 /*
374 * Kernel module for testing the foobinator
375 */
376
377 static int __init test_function()
378 {
379 ...
380 }
381
382 static void __init selftest(void)
383 {
384 KSTM_CHECK_ZERO(do_test_case("", 0)
385 }
386
387 KSTM_MODULE_LOADERS(test_foo);
388 MODULE_AUTHOR("John Developer <jd@fooman.org
389 MODULE_LICENSE("GPL");
390 MODULE_INFO(test, "Y");
391
392 Example test script
393 -------------------
394
395 .. code-block:: sh
396
397 #!/bin/bash
398 # SPDX-License-Identifier: GPL-2.0+
399 $(dirname $0)/../kselftest/module.sh "foo"
400
401
402 Test Harness
403 ============
404
405 The kselftest_harness.h file contains useful h
406 test harness is for userspace testing, for ker
407 Module`_ above.
408
409 The tests from tools/testing/selftests/seccomp
410 example.
411
412 Example
413 -------
414
415 .. kernel-doc:: tools/testing/selftests/kselft
416 :doc: example
417
418
419 Helpers
420 -------
421
422 .. kernel-doc:: tools/testing/selftests/kselft
423 :functions: TH_LOG TEST TEST_SIGNAL FIXTUR
424 FIXTURE_TEARDOWN TEST_F TEST_H
425 FIXTURE_VARIANT_ADD
426
427 Operators
428 ---------
429
430 .. kernel-doc:: tools/testing/selftests/kselft
431 :doc: operators
432
433 .. kernel-doc:: tools/testing/selftests/kselft
434 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT
435 ASSERT_NULL ASSERT_TRUE ASSERT
436 ASSERT_STREQ ASSERT_STRNE EXPE
437 EXPECT_LE EXPECT_GT EXPECT_GE
438 EXPECT_FALSE EXPECT_STREQ EXPE
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.