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
154 * First use the headers inside the kernel source and/or git repo, and then the
155   system headers.  Headers for the kernel release as opposed to headers
156   installed by the distro on the system should be the primary focus to be able
157   to find regressions.
158
159 * If a test needs specific kernel config options enabled, add a config file in
160   the test directory to enable them.
161
162   e.g: tools/testing/selftests/android/ion/config
163
164Test Harness
165============
166
167The kselftest_harness.h file contains useful helpers to build tests.  The tests
168from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example.
169
170Example
171-------
172
173.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
174    :doc: example
175
176
177Helpers
178-------
179
180.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
181    :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP
182                FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN
183
184Operators
185---------
186
187.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
188    :doc: operators
189
190.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
191    :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE
192                ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE
193                ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT
194                EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE
195                EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE
196