~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/dev-tools/kselftest.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/dev-tools/kselftest.rst (Version linux-6.12-rc7) and /Documentation/dev-tools/kselftest.rst (Version linux-6.0.19)


  1 ======================                              1 ======================
  2 Linux Kernel Selftests                              2 Linux Kernel Selftests
  3 ======================                              3 ======================
  4                                                     4 
  5 The kernel contains a set of "self tests" unde      5 The kernel contains a set of "self tests" under the tools/testing/selftests/
  6 directory. These are intended to be small test      6 directory. These are intended to be small tests to exercise individual code
  7 paths in the kernel. Tests are intended to be       7 paths in the kernel. Tests are intended to be run after building, installing
  8 and booting a kernel.                               8 and booting a kernel.
  9                                                     9 
 10 Kselftest from mainline can be run on older st     10 Kselftest from mainline can be run on older stable kernels. Running tests
 11 from mainline offers the best coverage. Severa     11 from mainline offers the best coverage. Several test rings run mainline
 12 kselftest suite on stable releases. The reason     12 kselftest suite on stable releases. The reason is that when a new test
 13 gets added to test existing code to regression     13 gets added to test existing code to regression test a bug, we should be
 14 able to run that test on an older kernel. Henc     14 able to run that test on an older kernel. Hence, it is important to keep
 15 code that can still test an older kernel and m     15 code that can still test an older kernel and make sure it skips the test
 16 gracefully on newer releases.                      16 gracefully on newer releases.
 17                                                    17 
 18 You can find additional information on Kselfte     18 You can find additional information on Kselftest framework, how to
 19 write new tests using the framework on Kselfte     19 write new tests using the framework on Kselftest wiki:
 20                                                    20 
 21 https://kselftest.wiki.kernel.org/                 21 https://kselftest.wiki.kernel.org/
 22                                                    22 
 23 On some systems, hot-plug tests could hang for     23 On some systems, hot-plug tests could hang forever waiting for cpu and
 24 memory to be ready to be offlined. A special h     24 memory to be ready to be offlined. A special hot-plug target is created
 25 to run the full range of hot-plug tests. In de     25 to run the full range of hot-plug tests. In default mode, hot-plug tests run
 26 in safe mode with a limited scope. In limited      26 in safe mode with a limited scope. In limited mode, cpu-hotplug test is
 27 run on a single cpu as opposed to all hotplug      27 run on a single cpu as opposed to all hotplug capable cpus, and memory
 28 hotplug test is run on 2% of hotplug capable m     28 hotplug test is run on 2% of hotplug capable memory instead of 10%.
 29                                                    29 
 30 kselftest runs as a userspace process.  Tests      30 kselftest runs as a userspace process.  Tests that can be written/run in
 31 userspace may wish to use the `Test Harness`_.     31 userspace may wish to use the `Test Harness`_.  Tests that need to be
 32 run in kernel space may wish to use a `Test Mo     32 run in kernel space may wish to use a `Test Module`_.
 33                                                    33 
 34 Running the selftests (hotplug tests are run i     34 Running the selftests (hotplug tests are run in limited mode)
 35 ==============================================     35 =============================================================
 36                                                    36 
 37 To build the tests::                               37 To build the tests::
 38                                                    38 
 39   $ make headers                               << 
 40   $ make -C tools/testing/selftests                39   $ make -C tools/testing/selftests
 41                                                    40 
 42 To run the tests::                                 41 To run the tests::
 43                                                    42 
 44   $ make -C tools/testing/selftests run_tests      43   $ make -C tools/testing/selftests run_tests
 45                                                    44 
 46 To build and run the tests with a single comma     45 To build and run the tests with a single command, use::
 47                                                    46 
 48   $ make kselftest                                 47   $ make kselftest
 49                                                    48 
 50 Note that some tests will require root privile     49 Note that some tests will require root privileges.
 51                                                    50 
 52 Kselftest supports saving output files in a se     51 Kselftest supports saving output files in a separate directory and then
 53 running tests. To locate output files in a sep     52 running tests. To locate output files in a separate directory two syntaxes
 54 are supported. In both cases the working direc     53 are supported. In both cases the working directory must be the root of the
 55 kernel src. This is applicable to "Running a s     54 kernel src. This is applicable to "Running a subset of selftests" section
 56 below.                                             55 below.
 57                                                    56 
 58 To build, save output files in a separate dire     57 To build, save output files in a separate directory with O= ::
 59                                                    58 
 60   $ make O=/tmp/kselftest kselftest                59   $ make O=/tmp/kselftest kselftest
 61                                                    60 
 62 To build, save output files in a separate dire     61 To build, save output files in a separate directory with KBUILD_OUTPUT ::
 63                                                    62 
 64   $ export KBUILD_OUTPUT=/tmp/kselftest; make      63   $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
 65                                                    64 
 66 The O= assignment takes precedence over the KB     65 The O= assignment takes precedence over the KBUILD_OUTPUT environment
 67 variable.                                          66 variable.
 68                                                    67 
 69 The above commands by default run the tests an     68 The above commands by default run the tests and print full pass/fail report.
 70 Kselftest supports "summary" option to make it     69 Kselftest supports "summary" option to make it easier to understand the test
 71 results. Please find the detailed individual t     70 results. Please find the detailed individual test results for each test in
 72 /tmp/testname file(s) when summary option is s     71 /tmp/testname file(s) when summary option is specified. This is applicable
 73 to "Running a subset of selftests" section bel     72 to "Running a subset of selftests" section below.
 74                                                    73 
 75 To run kselftest with summary option enabled :     74 To run kselftest with summary option enabled ::
 76                                                    75 
 77   $ make summary=1 kselftest                       76   $ make summary=1 kselftest
 78                                                    77 
 79 Running a subset of selftests                      78 Running a subset of selftests
 80 =============================                      79 =============================
 81                                                    80 
 82 You can use the "TARGETS" variable on the make     81 You can use the "TARGETS" variable on the make command line to specify
 83 single test to run, or a list of tests to run.     82 single test to run, or a list of tests to run.
 84                                                    83 
 85 To run only tests targeted for a single subsys     84 To run only tests targeted for a single subsystem::
 86                                                    85 
 87   $ make -C tools/testing/selftests TARGETS=pt     86   $ make -C tools/testing/selftests TARGETS=ptrace run_tests
 88                                                    87 
 89 You can specify multiple tests to build and ru     88 You can specify multiple tests to build and run::
 90                                                    89 
 91   $  make TARGETS="size timers" kselftest          90   $  make TARGETS="size timers" kselftest
 92                                                    91 
 93 To build, save output files in a separate dire     92 To build, save output files in a separate directory with O= ::
 94                                                    93 
 95   $ make O=/tmp/kselftest TARGETS="size timers     94   $ make O=/tmp/kselftest TARGETS="size timers" kselftest
 96                                                    95 
 97 To build, save output files in a separate dire     96 To build, save output files in a separate directory with KBUILD_OUTPUT ::
 98                                                    97 
 99   $ export KBUILD_OUTPUT=/tmp/kselftest; make      98   $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest
100                                                    99 
101 Additionally you can use the "SKIP_TARGETS" va    100 Additionally you can use the "SKIP_TARGETS" variable on the make command
102 line to specify one or more targets to exclude    101 line to specify one or more targets to exclude from the TARGETS list.
103                                                   102 
104 To run all tests but a single subsystem::         103 To run all tests but a single subsystem::
105                                                   104 
106   $ make -C tools/testing/selftests SKIP_TARGE    105   $ make -C tools/testing/selftests SKIP_TARGETS=ptrace run_tests
107                                                   106 
108 You can specify multiple tests to skip::          107 You can specify multiple tests to skip::
109                                                   108 
110   $  make SKIP_TARGETS="size timers" kselftest    109   $  make SKIP_TARGETS="size timers" kselftest
111                                                   110 
112 You can also specify a restricted list of test    111 You can also specify a restricted list of tests to run together with a
113 dedicated skiplist::                              112 dedicated skiplist::
114                                                   113 
115   $  make TARGETS="breakpoints size timers" SK !! 114   $  make TARGETS="bpf breakpoints size timers" SKIP_TARGETS=bpf kselftest
116                                                   115 
117 See the top-level tools/testing/selftests/Make    116 See the top-level tools/testing/selftests/Makefile for the list of all
118 possible targets.                                 117 possible targets.
119                                                   118 
120 Running the full range hotplug selftests          119 Running the full range hotplug selftests
121 ========================================          120 ========================================
122                                                   121 
123 To build the hotplug tests::                      122 To build the hotplug tests::
124                                                   123 
125   $ make -C tools/testing/selftests hotplug       124   $ make -C tools/testing/selftests hotplug
126                                                   125 
127 To run the hotplug tests::                        126 To run the hotplug tests::
128                                                   127 
129   $ make -C tools/testing/selftests run_hotplu    128   $ make -C tools/testing/selftests run_hotplug
130                                                   129 
131 Note that some tests will require root privile    130 Note that some tests will require root privileges.
132                                                   131 
133                                                   132 
134 Install selftests                                 133 Install selftests
135 =================                                 134 =================
136                                                   135 
137 You can use the "install" target of "make" (wh    136 You can use the "install" target of "make" (which calls the `kselftest_install.sh`
138 tool) to install selftests in the default loca    137 tool) to install selftests in the default location (`tools/testing/selftests/kselftest_install`),
139 or in a user specified location via the `INSTA    138 or in a user specified location via the `INSTALL_PATH` "make" variable.
140                                                   139 
141 To install selftests in default location::        140 To install selftests in default location::
142                                                   141 
143    $ make -C tools/testing/selftests install      142    $ make -C tools/testing/selftests install
144                                                   143 
145 To install selftests in a user specified locat    144 To install selftests in a user specified location::
146                                                   145 
147    $ make -C tools/testing/selftests install I    146    $ make -C tools/testing/selftests install INSTALL_PATH=/some/other/path
148                                                   147 
149 Running installed selftests                       148 Running installed selftests
150 ===========================                       149 ===========================
151                                                   150 
152 Found in the install directory, as well as in     151 Found in the install directory, as well as in the Kselftest tarball,
153 is a script named `run_kselftest.sh` to run th    152 is a script named `run_kselftest.sh` to run the tests.
154                                                   153 
155 You can simply do the following to run the ins    154 You can simply do the following to run the installed Kselftests. Please
156 note some tests will require root privileges::    155 note some tests will require root privileges::
157                                                   156 
158    $ cd kselftest_install                         157    $ cd kselftest_install
159    $ ./run_kselftest.sh                           158    $ ./run_kselftest.sh
160                                                   159 
161 To see the list of available tests, the `-l` o    160 To see the list of available tests, the `-l` option can be used::
162                                                   161 
163    $ ./run_kselftest.sh -l                        162    $ ./run_kselftest.sh -l
164                                                   163 
165 The `-c` option can be used to run all the tes    164 The `-c` option can be used to run all the tests from a test collection, or
166 the `-t` option for specific single tests. Eit    165 the `-t` option for specific single tests. Either can be used multiple times::
167                                                   166 
168    $ ./run_kselftest.sh -c size -c seccomp -t  !! 167    $ ./run_kselftest.sh -c bpf -c seccomp -t timers:posix_timers -t timer:nanosleep
169                                                   168 
170 For other features see the script usage output    169 For other features see the script usage output, seen with the `-h` option.
171                                                   170 
172 Timeout for selftests                          << 
173 =====================                          << 
174                                                << 
175 Selftests are designed to be quick and so a de << 
176 seconds for each test. Tests can override the  << 
177 a settings file in their directory and set a t << 
178 configured a desired upper timeout for the tes << 
179 the timeout with a value higher than 45 second << 
180 it that way. Timeouts in selftests are not con << 
181 system under which a test runs may change and  << 
182 expected time it takes to run a test. If you h << 
183 which will run the tests you can configure a t << 
184 use a greater or lower timeout on the command  << 
185 the `--override-timeout` argument. For example << 
186 one would use::                                << 
187                                                << 
188    $ ./run_kselftest.sh --override-timeout 165 << 
189                                                << 
190 You can look at the TAP output to see if you r << 
191 runners which know a test must run under a spe << 
192 treat these timeouts then as fatal.            << 
193                                                << 
194 Packaging selftests                               171 Packaging selftests
195 ===================                               172 ===================
196                                                   173 
197 In some cases packaging is desired, such as wh    174 In some cases packaging is desired, such as when tests need to run on a
198 different system. To package selftests, run::     175 different system. To package selftests, run::
199                                                   176 
200    $ make -C tools/testing/selftests gen_tar      177    $ make -C tools/testing/selftests gen_tar
201                                                   178 
202 This generates a tarball in the `INSTALL_PATH/    179 This generates a tarball in the `INSTALL_PATH/kselftest-packages` directory. By
203 default, `.gz` format is used. The tar compres    180 default, `.gz` format is used. The tar compression format can be overridden by
204 specifying a `FORMAT` make variable. Any value    181 specifying a `FORMAT` make variable. Any value recognized by `tar's auto-compress`_
205 option is supported, such as::                    182 option is supported, such as::
206                                                   183 
207     $ make -C tools/testing/selftests gen_tar     184     $ make -C tools/testing/selftests gen_tar FORMAT=.xz
208                                                   185 
209 `make gen_tar` invokes `make install` so you c    186 `make gen_tar` invokes `make install` so you can use it to package a subset of
210 tests by using variables specified in `Running    187 tests by using variables specified in `Running a subset of selftests`_
211 section::                                         188 section::
212                                                   189 
213     $ make -C tools/testing/selftests gen_tar  !! 190     $ make -C tools/testing/selftests gen_tar TARGETS="bpf" FORMAT=.xz
214                                                   191 
215 .. _tar's auto-compress: https://www.gnu.org/s    192 .. _tar's auto-compress: https://www.gnu.org/software/tar/manual/html_node/gzip.html#auto_002dcompress
216                                                   193 
217 Contributing new tests                            194 Contributing new tests
218 ======================                            195 ======================
219                                                   196 
220 In general, the rules for selftests are           197 In general, the rules for selftests are
221                                                   198 
222  * Do as much as you can if you're not root;      199  * Do as much as you can if you're not root;
223                                                   200 
224  * Don't take too long;                           201  * Don't take too long;
225                                                   202 
226  * Don't break the build on any architecture,     203  * Don't break the build on any architecture, and
227                                                   204 
228  * Don't cause the top-level "make run_tests"     205  * Don't cause the top-level "make run_tests" to fail if your feature is
229    unconfigured.                                  206    unconfigured.
230                                                   207 
231  * The output of tests must conform to the TAP << 
232    testing quality and to capture failures/err << 
233    The kselftest.h and kselftest_harness.h hea << 
234    outputting test results. These wrappers sho << 
235    fail, exit, and skip messages. CI systems c << 
236    messages to detect test results.            << 
237                                                << 
238 Contributing new tests (details)                  208 Contributing new tests (details)
239 ================================                  209 ================================
240                                                   210 
241  * In your Makefile, use facilities from lib.m    211  * In your Makefile, use facilities from lib.mk by including it instead of
242    reinventing the wheel. Specify flags and bi    212    reinventing the wheel. Specify flags and binaries generation flags on
243    need basis before including lib.mk. ::         213    need basis before including lib.mk. ::
244                                                   214 
245     CFLAGS = $(KHDR_INCLUDES)                     215     CFLAGS = $(KHDR_INCLUDES)
246     TEST_GEN_PROGS := close_range_test            216     TEST_GEN_PROGS := close_range_test
247     include ../lib.mk                             217     include ../lib.mk
248                                                   218 
249  * Use TEST_GEN_XXX if such binaries or files     219  * Use TEST_GEN_XXX if such binaries or files are generated during
250    compiling.                                     220    compiling.
251                                                   221 
252    TEST_PROGS, TEST_GEN_PROGS mean it is the e    222    TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by
253    default.                                       223    default.
254                                                   224 
255    TEST_GEN_MODS_DIR should be used by tests t << 
256    before the test starts. The variable will c << 
257    containing the modules.                     << 
258                                                << 
259    TEST_CUSTOM_PROGS should be used by tests t    225    TEST_CUSTOM_PROGS should be used by tests that require custom build
260    rules and prevent common build rule use.       226    rules and prevent common build rule use.
261                                                   227 
262    TEST_PROGS are for test shell scripts. Plea    228    TEST_PROGS are for test shell scripts. Please ensure shell script has
263    its exec bit set. Otherwise, lib.mk run_tes    229    its exec bit set. Otherwise, lib.mk run_tests will generate a warning.
264                                                   230 
265    TEST_CUSTOM_PROGS and TEST_PROGS will be ru    231    TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests.
266                                                   232 
267    TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDE    233    TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the
268    executable which is not tested by default.     234    executable which is not tested by default.
269                                                << 
270    TEST_FILES, TEST_GEN_FILES mean it is the f    235    TEST_FILES, TEST_GEN_FILES mean it is the file which is used by
271    test.                                          236    test.
272                                                   237 
273    TEST_INCLUDES is similar to TEST_FILES, it  << 
274    included when exporting or installing the t << 
275    differences:                                << 
276                                                << 
277     * symlinks to files in other directories a << 
278     * the part of paths below tools/testing/se << 
279       copying the files to the output director << 
280                                                << 
281    TEST_INCLUDES is meant to list dependencies << 
282    the selftests hierarchy.                    << 
283                                                << 
284  * First use the headers inside the kernel sou    238  * First use the headers inside the kernel source and/or git repo, and then the
285    system headers.  Headers for the kernel rel    239    system headers.  Headers for the kernel release as opposed to headers
286    installed by the distro on the system shoul    240    installed by the distro on the system should be the primary focus to be able
287    to find regressions. Use KHDR_INCLUDES in M    241    to find regressions. Use KHDR_INCLUDES in Makefile to include headers from
288    the kernel source.                             242    the kernel source.
289                                                   243 
290  * If a test needs specific kernel config opti    244  * If a test needs specific kernel config options enabled, add a config file in
291    the test directory to enable them.             245    the test directory to enable them.
292                                                   246 
293    e.g: tools/testing/selftests/android/config    247    e.g: tools/testing/selftests/android/config
294                                                   248 
295  * Create a .gitignore file inside test direct    249  * Create a .gitignore file inside test directory and add all generated objects
296    in it.                                         250    in it.
297                                                   251 
298  * Add new test name in TARGETS in selftests/M    252  * Add new test name in TARGETS in selftests/Makefile::
299                                                   253 
300     TARGETS += android                            254     TARGETS += android
301                                                   255 
302  * All changes should pass::                      256  * All changes should pass::
303                                                   257 
304     kselftest-{all,install,clean,gen_tar}         258     kselftest-{all,install,clean,gen_tar}
305     kselftest-{all,install,clean,gen_tar} O=ab    259     kselftest-{all,install,clean,gen_tar} O=abo_path
306     kselftest-{all,install,clean,gen_tar} O=re    260     kselftest-{all,install,clean,gen_tar} O=rel_path
307     make -C tools/testing/selftests {all,insta    261     make -C tools/testing/selftests {all,install,clean,gen_tar}
308     make -C tools/testing/selftests {all,insta    262     make -C tools/testing/selftests {all,install,clean,gen_tar} O=abs_path
309     make -C tools/testing/selftests {all,insta    263     make -C tools/testing/selftests {all,install,clean,gen_tar} O=rel_path
310                                                   264 
311 Test Module                                       265 Test Module
312 ===========                                       266 ===========
313                                                   267 
314 Kselftest tests the kernel from userspace.  So    268 Kselftest tests the kernel from userspace.  Sometimes things need
315 testing from within the kernel, one method of     269 testing from within the kernel, one method of doing this is to create a
316 test module.  We can tie the module into the k    270 test module.  We can tie the module into the kselftest framework by
317 using a shell script test runner.  ``kselftest    271 using a shell script test runner.  ``kselftest/module.sh`` is designed
318 to facilitate this process.  There is also a h    272 to facilitate this process.  There is also a header file provided to
319 assist writing kernel modules that are for use    273 assist writing kernel modules that are for use with kselftest:
320                                                   274 
321 - ``tools/testing/selftests/kselftest_module.h    275 - ``tools/testing/selftests/kselftest_module.h``
322 - ``tools/testing/selftests/kselftest/module.s    276 - ``tools/testing/selftests/kselftest/module.sh``
323                                                   277 
324 Note that test modules should taint the kernel    278 Note that test modules should taint the kernel with TAINT_TEST. This will
325 happen automatically for modules which are in     279 happen automatically for modules which are in the ``tools/testing/``
326 directory, or for modules which use the ``ksel    280 directory, or for modules which use the ``kselftest_module.h`` header above.
327 Otherwise, you'll need to add ``MODULE_INFO(te    281 Otherwise, you'll need to add ``MODULE_INFO(test, "Y")`` to your module
328 source. selftests which do not load modules ty    282 source. selftests which do not load modules typically should not taint the
329 kernel, but in cases where a non-test module i    283 kernel, but in cases where a non-test module is loaded, TEST_TAINT can be
330 applied from userspace by writing to ``/proc/s    284 applied from userspace by writing to ``/proc/sys/kernel/tainted``.
331                                                   285 
332 How to use                                        286 How to use
333 ----------                                        287 ----------
334                                                   288 
335 Here we show the typical steps to create a tes    289 Here we show the typical steps to create a test module and tie it into
336 kselftest.  We use kselftests for lib/ as an e    290 kselftest.  We use kselftests for lib/ as an example.
337                                                   291 
338 1. Create the test module                         292 1. Create the test module
339                                                   293 
340 2. Create the test script that will run (load/    294 2. Create the test script that will run (load/unload) the module
341    e.g. ``tools/testing/selftests/lib/printf.s    295    e.g. ``tools/testing/selftests/lib/printf.sh``
342                                                   296 
343 3. Add line to config file e.g. ``tools/testin    297 3. Add line to config file e.g. ``tools/testing/selftests/lib/config``
344                                                   298 
345 4. Add test script to makefile  e.g. ``tools/t    299 4. Add test script to makefile  e.g. ``tools/testing/selftests/lib/Makefile``
346                                                   300 
347 5. Verify it works:                               301 5. Verify it works:
348                                                   302 
349 .. code-block:: sh                                303 .. code-block:: sh
350                                                   304 
351    # Assumes you have booted a fresh build of     305    # Assumes you have booted a fresh build of this kernel tree
352    cd /path/to/linux/tree                         306    cd /path/to/linux/tree
353    make kselftest-merge                           307    make kselftest-merge
354    make modules                                   308    make modules
355    sudo make modules_install                      309    sudo make modules_install
356    make TARGETS=lib kselftest                     310    make TARGETS=lib kselftest
357                                                   311 
358 Example Module                                    312 Example Module
359 --------------                                    313 --------------
360                                                   314 
361 A bare bones test module might look like this:    315 A bare bones test module might look like this:
362                                                   316 
363 .. code-block:: c                                 317 .. code-block:: c
364                                                   318 
365    // SPDX-License-Identifier: GPL-2.0+           319    // SPDX-License-Identifier: GPL-2.0+
366                                                   320 
367    #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt    321    #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
368                                                   322 
369    #include "../tools/testing/selftests/kselft !! 323    #include "../tools/testing/selftests/kselftest/module.h"
370                                                   324 
371    KSTM_MODULE_GLOBALS();                         325    KSTM_MODULE_GLOBALS();
372                                                   326 
373    /*                                             327    /*
374     * Kernel module for testing the foobinator    328     * Kernel module for testing the foobinator
375     */                                            329     */
376                                                   330 
377    static int __init test_function()              331    static int __init test_function()
378    {                                              332    {
379            ...                                    333            ...
380    }                                              334    }
381                                                   335 
382    static void __init selftest(void)              336    static void __init selftest(void)
383    {                                              337    {
384            KSTM_CHECK_ZERO(do_test_case("", 0)    338            KSTM_CHECK_ZERO(do_test_case("", 0));
385    }                                              339    }
386                                                   340 
387    KSTM_MODULE_LOADERS(test_foo);                 341    KSTM_MODULE_LOADERS(test_foo);
388    MODULE_AUTHOR("John Developer <jd@fooman.org    342    MODULE_AUTHOR("John Developer <jd@fooman.org>");
389    MODULE_LICENSE("GPL");                         343    MODULE_LICENSE("GPL");
390    MODULE_INFO(test, "Y");                        344    MODULE_INFO(test, "Y");
391                                                   345 
392 Example test script                               346 Example test script
393 -------------------                               347 -------------------
394                                                   348 
395 .. code-block:: sh                                349 .. code-block:: sh
396                                                   350 
397     #!/bin/bash                                   351     #!/bin/bash
398     # SPDX-License-Identifier: GPL-2.0+           352     # SPDX-License-Identifier: GPL-2.0+
399     $(dirname $0)/../kselftest/module.sh "foo"    353     $(dirname $0)/../kselftest/module.sh "foo" test_foo
400                                                   354 
401                                                   355 
402 Test Harness                                      356 Test Harness
403 ============                                      357 ============
404                                                   358 
405 The kselftest_harness.h file contains useful h    359 The kselftest_harness.h file contains useful helpers to build tests.  The
406 test harness is for userspace testing, for ker    360 test harness is for userspace testing, for kernel space testing see `Test
407 Module`_ above.                                   361 Module`_ above.
408                                                   362 
409 The tests from tools/testing/selftests/seccomp    363 The tests from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as
410 example.                                          364 example.
411                                                   365 
412 Example                                           366 Example
413 -------                                           367 -------
414                                                   368 
415 .. kernel-doc:: tools/testing/selftests/kselft    369 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
416     :doc: example                                 370     :doc: example
417                                                   371 
418                                                   372 
419 Helpers                                           373 Helpers
420 -------                                           374 -------
421                                                   375 
422 .. kernel-doc:: tools/testing/selftests/kselft    376 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
423     :functions: TH_LOG TEST TEST_SIGNAL FIXTUR    377     :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP
424                 FIXTURE_TEARDOWN TEST_F TEST_H    378                 FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN FIXTURE_VARIANT
425                 FIXTURE_VARIANT_ADD               379                 FIXTURE_VARIANT_ADD
426                                                   380 
427 Operators                                         381 Operators
428 ---------                                         382 ---------
429                                                   383 
430 .. kernel-doc:: tools/testing/selftests/kselft    384 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
431     :doc: operators                               385     :doc: operators
432                                                   386 
433 .. kernel-doc:: tools/testing/selftests/kselft    387 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
434     :functions: ASSERT_EQ ASSERT_NE ASSERT_LT     388     :functions: ASSERT_EQ ASSERT_NE ASSERT_LT ASSERT_LE ASSERT_GT ASSERT_GE
435                 ASSERT_NULL ASSERT_TRUE ASSERT    389                 ASSERT_NULL ASSERT_TRUE ASSERT_NULL ASSERT_TRUE ASSERT_FALSE
436                 ASSERT_STREQ ASSERT_STRNE EXPE    390                 ASSERT_STREQ ASSERT_STRNE EXPECT_EQ EXPECT_NE EXPECT_LT
437                 EXPECT_LE EXPECT_GT EXPECT_GE     391                 EXPECT_LE EXPECT_GT EXPECT_GE EXPECT_NULL EXPECT_TRUE
438                 EXPECT_FALSE EXPECT_STREQ EXPE    392                 EXPECT_FALSE EXPECT_STREQ EXPECT_STRNE
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php