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 | |
ddddda9b SK |
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 | ============================================================= | |
80d03428 | 19 | |
cef04cdc MS |
20 | To build the tests:: |
21 | ||
fde662d9 | 22 | $ make -C tools/testing/selftests |
cef04cdc MS |
23 | |
24 | To run the tests:: | |
80d03428 | 25 | |
fde662d9 | 26 | $ make -C tools/testing/selftests run_tests |
80d03428 | 27 | |
cef04cdc | 28 | To build and run the tests with a single command, use:: |
80d03428 | 29 | |
fde662d9 | 30 | $ make kselftest |
3c415707 | 31 | |
cef04cdc | 32 | Note that some tests will require root privileges. |
80d03428 | 33 | |
d5cdbb87 SK |
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). | |
80d03428 | 45 | |
3c415707 | 46 | Running a subset of selftests |
cef04cdc MS |
47 | ============================= |
48 | ||
3c415707 TB |
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 | ||
cef04cdc MS |
52 | To run only tests targeted for a single subsystem:: |
53 | ||
fde662d9 | 54 | $ make -C tools/testing/selftests TARGETS=ptrace run_tests |
3c415707 | 55 | |
cef04cdc MS |
56 | You can specify multiple tests to build and run:: |
57 | ||
fde662d9 | 58 | $ make TARGETS="size timers" kselftest |
3c415707 | 59 | |
d5cdbb87 SK |
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 | ||
3c415707 TB |
72 | See the top-level tools/testing/selftests/Makefile for the list of all |
73 | possible targets. | |
80d03428 | 74 | |
ddddda9b SK |
75 | Running the full range hotplug selftests |
76 | ======================================== | |
77 | ||
cef04cdc MS |
78 | To build the hotplug tests:: |
79 | ||
fde662d9 | 80 | $ make -C tools/testing/selftests hotplug |
cef04cdc MS |
81 | |
82 | To run the hotplug tests:: | |
ddddda9b | 83 | |
fde662d9 | 84 | $ make -C tools/testing/selftests run_hotplug |
ddddda9b | 85 | |
cef04cdc | 86 | Note that some tests will require root privileges. |
80d03428 | 87 | |
3c415707 | 88 | |
76caa6ca WL |
89 | Install selftests |
90 | ================= | |
91 | ||
92 | You can use kselftest_install.sh tool installs selftests in default | |
9332ef9d | 93 | location which is tools/testing/selftests/kselftest or a user specified |
76caa6ca WL |
94 | location. |
95 | ||
cef04cdc | 96 | To install selftests in default location:: |
76caa6ca | 97 | |
fde662d9 MCC |
98 | $ cd tools/testing/selftests |
99 | $ ./kselftest_install.sh | |
cef04cdc MS |
100 | |
101 | To install selftests in a user specified location:: | |
102 | ||
fde662d9 MCC |
103 | $ cd tools/testing/selftests |
104 | $ ./kselftest_install.sh install_dir | |
76caa6ca | 105 | |
78566cf1 SK |
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 | |
fde662d9 | 113 | note some tests will require root privileges:: |
78566cf1 | 114 | |
fde662d9 MCC |
115 | $ cd kselftest |
116 | $ ./run_kselftest.sh | |
76caa6ca | 117 | |
80d03428 JK |
118 | Contributing new tests |
119 | ====================== | |
120 | ||
4db1fa66 | 121 | In general, the rules for selftests are |
80d03428 JK |
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. | |
88baa78d | 131 | |
cef04cdc MS |
132 | Contributing new tests (details) |
133 | ================================ | |
88baa78d | 134 | |
135 | * Use TEST_GEN_XXX if such binaries or files are generated during | |
136 | compiling. | |
fde662d9 | 137 | |
d5cdbb87 | 138 | TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by |
88baa78d | 139 | default. |
fde662d9 | 140 | |
d5cdbb87 SK |
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 | ||
88baa78d | 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. | |
7e6a32ab | 153 | |
a997a703 AR |
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 | ||
8ab1416a AR |
159 | * If a test needs specific kernel config options enabled, add a config file in |
160 | the test directory to enable them. | |
161 | ||
0e0f0093 | 162 | e.g: tools/testing/selftests/android/config |
8ab1416a | 163 | |
7e6a32ab MS |
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 |