blob: 3bf371a938d033c45305531ad7e0b1c5bd3cbc3a [file] [log] [blame]
Mickaël Salaüncef04cd2017-05-26 20:44:00 +02001======================
Jeremy Kerr80d03422013-02-27 17:05:57 -08002Linux Kernel Selftests
Mickaël Salaüncef04cd2017-05-26 20:44:00 +02003======================
Jeremy Kerr80d03422013-02-27 17:05:57 -08004
5The kernel contains a set of "self tests" under the tools/testing/selftests/
Aleksander Alekseev3409f9a2016-08-18 12:36:53 +03006directory. 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.
Jeremy Kerr80d03422013-02-27 17:05:57 -08009
Shuah Khanddddda92014-07-02 09:51:38 -060010On 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=============================================================
Jeremy Kerr80d03422013-02-27 17:05:57 -080019
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020020To build the tests::
Jeremy Kerr80d03422013-02-27 17:05:57 -080021
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -030022 $ make -C tools/testing/selftests
Jeremy Kerr80d03422013-02-27 17:05:57 -080023
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020024To run the tests::
Jeremy Kerr80d03422013-02-27 17:05:57 -080025
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -030026 $ make -C tools/testing/selftests run_tests
Tim Bird3c415702014-11-19 16:16:16 -080027
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020028To build and run the tests with a single command, use::
29
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -030030 $ make kselftest
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020031
32Note that some tests will require root privileges.
Jeremy Kerr80d03422013-02-27 17:05:57 -080033
Shuah Khand5cdbb82017-10-02 17:44:17 -060034Build 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).
Jeremy Kerr80d03422013-02-27 17:05:57 -080045
Tim Bird3c415702014-11-19 16:16:16 -080046Running a subset of selftests
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020047=============================
48
Tim Bird3c415702014-11-19 16:16:16 -080049You can use the "TARGETS" variable on the make command line to specify
50single test to run, or a list of tests to run.
Jeremy Kerr80d03422013-02-27 17:05:57 -080051
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020052To run only tests targeted for a single subsystem::
Tim Bird3c415702014-11-19 16:16:16 -080053
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -030054 $ make -C tools/testing/selftests TARGETS=ptrace run_tests
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020055
56You can specify multiple tests to build and run::
57
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -030058 $ make TARGETS="size timers" kselftest
Tim Bird3c415702014-11-19 16:16:16 -080059
Shuah Khand5cdbb82017-10-02 17:44:17 -060060Build 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
Tim Bird3c415702014-11-19 16:16:16 -080072See the top-level tools/testing/selftests/Makefile for the list of all
73possible targets.
74
Shuah Khanddddda92014-07-02 09:51:38 -060075Running the full range hotplug selftests
76========================================
77
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020078To build the hotplug tests::
Shuah Khanddddda92014-07-02 09:51:38 -060079
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -030080 $ make -C tools/testing/selftests hotplug
Shuah Khanddddda92014-07-02 09:51:38 -060081
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020082To run the hotplug tests::
83
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -030084 $ make -C tools/testing/selftests run_hotplug
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020085
86Note that some tests will require root privileges.
Jeremy Kerr80d03422013-02-27 17:05:57 -080087
Tim Bird3c415702014-11-19 16:16:16 -080088
Wang Long76caa6c2015-09-23 09:35:25 +000089Install selftests
90=================
91
92You can use kselftest_install.sh tool installs selftests in default
Masahiro Yamada9332ef92017-02-27 14:28:47 -080093location which is tools/testing/selftests/kselftest or a user specified
Wang Long76caa6c2015-09-23 09:35:25 +000094location.
95
Mickaël Salaüncef04cd2017-05-26 20:44:00 +020096To install selftests in default location::
Wang Long76caa6c2015-09-23 09:35:25 +000097
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -030098 $ cd tools/testing/selftests
99 $ ./kselftest_install.sh
Mickaël Salaüncef04cd2017-05-26 20:44:00 +0200100
101To install selftests in a user specified location::
102
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -0300103 $ cd tools/testing/selftests
104 $ ./kselftest_install.sh install_dir
Wang Long76caa6c2015-09-23 09:35:25 +0000105
Shuah Khan78566cf2016-11-07 13:24:14 -0700106Running 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 KselftestsPlease
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -0300113note some tests will require root privileges::
Shuah Khan78566cf2016-11-07 13:24:14 -0700114
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -0300115 $ cd kselftest
116 $ ./run_kselftest.sh
Wang Long76caa6c2015-09-23 09:35:25 +0000117
Jeremy Kerr80d03422013-02-27 17:05:57 -0800118Contributing new tests
119======================
120
Zhiyi Sun4db1fa62016-02-24 00:08:11 +0800121In general, the rules for selftests are
Jeremy Kerr80d03422013-02-27 17:05:57 -0800122
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.
bamvor.zhangjian@huawei.com88baa782016-11-29 19:55:47 +0800131
Mickaël Salaüncef04cd2017-05-26 20:44:00 +0200132Contributing new tests (details)
133================================
bamvor.zhangjian@huawei.com88baa782016-11-29 19:55:47 +0800134
135 * Use TEST_GEN_XXX if such binaries or files are generated during
136 compiling.
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -0300137
Shuah Khand5cdbb82017-10-02 17:44:17 -0600138 TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by
bamvor.zhangjian@huawei.com88baa782016-11-29 19:55:47 +0800139 default.
Mauro Carvalho Chehabfde662d2017-06-17 12:26:40 -0300140
Shuah Khand5cdbb82017-10-02 17:44:17 -0600141 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
bamvor.zhangjian@huawei.com88baa782016-11-29 19:55:47 +0800149 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.
Mickaël Salaün7e6a32a2017-06-05 20:37:17 +0200153
Anders Roxella997a702018-04-19 12:28:25 +0200154 * 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
Mickaël Salaün7e6a32a2017-06-05 20:37:17 +0200159Test Harness
160============
161
162The kselftest_harness.h file contains useful helpers to build tests. The tests
163from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example.
164
165Example
166-------
167
168.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
169 :doc: example
170
171
172Helpers
173-------
174
175.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
176 :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP
177 FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN
178
179Operators
180---------
181
182.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
183 :doc: operators
184
185.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
186 :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE
187 ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE
188 ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT
189 EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE
190 EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE