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 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 << 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 34 79 Running a subset of selftests 35 Running a subset of selftests 80 ============================= 36 ============================= 81 37 82 You can use the "TARGETS" variable on the make 38 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. 39 single test to run, or a list of tests to run. 84 40 85 To run only tests targeted for a single subsys 41 To run only tests targeted for a single subsystem:: 86 42 87 $ make -C tools/testing/selftests TARGETS=pt 43 $ make -C tools/testing/selftests TARGETS=ptrace run_tests 88 44 89 You can specify multiple tests to build and ru 45 You can specify multiple tests to build and run:: 90 46 91 $ make TARGETS="size timers" kselftest 47 $ make TARGETS="size timers" kselftest 92 48 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 49 See the top-level tools/testing/selftests/Makefile for the list of all 118 possible targets. 50 possible targets. 119 51 >> 52 120 Running the full range hotplug selftests 53 Running the full range hotplug selftests 121 ======================================== 54 ======================================== 122 55 123 To build the hotplug tests:: 56 To build the hotplug tests:: 124 57 125 $ make -C tools/testing/selftests hotplug 58 $ make -C tools/testing/selftests hotplug 126 59 127 To run the hotplug tests:: 60 To run the hotplug tests:: 128 61 129 $ make -C tools/testing/selftests run_hotplu 62 $ make -C tools/testing/selftests run_hotplug 130 63 131 Note that some tests will require root privile 64 Note that some tests will require root privileges. 132 65 133 66 134 Install selftests 67 Install selftests 135 ================= 68 ================= 136 69 137 You can use the "install" target of "make" (wh !! 70 You can use kselftest_install.sh tool installs selftests in default 138 tool) to install selftests in the default loca !! 71 location which is tools/testing/selftests/kselftest or a user specified 139 or in a user specified location via the `INSTA !! 72 location. 140 73 141 To install selftests in default location:: 74 To install selftests in default location:: 142 75 143 $ make -C tools/testing/selftests install !! 76 $ cd tools/testing/selftests >> 77 $ ./kselftest_install.sh 144 78 145 To install selftests in a user specified locat 79 To install selftests in a user specified location:: 146 80 147 $ make -C tools/testing/selftests install I !! 81 $ cd tools/testing/selftests >> 82 $ ./kselftest_install.sh install_dir 148 83 149 Running installed selftests 84 Running installed selftests 150 =========================== 85 =========================== 151 86 152 Found in the install directory, as well as in !! 87 Kselftest install as well as the Kselftest tarball provide a script 153 is a script named `run_kselftest.sh` to run th !! 88 named "run_kselftest.sh" to run the tests. 154 89 155 You can simply do the following to run the ins !! 90 You can simply do the following to run the installed Kselftests. Please 156 note some tests will require root privileges:: 91 note some tests will require root privileges:: 157 92 158 $ cd kselftest_install !! 93 $ cd kselftest 159 $ ./run_kselftest.sh 94 $ ./run_kselftest.sh 160 95 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 96 Contributing new tests 218 ====================== 97 ====================== 219 98 220 In general, the rules for selftests are 99 In general, the rules for selftests are 221 100 222 * Do as much as you can if you're not root; 101 * Do as much as you can if you're not root; 223 102 224 * Don't take too long; 103 * Don't take too long; 225 104 226 * Don't break the build on any architecture, 105 * Don't break the build on any architecture, and 227 106 228 * Don't cause the top-level "make run_tests" 107 * Don't cause the top-level "make run_tests" to fail if your feature is 229 unconfigured. 108 unconfigured. 230 109 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) 110 Contributing new tests (details) 239 ================================ 111 ================================ 240 112 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 113 * Use TEST_GEN_XXX if such binaries or files are generated during 250 compiling. 114 compiling. 251 115 252 TEST_PROGS, TEST_GEN_PROGS mean it is the e !! 116 TEST_PROGS, TEST_GEN_PROGS mean it is the excutable tested by 253 default. 117 default. 254 118 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 119 TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the 268 executable which is not tested by default. 120 executable which is not tested by default. 269 << 270 TEST_FILES, TEST_GEN_FILES mean it is the f 121 TEST_FILES, TEST_GEN_FILES mean it is the file which is used by 271 test. 122 test. 272 123 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 124 Test Harness 403 ============ 125 ============ 404 126 405 The kselftest_harness.h file contains useful h !! 127 The kselftest_harness.h file contains useful helpers to build tests. The tests 406 test harness is for userspace testing, for ker !! 128 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 129 412 Example 130 Example 413 ------- 131 ------- 414 132 415 .. kernel-doc:: tools/testing/selftests/kselft 133 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h 416 :doc: example 134 :doc: example 417 135 418 136 419 Helpers 137 Helpers 420 ------- 138 ------- 421 139 422 .. kernel-doc:: tools/testing/selftests/kselft 140 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h 423 :functions: TH_LOG TEST TEST_SIGNAL FIXTUR 141 :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP 424 FIXTURE_TEARDOWN TEST_F TEST_H !! 142 FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN 425 FIXTURE_VARIANT_ADD << 426 143 427 Operators 144 Operators 428 --------- 145 --------- 429 146 430 .. kernel-doc:: tools/testing/selftests/kselft 147 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h 431 :doc: operators 148 :doc: operators 432 149 433 .. kernel-doc:: tools/testing/selftests/kselft 150 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h 434 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT 151 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE 435 ASSERT_NULL ASSERT_TRUE ASSERT 152 ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE 436 ASSERT_STREQ ASSERT_STRNE EXPE 153 ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT 437 EXPECT_LE EXPECT_GT EXPECT_GE 154 EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE 438 EXPECT_FALSE EXPECT_STREQ EXPE 155 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-4.14.336)

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-4.14.336)

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