Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 1 | ====================== |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 2 | Linux Kernel Selftests |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 3 | ====================== |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 4 | |
| 5 | The kernel contains a set of "self tests" under the tools/testing/selftests/ |
Aleksander Alekseev | 3409f9a | 2016-08-18 12:36:53 +0300 | [diff] [blame] | 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. |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 9 | |
Shuah Khan | ddddda9 | 2014-07-02 09:51:38 -0600 | [diff] [blame] | 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 | ============================================================= |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 19 | |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 20 | To build the tests:: |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 21 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 22 | $ make -C tools/testing/selftests |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 23 | |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 24 | To run the tests:: |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 25 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 26 | $ make -C tools/testing/selftests run_tests |
Tim Bird | 3c41570 | 2014-11-19 16:16:16 -0800 | [diff] [blame] | 27 | |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 28 | To build and run the tests with a single command, use:: |
| 29 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 30 | $ make kselftest |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 31 | |
| 32 | Note that some tests will require root privileges. |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 33 | |
Shuah Khan | d5cdbb8 | 2017-10-02 17:44:17 -0600 | [diff] [blame] | 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). |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 45 | |
Tim Bird | 3c41570 | 2014-11-19 16:16:16 -0800 | [diff] [blame] | 46 | Running a subset of selftests |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 47 | ============================= |
| 48 | |
Tim Bird | 3c41570 | 2014-11-19 16:16:16 -0800 | [diff] [blame] | 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. |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 51 | |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 52 | To run only tests targeted for a single subsystem:: |
Tim Bird | 3c41570 | 2014-11-19 16:16:16 -0800 | [diff] [blame] | 53 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 54 | $ make -C tools/testing/selftests TARGETS=ptrace run_tests |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 55 | |
| 56 | You can specify multiple tests to build and run:: |
| 57 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 58 | $ make TARGETS="size timers" kselftest |
Tim Bird | 3c41570 | 2014-11-19 16:16:16 -0800 | [diff] [blame] | 59 | |
Shuah Khan | d5cdbb8 | 2017-10-02 17:44:17 -0600 | [diff] [blame] | 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 | |
Tim Bird | 3c41570 | 2014-11-19 16:16:16 -0800 | [diff] [blame] | 72 | See the top-level tools/testing/selftests/Makefile for the list of all |
| 73 | possible targets. |
| 74 | |
Shuah Khan | ddddda9 | 2014-07-02 09:51:38 -0600 | [diff] [blame] | 75 | Running the full range hotplug selftests |
| 76 | ======================================== |
| 77 | |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 78 | To build the hotplug tests:: |
Shuah Khan | ddddda9 | 2014-07-02 09:51:38 -0600 | [diff] [blame] | 79 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 80 | $ make -C tools/testing/selftests hotplug |
Shuah Khan | ddddda9 | 2014-07-02 09:51:38 -0600 | [diff] [blame] | 81 | |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 82 | To run the hotplug tests:: |
| 83 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 84 | $ make -C tools/testing/selftests run_hotplug |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 85 | |
| 86 | Note that some tests will require root privileges. |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 87 | |
Tim Bird | 3c41570 | 2014-11-19 16:16:16 -0800 | [diff] [blame] | 88 | |
Wang Long | 76caa6c | 2015-09-23 09:35:25 +0000 | [diff] [blame] | 89 | Install selftests |
| 90 | ================= |
| 91 | |
| 92 | You can use kselftest_install.sh tool installs selftests in default |
Masahiro Yamada | 9332ef9 | 2017-02-27 14:28:47 -0800 | [diff] [blame] | 93 | location which is tools/testing/selftests/kselftest or a user specified |
Wang Long | 76caa6c | 2015-09-23 09:35:25 +0000 | [diff] [blame] | 94 | location. |
| 95 | |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 96 | To install selftests in default location:: |
Wang Long | 76caa6c | 2015-09-23 09:35:25 +0000 | [diff] [blame] | 97 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 98 | $ cd tools/testing/selftests |
| 99 | $ ./kselftest_install.sh |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 100 | |
| 101 | To install selftests in a user specified location:: |
| 102 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 103 | $ cd tools/testing/selftests |
| 104 | $ ./kselftest_install.sh install_dir |
Wang Long | 76caa6c | 2015-09-23 09:35:25 +0000 | [diff] [blame] | 105 | |
Shuah Khan | 78566cf | 2016-11-07 13:24:14 -0700 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 113 | note some tests will require root privileges:: |
Shuah Khan | 78566cf | 2016-11-07 13:24:14 -0700 | [diff] [blame] | 114 | |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 115 | $ cd kselftest |
| 116 | $ ./run_kselftest.sh |
Wang Long | 76caa6c | 2015-09-23 09:35:25 +0000 | [diff] [blame] | 117 | |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 118 | Contributing new tests |
| 119 | ====================== |
| 120 | |
Zhiyi Sun | 4db1fa6 | 2016-02-24 00:08:11 +0800 | [diff] [blame] | 121 | In general, the rules for selftests are |
Jeremy Kerr | 80d0342 | 2013-02-27 17:05:57 -0800 | [diff] [blame] | 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. |
bamvor.zhangjian@huawei.com | 88baa78 | 2016-11-29 19:55:47 +0800 | [diff] [blame] | 131 | |
Mickaël Salaün | cef04cd | 2017-05-26 20:44:00 +0200 | [diff] [blame] | 132 | Contributing new tests (details) |
| 133 | ================================ |
bamvor.zhangjian@huawei.com | 88baa78 | 2016-11-29 19:55:47 +0800 | [diff] [blame] | 134 | |
| 135 | * Use TEST_GEN_XXX if such binaries or files are generated during |
| 136 | compiling. |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 137 | |
Shuah Khan | d5cdbb8 | 2017-10-02 17:44:17 -0600 | [diff] [blame] | 138 | TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by |
bamvor.zhangjian@huawei.com | 88baa78 | 2016-11-29 19:55:47 +0800 | [diff] [blame] | 139 | default. |
Mauro Carvalho Chehab | fde662d | 2017-06-17 12:26:40 -0300 | [diff] [blame] | 140 | |
Shuah Khan | d5cdbb8 | 2017-10-02 17:44:17 -0600 | [diff] [blame] | 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 | |
bamvor.zhangjian@huawei.com | 88baa78 | 2016-11-29 19:55:47 +0800 | [diff] [blame] | 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. |
Mickaël Salaün | 7e6a32a | 2017-06-05 20:37:17 +0200 | [diff] [blame] | 153 | |
Anders Roxell | a997a70 | 2018-04-19 12:28:25 +0200 | [diff] [blame] | 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 | |
Mickaël Salaün | 7e6a32a | 2017-06-05 20:37:17 +0200 | [diff] [blame] | 159 | Test Harness |
| 160 | ============ |
| 161 | |
| 162 | The kselftest_harness.h file contains useful helpers to build tests. The tests |
| 163 | from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example. |
| 164 | |
| 165 | Example |
| 166 | ------- |
| 167 | |
| 168 | .. kernel-doc:: tools/testing/selftests/kselftest_harness.h |
| 169 | :doc: example |
| 170 | |
| 171 | |
| 172 | Helpers |
| 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 | |
| 179 | Operators |
| 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 |