Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit7cf726a

Browse files
committed
Merge tag 'linux-kselftest-kunit-5.10-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest
Pull more Kunit updates from Shuah Khan: - add Kunit to kernel_init() and remove KUnit from init calls entirely. This addresses the concern that Kunit would not work correctly during late init phase. - add a linker section where KUnit can put references to its test suites. This is the first step in transitioning to dispatching all KUnit tests from a centralized executor rather than having each as its own separate late_initcall. - add a centralized executor to dispatch tests rather than relying on late_initcall to schedule each test suite separately. Centralized execution is for built-in tests only; modules will execute tests when loaded. - convert bitfield test to use KUnit framework - Documentation updates for naming guidelines and how kunit_test_suite() works. - add test plan to KUnit TAP format* tag 'linux-kselftest-kunit-5.10-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest: lib: kunit: Fix compilation test when using TEST_BIT_FIELD_COMPILE lib: kunit: add bitfield test conversion to KUnit Documentation: kunit: add a brief blurb about kunit_test_suite kunit: test: add test plan to KUnit TAP format init: main: add KUnit to kernel init kunit: test: create a single centralized executor for all tests vmlinux.lds.h: add linker section for KUnit test suites Documentation: kunit: Add naming guidelines
2 parents41eea65 +294a7f1 commit7cf726a

File tree

16 files changed

+444
-110
lines changed

16 files changed

+444
-110
lines changed

‎Documentation/dev-tools/kunit/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ KUnit - Unit Testing for the Linux Kernel
1111
usage
1212
kunit-tool
1313
api/index
14+
style
1415
faq
1516

1617
What is KUnit?
Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
===========================
4+
Test Style and Nomenclature
5+
===========================
6+
7+
To make finding, writing, and using KUnit tests as simple as possible, it's
8+
strongly encouraged that they are named and written according to the guidelines
9+
below. While it's possible to write KUnit tests which do not follow these rules,
10+
they may break some tooling, may conflict with other tests, and may not be run
11+
automatically by testing systems.
12+
13+
It's recommended that you only deviate from these guidelines when:
14+
15+
1. Porting tests to KUnit which are already known with an existing name, or
16+
2. Writing tests which would cause serious problems if automatically run (e.g.,
17+
non-deterministically producing false positives or negatives, or taking an
18+
extremely long time to run).
19+
20+
Subsystems, Suites, and Tests
21+
=============================
22+
23+
In order to make tests as easy to find as possible, they're grouped into suites
24+
and subsystems. A test suite is a group of tests which test a related area of
25+
the kernel, and a subsystem is a set of test suites which test different parts
26+
of the same kernel subsystem or driver.
27+
28+
Subsystems
29+
----------
30+
31+
Every test suite must belong to a subsystem. A subsystem is a collection of one
32+
or more KUnit test suites which test the same driver or part of the kernel. A
33+
rule of thumb is that a test subsystem should match a single kernel module. If
34+
the code being tested can't be compiled as a module, in many cases the subsystem
35+
should correspond to a directory in the source tree or an entry in the
36+
MAINTAINERS file. If unsure, follow the conventions set by tests in similar
37+
areas.
38+
39+
Test subsystems should be named after the code being tested, either after the
40+
module (wherever possible), or after the directory or files being tested. Test
41+
subsystems should be named to avoid ambiguity where necessary.
42+
43+
If a test subsystem name has multiple components, they should be separated by
44+
underscores. *Do not* include "test" or "kunit" directly in the subsystem name
45+
unless you are actually testing other tests or the kunit framework itself.
46+
47+
Example subsystems could be:
48+
49+
``ext4``
50+
Matches the module and filesystem name.
51+
``apparmor``
52+
Matches the module name and LSM name.
53+
``kasan``
54+
Common name for the tool, prominent part of the path ``mm/kasan``
55+
``snd_hda_codec_hdmi``
56+
Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by
57+
underscores. Matches the module name.
58+
59+
Avoid names like these:
60+
61+
``linear-ranges``
62+
Names should use underscores, not dashes, to separate words. Prefer
63+
``linear_ranges``.
64+
``qos-kunit-test``
65+
As well as using underscores, this name should not have "kunit-test" as a
66+
suffix, and ``qos`` is ambiguous as a subsystem name. ``power_qos`` would be a
67+
better name.
68+
``pc_parallel_port``
69+
The corresponding module name is ``parport_pc``, so this subsystem should also
70+
be named ``parport_pc``.
71+
72+
..note::
73+
The KUnit API and tools do not explicitly know about subsystems. They're
74+
simply a way of categorising test suites and naming modules which
75+
provides a simple, consistent way for humans to find and run tests. This
76+
may change in the future, though.
77+
78+
Suites
79+
------
80+
81+
KUnit tests are grouped into test suites, which cover a specific area of
82+
functionality being tested. Test suites can have shared initialisation and
83+
shutdown code which is run for all tests in the suite.
84+
Not all subsystems will need to be split into multiple test suites (e.g. simple drivers).
85+
86+
Test suites are named after the subsystem they are part of. If a subsystem
87+
contains several suites, the specific area under test should be appended to the
88+
subsystem name, separated by an underscore.
89+
90+
In the event that there are multiple types of test using KUnit within a
91+
subsystem (e.g., both unit tests and integration tests), they should be put into
92+
separate suites, with the type of test as the last element in the suite name.
93+
Unless these tests are actually present, avoid using ``_test``, ``_unittest`` or
94+
similar in the suite name.
95+
96+
The full test suite name (including the subsystem name) should be specified as
97+
the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the
98+
module name (see below).
99+
100+
Example test suites could include:
101+
102+
``ext4_inode``
103+
Part of the ``ext4`` subsystem, testing the ``inode`` area.
104+
``kunit_try_catch``
105+
Part of the ``kunit`` implementation itself, testing the ``try_catch`` area.
106+
``apparmor_property_entry``
107+
Part of the ``apparmor`` subsystem, testing the ``property_entry`` area.
108+
``kasan``
109+
The ``kasan`` subsystem has only one suite, so the suite name is the same as
110+
the subsystem name.
111+
112+
Avoid names like:
113+
114+
``ext4_ext4_inode``
115+
There's no reason to state the subsystem twice.
116+
``property_entry``
117+
The suite name is ambiguous without the subsystem name.
118+
``kasan_integration_test``
119+
Because there is only one suite in the ``kasan`` subsystem, the suite should
120+
just be called ``kasan``. There's no need to redundantly add
121+
``integration_test``. Should a separate test suite with, for example, unit
122+
tests be added, then that suite could be named ``kasan_unittest`` or similar.
123+
124+
Test Cases
125+
----------
126+
127+
Individual tests consist of a single function which tests a constrained
128+
codepath, property, or function. In the test output, individual tests' results
129+
will show up as subtests of the suite's results.
130+
131+
Tests should be named after what they're testing. This is often the name of the
132+
function being tested, with a description of the input or codepath being tested.
133+
As tests are C functions, they should be named and written in accordance with
134+
the kernel coding style.
135+
136+
..note::
137+
As tests are themselves functions, their names cannot conflict with
138+
other C identifiers in the kernel. This may require some creative
139+
naming. It's a good idea to make your test functions `static` to avoid
140+
polluting the global namespace.
141+
142+
Example test names include:
143+
144+
``unpack_u32_with_null_name``
145+
Tests the ``unpack_u32`` function when a NULL name is passed in.
146+
``test_list_splice``
147+
Tests the ``list_splice`` macro. It has the prefix ``test_`` to avoid a
148+
name conflict with the macro itself.
149+
150+
151+
Should it be necessary to refer to a test outside the context of its test suite,
152+
the *fully-qualified* name of a test should be the suite name followed by the
153+
test name, separated by a colon (i.e. ``suite:test``).
154+
155+
Test Kconfig Entries
156+
====================
157+
158+
Every test suite should be tied to a Kconfig entry.
159+
160+
This Kconfig entry must:
161+
162+
* be named ``CONFIG_<name>_KUNIT_TEST``: where <name> is the name of the test
163+
suite.
164+
* be listed either alongside the config entries for the driver/subsystem being
165+
tested, or be under [Kernel Hacking]→[Kernel Testing and Coverage]
166+
* depend on ``CONFIG_KUNIT``
167+
* be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled.
168+
* have a default value of ``CONFIG_KUNIT_ALL_TESTS``.
169+
* have a brief description of KUnit in the help text
170+
171+
Unless there's a specific reason not to (e.g. the test is unable to be built as
172+
a module), Kconfig entries for tests should be tristate.
173+
174+
An example Kconfig entry:
175+
176+
..code-block::none
177+
178+
config FOO_KUNIT_TEST
179+
tristate "KUnit test for foo" if !KUNIT_ALL_TESTS
180+
depends on KUNIT
181+
default KUNIT_ALL_TESTS
182+
help
183+
This builds unit tests for foo.
184+
185+
For more information on KUnit and unit tests in general, please refer
186+
to the KUnit documentation in Documentation/dev-tools/kunit
187+
188+
If unsure, say N
189+
190+
191+
Test File and Module Names
192+
==========================
193+
194+
KUnit tests can often be compiled as a module. These modules should be named
195+
after the test suite, followed by ``_test``. If this is likely to conflict with
196+
non-KUnit tests, the suffix ``_kunit`` can also be used.
197+
198+
The easiest way of achieving this is to name the file containing the test suite
199+
``<suite>_test.c`` (or, as above, ``<suite>_kunit.c``). This file should be
200+
placed next to the code under test.
201+
202+
If the suite name contains some or all of the name of the test's parent
203+
directory, it may make sense to modify the source filename to reduce redundancy.
204+
For example, a ``foo_firmware`` suite could be in the ``foo/firmware_test.c``
205+
file.

‎Documentation/dev-tools/kunit/usage.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,11 @@ KUnit test framework.
211211
..note::
212212
A test case will only be run if it is associated with a test suite.
213213

214+
``kunit_test_suite(...)`` is a macro which tells the linker to put the specified
215+
test suite in a special linker section so that it can be run by KUnit either
216+
after late_init, or when the test module is loaded (depending on whether the
217+
test was built in or not).
218+
214219
For more information on these types of things see the:doc:`api/test`.
215220

216221
Isolating Behavior

‎include/asm-generic/vmlinux.lds.h‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -734,7 +734,8 @@
734734
THERMAL_TABLE(governor)\
735735
EARLYCON_TABLE()\
736736
LSM_TABLE()\
737-
EARLY_LSM_TABLE()
737+
EARLY_LSM_TABLE()\
738+
KUNIT_TABLE()
738739

739740
#defineINIT_TEXT\
740741
*(.init.text .init.text.*)\
@@ -932,6 +933,13 @@
932933
KEEP(*(.con_initcall.init))\
933934
__con_initcall_end = .;
934935

936+
/* Alignment must be consistent with (kunit_suite *) in include/kunit/test.h */
937+
#defineKUNIT_TABLE()\
938+
. = ALIGN(8);\
939+
__kunit_suites_start = .;\
940+
KEEP(*(.kunit_test_suites))\
941+
__kunit_suites_end = .;
942+
935943
#ifdefCONFIG_BLK_DEV_INITRD
936944
#defineINIT_RAM_FS\
937945
. = ALIGN(4);\

‎include/kunit/test.h‎

Lines changed: 54 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -239,10 +239,19 @@ size_t kunit_suite_num_test_cases(struct kunit_suite *suite);
239239
unsignedintkunit_test_case_num(structkunit_suite*suite,
240240
structkunit_case*test_case);
241241

242-
int__kunit_test_suites_init(structkunit_suite**suites);
242+
int__kunit_test_suites_init(structkunit_suite*const*constsuites);
243243

244244
void__kunit_test_suites_exit(structkunit_suite**suites);
245245

246+
#ifIS_BUILTIN(CONFIG_KUNIT)
247+
intkunit_run_all_tests(void);
248+
#else
249+
staticinlineintkunit_run_all_tests(void)
250+
{
251+
return0;
252+
}
253+
#endif/* IS_BUILTIN(CONFIG_KUNIT) */
254+
246255
/**
247256
* kunit_test_suites() - used to register one or more &struct kunit_suite
248257
* with KUnit.
@@ -252,34 +261,57 @@ void __kunit_test_suites_exit(struct kunit_suite **suites);
252261
* Registers @suites_list with the test framework. See &struct kunit_suite for
253262
* more information.
254263
*
255-
* When builtin, KUnit tests are all run as late_initcalls; this means
256-
* that they cannot test anything where tests must run at a different init
257-
* phase. One significant restriction resulting from this is that KUnit
258-
* cannot reliably test anything that is initialize in the late_init phase;
259-
* another is that KUnit is useless to test things that need to be run in
260-
* an earlier init phase.
261-
*
262-
* An alternative is to build the tests as a module. Because modules
263-
* do not support multiple late_initcall()s, we need to initialize an
264-
* array of suites for a module.
265-
*
266-
* TODO(brendanhiggins@google.com): Don't run all KUnit tests as
267-
* late_initcalls. I have some future work planned to dispatch all KUnit
268-
* tests from the same place, and at the very least to do so after
269-
* everything else is definitely initialized.
264+
* If a test suite is built-in, module_init() gets translated into
265+
* an initcall which we don't want as the idea is that for builtins
266+
* the executor will manage execution. So ensure we do not define
267+
* module_{init|exit} functions for the builtin case when registering
268+
* suites via kunit_test_suites() below.
270269
*/
271-
#definekunit_test_suites(suites_list...)\
272-
static struct kunit_suite *suites[] = {suites_list, NULL};\
273-
static int kunit_test_suites_init(void)\
270+
#ifdefMODULE
271+
#definekunit_test_suites_for_module(__suites)\
272+
static int__initkunit_test_suites_init(void)\
274273
{\
275-
return __kunit_test_suites_init(suites);\
274+
return __kunit_test_suites_init(__suites);\
276275
}\
277-
late_initcall(kunit_test_suites_init);\
276+
module_init(kunit_test_suites_init);\
277+
\
278278
static void __exit kunit_test_suites_exit(void)\
279279
{\
280-
return __kunit_test_suites_exit(suites);\
280+
return __kunit_test_suites_exit(__suites);\
281281
}\
282282
module_exit(kunit_test_suites_exit)
283+
#else
284+
#definekunit_test_suites_for_module(__suites)
285+
#endif/* MODULE */
286+
287+
#define__kunit_test_suites(unique_array,unique_suites, ...) \
288+
static struct kunit_suite *unique_array[] = { __VA_ARGS__, NULL }; \
289+
kunit_test_suites_for_module(unique_array); \
290+
static struct kunit_suite **unique_suites \
291+
__used __section(.kunit_test_suites) = unique_array
292+
293+
/**
294+
* kunit_test_suites() - used to register one or more &struct kunit_suite
295+
* with KUnit.
296+
*
297+
* @suites: a statically allocated list of &struct kunit_suite.
298+
*
299+
* Registers @suites with the test framework. See &struct kunit_suite for
300+
* more information.
301+
*
302+
* When builtin, KUnit tests are all run via executor; this is done
303+
* by placing the array of struct kunit_suite * in the .kunit_test_suites
304+
* ELF section.
305+
*
306+
* An alternative is to build the tests as a module. Because modules do not
307+
* support multiple initcall()s, we need to initialize an array of suites for a
308+
* module.
309+
*
310+
*/
311+
#definekunit_test_suites(...)\
312+
__kunit_test_suites(__UNIQUE_ID(array),\
313+
__UNIQUE_ID(suites),\
314+
__VA_ARGS__)
283315

284316
#definekunit_test_suite(suite)kunit_test_suites(&suite)
285317

‎init/main.c‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,8 @@
108108
#defineCREATE_TRACE_POINTS
109109
#include<trace/events/initcall.h>
110110

111+
#include<kunit/test.h>
112+
111113
staticintkernel_init(void*);
112114

113115
externvoidinit_IRQ(void);
@@ -1513,6 +1515,8 @@ static noinline void __init kernel_init_freeable(void)
15131515

15141516
do_basic_setup();
15151517

1518+
kunit_run_all_tests();
1519+
15161520
console_on_rootfs();
15171521

15181522
/*

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp