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 92See the top-level tools/testing/selftests/Makefile for the list of all 93possible targets. 94 95Running the full range hotplug selftests 96======================================== 97 98To build the hotplug tests:: 99 100 $ make -C tools/testing/selftests hotplug 101 102To run the hotplug tests:: 103 104 $ make -C tools/testing/selftests run_hotplug 105 106Note that some tests will require root privileges. 107 108 109Install selftests 110================= 111 112You can use the kselftest_install.sh tool to install selftests in the 113default location, which is tools/testing/selftests/kselftest, or in a 114user specified location. 115 116To install selftests in default location:: 117 118 $ cd tools/testing/selftests 119 $ ./kselftest_install.sh 120 121To install selftests in a user specified location:: 122 123 $ cd tools/testing/selftests 124 $ ./kselftest_install.sh install_dir 125 126Running installed selftests 127=========================== 128 129Kselftest install as well as the Kselftest tarball provide a script 130named "run_kselftest.sh" to run the tests. 131 132You can simply do the following to run the installed Kselftests. Please 133note some tests will require root privileges:: 134 135 $ cd kselftest 136 $ ./run_kselftest.sh 137 138Contributing new tests 139====================== 140 141In general, the rules for selftests are 142 143 * Do as much as you can if you're not root; 144 145 * Don't take too long; 146 147 * Don't break the build on any architecture, and 148 149 * Don't cause the top-level "make run_tests" to fail if your feature is 150 unconfigured. 151 152Contributing new tests (details) 153================================ 154 155 * Use TEST_GEN_XXX if such binaries or files are generated during 156 compiling. 157 158 TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by 159 default. 160 161 TEST_CUSTOM_PROGS should be used by tests that require custom build 162 rules and prevent common build rule use. 163 164 TEST_PROGS are for test shell scripts. Please ensure shell script has 165 its exec bit set. Otherwise, lib.mk run_tests will generate a warning. 166 167 TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests. 168 169 TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the 170 executable which is not tested by default. 171 TEST_FILES, TEST_GEN_FILES mean it is the file which is used by 172 test. 173 174 * First use the headers inside the kernel source and/or git repo, and then the 175 system headers. Headers for the kernel release as opposed to headers 176 installed by the distro on the system should be the primary focus to be able 177 to find regressions. 178 179 * If a test needs specific kernel config options enabled, add a config file in 180 the test directory to enable them. 181 182 e.g: tools/testing/selftests/android/config 183 184Test Module 185=========== 186 187Kselftest tests the kernel from userspace. Sometimes things need 188testing from within the kernel, one method of doing this is to create a 189test module. We can tie the module into the kselftest framework by 190using a shell script test runner. ``kselftest_module.sh`` is designed 191to facilitate this process. There is also a header file provided to 192assist writing kernel modules that are for use with kselftest: 193 194- ``tools/testing/kselftest/kselftest_module.h`` 195- ``tools/testing/kselftest/kselftest_module.sh`` 196 197How to use 198---------- 199 200Here we show the typical steps to create a test module and tie it into 201kselftest. We use kselftests for lib/ as an example. 202 2031. Create the test module 204 2052. Create the test script that will run (load/unload) the module 206 e.g. ``tools/testing/selftests/lib/printf.sh`` 207 2083. Add line to config file e.g. ``tools/testing/selftests/lib/config`` 209 2104. Add test script to makefile e.g. ``tools/testing/selftests/lib/Makefile`` 211 2125. Verify it works: 213 214.. code-block:: sh 215 216 # Assumes you have booted a fresh build of this kernel tree 217 cd /path/to/linux/tree 218 make kselftest-merge 219 make modules 220 sudo make modules_install 221 make TARGETS=lib kselftest 222 223Example Module 224-------------- 225 226A bare bones test module might look like this: 227 228.. code-block:: c 229 230 // SPDX-License-Identifier: GPL-2.0+ 231 232 #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt 233 234 #include "../tools/testing/selftests/kselftest_module.h" 235 236 KSTM_MODULE_GLOBALS(); 237 238 /* 239 * Kernel module for testing the foobinator 240 */ 241 242 static int __init test_function() 243 { 244 ... 245 } 246 247 static void __init selftest(void) 248 { 249 KSTM_CHECK_ZERO(do_test_case("", 0)); 250 } 251 252 KSTM_MODULE_LOADERS(test_foo); 253 MODULE_AUTHOR("John Developer <jd@fooman.org>"); 254 MODULE_LICENSE("GPL"); 255 256Example test script 257------------------- 258 259.. code-block:: sh 260 261 #!/bin/bash 262 # SPDX-License-Identifier: GPL-2.0+ 263 $(dirname $0)/../kselftest_module.sh "foo" test_foo 264 265 266Test Harness 267============ 268 269The kselftest_harness.h file contains useful helpers to build tests. The 270test harness is for userspace testing, for kernel space testing see `Test 271Module`_ above. 272 273The tests from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as 274example. 275 276Example 277------- 278 279.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 280 :doc: example 281 282 283Helpers 284------- 285 286.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 287 :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP 288 FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN 289 290Operators 291--------- 292 293.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 294 :doc: operators 295 296.. kernel-doc:: tools/testing/selftests/kselftest_harness.h 297 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE 298 ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE 299 ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT 300 EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE 301 EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE 302