GNU Linux-libre 4.19.211-gnu1
[releases.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 On some systems, hot-plug tests could hang forever waiting for cpu and
11 memory to be ready to be offlined. A special hot-plug target is created
12 to run full range of hot-plug tests. In default mode, hot-plug tests run
13 in safe mode with a limited scope. In limited mode, cpu-hotplug test is
14 run on a single cpu as opposed to all hotplug capable cpus, and memory
15 hotplug test is run on 2% of hotplug capable memory instead of 10%.
16
17 Running the selftests (hotplug tests are run in limited mode)
18 =============================================================
19
20 To build the tests::
21
22   $ make -C tools/testing/selftests
23
24 To run the tests::
25
26   $ make -C tools/testing/selftests run_tests
27
28 To build and run the tests with a single command, use::
29
30   $ make kselftest
31
32 Note that some tests will require root privileges.
33
34 Build and run from user specific object directory (make O=dir)::
35
36   $ make O=/tmp/kselftest kselftest
37
38 Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
39
40   $ make KBUILD_OUTPUT=/tmp/kselftest kselftest
41
42 The above commands run the tests and print pass/fail summary to make it
43 easier to understand the test results. Please find the detailed individual
44 test results for each test in /tmp/testname file(s).
45
46 Running a subset of selftests
47 =============================
48
49 You can use the "TARGETS" variable on the make command line to specify
50 single test to run, or a list of tests to run.
51
52 To run only tests targeted for a single subsystem::
53
54   $ make -C tools/testing/selftests TARGETS=ptrace run_tests
55
56 You can specify multiple tests to build and run::
57
58   $  make TARGETS="size timers" kselftest
59
60 Build and run from user specific object directory (make O=dir)::
61
62   $ make O=/tmp/kselftest TARGETS="size timers" kselftest
63
64 Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
65
66   $ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest
67
68 The above commands run the tests and print pass/fail summary to make it
69 easier to understand the test results. Please find the detailed individual
70 test results for each test in /tmp/testname file(s).
71
72 See the top-level tools/testing/selftests/Makefile for the list of all
73 possible targets.
74
75 Running the full range hotplug selftests
76 ========================================
77
78 To build the hotplug tests::
79
80   $ make -C tools/testing/selftests hotplug
81
82 To run the hotplug tests::
83
84   $ make -C tools/testing/selftests run_hotplug
85
86 Note that some tests will require root privileges.
87
88
89 Install selftests
90 =================
91
92 You can use kselftest_install.sh tool installs selftests in default
93 location which is tools/testing/selftests/kselftest or a user specified
94 location.
95
96 To install selftests in default location::
97
98    $ cd tools/testing/selftests
99    $ ./kselftest_install.sh
100
101 To install selftests in a user specified location::
102
103    $ cd tools/testing/selftests
104    $ ./kselftest_install.sh install_dir
105
106 Running installed selftests
107 ===========================
108
109 Kselftest install as well as the Kselftest tarball provide a script
110 named "run_kselftest.sh" to run the tests.
111
112 You can simply do the following to run the installed Kselftests. Please
113 note some tests will require root privileges::
114
115    $ cd kselftest
116    $ ./run_kselftest.sh
117
118 Contributing new tests
119 ======================
120
121 In 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
132 Contributing 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
164 Test Harness
165 ============
166
167 The kselftest_harness.h file contains useful helpers to build tests.  The tests
168 from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example.
169
170 Example
171 -------
172
173 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
174     :doc: example
175
176
177 Helpers
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
184 Operators
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