]>
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 | |
80d03428 | 34 | |
3c415707 | 35 | Running a subset of selftests |
cef04cdc MS |
36 | ============================= |
37 | ||
3c415707 TB |
38 | You can use the "TARGETS" variable on the make command line to specify |
39 | single test to run, or a list of tests to run. | |
40 | ||
cef04cdc MS |
41 | To run only tests targeted for a single subsystem:: |
42 | ||
fde662d9 | 43 | $ make -C tools/testing/selftests TARGETS=ptrace run_tests |
3c415707 | 44 | |
cef04cdc MS |
45 | You can specify multiple tests to build and run:: |
46 | ||
fde662d9 | 47 | $ make TARGETS="size timers" kselftest |
3c415707 TB |
48 | |
49 | See the top-level tools/testing/selftests/Makefile for the list of all | |
50 | possible targets. | |
80d03428 | 51 | |
80d03428 | 52 | |
ddddda9b SK |
53 | Running the full range hotplug selftests |
54 | ======================================== | |
55 | ||
cef04cdc MS |
56 | To build the hotplug tests:: |
57 | ||
fde662d9 | 58 | $ make -C tools/testing/selftests hotplug |
cef04cdc MS |
59 | |
60 | To run the hotplug tests:: | |
ddddda9b | 61 | |
fde662d9 | 62 | $ make -C tools/testing/selftests run_hotplug |
ddddda9b | 63 | |
cef04cdc | 64 | Note that some tests will require root privileges. |
80d03428 | 65 | |
3c415707 | 66 | |
76caa6ca WL |
67 | Install selftests |
68 | ================= | |
69 | ||
70 | You can use kselftest_install.sh tool installs selftests in default | |
9332ef9d | 71 | location which is tools/testing/selftests/kselftest or a user specified |
76caa6ca WL |
72 | location. |
73 | ||
cef04cdc | 74 | To install selftests in default location:: |
76caa6ca | 75 | |
fde662d9 MCC |
76 | $ cd tools/testing/selftests |
77 | $ ./kselftest_install.sh | |
cef04cdc MS |
78 | |
79 | To install selftests in a user specified location:: | |
80 | ||
fde662d9 MCC |
81 | $ cd tools/testing/selftests |
82 | $ ./kselftest_install.sh install_dir | |
76caa6ca | 83 | |
78566cf1 SK |
84 | Running installed selftests |
85 | =========================== | |
86 | ||
87 | Kselftest install as well as the Kselftest tarball provide a script | |
88 | named "run_kselftest.sh" to run the tests. | |
89 | ||
90 | You can simply do the following to run the installed Kselftests. Please | |
fde662d9 | 91 | note some tests will require root privileges:: |
78566cf1 | 92 | |
fde662d9 MCC |
93 | $ cd kselftest |
94 | $ ./run_kselftest.sh | |
76caa6ca | 95 | |
80d03428 JK |
96 | Contributing new tests |
97 | ====================== | |
98 | ||
4db1fa66 | 99 | In general, the rules for selftests are |
80d03428 JK |
100 | |
101 | * Do as much as you can if you're not root; | |
102 | ||
103 | * Don't take too long; | |
104 | ||
105 | * Don't break the build on any architecture, and | |
106 | ||
107 | * Don't cause the top-level "make run_tests" to fail if your feature is | |
108 | unconfigured. | |
88baa78d | 109 | |
cef04cdc MS |
110 | Contributing new tests (details) |
111 | ================================ | |
88baa78d | 112 | |
113 | * Use TEST_GEN_XXX if such binaries or files are generated during | |
114 | compiling. | |
fde662d9 | 115 | |
88baa78d | 116 | TEST_PROGS, TEST_GEN_PROGS mean it is the excutable tested by |
117 | default. | |
fde662d9 | 118 | |
88baa78d | 119 | TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the |
120 | executable which is not tested by default. | |
121 | TEST_FILES, TEST_GEN_FILES mean it is the file which is used by | |
122 | test. | |
7e6a32ab MS |
123 | |
124 | Test Harness | |
125 | ============ | |
126 | ||
127 | The kselftest_harness.h file contains useful helpers to build tests. The tests | |
128 | from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as example. | |
129 | ||
130 | Example | |
131 | ------- | |
132 | ||
133 | .. kernel-doc:: tools/testing/selftests/kselftest_harness.h | |
134 | :doc: example | |
135 | ||
136 | ||
137 | Helpers | |
138 | ------- | |
139 | ||
140 | .. kernel-doc:: tools/testing/selftests/kselftest_harness.h | |
141 | :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP | |
142 | FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN | |
143 | ||
144 | Operators | |
145 | --------- | |
146 | ||
147 | .. kernel-doc:: tools/testing/selftests/kselftest_harness.h | |
148 | :doc: operators | |
149 | ||
150 | .. kernel-doc:: tools/testing/selftests/kselftest_harness.h | |
151 | :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE | |
152 | ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE | |
153 | ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT | |
154 | EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE | |
155 | EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE |