1====================== 2Linux Kernel Selftests 3====================== 4 5The kernel contains a set of "self tests" under the tools/testing/selftests/ 6directory. These are intended to be small tests to exercise individual code 7paths in the kernel. Tests are intended to be run after building, installing 8and booting a kernel. 9 10You can find additional information on Kselftest framework, how to 11write new tests using the framework on Kselftest wiki: 12 13https://kselftest.wiki.kernel.org/ 14 15On some systems, hot-plug tests could hang forever waiting for cpu and 16memory to be ready to be offlined. A special hot-plug target is created 17to run the full range of hot-plug tests. In default mode, hot-plug tests run 18in safe mode with a limited scope. In limited mode, cpu-hotplug test is 19run on a single cpu as opposed to all hotplug capable cpus, and memory 20hotplug test is run on 2% of hotplug capable memory instead of 10%. 21 22kselftest runs as a userspace process. Tests that can be written/run in 23userspace may wish to use the `Test Harness`_. Tests that need to be 24run in kernel space may wish to use a `Test Module`_. 25 26Running the selftests (hotplug tests are run in limited mode) 27============================================================= 28 29To build the tests:: 30 31 $ make -C tools/testing/selftests 32 33To run the tests:: 34 35 $ make -C tools/testing/selftests run_tests 36 37To build and run the tests with a single command, use:: 38 39 $ make kselftest 40 41Note that some tests will require root privileges. 42 43Kselftest supports saving output files in a separate directory and then 44running tests. To locate output files in a separate directory two syntaxes 45are supported. In both cases the working directory must be the root of the 46kernel src. This is applicable to "Running a subset of selftests" section 47below. 48 49To build, save output files in a separate directory with O= :: 50 51 $ make O=/tmp/kselftest kselftest 52 53To build, save output files in a separate directory with KBUILD_OUTPUT :: 54 55 $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest 56 57The O= assignment takes precedence over the KBUILD_OUTPUT environment 58variable. 59 60The above commands by default run the tests and print full pass/fail report. 61Kselftest supports "summary" option to make it easier to understand the test 62results. Please find the detailed individual test results for each test in 63/tmp/testname file(s) when summary option is specified. This is applicable 64to "Running a subset of selftests" section below. 65 66To run kselftest with summary option enabled :: 67 68 $ make summary=1 kselftest 69 70Running a subset of selftests 71============================= 72 73You can use the "TARGETS" variable on the make command line to specify 74single test to run, or a list of tests to run. 75 76To run only tests targeted for a single subsystem:: 77 78 $ make -C tools/testing/selftests TARGETS=ptrace run_tests 79 80You can specify multiple tests to build and run:: 81 82 $ make TARGETS="size timers" kselftest 83 84To build, save output files in a separate directory with O= :: 85 86 $ make O=/tmp/kselftest TARGETS="size timers" kselftest 87 88To build, save output files in a separate directory with KBUILD_OUTPUT :: 89 90 $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest 91 92Additionally you can use the "SKIP_TARGETS" variable on the make command 93line to specify one or more targets to exclude from the TARGETS list. 94 95To run all tests but a single subsystem:: 96 97 $ make -C tools/testing/selftests SKIP_TARGETS=ptrace run_tests 98 99You can specify multiple tests to skip:: 100 101 $ make SKIP_TARGETS="size timers" kselftest 102 103You can also specify a restricted list of tests to run together with a 104dedicated skiplist:: 105 106 $ make TARGETS="bpf breakpoints size timers" SKIP_TARGETS=bpf kselftest 107 108See the top-level tools/testing/selftests/Makefile for the list of all 109possible targets. 110 111Running the full range hotplug selftests 112======================================== 113 114To build the hotplug tests:: 115 116 $ make -C tools/testing/selftests hotplug 117 118To run the hotplug tests:: 119 120 $ make -C tools/testing/selftests run_hotplug 121 122Note that some tests will require root privileges. 123 124 125Install selftests 126================= 127 128You can use the kselftest_install.sh tool to install selftests in the 129default location, which is tools/testing/selftests/kselftest, or in a 130user specified location. 131 132To install selftests in default location:: 133 134 $ cd tools/testing/selftests 135 $ ./kselftest_install.sh 136 137To install selftests in a user specified location:: 138 139 $ cd tools/testing/selftests 140 $ ./kselftest_install.sh install_dir 141 142Running installed selftests 143=========================== 144 145Kselftest install as well as the Kselftest tarball provide a script 146named "run_kselftest.sh" to run the tests. 147 148You can simply do the following to run the installed Kselftests. Please 149note some tests will require root privileges:: 150 151 $ cd kselftest 152 $ ./run_kselftest.sh 153 154Packaging selftests 155=================== 156 157In some cases packaging is desired, such as when tests need to run on a 158different system. To package selftests, run:: 159 160 $ make -C tools/testing/selftests gen_tar 161 162This generates a tarball in the `INSTALL_PATH/kselftest-packages` directory. By 163default, `.gz` format is used. The tar format can be overridden by specifying 164a `FORMAT` make variable. Any value recognized by `tar's auto-compress`_ option 165is supported, such as:: 166 167 $ make -C tools/testing/selftests gen_tar FORMAT=.xz 168 169`make gen_tar` invokes `make install` so you can use it to package a subset of 170tests by using variables specified in `Running a subset of selftests`_ 171section:: 172 173 $ make -C tools/testing/selftests gen_tar TARGETS="bpf" FORMAT=.xz 174 175.. _tar's auto-compress: https://www.gnu.org/software/tar/manual/html_node/gzip.html#auto_002dcompress 176 177Contributing new tests 178====================== 179 180In general, the rules for selftests are 181 182 * Do as much as you can if you're not root; 183 184 * Don't take too long; 185 186 * Don't break the build on any architecture, and 187 188 * Don't cause the top-level "make run_tests" to fail if your feature is 189 unconfigured. 190 191Contributing new tests (details) 192================================ 193 194 * Use TEST_GEN_XXX if such binaries or files are generated during 195 compiling. 196 197 TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by 198 default. 199 200 TEST_CUSTOM_PROGS should be used by tests that require custom build 201 rules and prevent common build rule use. 202 203 TEST_PROGS are for test shell scripts. Please ensure shell script has 204 its exec bit set. Otherwise, lib.mk run_tests will generate a warning. 205 206 TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests. 207 208 TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the 209 executable which is not tested by default. 210 TEST_FILES, TEST_GEN_FILES mean it is the file which is used by 211 test. 212 213 * First use the headers inside the kernel source and/or git repo, and then the 214 system headers. Headers for the kernel release as opposed to headers 215 installed by the distro on the system should be the primary focus to be able 216 to find regressions. 217 218 * If a test needs specific kernel config options enabled, add a config file in 219 the test directory to enable them. 220 221 e.g: tools/testing/selftests/android/config 222 223Test Module 224=========== 225 226Kselftest tests the kernel from userspace. Sometimes things need 227testing from within the kernel, one method of doing this is to create a 228test module. We can tie the module into the kselftest framework by 229using a shell script test runner. ``kselftest/module.sh`` is designed 230to facilitate this process. There is also a header file provided to 231assist writing kernel modules that are for use with kselftest: 232 233- ``tools/testing/kselftest/kselftest_module.h`` 234- ``tools/testing/kselftest/kselftest/module.sh`` 235 236How to use 237---------- 238 239Here we show the typical steps to create a test module and tie it into 240kselftest. We use kselftests for lib/ as an example. 241 2421. Create the test module 243 2442. Create the test script that will run (load/unload) the module 245 e.g. ``tools/testing/selftests/lib/printf.sh`` 246 2473. Add line to config file e.g. ``tools/testing/selftests/lib/config`` 248 2494. Add test script to makefile e.g. ``tools/testing/selftests/lib/Makefile`` 250 2515. Verify it works: 252 253.. code-block:: sh 254 255 # Assumes you have booted a fresh build of this kernel tree 256 cd /path/to/linux/tree 257 make kselftest-merge 258 make modules 259 sudo make modules_install 260 make TARGETS=lib kselftest 261 262Example Module 263-------------- 264 265A bare bones test module might look like this: 266 267.. code-block:: c 268 269 // SPDX-License-Identifier: GPL-2.0+ 270 271 #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt 272 273 #include "../tools/testing/selftests/kselftest/module.h" 274 275 KSTM_MODULE_GLOBALS(); 276 277 /* 278 * Kernel module for testing the foobinator 279 */ 280 281 static int __init test_function() 282 { 283 ... 284 } 285 286 static void __init selftest(void) 287 { 288 KSTM_CHECK_ZERO(do_test_case("", 0)); 289 } 290 291 KSTM_MODULE_LOADERS(test_foo); 292 MODULE_AUTHOR("John Developer <jd@fooman.org>"); 293 MODULE_LICENSE("GPL"); 294 295Example test script 296------------------- 297 298.. code-block:: sh 299 300 #!/bin/bash 301 # SPDX-License-Identifier: GPL-2.0+ 302 $(dirname $0)/../kselftest/module.sh "foo" test_foo 303 304 305Test Harness 306============ 307 308The kselftest_harness.h file contains useful helpers to build tests. The 309test harness is for userspace testing, for kernel space testing see `Test 310Module`_ above. 311 312The tests from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as 313example. 314 315Example 316------- 317 318.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 319 :doc: example 320 321 322Helpers 323------- 324 325.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 326 :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP 327 FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN FIXTURE_VARIANT 328 FIXTURE_VARIANT_ADD 329 330Operators 331--------- 332 333.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 334 :doc: operators 335 336.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 337 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE 338 ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE 339 ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT 340 EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE 341 EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE 342