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
10On some systems, hot-plug tests could hang forever waiting for cpu and
11memory to be ready to be offlined. A special hot-plug target is created
12to run full range of hot-plug tests. In default mode, hot-plug tests run
13in safe mode with a limited scope. In limited mode, cpu-hotplug test is
14run on a single cpu as opposed to all hotplug capable cpus, and memory
15hotplug test is run on 2% of hotplug capable memory instead of 10%.
16
17Running the selftests (hotplug tests are run in limited mode)
18=============================================================
19
20To build the tests::
21
22  $ make -C tools/testing/selftests
23
24To run the tests::
25
26  $ make -C tools/testing/selftests run_tests
27
28To build and run the tests with a single command, use::
29
30  $ make kselftest
31
32Note that some tests will require root privileges.
33
34Build and run from user specific object directory (make O=dir)::
35
36  $ make O=/tmp/kselftest kselftest
37
38Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
39
40  $ make KBUILD_OUTPUT=/tmp/kselftest kselftest
41
42The above commands run the tests and print pass/fail summary to make it
43easier to understand the test results. Please find the detailed individual
44test results for each test in /tmp/testname file(s).
45
46Running a subset of selftests
47=============================
48
49You can use the "TARGETS" variable on the make command line to specify
50single test to run, or a list of tests to run.
51
52To run only tests targeted for a single subsystem::
53
54  $ make -C tools/testing/selftests TARGETS=ptrace run_tests
55
56You can specify multiple tests to build and run::
57
58  $  make TARGETS="size timers" kselftest
59
60Build and run from user specific object directory (make O=dir)::
61
62  $ make O=/tmp/kselftest TARGETS="size timers" kselftest
63
64Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
65
66  $ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest
67
68The above commands run the tests and print pass/fail summary to make it
69easier to understand the test results. Please find the detailed individual
70test results for each test in /tmp/testname file(s).
71
72See the top-level tools/testing/selftests/Makefile for the list of all
73possible targets.
74
75Running the full range hotplug selftests
76========================================
77
78To build the hotplug tests::
79
80  $ make -C tools/testing/selftests hotplug
81
82To run the hotplug tests::
83
84  $ make -C tools/testing/selftests run_hotplug
85
86Note that some tests will require root privileges.
87
88
89Install selftests
90=================
91
92You can use kselftest_install.sh tool installs selftests in default
93location which is tools/testing/selftests/kselftest or a user specified
94location.
95
96To install selftests in default location::
97
98   $ cd tools/testing/selftests
99   $ ./kselftest_install.sh
100
101To install selftests in a user specified location::
102
103   $ cd tools/testing/selftests
104   $ ./kselftest_install.sh install_dir
105
106Running installed selftests
107===========================
108
109Kselftest install as well as the Kselftest tarball provide a script
110named "run_kselftest.sh" to run the tests.
111
112You can simply do the following to run the installed Kselftests. Please
113note some tests will require root privileges::
114
115   $ cd kselftest
116   $ ./run_kselftest.sh
117
118Contributing new tests
119======================
120
121In general, the rules for selftests are
122
123 * Do as much as you can if you're not root;
124
125 * Don't take too long;
126
127 * Don't break the build on any architecture, and
128
129 * Don't cause the top-level "make run_tests" to fail if your feature is
130   unconfigured.
131
132Contributing new tests (details)
133================================
134
135 * Use TEST_GEN_XXX if such binaries or files are generated during
136   compiling.
137
138   TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by
139   default.
140
141   TEST_CUSTOM_PROGS should be used by tests that require custom build
142   rule and prevent common build rule use.
143
144   TEST_PROGS are for test shell scripts. Please ensure shell script has
145   its exec bit set. Otherwise, lib.mk run_tests will generate a warning.
146
147   TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests.
148
149   TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the
150   executable which is not tested by default.
151   TEST_FILES, TEST_GEN_FILES mean it is the file which is used by
152   test.
153
154Test Harness
155============
156
157The kselftest_harness.h file contains useful helpers to build tests.  The tests
158from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example.
159
160Example
161-------
162
163.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
164    :doc: example
165
166
167Helpers
168-------
169
170.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
171    :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP
172                FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN
173
174Operators
175---------
176
177.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
178    :doc: operators
179
180.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
181    :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE
182                ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE
183                ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT
184                EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE
185                EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE
186