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