Linux/Documentation/dev-tools/kselftest.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

1 ====================== 1 ====================== 2 Linux Kernel Selftests 2 Linux Kernel Selftests 3 ====================== 3 ====================== 4 4 5 The kernel contains a set of "self tests" unde 5 The kernel contains a set of "self tests" under the tools/testing/selftests/ 6 directory. These are intended to be small test 6 directory. These are intended to be small tests to exercise individual code 7 paths in the kernel. Tests are intended to be 7 paths in the kernel. Tests are intended to be run after building, installing 8 and booting a kernel. 8 and booting a kernel. 9 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 10 On some systems, hot-plug tests could hang forever waiting for cpu and 24 memory to be ready to be offlined. A special h 11 memory to be ready to be offlined. A special hot-plug target is created 25 to run the full range of hot-plug tests. In de 12 to run the full range of hot-plug tests. In default mode, hot-plug tests run 26 in safe mode with a limited scope. In limited 13 in safe mode with a limited scope. In limited mode, cpu-hotplug test is 27 run on a single cpu as opposed to all hotplug 14 run on a single cpu as opposed to all hotplug capable cpus, and memory 28 hotplug test is run on 2% of hotplug capable m 15 hotplug test is run on 2% of hotplug capable memory instead of 10%. 29 16 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 17 Running the selftests (hotplug tests are run in limited mode) 35 ============================================== 18 ============================================================= 36 19 37 To build the tests:: 20 To build the tests:: 38 21 39 $ make headers << 40 $ make -C tools/testing/selftests 22 $ make -C tools/testing/selftests 41 23 42 To run the tests:: 24 To run the tests:: 43 25 44 $ make -C tools/testing/selftests run_tests 26 $ make -C tools/testing/selftests run_tests 45 27 46 To build and run the tests with a single comma 28 To build and run the tests with a single command, use:: 47 29 48 $ make kselftest 30 $ make kselftest 49 31 50 Note that some tests will require root privile 32 Note that some tests will require root privileges. 51 33 52 Kselftest supports saving output files in a se !! 34 Build and run from user specific object directory (make O=dir):: 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 35 60 $ make O=/tmp/kselftest kselftest 36 $ make O=/tmp/kselftest kselftest 61 37 62 To build, save output files in a separate dire !! 38 Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=):: 63 39 64 $ export KBUILD_OUTPUT=/tmp/kselftest; make !! 40 $ make KBUILD_OUTPUT=/tmp/kselftest kselftest 65 41 66 The O= assignment takes precedence over the KB !! 42 The above commands run the tests and print pass/fail summary to make it 67 variable. !! 43 easier to understand the test results. Please find the detailed individual 68 !! 44 test results for each test in /tmp/testname file(s). 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 45 79 Running a subset of selftests 46 Running a subset of selftests 80 ============================= 47 ============================= 81 48 82 You can use the "TARGETS" variable on the make 49 You can use the "TARGETS" variable on the make command line to specify 83 single test to run, or a list of tests to run. 50 single test to run, or a list of tests to run. 84 51 85 To run only tests targeted for a single subsys 52 To run only tests targeted for a single subsystem:: 86 53 87 $ make -C tools/testing/selftests TARGETS=pt 54 $ make -C tools/testing/selftests TARGETS=ptrace run_tests 88 55 89 You can specify multiple tests to build and ru 56 You can specify multiple tests to build and run:: 90 57 91 $ make TARGETS="size timers" kselftest 58 $ make TARGETS="size timers" kselftest 92 59 93 To build, save output files in a separate dire !! 60 Build and run from user specific object directory (make O=dir):: 94 61 95 $ make O=/tmp/kselftest TARGETS="size timers 62 $ make O=/tmp/kselftest TARGETS="size timers" kselftest 96 63 97 To build, save output files in a separate dire !! 64 Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=):: 98 << 99 $ export KBUILD_OUTPUT=/tmp/kselftest; make << 100 65 101 Additionally you can use the "SKIP_TARGETS" va !! 66 $ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest 102 line to specify one or more targets to exclude << 103 67 104 To run all tests but a single subsystem:: !! 68 The above commands run the tests and print pass/fail summary to make it 105 !! 69 easier to understand the test results. Please find the detailed individual 106 $ make -C tools/testing/selftests SKIP_TARGE !! 70 test results for each test in /tmp/testname file(s). 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 71 117 See the top-level tools/testing/selftests/Make 72 See the top-level tools/testing/selftests/Makefile for the list of all 118 possible targets. 73 possible targets. 119 74 120 Running the full range hotplug selftests 75 Running the full range hotplug selftests 121 ======================================== 76 ======================================== 122 77 123 To build the hotplug tests:: 78 To build the hotplug tests:: 124 79 125 $ make -C tools/testing/selftests hotplug 80 $ make -C tools/testing/selftests hotplug 126 81 127 To run the hotplug tests:: 82 To run the hotplug tests:: 128 83 129 $ make -C tools/testing/selftests run_hotplu 84 $ make -C tools/testing/selftests run_hotplug 130 85 131 Note that some tests will require root privile 86 Note that some tests will require root privileges. 132 87 133 88 134 Install selftests 89 Install selftests 135 ================= 90 ================= 136 91 137 You can use the "install" target of "make" (wh !! 92 You can use the kselftest_install.sh tool to install selftests in the 138 tool) to install selftests in the default loca !! 93 default location, which is tools/testing/selftests/kselftest, or in a 139 or in a user specified location via the `INSTA !! 94 user specified location. 140 95 141 To install selftests in default location:: 96 To install selftests in default location:: 142 97 143 $ make -C tools/testing/selftests install !! 98 $ cd tools/testing/selftests >> 99 $ ./kselftest_install.sh 144 100 145 To install selftests in a user specified locat 101 To install selftests in a user specified location:: 146 102 147 $ make -C tools/testing/selftests install I !! 103 $ cd tools/testing/selftests >> 104 $ ./kselftest_install.sh install_dir 148 105 149 Running installed selftests 106 Running installed selftests 150 =========================== 107 =========================== 151 108 152 Found in the install directory, as well as in !! 109 Kselftest install as well as the Kselftest tarball provide a script 153 is a script named `run_kselftest.sh` to run th !! 110 named "run_kselftest.sh" to run the tests. 154 111 155 You can simply do the following to run the ins 112 You can simply do the following to run the installed Kselftests. Please 156 note some tests will require root privileges:: 113 note some tests will require root privileges:: 157 114 158 $ cd kselftest_install !! 115 $ cd kselftest 159 $ ./run_kselftest.sh 116 $ ./run_kselftest.sh 160 117 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 118 Contributing new tests 218 ====================== 119 ====================== 219 120 220 In general, the rules for selftests are 121 In general, the rules for selftests are 221 122 222 * Do as much as you can if you're not root; 123 * Do as much as you can if you're not root; 223 124 224 * Don't take too long; 125 * Don't take too long; 225 126 226 * Don't break the build on any architecture, 127 * Don't break the build on any architecture, and 227 128 228 * Don't cause the top-level "make run_tests" 129 * Don't cause the top-level "make run_tests" to fail if your feature is 229 unconfigured. 130 unconfigured. 230 131 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) 132 Contributing new tests (details) 239 ================================ 133 ================================ 240 134 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 135 * Use TEST_GEN_XXX if such binaries or files are generated during 250 compiling. 136 compiling. 251 137 252 TEST_PROGS, TEST_GEN_PROGS mean it is the e 138 TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by 253 default. 139 default. 254 140 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 141 TEST_CUSTOM_PROGS should be used by tests that require custom build 260 rules and prevent common build rule use. 142 rules and prevent common build rule use. 261 143 262 TEST_PROGS are for test shell scripts. Plea 144 TEST_PROGS are for test shell scripts. Please ensure shell script has 263 its exec bit set. Otherwise, lib.mk run_tes 145 its exec bit set. Otherwise, lib.mk run_tests will generate a warning. 264 146 265 TEST_CUSTOM_PROGS and TEST_PROGS will be ru 147 TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests. 266 148 267 TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDE 149 TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the 268 executable which is not tested by default. 150 executable which is not tested by default. 269 << 270 TEST_FILES, TEST_GEN_FILES mean it is the f 151 TEST_FILES, TEST_GEN_FILES mean it is the file which is used by 271 test. 152 test. 272 153 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 154 * First use the headers inside the kernel source and/or git repo, and then the 285 system headers. Headers for the kernel rel 155 system headers. Headers for the kernel release as opposed to headers 286 installed by the distro on the system shoul 156 installed by the distro on the system should be the primary focus to be able 287 to find regressions. Use KHDR_INCLUDES in M !! 157 to find regressions. 288 the kernel source. << 289 158 290 * If a test needs specific kernel config opti 159 * If a test needs specific kernel config options enabled, add a config file in 291 the test directory to enable them. 160 the test directory to enable them. 292 161 293 e.g: tools/testing/selftests/android/config 162 e.g: tools/testing/selftests/android/config 294 163 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 164 Test Harness 403 ============ 165 ============ 404 166 405 The kselftest_harness.h file contains useful h !! 167 The kselftest_harness.h file contains useful helpers to build tests. The tests 406 test harness is for userspace testing, for ker !! 168 from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example. 407 Module`_ above. << 408 << 409 The tests from tools/testing/selftests/seccomp << 410 example. << 411 169 412 Example 170 Example 413 ------- 171 ------- 414 172 415 .. kernel-doc:: tools/testing/selftests/kselft 173 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h 416 :doc: example 174 :doc: example 417 175 418 176 419 Helpers 177 Helpers 420 ------- 178 ------- 421 179 422 .. kernel-doc:: tools/testing/selftests/kselft 180 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h 423 :functions: TH_LOG TEST TEST_SIGNAL FIXTUR 181 :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP 424 FIXTURE_TEARDOWN TEST_F TEST_H !! 182 FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN 425 FIXTURE_VARIANT_ADD << 426 183 427 Operators 184 Operators 428 --------- 185 --------- 429 186 430 .. kernel-doc:: tools/testing/selftests/kselft 187 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h 431 :doc: operators 188 :doc: operators 432 189 433 .. kernel-doc:: tools/testing/selftests/kselft 190 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h 434 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT 191 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE 435 ASSERT_NULL ASSERT_TRUE ASSERT 192 ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE 436 ASSERT_STREQ ASSERT_STRNE EXPE 193 ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT 437 EXPECT_LE EXPECT_GT EXPECT_GE 194 EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE 438 EXPECT_FALSE EXPECT_STREQ EXPE 195 EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

TOMOYO Linux Cross Reference
Linux/Documentation/dev-tools/kselftest.rst

Diff markup

Differences between /Documentation/dev-tools/kselftest.rst (Version linux-6.12-rc7) and /Documentation/dev-tools/kselftest.rst (Version linux-5.1.21)

TOMOYO Linux Cross Reference Linux/Documentation/dev-tools/kselftest.rst

Diff markup

Differences between /Documentation/dev-tools/kselftest.rst (Version linux-6.12-rc7) and /Documentation/dev-tools/kselftest.rst (Version linux-5.1.21)

TOMOYO Linux Cross Reference
Linux/Documentation/dev-tools/kselftest.rst