interconnect: qcom: icc-rpm: Fix peak rate calculation
[linux-2.6-microblaze.git] / Documentation / process / maintainer-netdev.rst
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 The netdev list is managed (like many other Linux mailing lists) through
29 VGER (http://vger.kernel.org/) with archives available at
30 https://lore.kernel.org/netdev/
31
32 Aside from subsystems like those mentioned above, all network-related
33 Linux development (i.e. RFC, review, comments, etc.) takes place on
34 netdev.
35
36 Development cycle
37 -----------------
38
39 Here is a bit of background information on
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
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
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
85 .. warning::
86   Do not send new ``net-next`` content to netdev during the
87   period during which ``net-next`` tree is closed.
88
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
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   https://netdev.bots.linux.dev/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
109 netdev patch review
110 -------------------
111
112 .. _patch_status:
113
114 Patch status
115 ~~~~~~~~~~~~
116
117 Status of a patch can be checked by looking at the main patchwork
118 queue for netdev:
119
120   https://patchwork.kernel.org/project/netdevbpf/list/
121
122 The "State" field will tell you exactly where things are at with your
123 patch:
124
125 ================== =============================================================
126 Patch state        Description
127 ================== =============================================================
128 New, Under review  pending review, patch is in the maintainer’s queue for
129                    review; the two states are used interchangeably (depending on
130                    the exact co-maintainer handling patchwork at the time)
131 Accepted           patch was applied to the appropriate networking tree, this is
132                    usually set automatically by the pw-bot
133 Needs ACK          waiting for an ack from an area expert or testing
134 Changes requested  patch has not passed the review, new revision is expected
135                    with appropriate code and commit message changes
136 Rejected           patch has been rejected and new revision is not expected
137 Not applicable     patch is expected to be applied outside of the networking
138                    subsystem
139 Awaiting upstream  patch should be reviewed and handled by appropriate
140                    sub-maintainer, who will send it on to the networking trees;
141                    patches set to ``Awaiting upstream`` in netdev's patchwork
142                    will usually remain in this state, whether the sub-maintainer
143                    requested changes, accepted or rejected the patch
144 Deferred           patch needs to be reposted later, usually due to dependency
145                    or because it was posted for a closed tree
146 Superseded         new version of the patch was posted, usually set by the
147                    pw-bot
148 RFC                not to be applied, usually not in maintainer’s review queue,
149                    pw-bot can automatically set patches to this state based
150                    on subject tags
151 ================== =============================================================
152
153 Patches are indexed by the ``Message-ID`` header of the emails
154 which carried them so if you have trouble finding your patch append
155 the value of ``Message-ID`` to the URL above.
156
157 Updating patch status
158 ~~~~~~~~~~~~~~~~~~~~~
159
160 Contributors and reviewers do not have the permissions to update patch
161 state directly in patchwork. Patchwork doesn't expose much information
162 about the history of the state of patches, therefore having multiple
163 people update the state leads to confusion.
164
165 Instead of delegating patchwork permissions netdev uses a simple mail
166 bot which looks for special commands/lines within the emails sent to
167 the mailing list. For example to mark a series as Changes Requested
168 one needs to send the following line anywhere in the email thread::
169
170   pw-bot: changes-requested
171
172 As a result the bot will set the entire series to Changes Requested.
173 This may be useful when author discovers a bug in their own series
174 and wants to prevent it from getting applied.
175
176 The use of the bot is entirely optional, if in doubt ignore its existence
177 completely. Maintainers will classify and update the state of the patches
178 themselves. No email should ever be sent to the list with the main purpose
179 of communicating with the bot, the bot commands should be seen as metadata.
180
181 The use of the bot is restricted to authors of the patches (the ``From:``
182 header on patch submission and command must match!), maintainers of
183 the modified code according to the MAINTAINERS file (again, ``From:``
184 must match the MAINTAINERS entry) and a handful of senior reviewers.
185
186 Bot records its activity here:
187
188   https://netdev.bots.linux.dev/pw-bot.html
189
190 Review timelines
191 ~~~~~~~~~~~~~~~~
192
193 Generally speaking, the patches get triaged quickly (in less than
194 48h). But be patient, if your patch is active in patchwork (i.e. it's
195 listed on the project's patch list) the chances it was missed are close to zero.
196 Asking the maintainer for status updates on your
197 patch is a good way to ensure your patch is ignored or pushed to the
198 bottom of the priority list.
199
200 .. _Changes requested:
201
202 Changes requested
203 ~~~~~~~~~~~~~~~~~
204
205 Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
206 to be revised. The new version should come with a change log,
207 preferably including links to previous postings, for example::
208
209   [PATCH net-next v3] net: make cows go moo
210
211   Even users who don't drink milk appreciate hearing the cows go "moo".
212
213   The amount of mooing will depend on packet rate so should match
214   the diurnal cycle quite well.
215
216   Signed-of-by: Joe Defarmer <joe@barn.org>
217   ---
218   v3:
219     - add a note about time-of-day mooing fluctuation to the commit message
220   v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
221     - fix missing argument in kernel doc for netif_is_bovine()
222     - fix memory leak in netdev_register_cow()
223   v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/
224
225 The commit message should be revised to answer any questions reviewers
226 had to ask in previous discussions. Occasionally the update of
227 the commit message will be the only change in the new version.
228
229 Partial resends
230 ~~~~~~~~~~~~~~~
231
232 Please always resend the entire patch series and make sure you do number your
233 patches such that it is clear this is the latest and greatest set of patches
234 that can be applied. Do not try to resend just the patches which changed.
235
236 Handling misapplied patches
237 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
238
239 Occasionally a patch series gets applied before receiving critical feedback,
240 or the wrong version of a series gets applied.
241
242 Making the patch disappear once it is pushed out is not possible, the commit
243 history in netdev trees is immutable.
244 Please send incremental versions on top of what has been merged in order to fix
245 the patches the way they would look like if your latest patch series was to be
246 merged.
247
248 In cases where full revert is needed the revert has to be submitted
249 as a patch to the list with a commit message explaining the technical
250 problems with the reverted commit. Reverts should be used as a last resort,
251 when original change is completely wrong; incremental fixes are preferred.
252
253 Stable tree
254 ~~~~~~~~~~~
255
256 While it used to be the case that netdev submissions were not supposed
257 to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
258 the case today. Please follow the standard stable rules in
259 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`,
260 and make sure you include appropriate Fixes tags!
261
262 Security fixes
263 ~~~~~~~~~~~~~~
264
265 Do not email netdev maintainers directly if you think you discovered
266 a bug that might have possible security implications.
267 The current netdev maintainer has consistently requested that
268 people use the mailing lists and not reach out directly.  If you aren't
269 OK with that, then perhaps consider mailing security@kernel.org or
270 reading about http://oss-security.openwall.org/wiki/mailing-lists/distros
271 as possible alternative mechanisms.
272
273
274 Co-posting changes to user space components
275 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
276
277 User space code exercising kernel features should be posted
278 alongside kernel patches. This gives reviewers a chance to see
279 how any new interface is used and how well it works.
280
281 When user space tools reside in the kernel repo itself all changes
282 should generally come as one series. If series becomes too large
283 or the user space project is not reviewed on netdev include a link
284 to a public repo where user space patches can be seen.
285
286 In case user space tooling lives in a separate repository but is
287 reviewed on netdev  (e.g. patches to ``iproute2`` tools) kernel and
288 user space patches should form separate series (threads) when posted
289 to the mailing list, e.g.::
290
291   [PATCH net-next 0/3] net: some feature cover letter
292    └─ [PATCH net-next 1/3] net: some feature prep
293    └─ [PATCH net-next 2/3] net: some feature do it
294    └─ [PATCH net-next 3/3] selftest: net: some feature
295
296   [PATCH iproute2-next] ip: add support for some feature
297
298 Posting as one thread is discouraged because it confuses patchwork
299 (as of patchwork 2.2.2).
300
301 Preparing changes
302 -----------------
303
304 Attention to detail is important.  Re-read your own work as if you were the
305 reviewer.  You can start with using ``checkpatch.pl``, perhaps even with
306 the ``--strict`` flag.  But do not be mindlessly robotic in doing so.
307 If your change is a bug fix, make sure your commit log indicates the
308 end-user visible symptom, the underlying reason as to why it happens,
309 and then if necessary, explain why the fix proposed is the best way to
310 get things done.  Don't mangle whitespace, and as is common, don't
311 mis-indent function arguments that span multiple lines.  If it is your
312 first patch, mail it to yourself so you can test apply it to an
313 unpatched tree to confirm infrastructure didn't mangle it.
314
315 Finally, go back and read
316 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
317 to be sure you are not repeating some common mistake documented there.
318
319 Indicating target tree
320 ~~~~~~~~~~~~~~~~~~~~~~
321
322 To help maintainers and CI bots you should explicitly mark which tree
323 your patch is targeting. Assuming that you use git, use the prefix
324 flag::
325
326   git format-patch --subject-prefix='PATCH net-next' start..finish
327
328 Use ``net`` instead of ``net-next`` (always lower case) in the above for
329 bug-fix ``net`` content.
330
331 Dividing work into patches
332 ~~~~~~~~~~~~~~~~~~~~~~~~~~
333
334 Put yourself in the shoes of the reviewer. Each patch is read separately
335 and therefore should constitute a comprehensible step towards your stated
336 goal.
337
338 Avoid sending series longer than 15 patches. Larger series takes longer
339 to review as reviewers will defer looking at it until they find a large
340 chunk of time. A small series can be reviewed in a short time, so Maintainers
341 just do it. As a result, a sequence of smaller series gets merged quicker and
342 with better review coverage. Re-posting large series also increases the mailing
343 list traffic.
344
345 Multi-line comments
346 ~~~~~~~~~~~~~~~~~~~
347
348 Comment style convention is slightly different for networking and most of
349 the tree.  Instead of this::
350
351   /*
352    * foobar blah blah blah
353    * another line of text
354    */
355
356 it is requested that you make it look like this::
357
358   /* foobar blah blah blah
359    * another line of text
360    */
361
362 Local variable ordering ("reverse xmas tree", "RCS")
363 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
364
365 Netdev has a convention for ordering local variables in functions.
366 Order the variable declaration lines longest to shortest, e.g.::
367
368   struct scatterlist *sg;
369   struct sk_buff *skb;
370   int err, i;
371
372 If there are dependencies between the variables preventing the ordering
373 move the initialization out of line.
374
375 Format precedence
376 ~~~~~~~~~~~~~~~~~
377
378 When working in existing code which uses nonstandard formatting make
379 your code follow the most recent guidelines, so that eventually all code
380 in the domain of netdev is in the preferred format.
381
382 Resending after review
383 ~~~~~~~~~~~~~~~~~~~~~~
384
385 Allow at least 24 hours to pass between postings. This will ensure reviewers
386 from all geographical locations have a chance to chime in. Do not wait
387 too long (weeks) between postings either as it will make it harder for reviewers
388 to recall all the context.
389
390 Make sure you address all the feedback in your new posting. Do not post a new
391 version of the code if the discussion about the previous version is still
392 ongoing, unless directly instructed by a reviewer.
393
394 The new version of patches should be posted as a separate thread,
395 not as a reply to the previous posting. Change log should include a link
396 to the previous posting (see :ref:`Changes requested`).
397
398 Testing
399 -------
400
401 Expected level of testing
402 ~~~~~~~~~~~~~~~~~~~~~~~~~
403
404 At the very minimum your changes must survive an ``allyesconfig`` and an
405 ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
406
407 Ideally you will have done run-time testing specific to your change,
408 and the patch series contains a set of kernel selftest for
409 ``tools/testing/selftests/net`` or using the KUnit framework.
410
411 You are expected to test your changes on top of the relevant networking
412 tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
413
414 patchwork checks
415 ~~~~~~~~~~~~~~~~
416
417 Checks in patchwork are mostly simple wrappers around existing kernel
418 scripts, the sources are available at:
419
420 https://github.com/kuba-moo/nipa/tree/master/tests
421
422 **Do not** post your patches just to run them through the checks.
423 You must ensure that your patches are ready by testing them locally
424 before posting to the mailing list. The patchwork build bot instance
425 gets overloaded very easily and netdev@vger really doesn't need more
426 traffic if we can help it.
427
428 netdevsim
429 ~~~~~~~~~
430
431 ``netdevsim`` is a test driver which can be used to exercise driver
432 configuration APIs without requiring capable hardware.
433 Mock-ups and tests based on ``netdevsim`` are strongly encouraged when
434 adding new APIs, but ``netdevsim`` in itself is **not** considered
435 a use case/user. You must also implement the new APIs in a real driver.
436
437 We give no guarantees that ``netdevsim`` won't change in the future
438 in a way which would break what would normally be considered uAPI.
439
440 ``netdevsim`` is reserved for use by upstream tests only, so any
441 new ``netdevsim`` features must be accompanied by selftests under
442 ``tools/testing/selftests/``.
443
444 Reviewer guidance
445 -----------------
446
447 Reviewing other people's patches on the list is highly encouraged,
448 regardless of the level of expertise. For general guidance and
449 helpful tips please see :ref:`development_advancedtopics_reviews`.
450
451 It's safe to assume that netdev maintainers know the community and the level
452 of expertise of the reviewers. The reviewers should not be concerned about
453 their comments impeding or derailing the patch flow.
454
455 Less experienced reviewers are highly encouraged to do more in-depth
456 review of submissions and not focus exclusively on trivial or subjective
457 matters like code formatting, tags etc.
458
459 Testimonials / feedback
460 -----------------------
461
462 Some companies use peer feedback in employee performance reviews.
463 Please feel free to request feedback from netdev maintainers,
464 especially if you spend significant amount of time reviewing code
465 and go out of your way to improve shared infrastructure.
466
467 The feedback must be requested by you, the contributor, and will always
468 be shared with you (even if you request for it to be submitted to your
469 manager).