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 net]`` or ``[PATCH net-next]``
13 - for fixes the ``Fixes:`` tag is required, regardless of the tree
14 - don't post large series (> 15 patches), break them up
15 - don't repost your patches within one 24h period
16 - reverse xmas tree
17
18 netdev
19 ------
20
21 netdev is a mailing list for all network-related Linux stuff. This
22 includes anything found under net/ (i.e. core code like IPv6) and
23 drivers/net (i.e. hardware specific drivers) in the Linux source tree.
24
25 Note that some subsystems (e.g. wireless drivers) which have a high
26 volume of traffic have their own specific mailing lists and trees.
27
28 Like many other Linux mailing lists, the netdev list is hosted at
29 kernel.org with archives available at https://lore.kernel.org/netdev/.
30
31 Aside from subsystems like those mentioned above, all network-related
32 Linux development (i.e. RFC, review, comments, etc.) takes place on
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 release starts off with a
40 two week "merge window" where the main maintainers feed their new stuff
41 to Linus for merging into the mainline tree. After the two weeks, the
42 merge window is closed, and it is called/tagged ``-rc1``. No new
43 features get mainlined after this -- only fixes to the rc1 content are
44 expected. After roughly a week of collecting fixes to the rc1 content,
45 rc2 is released. This repeats on a roughly weekly basis until rc7
46 (typically; sometimes rc6 if things are quiet, or rc8 if things are in a
47 state of churn), and a week after the last vX.Y-rcN was done, the
48 official vX.Y is released.
49
50 To find out where we are now in the cycle - load the mainline (Linus)
51 page here:
52
53 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
54
55 and note the top of the "tags" section. If it is rc1, it is early in
56 the dev cycle. If it was tagged rc7 a week ago, then a release is
57 probably imminent. If the most recent tag is a final release tag
58 (without an ``-rcN`` suffix) - we are most likely in a merge window
59 and ``net-next`` is closed.
60
61 git trees and patch flow
62 ------------------------
63
64 There are two networking trees (git repositories) in play. Both are
65 driven by David Miller, the main network maintainer. There is the
66 ``net`` tree, and the ``net-next`` tree. As you can probably guess from
67 the names, the ``net`` tree is for fixes to existing code already in the
68 mainline tree from Linus, and ``net-next`` is where the new code goes
69 for the future release. You can find the trees here:
70
71 - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git
72 - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git
73
74 Relating that to kernel development: At the beginning of the 2-week
75 merge window, the ``net-next`` tree will be closed - no new changes/features.
76 The accumulated new content of the past ~10 weeks will be passed onto
77 mainline/Linus via a pull request for vX.Y -- at the same time, the
78 ``net`` tree will start accumulating fixes for this pulled content
79 relating to vX.Y
80
81 An announcement indicating when ``net-next`` has been closed is usually
82 sent to netdev, but knowing the above, you can predict that in advance.
83
84 .. warning::
85 Do not send new ``net-next`` content to netdev during the
86 period during which ``net-next`` tree is closed.
87
88 RFC patches sent for review only are obviously welcome at any time
89 (use ``--subject-prefix='RFC net-next'`` with ``git format-patch``).
90
91 Shortly after the two weeks have passed (and vX.Y-rc1 is released), the
92 tree for ``net-next`` reopens to collect content for the next (vX.Y+1)
93 release.
94
95 If you aren't subscribed to netdev and/or are simply unsure if
96 ``net-next`` has re-opened yet, simply check the ``net-next`` git
97 repository link above for any new networking-related commits. You may
98 also check the following website for the current status:
99
100 https://netdev.bots.linux.dev/net-next.html
101
102 The ``net`` tree continues to collect fixes for the vX.Y content, and is
103 fed back to Linus at regular (~weekly) intervals. Meaning that the
104 focus for ``net`` is on stabilization and bug fixes.
105
106 Finally, the vX.Y gets released, and the whole cycle starts over.
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 the main patchwork
117 queue for netdev:
118
119 https://patchwork.kernel.org/project/netdevbpf/list/
120
121 The "State" field will tell you exactly where things are at with your
122 patch:
123
124 ================== =============================================================
125 Patch state Description
126 ================== =============================================================
127 New, Under review pending review, patch is in the maintainer’s queue for
128 review; the two states are used interchangeably (depending on
129 the exact co-maintainer handling patchwork at the time)
130 Accepted patch was applied to the appropriate networking tree, this is
131 usually set automatically by the pw-bot
132 Needs ACK waiting for an ack from an area expert or testing
133 Changes requested patch has not passed the review, new revision is expected
134 with appropriate code and commit message changes
135 Rejected patch has been rejected and new revision is not expected
136 Not applicable patch is expected to be applied outside of the networking
137 subsystem
138 Awaiting upstream patch should be reviewed and handled by appropriate
139 sub-maintainer, who will send it on to the networking trees;
140 patches set to ``Awaiting upstream`` in netdev's patchwork
141 will usually remain in this state, whether the sub-maintainer
142 requested changes, accepted or rejected the patch
143 Deferred patch needs to be reposted later, usually due to dependency
144 or because it was posted for a closed tree
145 Superseded new version of the patch was posted, usually set by the
146 pw-bot
147 RFC not to be applied, usually not in maintainer’s review queue,
148 pw-bot can automatically set patches to this state based
149 on subject tags
150 ================== =============================================================
151
152 Patches are indexed by the ``Message-ID`` header of the emails
153 which carried them so if you have trouble finding your patch append
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 permissions to update patch
160 state directly in patchwork. Patchwork doesn't expose much information
161 about the history of the state of patches, therefore having multiple
162 people update the state leads to confusion.
163
164 Instead of delegating patchwork permissions netdev uses a simple mail
165 bot which looks for special commands/lines within the emails sent to
166 the mailing list. For example to mark a series as Changes Requested
167 one needs to send the following line anywhere in the email thread::
168
169 pw-bot: changes-requested
170
171 As a result the bot will set the entire series to Changes Requested.
172 This may be useful when author discovers a bug in their own series
173 and wants to prevent it from getting applied.
174
175 The use of the bot is entirely optional, if in doubt ignore its existence
176 completely. Maintainers will classify and update the state of the patches
177 themselves. No email should ever be sent to the list with the main purpose
178 of communicating with the bot, the bot commands should be seen as metadata.
179
180 The use of the bot is restricted to authors of the patches (the ``From:``
181 header on patch submission and command must match!), maintainers of
182 the modified code according to the MAINTAINERS file (again, ``From:``
183 must match the MAINTAINERS entry) and a handful of senior reviewers.
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 quickly (in less than
193 48h). But be patient, if your patch is active in patchwork (i.e. it's
194 listed on the project's patch list) the chances it was missed are close to zero.
195
196 The high volume of development on netdev makes reviewers move on
197 from discussions relatively quickly. New comments and replies
198 are very unlikely to arrive after a week of silence. If a patch
199 is no longer active in patchwork and the thread went idle for more
200 than a week - clarify the next steps and/or post the next version.
201
202 For RFC postings specifically, if nobody responded in a week - reviewers
203 either missed the posting or have no strong opinions. If the code is ready,
204 repost as a PATCH.
205
206 Emails saying just "ping" or "bump" are considered rude. If you can't figure
207 out the status of the patch from patchwork or where the discussion has
208 landed - describe your best guess and ask if it's correct. For example::
209
210 I don't understand what the next steps are. Person X seems to be unhappy
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 ``Changes Requested`` need
219 to be revised. The new version should come with a change log,
220 preferably including links to previous postings, for example::
221
222 [PATCH net-next v3] net: make cows go moo
223
224 Even users who don't drink milk appreciate hearing the cows go "moo".
225
226 The amount of mooing will depend on packet rate so should match
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 fluctuation to the commit message
233 v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
234 - fix missing argument in kernel doc for netif_is_bovine()
235 - fix memory leak in netdev_register_cow()
236 v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/
237
238 The commit message should be revised to answer any questions reviewers
239 had to ask in previous discussions. Occasionally the update of
240 the commit message will be the only change in the new version.
241
242 Partial resends
243 ~~~~~~~~~~~~~~~
244
245 Please always resend the entire patch series and make sure you do number your
246 patches such that it is clear this is the latest and greatest set of patches
247 that can be applied. Do not try to resend just the patches which changed.
248
249 Handling misapplied patches
250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
251
252 Occasionally a patch series gets applied before receiving critical feedback,
253 or the wrong version of a series gets applied.
254
255 Making the patch disappear once it is pushed out is not possible, the commit
256 history in netdev trees is immutable.
257 Please send incremental versions on top of what has been merged in order to fix
258 the patches the way they would look like if your latest patch series was to be
259 merged.
260
261 In cases where full revert is needed the revert has to be submitted
262 as a patch to the list with a commit message explaining the technical
263 problems with the reverted commit. Reverts should be used as a last resort,
264 when original change is completely wrong; incremental fixes are preferred.
265
266 Stable tree
267 ~~~~~~~~~~~
268
269 While it used to be the case that netdev submissions were not supposed
270 to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
271 the case today. Please follow the standard stable rules in
272 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
273 and make sure you include appropriate Fixes tags!
274
275 Security fixes
276 ~~~~~~~~~~~~~~
277
278 Do not email netdev maintainers directly if you think you discovered
279 a bug that might have possible security implications.
280 The current netdev maintainer has consistently requested that
281 people use the mailing lists and not reach out directly. If you aren't
282 OK with that, then perhaps consider mailing security@kernel.org or
283 reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
284 as possible alternative mechanisms.
285
286
287 Co-posting changes to user space components
288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
289
290 User space code exercising kernel features should be posted
291 alongside kernel patches. This gives reviewers a chance to see
292 how any new interface is used and how well it works.
293
294 When user space tools reside in the kernel repo itself all changes
295 should generally come as one series. If series becomes too large
296 or the user space project is not reviewed on netdev include a link
297 to a public repo where user space patches can be seen.
298
299 In case user space tooling lives in a separate repository but is
300 reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and
301 user space patches should form separate series (threads) when posted
302 to the mailing list, e.g.::
303
304 [PATCH net-next 0/3] net: some feature cover letter
305 └─ [PATCH net-next 1/3] net: some feature prep
306 └─ [PATCH net-next 2/3] net: some feature do it
307 └─ [PATCH net-next 3/3] selftest: net: some feature
308
309 [PATCH iproute2-next] ip: add support for some feature
310
311 Posting as one thread is discouraged because it confuses patchwork
312 (as of patchwork 2.2.2).
313
314 Preparing changes
315 -----------------
316
317 Attention to detail is important. Re-read your own work as if you were the
318 reviewer. You can start with using ``checkpatch.pl``, perhaps even with
319 the ``--strict`` flag. But do not be mindlessly robotic in doing so.
320 If your change is a bug fix, make sure your commit log indicates the
321 end-user visible symptom, the underlying reason as to why it happens,
322 and then if necessary, explain why the fix proposed is the best way to
323 get things done. Don't mangle whitespace, and as is common, don't
324 mis-indent function arguments that span multiple lines. If it is your
325 first patch, mail it to yourself so you can test apply it to an
326 unpatched tree to confirm infrastructure didn't mangle it.
327
328 Finally, go back and read
329 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
330 to be sure you are not repeating some common mistake documented there.
331
332 Indicating target tree
333 ~~~~~~~~~~~~~~~~~~~~~~
334
335 To help maintainers and CI bots you should explicitly mark which tree
336 your patch is targeting. Assuming that you use git, use the prefix
337 flag::
338
339 git format-patch --subject-prefix='PATCH net-next' start..finish
340
341 Use ``net`` instead of ``net-next`` (always lower case) in the above for
342 bug-fix ``net`` content.
343
344 Dividing work into patches
345 ~~~~~~~~~~~~~~~~~~~~~~~~~~
346
347 Put yourself in the shoes of the reviewer. Each patch is read separately
348 and therefore should constitute a comprehensible step towards your stated
349 goal.
350
351 Avoid sending series longer than 15 patches. Larger series takes longer
352 to review as reviewers will defer looking at it until they find a large
353 chunk of time. A small series can be reviewed in a short time, so Maintainers
354 just do it. As a result, a sequence of smaller series gets merged quicker and
355 with better review coverage. Re-posting large series also increases the mailing
356 list traffic.
357
358 Local variable ordering ("reverse xmas tree", "RCS")
359 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
360
361 Netdev has a convention for ordering local variables in functions.
362 Order the variable declaration lines longest to shortest, e.g.::
363
364 struct scatterlist *sg;
365 struct sk_buff *skb;
366 int err, i;
367
368 If there are dependencies between the variables preventing the ordering
369 move the initialization out of line.
370
371 Format precedence
372 ~~~~~~~~~~~~~~~~~
373
374 When working in existing code which uses nonstandard formatting make
375 your code follow the most recent guidelines, so that eventually all code
376 in the domain of netdev is in the preferred format.
377
378 Using device-managed and cleanup.h constructs
379 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
380
381 Netdev remains skeptical about promises of all "auto-cleanup" APIs,
382 including even ``devm_`` helpers, historically. They are not the preferred
383 style of implementation, merely an acceptable one.
384
385 Use of ``guard()`` is discouraged within any function longer than 20 lines,
386 ``scoped_guard()`` is considered more readable. Using normal lock/unlock is
387 still (weakly) preferred.
388
389 Low level cleanup constructs (such as ``__free()``) can be used when building
390 APIs and helpers, especially scoped iterators. However, direct use of
391 ``__free()`` within networking core and drivers is discouraged.
392 Similar guidance applies to declaring variables mid-function.
393
394 Resending after review
395 ~~~~~~~~~~~~~~~~~~~~~~
396
397 Allow at least 24 hours to pass between postings. This will ensure reviewers
398 from all geographical locations have a chance to chime in. Do not wait
399 too long (weeks) between postings either as it will make it harder for reviewers
400 to recall all the context.
401
402 Make sure you address all the feedback in your new posting. Do not post a new
403 version of the code if the discussion about the previous version is still
404 ongoing, unless directly instructed by a reviewer.
405
406 The new version of patches should be posted as a separate thread,
407 not as a reply to the previous posting. Change log should include a link
408 to the previous posting (see :ref:`Changes requested`).
409
410 Testing
411 -------
412
413 Expected level of testing
414 ~~~~~~~~~~~~~~~~~~~~~~~~~
415
416 At the very minimum your changes must survive an ``allyesconfig`` and an
417 ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
418
419 Ideally you will have done run-time testing specific to your change,
420 and the patch series contains a set of kernel selftest for
421 ``tools/testing/selftests/net`` or using the KUnit framework.
422
423 You are expected to test your changes on top of the relevant networking
424 tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
425
426 patchwork checks
427 ~~~~~~~~~~~~~~~~
428
429 Checks in patchwork are mostly simple wrappers around existing kernel
430 scripts, the sources are available at:
431
432 https://github.com/linux-netdev/nipa/tree/master/tests
433
434 **Do not** post your patches just to run them through the checks.
435 You must ensure that your patches are ready by testing them locally
436 before posting to the mailing list. The patchwork build bot instance
437 gets overloaded very easily and netdev@vger really doesn't need more
438 traffic if we can help it.
439
440 netdevsim
441 ~~~~~~~~~
442
443 ``netdevsim`` is a test driver which can be used to exercise driver
444 configuration APIs without requiring capable hardware.
445 Mock-ups and tests based on ``netdevsim`` are strongly encouraged when
446 adding new APIs, but ``netdevsim`` in itself is **not** considered
447 a use case/user. You must also implement the new APIs in a real driver.
448
449 We give no guarantees that ``netdevsim`` won't change in the future
450 in a way which would break what would normally be considered uAPI.
451
452 ``netdevsim`` is reserved for use by upstream tests only, so any
453 new ``netdevsim`` features must be accompanied by selftests under
454 ``tools/testing/selftests/``.
455
456 Reviewer guidance
457 -----------------
458
459 Reviewing other people's patches on the list is highly encouraged,
460 regardless of the level of expertise. For general guidance and
461 helpful tips please see :ref:`development_advancedtopics_reviews`.
462
463 It's safe to assume that netdev maintainers know the community and the level
464 of expertise of the reviewers. The reviewers should not be concerned about
465 their comments impeding or derailing the patch flow.
466
467 Less experienced reviewers are highly encouraged to do more in-depth
468 review of submissions and not focus exclusively on trivial or subjective
469 matters like code formatting, tags etc.
470
471 Testimonials / feedback
472 -----------------------
473
474 Some companies use peer feedback in employee performance reviews.
475 Please feel free to request feedback from netdev maintainers,
476 especially if you spend significant amount of time reviewing code
477 and go out of your way to improve shared infrastructure.
478
479 The feedback must be requested by you, the contributor, and will always
480 be shared with you (even if you request for it to be submitted to your
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.