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