1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ============================ 3 ============================
4 Run Tests without kunit_tool 4 Run Tests without kunit_tool
5 ============================ 5 ============================
6 6
7 If we do not want to use kunit_tool (For examp 7 If we do not want to use kunit_tool (For example: we want to integrate
8 with other systems, or run tests on real hardw 8 with other systems, or run tests on real hardware), we can
9 include KUnit in any kernel, read out results, 9 include KUnit in any kernel, read out results, and parse manually.
10 10
11 .. note:: KUnit is not designed for use in a p 11 .. note:: KUnit is not designed for use in a production system. It is
12 possible that tests may reduce the s 12 possible that tests may reduce the stability or security of
13 the system. 13 the system.
14 14
15 Configure the Kernel 15 Configure the Kernel
16 ==================== 16 ====================
17 17
18 KUnit tests can run without kunit_tool. This c 18 KUnit tests can run without kunit_tool. This can be useful, if:
19 19
20 - We have an existing kernel configuration to 20 - We have an existing kernel configuration to test.
21 - Need to run on real hardware (or using an em 21 - Need to run on real hardware (or using an emulator/VM kunit_tool
22 does not support). 22 does not support).
23 - Wish to integrate with some existing testing 23 - Wish to integrate with some existing testing systems.
24 24
25 KUnit is configured with the ``CONFIG_KUNIT`` 25 KUnit is configured with the ``CONFIG_KUNIT`` option, and individual
26 tests can also be built by enabling their conf 26 tests can also be built by enabling their config options in our
27 ``.config``. KUnit tests usually (but don't al 27 ``.config``. KUnit tests usually (but don't always) have config options
28 ending in ``_KUNIT_TEST``. Most tests can eith 28 ending in ``_KUNIT_TEST``. Most tests can either be built as a module,
29 or be built into the kernel. 29 or be built into the kernel.
30 30
31 .. note :: 31 .. note ::
32 32
33 We can enable the ``KUNIT_ALL_TESTS`` 33 We can enable the ``KUNIT_ALL_TESTS`` config option to
34 automatically enable all tests with sa 34 automatically enable all tests with satisfied dependencies. This is
35 a good way of quickly testing everythi 35 a good way of quickly testing everything applicable to the current
36 config. 36 config.
37 37
38 Once we have built our kernel (and/or modules) 38 Once we have built our kernel (and/or modules), it is simple to run
39 the tests. If the tests are built-in, they wil 39 the tests. If the tests are built-in, they will run automatically on the
40 kernel boot. The results will be written to th 40 kernel boot. The results will be written to the kernel log (``dmesg``)
41 in TAP format. 41 in TAP format.
42 42
43 If the tests are built as modules, they will r 43 If the tests are built as modules, they will run when the module is
44 loaded. 44 loaded.
45 45
46 .. code-block :: bash 46 .. code-block :: bash
47 47
48 # modprobe example-test 48 # modprobe example-test
49 49
50 The results will appear in TAP format in ``dme 50 The results will appear in TAP format in ``dmesg``.
51 51
52 debugfs 52 debugfs
53 ======= 53 =======
54 54
55 KUnit can be accessed from userspace via the d 55 KUnit can be accessed from userspace via the debugfs filesystem (See more
56 information about debugfs at Documentation/fil 56 information about debugfs at Documentation/filesystems/debugfs.rst).
57 57
58 If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the KU 58 If ``CONFIG_KUNIT_DEBUGFS`` is enabled, the KUnit debugfs filesystem is
59 mounted at /sys/kernel/debug/kunit. You can us 59 mounted at /sys/kernel/debug/kunit. You can use this filesystem to perform
60 the following actions. 60 the following actions.
61 61
62 Retrieve Test Results 62 Retrieve Test Results
63 ===================== 63 =====================
64 64
65 You can use debugfs to retrieve KUnit test res 65 You can use debugfs to retrieve KUnit test results. The test results are
66 accessible from the debugfs filesystem in the 66 accessible from the debugfs filesystem in the following read-only file:
67 67
68 .. code-block :: bash 68 .. code-block :: bash
69 69
70 /sys/kernel/debug/kunit/<test_suite>/r 70 /sys/kernel/debug/kunit/<test_suite>/results
71 71
72 The test results are printed in a KTAP documen 72 The test results are printed in a KTAP document. Note this document is separate
73 to the kernel log and thus, may have different 73 to the kernel log and thus, may have different test suite numbering.
74 74
75 Run Tests After Kernel Has Booted 75 Run Tests After Kernel Has Booted
76 ================================= 76 =================================
77 77
78 You can use the debugfs filesystem to trigger 78 You can use the debugfs filesystem to trigger built-in tests to run after
79 boot. To run the test suite, you can use the f 79 boot. To run the test suite, you can use the following command to write to
80 the ``/sys/kernel/debug/kunit/<test_suite>/run 80 the ``/sys/kernel/debug/kunit/<test_suite>/run`` file:
81 81
82 .. code-block :: bash 82 .. code-block :: bash
83 83
84 echo "any string" > /sys/kernel/debugf 84 echo "any string" > /sys/kernel/debugfs/kunit/<test_suite>/run
85 85
86 As a result, the test suite runs and the resul 86 As a result, the test suite runs and the results are printed to the kernel
87 log. 87 log.
88 88
89 However, this feature is not available with KU 89 However, this feature is not available with KUnit suites that use init data,
90 because init data may have been discarded afte 90 because init data may have been discarded after the kernel boots. KUnit
91 suites that use init data should be defined us 91 suites that use init data should be defined using the
92 kunit_test_init_section_suites() macro. 92 kunit_test_init_section_suites() macro.
93 93
94 Also, you cannot use this feature to run tests 94 Also, you cannot use this feature to run tests concurrently. Instead a test
95 will wait to run until other tests have comple 95 will wait to run until other tests have completed or failed.
96 96
97 .. note :: 97 .. note ::
98 98
99 For test authors, to use this feature, 99 For test authors, to use this feature, tests will need to correctly initialise
100 and/or clean up any data, so the test 100 and/or clean up any data, so the test runs correctly a second time.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.