Commit | Line | Data |
---|---|---|
96398ddf TH |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | .. _netdev-FAQ: | |
4 | ||
ff249be5 JK |
5 | ============================= |
6 | Networking subsystem (netdev) | |
7 | ============================= | |
96398ddf | 8 | |
5d407ca7 JK |
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 | ||
ff249be5 JK |
18 | netdev |
19 | ------ | |
20 | ||
21 | netdev is a mailing list for all network-related Linux stuff. This | |
96398ddf TH |
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 | |
ff249be5 | 26 | volume of traffic have their own specific mailing lists and trees. |
96398ddf TH |
27 | |
28 | The netdev list is managed (like many other Linux mailing lists) through | |
50386f75 JK |
29 | VGER (http://vger.kernel.org/) with archives available at |
30 | https://lore.kernel.org/netdev/ | |
96398ddf | 31 | |
30cddd30 | 32 | Aside from subsystems like those mentioned above, all network-related |
96398ddf TH |
33 | Linux development (i.e. RFC, review, comments, etc.) takes place on |
34 | netdev. | |
35 | ||
ff249be5 JK |
36 | Development cycle |
37 | ----------------- | |
96398ddf | 38 | |
ff249be5 | 39 | Here is a bit of background information on |
96398ddf TH |
40 | the cadence of Linux development. Each new release starts off with a |
41 | two week "merge window" where the main maintainers feed their new stuff | |
42 | to Linus for merging into the mainline tree. After the two weeks, the | |
43 | merge window is closed, and it is called/tagged ``-rc1``. No new | |
44 | features get mainlined after this -- only fixes to the rc1 content are | |
45 | expected. After roughly a week of collecting fixes to the rc1 content, | |
46 | rc2 is released. This repeats on a roughly weekly basis until rc7 | |
47 | (typically; sometimes rc6 if things are quiet, or rc8 if things are in a | |
48 | state of churn), and a week after the last vX.Y-rcN was done, the | |
49 | official vX.Y is released. | |
50 | ||
ff249be5 JK |
51 | To find out where we are now in the cycle - load the mainline (Linus) |
52 | page here: | |
53 | ||
54 | https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git | |
55 | ||
56 | and note the top of the "tags" section. If it is rc1, it is early in | |
57 | the dev cycle. If it was tagged rc7 a week ago, then a release is | |
58 | probably imminent. If the most recent tag is a final release tag | |
59 | (without an ``-rcN`` suffix) - we are most likely in a merge window | |
60 | and ``net-next`` is closed. | |
61 | ||
62 | git trees and patch flow | |
63 | ------------------------ | |
64 | ||
65 | There are two networking trees (git repositories) in play. Both are | |
66 | driven by David Miller, the main network maintainer. There is the | |
67 | ``net`` tree, and the ``net-next`` tree. As you can probably guess from | |
68 | the names, the ``net`` tree is for fixes to existing code already in the | |
69 | mainline tree from Linus, and ``net-next`` is where the new code goes | |
70 | for the future release. You can find the trees here: | |
71 | ||
72 | - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net.git | |
73 | - https://git.kernel.org/pub/scm/linux/kernel/git/netdev/net-next.git | |
74 | ||
75 | Relating that to kernel development: At the beginning of the 2-week | |
76 | merge window, the ``net-next`` tree will be closed - no new changes/features. | |
77 | The accumulated new content of the past ~10 weeks will be passed onto | |
96398ddf TH |
78 | mainline/Linus via a pull request for vX.Y -- at the same time, the |
79 | ``net`` tree will start accumulating fixes for this pulled content | |
80 | relating to vX.Y | |
81 | ||
82 | An announcement indicating when ``net-next`` has been closed is usually | |
83 | sent to netdev, but knowing the above, you can predict that in advance. | |
84 | ||
2fd4c50d JK |
85 | .. warning:: |
86 | Do not send new ``net-next`` content to netdev during the | |
87 | period during which ``net-next`` tree is closed. | |
96398ddf | 88 | |
0e242e3f JK |
89 | RFC patches sent for review only are obviously welcome at any time |
90 | (use ``--subject-prefix='RFC net-next'`` with ``git format-patch``). | |
91 | ||
96398ddf TH |
92 | Shortly after the two weeks have passed (and vX.Y-rc1 is released), the |
93 | tree for ``net-next`` reopens to collect content for the next (vX.Y+1) | |
94 | release. | |
95 | ||
96 | If you aren't subscribed to netdev and/or are simply unsure if | |
97 | ``net-next`` has re-opened yet, simply check the ``net-next`` git | |
98 | repository link above for any new networking-related commits. You may | |
99 | also check the following website for the current status: | |
100 | ||
101 | http://vger.kernel.org/~davem/net-next.html | |
102 | ||
103 | The ``net`` tree continues to collect fixes for the vX.Y content, and is | |
104 | fed back to Linus at regular (~weekly) intervals. Meaning that the | |
105 | focus for ``net`` is on stabilization and bug fixes. | |
106 | ||
107 | Finally, the vX.Y gets released, and the whole cycle starts over. | |
108 | ||
ff249be5 JK |
109 | netdev patch review |
110 | ------------------- | |
96398ddf | 111 | |
e110ba65 JK |
112 | .. _patch_status: |
113 | ||
ff249be5 JK |
114 | Patch status |
115 | ~~~~~~~~~~~~ | |
96398ddf | 116 | |
ff249be5 JK |
117 | Status of a patch can be checked by looking at the main patchwork |
118 | queue for netdev: | |
96398ddf | 119 | |
460cd17e | 120 | https://patchwork.kernel.org/project/netdevbpf/list/ |
96398ddf TH |
121 | |
122 | The "State" field will tell you exactly where things are at with your | |
5d84921a JK |
123 | patch. Patches are indexed by the ``Message-ID`` header of the emails |
124 | which carried them so if you have trouble finding your patch append | |
125 | the value of ``Message-ID`` to the URL above. | |
96398ddf | 126 | |
ff249be5 JK |
127 | Updating patch status |
128 | ~~~~~~~~~~~~~~~~~~~~~ | |
129 | ||
724c1a74 | 130 | It may be tempting to help the maintainers and update the state of your |
ff249be5 JK |
131 | own patches when you post a new version or spot a bug. Please **do not** |
132 | do that. | |
724c1a74 | 133 | Interfering with the patch status on patchwork will only cause confusion. Leave |
96398ddf TH |
134 | it to the maintainer to figure out what is the most recent and current |
135 | version that should be applied. If there is any doubt, the maintainer | |
136 | will reply and ask what should be done. | |
137 | ||
ff249be5 JK |
138 | Review timelines |
139 | ~~~~~~~~~~~~~~~~ | |
140 | ||
f4ef6811 JK |
141 | Generally speaking, the patches get triaged quickly (in less than |
142 | 48h). But be patient, if your patch is active in patchwork (i.e. it's | |
143 | listed on the project's patch list) the chances it was missed are close to zero. | |
144 | Asking the maintainer for status updates on your | |
145 | patch is a good way to ensure your patch is ignored or pushed to the | |
146 | bottom of the priority list. | |
02514a06 | 147 | |
e110ba65 JK |
148 | Changes requested |
149 | ~~~~~~~~~~~~~~~~~ | |
150 | ||
151 | Patches :ref:`marked<patch_status>` as ``Changes Requested`` need | |
152 | to be revised. The new version should come with a change log, | |
153 | preferably including links to previous postings, for example:: | |
154 | ||
155 | [PATCH net-next v3] net: make cows go moo | |
156 | ||
157 | Even users who don't drink milk appreciate hearing the cows go "moo". | |
158 | ||
159 | The amount of mooing will depend on packet rate so should match | |
160 | the diurnal cycle quite well. | |
161 | ||
162 | Signed-of-by: Joe Defarmer <joe@barn.org> | |
163 | --- | |
164 | v3: | |
165 | - add a note about time-of-day mooing fluctuation to the commit message | |
166 | v2: https://lore.kernel.org/netdev/123themessageid@barn.org/ | |
167 | - fix missing argument in kernel doc for netif_is_bovine() | |
168 | - fix memory leak in netdev_register_cow() | |
169 | v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/ | |
170 | ||
171 | The commit message should be revised to answer any questions reviewers | |
172 | had to ask in previous discussions. Occasionally the update of | |
173 | the commit message will be the only change in the new version. | |
174 | ||
ff249be5 JK |
175 | Partial resends |
176 | ~~~~~~~~~~~~~~~ | |
177 | ||
178 | Please always resend the entire patch series and make sure you do number your | |
ffa91253 | 179 | patches such that it is clear this is the latest and greatest set of patches |
ff249be5 JK |
180 | that can be applied. Do not try to resend just the patches which changed. |
181 | ||
182 | Handling misapplied patches | |
183 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
ffa91253 | 184 | |
ff249be5 JK |
185 | Occasionally a patch series gets applied before receiving critical feedback, |
186 | or the wrong version of a series gets applied. | |
e70f94c6 JK |
187 | |
188 | Making the patch disappear once it is pushed out is not possible, the commit | |
189 | history in netdev trees is immutable. | |
ffa91253 FF |
190 | Please send incremental versions on top of what has been merged in order to fix |
191 | the patches the way they would look like if your latest patch series was to be | |
192 | merged. | |
193 | ||
e70f94c6 JK |
194 | In cases where full revert is needed the revert has to be submitted |
195 | as a patch to the list with a commit message explaining the technical | |
196 | problems with the reverted commit. Reverts should be used as a last resort, | |
197 | when original change is completely wrong; incremental fixes are preferred. | |
198 | ||
ff249be5 JK |
199 | Stable tree |
200 | ~~~~~~~~~~~ | |
201 | ||
dbbe7c96 JK |
202 | While it used to be the case that netdev submissions were not supposed |
203 | to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer | |
204 | the case today. Please follow the standard stable rules in | |
205 | :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`, | |
206 | and make sure you include appropriate Fixes tags! | |
96398ddf | 207 | |
ff249be5 JK |
208 | Security fixes |
209 | ~~~~~~~~~~~~~~ | |
210 | ||
211 | Do not email netdev maintainers directly if you think you discovered | |
212 | a bug that might have possible security implications. | |
213 | The current netdev maintainer has consistently requested that | |
f4ef6811 JK |
214 | people use the mailing lists and not reach out directly. If you aren't |
215 | OK with that, then perhaps consider mailing security@kernel.org or | |
216 | reading about http://oss-security.openwall.org/wiki/mailing-lists/distros | |
217 | as possible alternative mechanisms. | |
218 | ||
ff249be5 JK |
219 | |
220 | Co-posting changes to user space components | |
221 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
222 | ||
f4ef6811 JK |
223 | User space code exercising kernel features should be posted |
224 | alongside kernel patches. This gives reviewers a chance to see | |
225 | how any new interface is used and how well it works. | |
226 | ||
227 | When user space tools reside in the kernel repo itself all changes | |
228 | should generally come as one series. If series becomes too large | |
229 | or the user space project is not reviewed on netdev include a link | |
230 | to a public repo where user space patches can be seen. | |
231 | ||
232 | In case user space tooling lives in a separate repository but is | |
233 | reviewed on netdev (e.g. patches to ``iproute2`` tools) kernel and | |
234 | user space patches should form separate series (threads) when posted | |
235 | to the mailing list, e.g.:: | |
236 | ||
237 | [PATCH net-next 0/3] net: some feature cover letter | |
238 | └─ [PATCH net-next 1/3] net: some feature prep | |
239 | └─ [PATCH net-next 2/3] net: some feature do it | |
240 | └─ [PATCH net-next 3/3] selftest: net: some feature | |
241 | ||
242 | [PATCH iproute2-next] ip: add support for some feature | |
243 | ||
244 | Posting as one thread is discouraged because it confuses patchwork | |
245 | (as of patchwork 2.2.2). | |
246 | ||
ff249be5 JK |
247 | Preparing changes |
248 | ----------------- | |
249 | ||
250 | Attention to detail is important. Re-read your own work as if you were the | |
f4ef6811 JK |
251 | reviewer. You can start with using ``checkpatch.pl``, perhaps even with |
252 | the ``--strict`` flag. But do not be mindlessly robotic in doing so. | |
253 | If your change is a bug fix, make sure your commit log indicates the | |
254 | end-user visible symptom, the underlying reason as to why it happens, | |
255 | and then if necessary, explain why the fix proposed is the best way to | |
256 | get things done. Don't mangle whitespace, and as is common, don't | |
257 | mis-indent function arguments that span multiple lines. If it is your | |
258 | first patch, mail it to yourself so you can test apply it to an | |
259 | unpatched tree to confirm infrastructure didn't mangle it. | |
260 | ||
261 | Finally, go back and read | |
262 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` | |
263 | to be sure you are not repeating some common mistake documented there. | |
264 | ||
ff249be5 JK |
265 | Indicating target tree |
266 | ~~~~~~~~~~~~~~~~~~~~~~ | |
267 | ||
f4ef6811 JK |
268 | To help maintainers and CI bots you should explicitly mark which tree |
269 | your patch is targeting. Assuming that you use git, use the prefix | |
270 | flag:: | |
271 | ||
272 | git format-patch --subject-prefix='PATCH net-next' start..finish | |
273 | ||
274 | Use ``net`` instead of ``net-next`` (always lower case) in the above for | |
275 | bug-fix ``net`` content. | |
276 | ||
ff249be5 JK |
277 | Dividing work into patches |
278 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
f4ef6811 JK |
279 | |
280 | Put yourself in the shoes of the reviewer. Each patch is read separately | |
281 | and therefore should constitute a comprehensible step towards your stated | |
282 | goal. | |
283 | ||
284 | Avoid sending series longer than 15 patches. Larger series takes longer | |
285 | to review as reviewers will defer looking at it until they find a large | |
286 | chunk of time. A small series can be reviewed in a short time, so Maintainers | |
287 | just do it. As a result, a sequence of smaller series gets merged quicker and | |
288 | with better review coverage. Re-posting large series also increases the mailing | |
289 | list traffic. | |
290 | ||
ff249be5 JK |
291 | Multi-line comments |
292 | ~~~~~~~~~~~~~~~~~~~ | |
293 | ||
294 | Comment style convention is slightly different for networking and most of | |
295 | the tree. Instead of this:: | |
96398ddf TH |
296 | |
297 | /* | |
298 | * foobar blah blah blah | |
299 | * another line of text | |
300 | */ | |
301 | ||
302 | it is requested that you make it look like this:: | |
303 | ||
304 | /* foobar blah blah blah | |
305 | * another line of text | |
306 | */ | |
307 | ||
ff249be5 JK |
308 | Local variable ordering ("reverse xmas tree", "RCS") |
309 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
a2487564 JK |
310 | |
311 | Netdev has a convention for ordering local variables in functions. | |
312 | Order the variable declaration lines longest to shortest, e.g.:: | |
313 | ||
314 | struct scatterlist *sg; | |
315 | struct sk_buff *skb; | |
316 | int err, i; | |
317 | ||
318 | If there are dependencies between the variables preventing the ordering | |
319 | move the initialization out of line. | |
320 | ||
ff249be5 JK |
321 | Format precedence |
322 | ~~~~~~~~~~~~~~~~~ | |
323 | ||
324 | When working in existing code which uses nonstandard formatting make | |
325 | your code follow the most recent guidelines, so that eventually all code | |
08767a26 | 326 | in the domain of netdev is in the preferred format. |
96398ddf | 327 | |
ff249be5 JK |
328 | Resending after review |
329 | ~~~~~~~~~~~~~~~~~~~~~~ | |
330 | ||
f4ef6811 JK |
331 | Allow at least 24 hours to pass between postings. This will ensure reviewers |
332 | from all geographical locations have a chance to chime in. Do not wait | |
333 | too long (weeks) between postings either as it will make it harder for reviewers | |
334 | to recall all the context. | |
335 | ||
336 | Make sure you address all the feedback in your new posting. Do not post a new | |
337 | version of the code if the discussion about the previous version is still | |
338 | ongoing, unless directly instructed by a reviewer. | |
96398ddf | 339 | |
ff249be5 JK |
340 | Testing |
341 | ------- | |
342 | ||
343 | Expected level of testing | |
344 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
345 | ||
3eca3814 JK |
346 | At the very minimum your changes must survive an ``allyesconfig`` and an |
347 | ``allmodconfig`` build with ``W=1`` set without new warnings or failures. | |
348 | ||
349 | Ideally you will have done run-time testing specific to your change, | |
350 | and the patch series contains a set of kernel selftest for | |
351 | ``tools/testing/selftests/net`` or using the KUnit framework. | |
352 | ||
353 | You are expected to test your changes on top of the relevant networking | |
354 | tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``. | |
96398ddf | 355 | |
ff249be5 JK |
356 | patchwork checks |
357 | ~~~~~~~~~~~~~~~~ | |
f1d77b2e JK |
358 | |
359 | Checks in patchwork are mostly simple wrappers around existing kernel | |
360 | scripts, the sources are available at: | |
361 | ||
362 | https://github.com/kuba-moo/nipa/tree/master/tests | |
363 | ||
ff249be5 JK |
364 | **Do not** post your patches just to run them through the checks. |
365 | You must ensure that your patches are ready by testing them locally | |
f1d77b2e JK |
366 | before posting to the mailing list. The patchwork build bot instance |
367 | gets overloaded very easily and netdev@vger really doesn't need more | |
368 | traffic if we can help it. | |
369 | ||
ff249be5 JK |
370 | netdevsim |
371 | ~~~~~~~~~ | |
396492b4 | 372 | |
ff249be5 JK |
373 | ``netdevsim`` is a test driver which can be used to exercise driver |
374 | configuration APIs without requiring capable hardware. | |
375 | Mock-ups and tests based on ``netdevsim`` are strongly encouraged when | |
376 | adding new APIs, but ``netdevsim`` in itself is **not** considered | |
377 | a use case/user. You must also implement the new APIs in a real driver. | |
396492b4 | 378 | |
ff249be5 | 379 | We give no guarantees that ``netdevsim`` won't change in the future |
396492b4 JK |
380 | in a way which would break what would normally be considered uAPI. |
381 | ||
ff249be5 JK |
382 | ``netdevsim`` is reserved for use by upstream tests only, so any |
383 | new ``netdevsim`` features must be accompanied by selftests under | |
384 | ``tools/testing/selftests/``. | |
396492b4 | 385 | |
ff249be5 JK |
386 | Testimonials / feedback |
387 | ----------------------- | |
c5884ef4 | 388 | |
ff249be5 JK |
389 | Some companies use peer feedback in employee performance reviews. |
390 | Please feel free to request feedback from netdev maintainers, | |
391 | especially if you spend significant amount of time reviewing code | |
c5884ef4 JK |
392 | and go out of your way to improve shared infrastructure. |
393 | ||
394 | The feedback must be requested by you, the contributor, and will always | |
395 | be shared with you (even if you request for it to be submitted to your | |
396 | manager). |