]>
Commit | Line | Data |
---|---|---|
cef04cdc | 1 | ====================== |
80d03428 | 2 | Linux Kernel Selftests |
cef04cdc | 3 | ====================== |
80d03428 JK |
4 | |
5 | The kernel contains a set of "self tests" under the tools/testing/selftests/ | |
3409f9ab AA |
6 | directory. These are intended to be small tests to exercise individual code |
7 | paths in the kernel. Tests are intended to be run after building, installing | |
8 | and booting a kernel. | |
80d03428 | 9 | |
9f436194 SK |
10 | You can find additional information on Kselftest framework, how to |
11 | write new tests using the framework on Kselftest wiki: | |
12 | ||
13 | https://kselftest.wiki.kernel.org/ | |
14 | ||
ddddda9b SK |
15 | On some systems, hot-plug tests could hang forever waiting for cpu and |
16 | memory to be ready to be offlined. A special hot-plug target is created | |
c284d428 | 17 | to run the full range of hot-plug tests. In default mode, hot-plug tests run |
ddddda9b SK |
18 | in safe mode with a limited scope. In limited mode, cpu-hotplug test is |
19 | run on a single cpu as opposed to all hotplug capable cpus, and memory | |
20 | hotplug test is run on 2% of hotplug capable memory instead of 10%. | |
21 | ||
eebf4dd4 TH |
22 | kselftest runs as a userspace process. Tests that can be written/run in |
23 | userspace may wish to use the `Test Harness`_. Tests that need to be | |
24 | run in kernel space may wish to use a `Test Module`_. | |
25 | ||
ddddda9b SK |
26 | Running the selftests (hotplug tests are run in limited mode) |
27 | ============================================================= | |
80d03428 | 28 | |
cef04cdc MS |
29 | To build the tests:: |
30 | ||
fde662d9 | 31 | $ make -C tools/testing/selftests |
cef04cdc MS |
32 | |
33 | To run the tests:: | |
80d03428 | 34 | |
fde662d9 | 35 | $ make -C tools/testing/selftests run_tests |
80d03428 | 36 | |
cef04cdc | 37 | To build and run the tests with a single command, use:: |
80d03428 | 38 | |
fde662d9 | 39 | $ make kselftest |
3c415707 | 40 | |
cef04cdc | 41 | Note that some tests will require root privileges. |
80d03428 | 42 | |
9f436194 SK |
43 | Kselftest supports saving output files in a separate directory and then |
44 | running tests. To locate output files in a separate directory two syntaxes | |
45 | are supported. In both cases the working directory must be the root of the | |
46 | kernel src. This is applicable to "Running a subset of selftests" section | |
47 | below. | |
48 | ||
49 | To build, save output files in a separate directory with O= :: | |
d5cdbb87 SK |
50 | |
51 | $ make O=/tmp/kselftest kselftest | |
52 | ||
9f436194 SK |
53 | To build, save output files in a separate directory with KBUILD_OUTPUT :: |
54 | ||
55 | $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest | |
d5cdbb87 | 56 | |
9f436194 SK |
57 | The O= assignment takes precedence over the KBUILD_OUTPUT environment |
58 | variable. | |
d5cdbb87 | 59 | |
9f436194 SK |
60 | The above commands by default run the tests and print full pass/fail report. |
61 | Kselftest supports "summary" option to make it easier to understand the test | |
62 | results. Please find the detailed individual test results for each test in | |
63 | /tmp/testname file(s) when summary option is specified. This is applicable | |
64 | to "Running a subset of selftests" section below. | |
65 | ||
66 | To run kselftest with summary option enabled :: | |
67 | ||
68 | $ make summary=1 kselftest | |
80d03428 | 69 | |
3c415707 | 70 | Running a subset of selftests |
cef04cdc MS |
71 | ============================= |
72 | ||
3c415707 TB |
73 | You can use the "TARGETS" variable on the make command line to specify |
74 | single test to run, or a list of tests to run. | |
75 | ||
cef04cdc MS |
76 | To run only tests targeted for a single subsystem:: |
77 | ||
fde662d9 | 78 | $ make -C tools/testing/selftests TARGETS=ptrace run_tests |
3c415707 | 79 | |
cef04cdc MS |
80 | You can specify multiple tests to build and run:: |
81 | ||
fde662d9 | 82 | $ make TARGETS="size timers" kselftest |
3c415707 | 83 | |
9f436194 | 84 | To build, save output files in a separate directory with O= :: |
d5cdbb87 SK |
85 | |
86 | $ make O=/tmp/kselftest TARGETS="size timers" kselftest | |
87 | ||
9f436194 | 88 | To build, save output files in a separate directory with KBUILD_OUTPUT :: |
d5cdbb87 | 89 | |
9f436194 | 90 | $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest |
d5cdbb87 | 91 | |
3a24f7f6 CM |
92 | Additionally you can use the "SKIP_TARGETS" variable on the make command |
93 | line to specify one or more targets to exclude from the TARGETS list. | |
94 | ||
95 | To run all tests but a single subsystem:: | |
96 | ||
97 | $ make -C tools/testing/selftests SKIP_TARGETS=ptrace run_tests | |
98 | ||
99 | You can specify multiple tests to skip:: | |
100 | ||
101 | $ make SKIP_TARGETS="size timers" kselftest | |
102 | ||
103 | You can also specify a restricted list of tests to run together with a | |
104 | dedicated skiplist:: | |
105 | ||
106 | $ make TARGETS="bpf breakpoints size timers" SKIP_TARGETS=bpf kselftest | |
107 | ||
3c415707 TB |
108 | See the top-level tools/testing/selftests/Makefile for the list of all |
109 | possible targets. | |
80d03428 | 110 | |
ddddda9b SK |
111 | Running the full range hotplug selftests |
112 | ======================================== | |
113 | ||
cef04cdc MS |
114 | To build the hotplug tests:: |
115 | ||
fde662d9 | 116 | $ make -C tools/testing/selftests hotplug |
cef04cdc MS |
117 | |
118 | To run the hotplug tests:: | |
ddddda9b | 119 | |
fde662d9 | 120 | $ make -C tools/testing/selftests run_hotplug |
ddddda9b | 121 | |
cef04cdc | 122 | Note that some tests will require root privileges. |
80d03428 | 123 | |
3c415707 | 124 | |
76caa6ca WL |
125 | Install selftests |
126 | ================= | |
127 | ||
c284d428 RD |
128 | You can use the kselftest_install.sh tool to install selftests in the |
129 | default location, which is tools/testing/selftests/kselftest, or in a | |
130 | user specified location. | |
76caa6ca | 131 | |
cef04cdc | 132 | To install selftests in default location:: |
76caa6ca | 133 | |
fde662d9 MCC |
134 | $ cd tools/testing/selftests |
135 | $ ./kselftest_install.sh | |
cef04cdc MS |
136 | |
137 | To install selftests in a user specified location:: | |
138 | ||
fde662d9 MCC |
139 | $ cd tools/testing/selftests |
140 | $ ./kselftest_install.sh install_dir | |
76caa6ca | 141 | |
78566cf1 SK |
142 | Running installed selftests |
143 | =========================== | |
144 | ||
145 | Kselftest install as well as the Kselftest tarball provide a script | |
146 | named "run_kselftest.sh" to run the tests. | |
147 | ||
c284d428 | 148 | You can simply do the following to run the installed Kselftests. Please |
fde662d9 | 149 | note some tests will require root privileges:: |
78566cf1 | 150 | |
fde662d9 MCC |
151 | $ cd kselftest |
152 | $ ./run_kselftest.sh | |
76caa6ca | 153 | |
80d03428 JK |
154 | Contributing new tests |
155 | ====================== | |
156 | ||
4db1fa66 | 157 | In general, the rules for selftests are |
80d03428 JK |
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. | |
88baa78d | 167 | |
cef04cdc MS |
168 | Contributing new tests (details) |
169 | ================================ | |
88baa78d | 170 | |
171 | * Use TEST_GEN_XXX if such binaries or files are generated during | |
172 | compiling. | |
fde662d9 | 173 | |
d5cdbb87 | 174 | TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by |
88baa78d | 175 | default. |
fde662d9 | 176 | |
d5cdbb87 | 177 | TEST_CUSTOM_PROGS should be used by tests that require custom build |
c284d428 | 178 | rules and prevent common build rule use. |
d5cdbb87 SK |
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 | ||
88baa78d | 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. | |
7e6a32ab | 189 | |
a997a703 AR |
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 | ||
8ab1416a AR |
195 | * If a test needs specific kernel config options enabled, add a config file in |
196 | the test directory to enable them. | |
197 | ||
0e0f0093 | 198 | e.g: tools/testing/selftests/android/config |
8ab1416a | 199 | |
eebf4dd4 TH |
200 | Test Module |
201 | =========== | |
202 | ||
203 | Kselftest tests the kernel from userspace. Sometimes things need | |
204 | testing from within the kernel, one method of doing this is to create a | |
205 | test module. We can tie the module into the kselftest framework by | |
3a019636 | 206 | using a shell script test runner. ``kselftest/module.sh`` is designed |
eebf4dd4 TH |
207 | to facilitate this process. There is also a header file provided to |
208 | assist writing kernel modules that are for use with kselftest: | |
209 | ||
210 | - ``tools/testing/kselftest/kselftest_module.h`` | |
3a019636 | 211 | - ``tools/testing/kselftest/kselftest/module.sh`` |
eebf4dd4 TH |
212 | |
213 | How to use | |
214 | ---------- | |
215 | ||
216 | Here we show the typical steps to create a test module and tie it into | |
217 | kselftest. We use kselftests for lib/ as an example. | |
218 | ||
219 | 1. Create the test module | |
220 | ||
221 | 2. Create the test script that will run (load/unload) the module | |
222 | e.g. ``tools/testing/selftests/lib/printf.sh`` | |
223 | ||
224 | 3. Add line to config file e.g. ``tools/testing/selftests/lib/config`` | |
225 | ||
226 | 4. Add test script to makefile e.g. ``tools/testing/selftests/lib/Makefile`` | |
227 | ||
228 | 5. 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 | ||
239 | Example Module | |
240 | -------------- | |
241 | ||
242 | A 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 | ||
3a019636 | 250 | #include "../tools/testing/selftests/kselftest/module.h" |
eebf4dd4 TH |
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 | ||
272 | Example test script | |
273 | ------------------- | |
274 | ||
275 | .. code-block:: sh | |
276 | ||
277 | #!/bin/bash | |
278 | # SPDX-License-Identifier: GPL-2.0+ | |
3a019636 | 279 | $(dirname $0)/../kselftest/module.sh "foo" test_foo |
eebf4dd4 TH |
280 | |
281 | ||
7e6a32ab MS |
282 | Test Harness |
283 | ============ | |
284 | ||
eebf4dd4 TH |
285 | The kselftest_harness.h file contains useful helpers to build tests. The |
286 | test harness is for userspace testing, for kernel space testing see `Test | |
287 | Module`_ above. | |
288 | ||
289 | The tests from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as | |
290 | example. | |
7e6a32ab MS |
291 | |
292 | Example | |
293 | ------- | |
294 | ||
295 | .. kernel-doc:: tools/testing/selftests/kselftest_harness.h | |
296 | :doc: example | |
297 | ||
298 | ||
299 | Helpers | |
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 | ||
306 | Operators | |
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 |