1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 Testing 3 Testing
4 ======= 4 =======
5 5
6 This document contains useful information how 6 This document contains useful information how to test the Rust code in the
7 kernel. 7 kernel.
8 8
9 There are three sorts of tests: !! 9 There are two sorts of tests:
10 10
11 - The KUnit tests. 11 - The KUnit tests.
12 - The ``#[test]`` tests. 12 - The ``#[test]`` tests.
13 - The Kselftests. <<
14 13
15 The KUnit tests 14 The KUnit tests
16 --------------- 15 ---------------
17 16
18 These are the tests that come from the example 17 These are the tests that come from the examples in the Rust documentation. They
19 get transformed into KUnit tests. 18 get transformed into KUnit tests.
20 19
21 Usage 20 Usage
22 ***** 21 *****
23 22
24 These tests can be run via KUnit. For example 23 These tests can be run via KUnit. For example via ``kunit_tool`` (``kunit.py``)
25 on the command line:: 24 on the command line::
26 25
27 ./tools/testing/kunit/kunit.py run --m 26 ./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
28 27
29 Alternatively, KUnit can run them as kernel bu 28 Alternatively, KUnit can run them as kernel built-in at boot. Refer to
30 Documentation/dev-tools/kunit/index.rst for th 29 Documentation/dev-tools/kunit/index.rst for the general KUnit documentation
31 and Documentation/dev-tools/kunit/architecture 30 and Documentation/dev-tools/kunit/architecture.rst for the details of kernel
32 built-in vs. command line testing. 31 built-in vs. command line testing.
33 32
34 To use these KUnit doctests, the following mus 33 To use these KUnit doctests, the following must be enabled::
35 34
36 CONFIG_KUNIT 35 CONFIG_KUNIT
37 Kernel hacking -> Kernel Testing an 36 Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests
38 CONFIG_RUST_KERNEL_DOCTESTS 37 CONFIG_RUST_KERNEL_DOCTESTS
39 Kernel hacking -> Rust hacking -> D 38 Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate
40 39
41 in the kernel config system. 40 in the kernel config system.
42 41
43 KUnit tests are documentation tests 42 KUnit tests are documentation tests
44 *********************************** 43 ***********************************
45 44
46 These documentation tests are typically exampl 45 These documentation tests are typically examples of usage of any item (e.g.
47 function, struct, module...). 46 function, struct, module...).
48 47
49 They are very convenient because they are just 48 They are very convenient because they are just written alongside the
50 documentation. For instance: 49 documentation. For instance:
51 50
52 .. code-block:: rust 51 .. code-block:: rust
53 52
54 /// Sums two numbers. 53 /// Sums two numbers.
55 /// 54 ///
56 /// ``` 55 /// ```
57 /// assert_eq!(mymod::f(10, 20), 30); 56 /// assert_eq!(mymod::f(10, 20), 30);
58 /// ``` 57 /// ```
59 pub fn f(a: i32, b: i32) -> i32 { 58 pub fn f(a: i32, b: i32) -> i32 {
60 a + b 59 a + b
61 } 60 }
62 61
63 In userspace, the tests are collected and run 62 In userspace, the tests are collected and run via ``rustdoc``. Using the tool
64 as-is would be useful already, since it allows 63 as-is would be useful already, since it allows verifying that examples compile
65 (thus enforcing they are kept in sync with the 64 (thus enforcing they are kept in sync with the code they document) and as well
66 as running those that do not depend on in-kern 65 as running those that do not depend on in-kernel APIs.
67 66
68 For the kernel, however, these tests get trans 67 For the kernel, however, these tests get transformed into KUnit test suites.
69 This means that doctests get compiled as Rust 68 This means that doctests get compiled as Rust kernel objects, allowing them to
70 run against a built kernel. 69 run against a built kernel.
71 70
72 A benefit of this KUnit integration is that Ru 71 A benefit of this KUnit integration is that Rust doctests get to reuse existing
73 testing facilities. For instance, the kernel l 72 testing facilities. For instance, the kernel log would look like::
74 73
75 KTAP version 1 74 KTAP version 1
76 1..1 75 1..1
77 KTAP version 1 76 KTAP version 1
78 # Subtest: rust_doctests_kernel 77 # Subtest: rust_doctests_kernel
79 1..59 78 1..59
80 # rust_doctest_kernel_build_assert 79 # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13
81 ok 1 rust_doctest_kernel_build_ass 80 ok 1 rust_doctest_kernel_build_assert_rs_0
82 # rust_doctest_kernel_build_assert 81 # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56
83 ok 2 rust_doctest_kernel_build_ass 82 ok 2 rust_doctest_kernel_build_assert_rs_1
84 # rust_doctest_kernel_init_rs_0.lo 83 # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122
85 ok 3 rust_doctest_kernel_init_rs_0 84 ok 3 rust_doctest_kernel_init_rs_0
86 ... 85 ...
87 # rust_doctest_kernel_types_rs_2.l 86 # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
88 ok 59 rust_doctest_kernel_types_rs 87 ok 59 rust_doctest_kernel_types_rs_2
89 # rust_doctests_kernel: pass:59 fail:0 88 # rust_doctests_kernel: pass:59 fail:0 skip:0 total:59
90 # Totals: pass:59 fail:0 skip:0 total: 89 # Totals: pass:59 fail:0 skip:0 total:59
91 ok 1 rust_doctests_kernel 90 ok 1 rust_doctests_kernel
92 91
93 Tests using the `? <https://doc.rust-lang.org/ 92 Tests using the `? <https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator>`_
94 operator are also supported as usual, e.g.: 93 operator are also supported as usual, e.g.:
95 94
96 .. code-block:: rust 95 .. code-block:: rust
97 96
98 /// ``` 97 /// ```
99 /// # use kernel::{spawn_work_item, wo 98 /// # use kernel::{spawn_work_item, workqueue};
100 /// spawn_work_item!(workqueue::system 99 /// spawn_work_item!(workqueue::system(), || pr_info!("x"))?;
101 /// # Ok::<(), Error>(()) 100 /// # Ok::<(), Error>(())
102 /// ``` 101 /// ```
103 102
104 The tests are also compiled with Clippy under 103 The tests are also compiled with Clippy under ``CLIPPY=1``, just like normal
105 code, thus also benefitting from extra linting 104 code, thus also benefitting from extra linting.
106 105
107 In order for developers to easily see which li 106 In order for developers to easily see which line of doctest code caused a
108 failure, a KTAP diagnostic line is printed to 107 failure, a KTAP diagnostic line is printed to the log. This contains the
109 location (file and line) of the original test 108 location (file and line) of the original test (i.e. instead of the location in
110 the generated Rust file):: 109 the generated Rust file)::
111 110
112 # rust_doctest_kernel_types_rs_2.locat 111 # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
113 112
114 Rust tests appear to assert using the usual `` 113 Rust tests appear to assert using the usual ``assert!`` and ``assert_eq!``
115 macros from the Rust standard library (``core` 114 macros from the Rust standard library (``core``). We provide a custom version
116 that forwards the call to KUnit instead. Impor 115 that forwards the call to KUnit instead. Importantly, these macros do not
117 require passing context, unlike those for KUni 116 require passing context, unlike those for KUnit testing (i.e.
118 ``struct kunit *``). This makes them easier to 117 ``struct kunit *``). This makes them easier to use, and readers of the
119 documentation do not need to care about which 118 documentation do not need to care about which testing framework is used. In
120 addition, it may allow us to test third-party 119 addition, it may allow us to test third-party code more easily in the future.
121 120
122 A current limitation is that KUnit does not su 121 A current limitation is that KUnit does not support assertions in other tasks.
123 Thus, we presently simply print an error to th 122 Thus, we presently simply print an error to the kernel log if an assertion
124 actually failed. Additionally, doctests are no 123 actually failed. Additionally, doctests are not run for nonpublic functions.
125 124
126 The ``#[test]`` tests 125 The ``#[test]`` tests
127 --------------------- 126 ---------------------
128 127
129 Additionally, there are the ``#[test]`` tests. 128 Additionally, there are the ``#[test]`` tests. These can be run using the
130 ``rusttest`` Make target:: 129 ``rusttest`` Make target::
131 130
132 make LLVM=1 rusttest 131 make LLVM=1 rusttest
133 132
134 This requires the kernel ``.config``. It runs !! 133 This requires the kernel ``.config`` and downloads external repositories. It
135 (currently) and thus is fairly limited in what !! 134 runs the ``#[test]`` tests on the host (currently) and thus is fairly limited in
136 !! 135 what these tests can test.
137 The Kselftests <<
138 -------------- <<
139 <<
140 Kselftests are also available in the ``tools/t <<
141 <<
142 The kernel config options required for the tes <<
143 ``tools/testing/selftests/rust/config`` file a <<
144 of the ``merge_config.sh`` script:: <<
145 <<
146 ./scripts/kconfig/merge_config.sh .con <<
147 <<
148 The kselftests are built within the kernel sou <<
149 be executed on a system that is running the sa <<
150 <<
151 Once a kernel matching the source tree has bee <<
152 tests can be compiled and executed using the f <<
153 <<
154 make TARGETS="rust" kselftest <<
155 <<
156 Refer to Documentation/dev-tools/kselftest.rst <<
157 documentation. <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.