1 .. SPDX-License-Identifier: GPL-2.0
2
3 .. _netdev-FAQ:
4
5 =============================
6 Networking subsystem (netdev)
7 =============================
8
9 tl;dr
10 -----
11
12 - designate your patch to a tree - ``[PATCH n
13 - for fixes the ``Fixes:`` tag is required, r
14 - don't post large series (> 15 patches), bre
15 - don't repost your patches within one 24h pe
16 - reverse xmas tree
17
18 netdev
19 ------
20
21 netdev is a mailing list for all network-relat
22 includes anything found under net/ (i.e. core
23 drivers/net (i.e. hardware specific drivers) i
24
25 Note that some subsystems (e.g. wireless drive
26 volume of traffic have their own specific mail
27
28 Like many other Linux mailing lists, the netde
29 kernel.org with archives available at https://
30
31 Aside from subsystems like those mentioned abo
32 Linux development (i.e. RFC, review, comments,
33 netdev.
34
35 Development cycle
36 -----------------
37
38 Here is a bit of background information on
39 the cadence of Linux development. Each new re
40 two week "merge window" where the main maintai
41 to Linus for merging into the mainline tree.
42 merge window is closed, and it is called/tagge
43 features get mainlined after this -- only fixe
44 expected. After roughly a week of collecting
45 rc2 is released. This repeats on a roughly we
46 (typically; sometimes rc6 if things are quiet,
47 state of churn), and a week after the last vX.
48 official vX.Y is released.
49
50 To find out where we are now in the cycle - lo
51 page here:
52
53 https://git.kernel.org/pub/scm/linux/kernel/
54
55 and note the top of the "tags" section. If it
56 the dev cycle. If it was tagged rc7 a week ag
57 probably imminent. If the most recent tag is a
58 (without an ``-rcN`` suffix) - we are most lik
59 and ``net-next`` is closed.
60
61 git trees and patch flow
62 ------------------------
63
64 There are two networking trees (git repositori
65 driven by David Miller, the main network maint
66 ``net`` tree, and the ``net-next`` tree. As y
67 the names, the ``net`` tree is for fixes to ex
68 mainline tree from Linus, and ``net-next`` is
69 for the future release. You can find the tree
70
71 - https://git.kernel.org/pub/scm/linux/kernel/
72 - https://git.kernel.org/pub/scm/linux/kernel/
73
74 Relating that to kernel development: At the be
75 merge window, the ``net-next`` tree will be cl
76 The accumulated new content of the past ~10 we
77 mainline/Linus via a pull request for vX.Y --
78 ``net`` tree will start accumulating fixes for
79 relating to vX.Y
80
81 An announcement indicating when ``net-next`` h
82 sent to netdev, but knowing the above, you can
83
84 .. warning::
85 Do not send new ``net-next`` content to netd
86 period during which ``net-next`` tree is clo
87
88 RFC patches sent for review only are obviously
89 (use ``--subject-prefix='RFC net-next'`` with
90
91 Shortly after the two weeks have passed (and v
92 tree for ``net-next`` reopens to collect conte
93 release.
94
95 If you aren't subscribed to netdev and/or are
96 ``net-next`` has re-opened yet, simply check t
97 repository link above for any new networking-r
98 also check the following website for the curre
99
100 https://netdev.bots.linux.dev/net-next.html
101
102 The ``net`` tree continues to collect fixes fo
103 fed back to Linus at regular (~weekly) interva
104 focus for ``net`` is on stabilization and bug
105
106 Finally, the vX.Y gets released, and the whole
107
108 netdev patch review
109 -------------------
110
111 .. _patch_status:
112
113 Patch status
114 ~~~~~~~~~~~~
115
116 Status of a patch can be checked by looking at
117 queue for netdev:
118
119 https://patchwork.kernel.org/project/netdevb
120
121 The "State" field will tell you exactly where
122 patch:
123
124 ================== ===========================
125 Patch state Description
126 ================== ===========================
127 New, Under review pending review, patch is in
128 review; the two states are
129 the exact co-maintainer han
130 Accepted patch was applied to the ap
131 usually set automatically b
132 Needs ACK waiting for an ack from an
133 Changes requested patch has not passed the re
134 with appropriate code and c
135 Rejected patch has been rejected and
136 Not applicable patch is expected to be app
137 subsystem
138 Awaiting upstream patch should be reviewed an
139 sub-maintainer, who will se
140 patches set to ``Awaiting u
141 will usually remain in this
142 requested changes, accepted
143 Deferred patch needs to be reposted
144 or because it was posted fo
145 Superseded new version of the patch wa
146 pw-bot
147 RFC not to be applied, usually
148 pw-bot can automatically se
149 on subject tags
150 ================== ===========================
151
152 Patches are indexed by the ``Message-ID`` head
153 which carried them so if you have trouble find
154 the value of ``Message-ID`` to the URL above.
155
156 Updating patch status
157 ~~~~~~~~~~~~~~~~~~~~~
158
159 Contributors and reviewers do not have the per
160 state directly in patchwork. Patchwork doesn't
161 about the history of the state of patches, the
162 people update the state leads to confusion.
163
164 Instead of delegating patchwork permissions ne
165 bot which looks for special commands/lines wit
166 the mailing list. For example to mark a series
167 one needs to send the following line anywhere
168
169 pw-bot: changes-requested
170
171 As a result the bot will set the entire series
172 This may be useful when author discovers a bug
173 and wants to prevent it from getting applied.
174
175 The use of the bot is entirely optional, if in
176 completely. Maintainers will classify and upda
177 themselves. No email should ever be sent to th
178 of communicating with the bot, the bot command
179
180 The use of the bot is restricted to authors of
181 header on patch submission and command must ma
182 the modified code according to the MAINTAINERS
183 must match the MAINTAINERS entry) and a handfu
184
185 Bot records its activity here:
186
187 https://netdev.bots.linux.dev/pw-bot.html
188
189 Review timelines
190 ~~~~~~~~~~~~~~~~
191
192 Generally speaking, the patches get triaged qu
193 48h). But be patient, if your patch is active
194 listed on the project's patch list) the chance
195
196 The high volume of development on netdev makes
197 from discussions relatively quickly. New comme
198 are very unlikely to arrive after a week of si
199 is no longer active in patchwork and the threa
200 than a week - clarify the next steps and/or po
201
202 For RFC postings specifically, if nobody respo
203 either missed the posting or have no strong op
204 repost as a PATCH.
205
206 Emails saying just "ping" or "bump" are consid
207 out the status of the patch from patchwork or
208 landed - describe your best guess and ask if i
209
210 I don't understand what the next steps are.
211 with A, should I do B and repost the patches
212
213 .. _Changes requested:
214
215 Changes requested
216 ~~~~~~~~~~~~~~~~~
217
218 Patches :ref:`marked<patch_status>` as ``Chang
219 to be revised. The new version should come wit
220 preferably including links to previous posting
221
222 [PATCH net-next v3] net: make cows go moo
223
224 Even users who don't drink milk appreciate h
225
226 The amount of mooing will depend on packet r
227 the diurnal cycle quite well.
228
229 Signed-off-by: Joe Defarmer <joe@barn.org>
230 ---
231 v3:
232 - add a note about time-of-day mooing fluc
233 v2: https://lore.kernel.org/netdev/123themes
234 - fix missing argument in kernel doc for n
235 - fix memory leak in netdev_register_cow()
236 v1: https://lore.kernel.org/netdev/456getsth
237
238 The commit message should be revised to answer
239 had to ask in previous discussions. Occasional
240 the commit message will be the only change in
241
242 Partial resends
243 ~~~~~~~~~~~~~~~
244
245 Please always resend the entire patch series a
246 patches such that it is clear this is the late
247 that can be applied. Do not try to resend just
248
249 Handling misapplied patches
250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
251
252 Occasionally a patch series gets applied befor
253 or the wrong version of a series gets applied.
254
255 Making the patch disappear once it is pushed o
256 history in netdev trees is immutable.
257 Please send incremental versions on top of wha
258 the patches the way they would look like if yo
259 merged.
260
261 In cases where full revert is needed the rever
262 as a patch to the list with a commit message e
263 problems with the reverted commit. Reverts sho
264 when original change is completely wrong; incr
265
266 Stable tree
267 ~~~~~~~~~~~
268
269 While it used to be the case that netdev submi
270 to carry explicit ``CC: stable@vger.kernel.org
271 the case today. Please follow the standard sta
272 :ref:`Documentation/process/stable-kernel-rule
273 and make sure you include appropriate Fixes ta
274
275 Security fixes
276 ~~~~~~~~~~~~~~
277
278 Do not email netdev maintainers directly if yo
279 a bug that might have possible security implic
280 The current netdev maintainer has consistently
281 people use the mailing lists and not reach out
282 OK with that, then perhaps consider mailing se
283 reading about http://oss-security.openwall.org
284 as possible alternative mechanisms.
285
286
287 Co-posting changes to user space components
288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
289
290 User space code exercising kernel features sho
291 alongside kernel patches. This gives reviewers
292 how any new interface is used and how well it
293
294 When user space tools reside in the kernel rep
295 should generally come as one series. If series
296 or the user space project is not reviewed on n
297 to a public repo where user space patches can
298
299 In case user space tooling lives in a separate
300 reviewed on netdev (e.g. patches to ``iproute
301 user space patches should form separate series
302 to the mailing list, e.g.::
303
304 [PATCH net-next 0/3] net: some feature cover
305 └─ [PATCH net-next 1/3] net: some featu
306 └─ [PATCH net-next 2/3] net: some featu
307 └─ [PATCH net-next 3/3] selftest: net:
308
309 [PATCH iproute2-next] ip: add support for so
310
311 Posting as one thread is discouraged because i
312 (as of patchwork 2.2.2).
313
314 Preparing changes
315 -----------------
316
317 Attention to detail is important. Re-read you
318 reviewer. You can start with using ``checkpat
319 the ``--strict`` flag. But do not be mindless
320 If your change is a bug fix, make sure your co
321 end-user visible symptom, the underlying reaso
322 and then if necessary, explain why the fix pro
323 get things done. Don't mangle whitespace, and
324 mis-indent function arguments that span multip
325 first patch, mail it to yourself so you can te
326 unpatched tree to confirm infrastructure didn'
327
328 Finally, go back and read
329 :ref:`Documentation/process/submitting-patches
330 to be sure you are not repeating some common m
331
332 Indicating target tree
333 ~~~~~~~~~~~~~~~~~~~~~~
334
335 To help maintainers and CI bots you should exp
336 your patch is targeting. Assuming that you use
337 flag::
338
339 git format-patch --subject-prefix='PATCH net
340
341 Use ``net`` instead of ``net-next`` (always lo
342 bug-fix ``net`` content.
343
344 Dividing work into patches
345 ~~~~~~~~~~~~~~~~~~~~~~~~~~
346
347 Put yourself in the shoes of the reviewer. Eac
348 and therefore should constitute a comprehensib
349 goal.
350
351 Avoid sending series longer than 15 patches. L
352 to review as reviewers will defer looking at i
353 chunk of time. A small series can be reviewed
354 just do it. As a result, a sequence of smaller
355 with better review coverage. Re-posting large
356 list traffic.
357
358 Local variable ordering ("reverse xmas tree",
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
360
361 Netdev has a convention for ordering local var
362 Order the variable declaration lines longest t
363
364 struct scatterlist *sg;
365 struct sk_buff *skb;
366 int err, i;
367
368 If there are dependencies between the variable
369 move the initialization out of line.
370
371 Format precedence
372 ~~~~~~~~~~~~~~~~~
373
374 When working in existing code which uses nonst
375 your code follow the most recent guidelines, s
376 in the domain of netdev is in the preferred fo
377
378 Using device-managed and cleanup.h constructs
379 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
380
381 Netdev remains skeptical about promises of all
382 including even ``devm_`` helpers, historically
383 style of implementation, merely an acceptable
384
385 Use of ``guard()`` is discouraged within any f
386 ``scoped_guard()`` is considered more readable
387 still (weakly) preferred.
388
389 Low level cleanup constructs (such as ``__free
390 APIs and helpers, especially scoped iterators.
391 ``__free()`` within networking core and driver
392 Similar guidance applies to declaring variable
393
394 Resending after review
395 ~~~~~~~~~~~~~~~~~~~~~~
396
397 Allow at least 24 hours to pass between postin
398 from all geographical locations have a chance
399 too long (weeks) between postings either as it
400 to recall all the context.
401
402 Make sure you address all the feedback in your
403 version of the code if the discussion about th
404 ongoing, unless directly instructed by a revie
405
406 The new version of patches should be posted as
407 not as a reply to the previous posting. Change
408 to the previous posting (see :ref:`Changes req
409
410 Testing
411 -------
412
413 Expected level of testing
414 ~~~~~~~~~~~~~~~~~~~~~~~~~
415
416 At the very minimum your changes must survive
417 ``allmodconfig`` build with ``W=1`` set withou
418
419 Ideally you will have done run-time testing sp
420 and the patch series contains a set of kernel
421 ``tools/testing/selftests/net`` or using the K
422
423 You are expected to test your changes on top o
424 tree (``net`` or ``net-next``) and not e.g. a
425
426 patchwork checks
427 ~~~~~~~~~~~~~~~~
428
429 Checks in patchwork are mostly simple wrappers
430 scripts, the sources are available at:
431
432 https://github.com/linux-netdev/nipa/tree/mast
433
434 **Do not** post your patches just to run them
435 You must ensure that your patches are ready by
436 before posting to the mailing list. The patchw
437 gets overloaded very easily and netdev@vger re
438 traffic if we can help it.
439
440 netdevsim
441 ~~~~~~~~~
442
443 ``netdevsim`` is a test driver which can be us
444 configuration APIs without requiring capable h
445 Mock-ups and tests based on ``netdevsim`` are
446 adding new APIs, but ``netdevsim`` in itself i
447 a use case/user. You must also implement the n
448
449 We give no guarantees that ``netdevsim`` won't
450 in a way which would break what would normally
451
452 ``netdevsim`` is reserved for use by upstream
453 new ``netdevsim`` features must be accompanied
454 ``tools/testing/selftests/``.
455
456 Reviewer guidance
457 -----------------
458
459 Reviewing other people's patches on the list i
460 regardless of the level of expertise. For gene
461 helpful tips please see :ref:`development_adva
462
463 It's safe to assume that netdev maintainers kn
464 of expertise of the reviewers. The reviewers s
465 their comments impeding or derailing the patch
466
467 Less experienced reviewers are highly encourag
468 review of submissions and not focus exclusivel
469 matters like code formatting, tags etc.
470
471 Testimonials / feedback
472 -----------------------
473
474 Some companies use peer feedback in employee p
475 Please feel free to request feedback from netd
476 especially if you spend significant amount of
477 and go out of your way to improve shared infra
478
479 The feedback must be requested by you, the con
480 be shared with you (even if you request for it
481 manager).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.