forked from ~ljy/RK356X_SDK_RELEASE
blame | history | patch | commit | commitdiff
hc
2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771 
 kernel/Documentation/dev-tools/kselftest.rst
....@@ -7,12 +7,21 @@
77 paths in the kernel. Tests are intended to be run after building, installing
88 and booting a kernel.
99 
10
+You can find additional information on Kselftest framework, how to
11
+write new tests using the framework on Kselftest wiki:
12
+
13
+https://kselftest.wiki.kernel.org/
14
+
1015 On some systems, hot-plug tests could hang forever waiting for cpu and
1116 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
17
+to run the full range of hot-plug tests. In default mode, hot-plug tests run
1318 in safe mode with a limited scope. In limited mode, cpu-hotplug test is
1419 run on a single cpu as opposed to all hotplug capable cpus, and memory
1520 hotplug test is run on 2% of hotplug capable memory instead of 10%.
21
+
22
+kselftest runs as a userspace process.  Tests that can be written/run in
23
+userspace may wish to use the `Test Harness`_.  Tests that need to be
24
+run in kernel space may wish to use a `Test Module`_.
1625 
1726 Running the selftests (hotplug tests are run in limited mode)
1827 =============================================================
....@@ -31,17 +40,32 @@
3140 
3241 Note that some tests will require root privileges.
3342 
34
-Build and run from user specific object directory (make O=dir)::
43
+Kselftest supports saving output files in a separate directory and then
44
+running tests. To locate output files in a separate directory two syntaxes
45
+are supported. In both cases the working directory must be the root of the
46
+kernel src. This is applicable to "Running a subset of selftests" section
47
+below.
48
+
49
+To build, save output files in a separate directory with O= ::
3550 
3651   $ make O=/tmp/kselftest kselftest
3752 
38
-Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
53
+To build, save output files in a separate directory with KBUILD_OUTPUT ::
3954 
40
-  $ make KBUILD_OUTPUT=/tmp/kselftest kselftest
55
+  $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
4156 
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).
57
+The O= assignment takes precedence over the KBUILD_OUTPUT environment
58
+variable.
59
+
60
+The above commands by default run the tests and print full pass/fail report.
61
+Kselftest supports "summary" option to make it easier to understand the test
62
+results. Please find the detailed individual test results for each test in
63
+/tmp/testname file(s) when summary option is specified. This is applicable
64
+to "Running a subset of selftests" section below.
65
+
66
+To run kselftest with summary option enabled ::
67
+
68
+  $ make summary=1 kselftest
4569 
4670 Running a subset of selftests
4771 =============================
....@@ -57,17 +81,29 @@
5781 
5882   $  make TARGETS="size timers" kselftest
5983 
60
-Build and run from user specific object directory (make O=dir)::
84
+To build, save output files in a separate directory with O= ::
6185 
6286   $ make O=/tmp/kselftest TARGETS="size timers" kselftest
6387 
64
-Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
88
+To build, save output files in a separate directory with KBUILD_OUTPUT ::
6589 
66
-  $ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest
90
+  $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest
6791 
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).
92
+Additionally you can use the "SKIP_TARGETS" variable on the make command
93
+line to specify one or more targets to exclude from the TARGETS list.
94
+
95
+To run all tests but a single subsystem::
96
+
97
+  $ make -C tools/testing/selftests SKIP_TARGETS=ptrace run_tests
98
+
99
+You can specify multiple tests to skip::
100
+
101
+  $  make SKIP_TARGETS="size timers" kselftest
102
+
103
+You can also specify a restricted list of tests to run together with a
104
+dedicated skiplist::
105
+
106
+  $  make TARGETS="bpf breakpoints size timers" SKIP_TARGETS=bpf kselftest
71107 
72108 See the top-level tools/testing/selftests/Makefile for the list of all
73109 possible targets.
....@@ -89,31 +125,63 @@
89125 Install selftests
90126 =================
91127 
92
-You can use kselftest_install.sh tool installs selftests in default
93
-location which is tools/testing/selftests/kselftest or a user specified
94
-location.
128
+You can use the "install" target of "make" (which calls the `kselftest_install.sh`
129
+tool) to install selftests in the default location (`tools/testing/selftests/kselftest_install`),
130
+or in a user specified location via the `INSTALL_PATH` "make" variable.
95131 
96132 To install selftests in default location::
97133 
98
-   $ cd tools/testing/selftests
99
-   $ ./kselftest_install.sh
134
+   $ make -C tools/testing/selftests install
100135 
101136 To install selftests in a user specified location::
102137 
103
-   $ cd tools/testing/selftests
104
-   $ ./kselftest_install.sh install_dir
138
+   $ make -C tools/testing/selftests install INSTALL_PATH=/some/other/path
105139 
106140 Running installed selftests
107141 ===========================
108142 
109
-Kselftest install as well as the Kselftest tarball provide a script
110
-named "run_kselftest.sh" to run the tests.
143
+Found in the install directory, as well as in the Kselftest tarball,
144
+is a script named `run_kselftest.sh` to run the tests.
111145 
112
-You can simply do the following to run the installed Kselftests. Please
146
+You can simply do the following to run the installed Kselftests. Please
113147 note some tests will require root privileges::
114148 
115
-   $ cd kselftest
149
+   $ cd kselftest_install
116150    $ ./run_kselftest.sh
151
+
152
+To see the list of available tests, the `-l` option can be used::
153
+
154
+   $ ./run_kselftest.sh -l
155
+
156
+The `-c` option can be used to run all the tests from a test collection, or
157
+the `-t` option for specific single tests. Either can be used multiple times::
158
+
159
+   $ ./run_kselftest.sh -c bpf -c seccomp -t timers:posix_timers -t timer:nanosleep
160
+
161
+For other features see the script usage output, seen with the `-h` option.
162
+
163
+Packaging selftests
164
+===================
165
+
166
+In some cases packaging is desired, such as when tests need to run on a
167
+different system. To package selftests, run::
168
+
169
+   $ make -C tools/testing/selftests gen_tar
170
+
171
+This generates a tarball in the `INSTALL_PATH/kselftest-packages` directory. By
172
+default, `.gz` format is used. The tar compression format can be overridden by
173
+specifying a `FORMAT` make variable. Any value recognized by `tar's auto-compress`_
174
+option is supported, such as::
175
+
176
+    $ make -C tools/testing/selftests gen_tar FORMAT=.xz
177
+
178
+`make gen_tar` invokes `make install` so you can use it to package a subset of
179
+tests by using variables specified in `Running a subset of selftests`_
180
+section::
181
+
182
+    $ make -C tools/testing/selftests gen_tar TARGETS="bpf" FORMAT=.xz
183
+
184
+.. _tar's auto-compress: https://www.gnu.org/software/tar/manual/html_node/gzip.html#auto_002dcompress
117185 
118186 Contributing new tests
119187 ======================
....@@ -139,7 +207,7 @@
139207    default.
140208 
141209    TEST_CUSTOM_PROGS should be used by tests that require custom build
142
-   rule and prevent common build rule use.
210
+   rules and prevent common build rule use.
143211 
144212    TEST_PROGS are for test shell scripts. Please ensure shell script has
145213    its exec bit set. Otherwise, lib.mk run_tests will generate a warning.
....@@ -159,13 +227,99 @@
159227  * If a test needs specific kernel config options enabled, add a config file in
160228    the test directory to enable them.
161229 
162
-   e.g: tools/testing/selftests/android/ion/config
230
+   e.g: tools/testing/selftests/android/config
231
+
232
+Test Module
233
+===========
234
+
235
+Kselftest tests the kernel from userspace.  Sometimes things need
236
+testing from within the kernel, one method of doing this is to create a
237
+test module.  We can tie the module into the kselftest framework by
238
+using a shell script test runner.  ``kselftest/module.sh`` is designed
239
+to facilitate this process.  There is also a header file provided to
240
+assist writing kernel modules that are for use with kselftest:
241
+
242
+- ``tools/testing/kselftest/kselftest_module.h``
243
+- ``tools/testing/kselftest/kselftest/module.sh``
244
+
245
+How to use
246
+----------
247
+
248
+Here we show the typical steps to create a test module and tie it into
249
+kselftest.  We use kselftests for lib/ as an example.
250
+
251
+1. Create the test module
252
+
253
+2. Create the test script that will run (load/unload) the module
254
+   e.g. ``tools/testing/selftests/lib/printf.sh``
255
+
256
+3. Add line to config file e.g. ``tools/testing/selftests/lib/config``
257
+
258
+4. Add test script to makefile  e.g. ``tools/testing/selftests/lib/Makefile``
259
+
260
+5. Verify it works:
261
+
262
+.. code-block:: sh
263
+
264
+   # Assumes you have booted a fresh build of this kernel tree
265
+   cd /path/to/linux/tree
266
+   make kselftest-merge
267
+   make modules
268
+   sudo make modules_install
269
+   make TARGETS=lib kselftest
270
+
271
+Example Module
272
+--------------
273
+
274
+A bare bones test module might look like this:
275
+
276
+.. code-block:: c
277
+
278
+   // SPDX-License-Identifier: GPL-2.0+
279
+
280
+   #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
281
+
282
+   #include "../tools/testing/selftests/kselftest/module.h"
283
+
284
+   KSTM_MODULE_GLOBALS();
285
+
286
+   /*
287
+    * Kernel module for testing the foobinator
288
+    */
289
+
290
+   static int __init test_function()
291
+   {
292
+           ...
293
+   }
294
+
295
+   static void __init selftest(void)
296
+   {
297
+           KSTM_CHECK_ZERO(do_test_case("", 0));
298
+   }
299
+
300
+   KSTM_MODULE_LOADERS(test_foo);
301
+   MODULE_AUTHOR("John Developer <jd@fooman.org>");
302
+   MODULE_LICENSE("GPL");
303
+
304
+Example test script
305
+-------------------
306
+
307
+.. code-block:: sh
308
+
309
+    #!/bin/bash
310
+    # SPDX-License-Identifier: GPL-2.0+
311
+    $(dirname $0)/../kselftest/module.sh "foo" test_foo
312
+
163313 
164314 Test Harness
165315 ============
166316 
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.
317
+The kselftest_harness.h file contains useful helpers to build tests.  The
318
+test harness is for userspace testing, for kernel space testing see `Test
319
+Module`_ above.
320
+
321
+The tests from tools/testing/selftests/seccomp/seccomp_bpf.c can be used as
322
+example.
169323 
170324 Example
171325 -------
....@@ -179,7 +333,8 @@
179333 
180334 .. kernel-doc:: tools/testing/selftests/kselftest_harness.h
181335     :functions: TH_LOG TEST TEST_SIGNAL FIXTURE FIXTURE_DATA FIXTURE_SETUP
182
-                FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN
336
+                FIXTURE_TEARDOWN TEST_F TEST_HARNESS_MAIN FIXTURE_VARIANT
337
+                FIXTURE_VARIANT_ADD
183338 
184339 Operators
185340 ---------