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 154Contributing new tests 155====================== 156 157In general, the rules for selftests are 158 159 * Do as much as you can if you're not root; 160 161 * Don't take too long; 162 163 * Don't break the build on any architecture, and 164 165 * Don't cause the top-level "make run_tests" to fail if your feature is 166 unconfigured. 167 168Contributing new tests (details) 169================================ 170 171 * Use TEST_GEN_XXX if such binaries or files are generated during 172 compiling. 173 174 TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by 175 default. 176 177 TEST_CUSTOM_PROGS should be used by tests that require custom build 178 rules and prevent common build rule use. 179 180 TEST_PROGS are for test shell scripts. Please ensure shell script has 181 its exec bit set. Otherwise, lib.mk run_tests will generate a warning. 182 183 TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests. 184 185 TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the 186 executable which is not tested by default. 187 TEST_FILES, TEST_GEN_FILES mean it is the file which is used by 188 test. 189 190 * First use the headers inside the kernel source and/or git repo, and then the 191 system headers. Headers for the kernel release as opposed to headers 192 installed by the distro on the system should be the primary focus to be able 193 to find regressions. 194 195 * If a test needs specific kernel config options enabled, add a config file in 196 the test directory to enable them. 197 198 e.g: tools/testing/selftests/android/config 199 200Test Module 201=========== 202 203Kselftest tests the kernel from userspace. Sometimes things need 204testing from within the kernel, one method of doing this is to create a 205test module. We can tie the module into the kselftest framework by 206using a shell script test runner. ``kselftest_module.sh`` is designed 207to facilitate this process. There is also a header file provided to 208assist writing kernel modules that are for use with kselftest: 209 210- ``tools/testing/kselftest/kselftest_module.h`` 211- ``tools/testing/kselftest/kselftest_module.sh`` 212 213How to use 214---------- 215 216Here we show the typical steps to create a test module and tie it into 217kselftest. We use kselftests for lib/ as an example. 218 2191. Create the test module 220 2212. Create the test script that will run (load/unload) the module 222 e.g. ``tools/testing/selftests/lib/printf.sh`` 223 2243. Add line to config file e.g. ``tools/testing/selftests/lib/config`` 225 2264. Add test script to makefile e.g. ``tools/testing/selftests/lib/Makefile`` 227 2285. Verify it works: 229 230.. code-block:: sh 231 232 # Assumes you have booted a fresh build of this kernel tree 233 cd /path/to/linux/tree 234 make kselftest-merge 235 make modules 236 sudo make modules_install 237 make TARGETS=lib kselftest 238 239Example Module 240-------------- 241 242A bare bones test module might look like this: 243 244.. code-block:: c 245 246 // SPDX-License-Identifier: GPL-2.0+ 247 248 #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt 249 250 #include "../tools/testing/selftests/kselftest_module.h" 251 252 KSTM_MODULE_GLOBALS(); 253 254 /* 255 * Kernel module for testing the foobinator 256 */ 257 258 static int __init test_function() 259 { 260 ... 261 } 262 263 static void __init selftest(void) 264 { 265 KSTM_CHECK_ZERO(do_test_case("", 0)); 266 } 267 268 KSTM_MODULE_LOADERS(test_foo); 269 MODULE_AUTHOR("John Developer <jd@fooman.org>"); 270 MODULE_LICENSE("GPL"); 271 272Example test script 273------------------- 274 275.. code-block:: sh 276 277 #!/bin/bash 278 # SPDX-License-Identifier: GPL-2.0+ 279 $(dirname $0)/../kselftest_module.sh "foo" test_foo 280 281 282Test Harness 283============ 284 285The kselftest_harness.h file contains useful helpers to build tests. The 286test harness is for userspace testing, for kernel space testing see `Test 287Module`_ above. 288 289The tests from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as 290example. 291 292Example 293------- 294 295.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 296 :doc: example 297 298 299Helpers 300------- 301 302.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 303 :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP 304 FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN 305 306Operators 307--------- 308 309.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 310 :doc: operators 311 312.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 313 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE 314 ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE 315 ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT 316 EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE 317 EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE 318