Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
selftests: drv-net: update the README
I have added some instructions for driver authors on the NIPA wiki:
https://github.com/linux-netdev/nipa/wiki/Guidance-for-test-authors
last year. Given the increasingly common use of LLMs let's add those
in tree as well. Hopefully this will decrease the number of review
comments we have to give to AI-assisted noobs.
While at it sync the overall instructions with what's on the GitHub
as well.
Link: https://patch.msgid.link/20260303213626.2320308-1-kuba@kernel.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
+88
-2
+88
-2
tools/testing/selftests/drivers/net/README.rst
+88
-2
tools/testing/selftests/drivers/net/README.rst
···
47
47
# Variable set in a file
48
48
NETIF=eth0
49
49
50
+
Please note that the config parser is very simple, if there are
51
+
any non-alphanumeric characters in the value it needs to be in
52
+
double quotes.
53
+
50
54
Local test (which don't require endpoint for sending / receiving traffic)
51
55
need only the ``NETIF`` variable. Remaining variables define the endpoint
52
56
and communication method.
···
111
107
1..1
112
108
# timeout set to 45
113
109
# selftests: drivers/net: ping.py
114
-
# TAP version 13
110
+
# KTAP version 1
115
111
# 1..3
116
112
# ok 1 ping.test_v4
117
113
# ok 2 ping.test_v6
···
132
128
Run the test::
133
129
134
130
[/root] # ./ksft-net-drv/drivers/net/ping.py
135
-
TAP version 13
131
+
KTAP version 1
136
132
1..3
137
133
ok 1 ping.test_v4
138
134
ok 2 ping.test_v6 # SKIP Test requires IPv6 connectivity
139
135
ok 3 ping.test_tcp
140
136
# Totals: pass:2 fail:0 xfail:0 xpass:0 skip:1 error:0
137
+
138
+
Dependencies
139
+
~~~~~~~~~~~~
140
+
141
+
The tests have a handful of dependencies. For Fedora / CentOS::
142
+
143
+
dnf -y install netsniff-ng python-yaml socat iperf3
144
+
145
+
Guidance for test authors
146
+
=========================
147
+
148
+
This section mostly applies to Python tests but some of the guidance
149
+
may be more broadly applicable.
150
+
151
+
Kernel config
152
+
~~~~~~~~~~~~~
153
+
154
+
Each test directory has a ``config`` file listing which kernel
155
+
configuration options the tests depend on. This file must be kept
156
+
up to date, the CIs build minimal kernels for each test group.
157
+
158
+
Adding checks inside the tests to validate that the necessary kernel
159
+
configs are enabled is discouraged. The test author may include such
160
+
checks, but standalone patches to make tests compatible e.g. with
161
+
distro kernel configs are unlikely to be accepted.
162
+
163
+
Avoid libraries and frameworks
164
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165
+
166
+
Test files should be relatively self contained. The libraries should
167
+
only include very core or non-trivial code.
168
+
It may be tempting to "factor out" the common code, but fight that urge.
169
+
Library code increases the barrier of entry, and complexity in general.
170
+
171
+
Avoid mixing test code and boilerplate
172
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
173
+
174
+
In Python, try to avoid adding code in the ``main()`` function which
175
+
instantiates ``NetDrvEnv()`` and calls ``ksft_run()``. It's okay to
176
+
set up global resources (e.g. open an RtNetlink socket used by multiple
177
+
tests), but any complex logic, test-specific environment configuration
178
+
and validation should be done in the tests (even if it means it has to
179
+
be repeated).
180
+
181
+
Local host is the DUT
182
+
~~~~~~~~~~~~~~~~~~~~~
183
+
184
+
Dual-host tests (tests with an endpoint) should be written from the DUT
185
+
perspective. IOW the local machine should be the one tested, remote is
186
+
just for traffic generation.
187
+
188
+
Avoid modifying remote
189
+
~~~~~~~~~~~~~~~~~~~~~~
190
+
191
+
Avoid making configuration changes to the remote system as much as possible.
192
+
Remote system may be used concurrently by multiple DUTs.
193
+
194
+
defer()
195
+
~~~~~~~
196
+
197
+
The env must be clean after test exits. Register a ``defer()`` for any
198
+
action that needs an "undo" as soon as possible. If you need to run
199
+
the cancel action as part of the test - ``defer()`` returns an object
200
+
you can ``.exec()``-ute.
201
+
202
+
ksft_pr()
203
+
~~~~~~~~~
204
+
205
+
Use ``ksft_pr()`` instead of ``print()`` to avoid breaking TAP format.
206
+
207
+
ksft_disruptive
208
+
~~~~~~~~~~~~~~~
209
+
210
+
By default the tests are expected to be able to run on
211
+
single-interface systems. All tests which may disconnect ``NETIF``
212
+
must be annotated with ``@ksft_disruptive``.
213
+
214
+
Running tests CI-style
215
+
======================
216
+
217
+
See https://github.com/linux-netdev/nipa/wiki for instructions on how
218
+
to easily run the tests using ``virtme-ng``.