Linux 5.4-rc3
[sfrench/cifs-2.6.git] / Documentation / dev-tools / kselftest.rst
1 ======================
2 Linux Kernel Selftests
3 ======================
4
5 The kernel contains a set of "self tests" under the tools/testing/selftests/
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.
9
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
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
17 to run the full range of hot-plug tests. In default mode, hot-plug tests run
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
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
26 Running the selftests (hotplug tests are run in limited mode)
27 =============================================================
28
29 To build the tests::
30
31   $ make -C tools/testing/selftests
32
33 To run the tests::
34
35   $ make -C tools/testing/selftests run_tests
36
37 To build and run the tests with a single command, use::
38
39   $ make kselftest
40
41 Note that some tests will require root privileges.
42
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= ::
50
51   $ make O=/tmp/kselftest kselftest
52
53 To build, save output files in a separate directory with KBUILD_OUTPUT ::
54
55   $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
56
57 The O= assignment takes precedence over the KBUILD_OUTPUT environment
58 variable.
59
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
69
70 Running a subset of selftests
71 =============================
72
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
76 To run only tests targeted for a single subsystem::
77
78   $ make -C tools/testing/selftests TARGETS=ptrace run_tests
79
80 You can specify multiple tests to build and run::
81
82   $  make TARGETS="size timers" kselftest
83
84 To build, save output files in a separate directory with O= ::
85
86   $ make O=/tmp/kselftest TARGETS="size timers" kselftest
87
88 To build, save output files in a separate directory with KBUILD_OUTPUT ::
89
90   $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest
91
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
108 See the top-level tools/testing/selftests/Makefile for the list of all
109 possible targets.
110
111 Running the full range hotplug selftests
112 ========================================
113
114 To build the hotplug tests::
115
116   $ make -C tools/testing/selftests hotplug
117
118 To run the hotplug tests::
119
120   $ make -C tools/testing/selftests run_hotplug
121
122 Note that some tests will require root privileges.
123
124
125 Install selftests
126 =================
127
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.
131
132 To install selftests in default location::
133
134    $ cd tools/testing/selftests
135    $ ./kselftest_install.sh
136
137 To install selftests in a user specified location::
138
139    $ cd tools/testing/selftests
140    $ ./kselftest_install.sh install_dir
141
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
148 You can simply do the following to run the installed Kselftests. Please
149 note some tests will require root privileges::
150
151    $ cd kselftest
152    $ ./run_kselftest.sh
153
154 Contributing new tests
155 ======================
156
157 In 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
168 Contributing 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
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
206 using a shell script test runner.  ``kselftest_module.sh`` is designed
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``
211 - ``tools/testing/kselftest/kselftest_module.sh``
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
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
272 Example 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
282 Test Harness
283 ============
284
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.
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