1 .. SPDX-License-Identifier: GPL-2.0
2
3 The tip tree handbook
4 =====================
5
6 What is the tip tree?
7 ---------------------
8
9 The tip tree is a collection of several subsys
10 development. The tip tree is both a direct dev
11 aggregation tree for several sub-maintainer tr
12 is: https://git.kernel.org/pub/scm/linux/kerne
13
14 The tip tree contains the following subsystems
15
16 - **x86 architecture**
17
18 The x86 architecture development takes pl
19 for the x86 KVM and XEN specific parts wh
20 corresponding subsystems and routed direc
21 there. It's still good practice to Cc the
22 x86-specific KVM and XEN patches.
23
24 Some x86 subsystems have their own mainta
25 overall x86 maintainers. Please Cc the o
26 patches touching files in arch/x86 even w
27 by the MAINTAINER file.
28
29 Note, that ``x86@kernel.org`` is not a ma
30 mail alias which distributes mails to the
31 team. Please always Cc the Linux Kernel m
32 ``linux-kernel@vger.kernel.org``, otherwi
33 the private inboxes of the maintainers.
34
35 - **Scheduler**
36
37 Scheduler development takes place in the
38 sched/core branch - with occasional sub-t
39 work-in-progress patch-sets.
40
41 - **Locking and atomics**
42
43 Locking development (including atomics an
44 primitives that are connected to locking)
45 tree, in the locking/core branch - with o
46 for work-in-progress patch-sets.
47
48 - **Generic interrupt subsystem and interru
49
50 - interrupt core development happens in t
51
52 - interrupt chip driver development also
53 branch, but the patches are usually app
54 tree and then aggregated into irq/core
55
56 - **Time, timers, timekeeping, NOHZ and rel
57
58 - timekeeping, clocksource core, NTP and
59 happens in the timers/core branch, but
60 a separate maintainer tree and then agg
61
62 - clocksource/event driver development ha
63 branch, but patches are mostly applied
64 and then aggregated into timers/core
65
66 - **Performance counters core, architecture
67
68 - perf core and architecture support deve
69 perf/core branch
70
71 - perf tooling development happens in the
72 tree and is aggregated into the tip tre
73
74 - **CPU hotplug core**
75
76 - **RAS core**
77
78 Mostly x86-specific RAS patches are colle
79 branch.
80
81 - **EFI core**
82
83 EFI development in the efi git tree. The
84 aggregated in the tip efi/core branch.
85
86 - **RCU**
87
88 RCU development happens in the linux-rcu
89 are aggregated into the tip core/rcu bran
90
91 - **Various core code components**:
92
93 - debugobjects
94
95 - objtool
96
97 - random bits and pieces
98
99
100 Patch submission notes
101 ----------------------
102
103 Selecting the tree/branch
104 ^^^^^^^^^^^^^^^^^^^^^^^^^
105
106 In general, development against the head of th
107 fine, but for the subsystems which are maintai
108 own git tree and are only aggregated into the
109 take place against the relevant subsystem tree
110
111 Bug fixes which target mainline should always
112 mainline kernel tree. Potential conflicts agai
113 queued in the tip tree are handled by the main
114
115 Patch subject
116 ^^^^^^^^^^^^^
117
118 The tip tree preferred format for patch subjec
119 'subsys/component:', e.g. 'x86/apic:', 'x86/mm
120 'genirq/core:'. Please do not use file names o
121 prefix. 'git log path/to/file' should give you
122 cases.
123
124 The condensed patch description in the subject
125 uppercase letter and should be written in impe
126
127
128 Changelog
129 ^^^^^^^^^
130
131 The general rules about changelogs in the :ref
132 <describe_changes>`, apply.
133
134 The tip tree maintainers set value on followin
135 the request to write changelogs in imperative
136 code or the execution of it. This is not just
137 maintainers. Changelogs written in abstract wo
138 tend to be less confusing than those written i
139
140 It's also useful to structure the changelog in
141 lump everything together into a single one. A
142 the context, the problem and the solution in s
143 order.
144
145 Examples for illustration:
146
147 Example 1::
148
149 x86/intel_rdt/mbm: Fix MBM overflow handle
150
151 When a CPU is dying, we cancel the worker
152 different CPU on the same domain. But if t
153 expire (say 0.99s) then we essentially dou
154
155 We modify the hot cpu handling to cancel t
156 cpu and run the worker immediately on a di
157 do not flush the worker because the MBM ov
158 worker on same CPU and scans the domain->c
159 pointer.
160
161 Improved version::
162
163 x86/intel_rdt/mbm: Fix MBM overflow handle
164
165 When a CPU is dying, the overflow worker i
166 different CPU in the same domain. But if t
167 expire this essentially doubles the interv
168 detected overflow.
169
170 Cancel the overflow worker and reschedule
171 in the same domain. The work could be flus
172 reschedule it on the same CPU.
173
174 Example 2::
175
176 time: POSIX CPU timers: Ensure that variab
177
178 If cpu_timer_sample_group returns -EINVAL,
179 *sample. Checking for cpu_timer_sample_gro
180 potential use of an uninitialized value of
181 Given an invalid clock_idx, the previous c
182 *oldval in an undefined manner. This is no
183 short-circuiting of && to sample the timer
184 actually be used to update *oldval.
185
186 Improved version::
187
188 posix-cpu-timers: Make set_process_cpu_tim
189
190 Because the return value of cpu_timer_samp
191 compilers and static checkers can legitima
192 of the uninitialized variable 'now'. This
193 call sites hand in valid clock ids.
194
195 Also cpu_timer_sample_group() is invoked u
196 result is not used because *oldval is NULL
197
198 Make the invocation conditional and check
199
200 Example 3::
201
202 The entity can also be used for other purp
203
204 Let's rename it to be more generic.
205
206 Improved version::
207
208 The entity can also be used for other purp
209
210 Rename it to be more generic.
211
212
213 For complex scenarios, especially race conditi
214 issues, it is valuable to depict the scenario
215 the parallelism and the temporal order of even
216
217 CPU0 CPU1
218 free_irq(X) interrupt
219 spin_lock(
220 wake irq t
221 spin_unloc
222 spin_lock(desc->lock)
223 remove action()
224 shutdown_irq()
225 release_resources() thread_han
226 spin_unlock(desc->lock) access r
227 ^^^^^^^^
228 synchronize_irq()
229
230 Lockdep provides similar useful output to depi
231 scenario::
232
233 CPU0 CP
234 rtmutex_lock(&rcu->rt_mutex)
235 spin_lock(&rcu->rt_mutex.wait_lock)
236 lo
237 sp
238 sp
239 --> Interrupt
240 spin_lock(&timer->it_lock)
241
242
243 Function references in changelogs
244 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
245
246 When a function is mentioned in the changelog,
247 subject line, please use the format 'function_
248 brackets after the function name can be ambigu
249
250 Subject: subsys/component: Make reservation_
251
252 reservation_count is only used in reservatio
253
254 The variant with brackets is more precise::
255
256 Subject: subsys/component: Make reservation_
257
258 reservation_count() is only called from rese
259 static.
260
261
262 Backtraces in changelogs
263 ^^^^^^^^^^^^^^^^^^^^^^^^
264
265 See :ref:`backtraces`.
266
267 Ordering of commit tags
268 ^^^^^^^^^^^^^^^^^^^^^^^
269
270 To have a uniform view of the commit tags, the
271 following tag ordering scheme:
272
273 - Fixes: 12char-SHA1 ("sub/sys: Original subj
274
275 A Fixes tag should be added even for change
276 backported to stable kernels, i.e. when add
277 issue which only affects tip or the current
278 are helpful to identify the original commit
279 than prominently mentioning the commit whic
280 text of the changelog itself because they c
281 extracted.
282
283 The following example illustrates the diffe
284
285 Commit
286
287 abcdef012345678 ("x86/xxx: Replace foo
288
289 left an unused instance of variable foo a
290
291 Signed-off-by: J.Dev <j.dev@mail>
292
293 Please say instead::
294
295 The recent replacement of foo with bar le
296 variable foo around. Remove it.
297
298 Fixes: abcdef012345678 ("x86/xxx: Replace
299 Signed-off-by: J.Dev <j.dev@mail>
300
301 The latter puts the information about the p
302 amends it with the reference to the commit
303 rather than putting the focus on the origin
304
305 - Reported-by: ``Reporter <reporter@mail>``
306
307 - Closes: ``URL or Message-ID of the bug repo
308
309 - Originally-by: ``Original author <original-a
310
311 - Suggested-by: ``Suggester <suggester@mail>``
312
313 - Co-developed-by: ``Co-author <co-author@mail
314
315 Signed-off-by: ``Co-author <co-author@mail>`
316
317 Note, that Co-developed-by and Signed-off-b
318 come in pairs.
319
320 - Signed-off-by: ``Author <author@mail>``
321
322 The first Signed-off-by (SOB) after the las
323 author SOB, i.e. the person flagged as auth
324
325 - Signed-off-by: ``Patch handler <handler@mail
326
327 SOBs after the author SOB are from people h
328 the patch, but were not involved in develop
329 reflect the **real** route a patch took as
330 with the first SOB entry signalling primary
331 author. Acks should be given as Acked-by li
332 as Reviewed-by lines.
333
334 If the handler made modifications to the pa
335 this should be mentioned **after** the chan
336 all commit tags in the following format::
337
338 ... changelog text ends.
339
340 [ handler: Replaced foo by bar and update
341
342 First-tag: .....
343
344 Note the two empty new lines which separate
345 commit tags from that notice.
346
347 If a patch is sent to the mailing list by a
348 to be noted in the first line of the change
349
350 From: Author <author@mail>
351
352 Changelog text starts here....
353
354 so the authorship is preserved. The 'From:'
355 by a empty newline. If that 'From:' line is
356 would be attributed to the person who sent
357 The 'From:' line is automatically removed w
358 and does not show up in the final git chang
359 the authorship information of the resulting
360
361 - Tested-by: ``Tester <tester@mail>``
362
363 - Reviewed-by: ``Reviewer <reviewer@mail>``
364
365 - Acked-by: ``Acker <acker@mail>``
366
367 - Cc: ``cc-ed-person <person@mail>``
368
369 If the patch should be backported to stable
370 stable@vger.kernel.org``' tag, but do not C
371 mail.
372
373 - Link: ``https://link/to/information``
374
375 For referring to an email posted to the ker
376 use the lore.kernel.org redirector URL::
377
378 Link: https://lore.kernel.org/email-messa
379
380 This URL should be used when referring to r
381 topics, related patch sets, or other notabl
382 A convenient way to associate ``Link:`` tra
383 message is to use markdown-like bracketed n
384
385 A similar approach was attempted before a
386 effort [1], but the initial implementatio
387 regressions [2], so it was backed out and
388
389 Link: https://lore.kernel.org/some-msgid@
390 Link: https://bugzilla.example.org/bug/12
391
392 You can also use ``Link:`` trailers to indi
393 patch when applying it to your git tree. In
394 dedicated ``patch.msgid.link`` domain inste
395 This practice makes it possible for automat
396 which link to use to retrieve the original
397 example::
398
399 Link: https://patch.msgid.link/patch-sour
400
401 Please do not use combined tags, e.g. ``Report
402 they just complicate automated extraction of t
403
404
405 Links to documentation
406 ^^^^^^^^^^^^^^^^^^^^^^
407
408 Providing links to documentation in the change
409 debugging and analysis. Unfortunately, URLs o
410 because companies restructure their websites f
411 exceptions include the Intel SDM and the AMD A
412
413 Therefore, for 'volatile' documents, please cr
414 bugzilla https://bugzilla.kernel.org and attac
415 to the bugzilla entry. Finally, provide the UR
416 the changelog.
417
418 Patch resend or reminders
419 ^^^^^^^^^^^^^^^^^^^^^^^^^
420
421 See :ref:`resend_reminders`.
422
423 Merge window
424 ^^^^^^^^^^^^
425
426 Please do not expect patches to be reviewed or
427 maintainers around or during the merge window.
428 to all but urgent fixes during this time. The
429 window closes and a new -rc1 kernel has been r
430
431 Large series should be submitted in mergeable
432 before the merge window opens. Exceptions are
433 *sometimes* for small standalone drivers for n
434 invasive patches for hardware enablement.
435
436 During the merge window, the maintainers inste
437 upstream changes, fixing merge window fallout,
438 allowing themselves a breath. Please respect t
439
440 So called _urgent_ branches will be merged int
441 stabilization phase of each release.
442
443
444 Git
445 ^^^
446
447 The tip maintainers accept git pull requests f
448 subsystem changes for aggregation in the tip t
449
450 Pull requests for new patch submissions are us
451 replace proper patch submission to the mailing
452 this is that the review workflow is email base
453
454 If you submit a larger patch series it is help
455 in a private repository which allows intereste
456 series for testing. The usual way to offer thi
457 letter of the patch series.
458
459 Testing
460 ^^^^^^^
461
462 Code should be tested before submitting to the
463 other than minor changes should be built, boot
464 comprehensive (and heavyweight) kernel debuggi
465
466 These debugging options can be found in kernel
467 and can be added to an existing kernel config
468
469 make x86_debug.config
470
471 Some of these options are x86-specific and can
472 on other architectures.
473
474 .. _maintainer-tip-coding-style:
475
476 Coding style notes
477 ------------------
478
479 Comment style
480 ^^^^^^^^^^^^^
481
482 Sentences in comments start with an uppercase
483
484 Single line comments::
485
486 /* This is a single line comment */
487
488 Multi-line comments::
489
490 /*
491 * This is a properly formatted
492 * multi-line comment.
493 *
494 * Larger multi-line comments should b
495 */
496
497 No tail comments (see below):
498
499 Please refrain from using tail comments. Tai
500 reading flow in almost all contexts, but esp
501
502 if (somecondition_is_true) /* Don't pu
503 dostuff(); /* Neither here */
504
505 seed = MAGIC_CONSTANT; /* Nor here */
506
507 Use freestanding comments instead::
508
509 /* This condition is not obvious witho
510 if (somecondition_is_true) {
511 /* This really needs to be doc
512 dostuff();
513 }
514
515 /* This magic initialization needs a c
516 seed = MAGIC_CONSTANT;
517
518 Use C++ style, tail comments when documentin
519 achieve a more compact layout and better rea
520
521 // eax
522 u32 x2apic_shift : 5, // Numbe
523 // for t
524 : 27; // Reser
525 // ebx
526 u32 num_processors : 16, // Numbe
527 : 16; // Reser
528
529 versus::
530
531 /* eax */
532 /*
533 * Number of bits to shift API
534 * at the next level
535 */
536 u32 x2apic_shift : 5,
537 /* Reserved */
538 : 27;
539
540 /* ebx */
541 /* Number of processors at cur
542 u32 num_processors : 16,
543 /* Reserved */
544 : 16;
545
546 Comment the important things:
547
548 Comments should be added where the operation
549 the obvious is just a distraction::
550
551 /* Decrement refcount and check for ze
552 if (refcount_dec_and_test(&p->refcnt))
553 do;
554 lots;
555 of;
556 magic;
557 things;
558 }
559
560 Instead, comments should explain the non-obv
561 constraints::
562
563 if (refcount_dec_and_test(&p->refcnt))
564 /*
565 * Really good explanation why
566 * need to be done, ordering a
567 * etc..
568 */
569 do;
570 lots;
571 of;
572 magic;
573 /* Needs to be the last operat
574 things;
575 }
576
577 Function documentation comments:
578
579 To document functions and their arguments pl
580 and not free form comments::
581
582 /**
583 * magic_function - Do lots of magic s
584 * @magic: Pointer to the magic d
585 * @offset: Offset in the data arr
586 *
587 * Deep explanation of mysterious thin
588 * with documentation of the return va
589 *
590 * Note, that the argument descriptors
591 * in a tabular fashion.
592 */
593
594 This applies especially to globally visible
595 functions in public header files. It might b
596 format for every (static) function which nee
597 usage of descriptive function names often re
598 Apply common sense as always.
599
600
601 Documenting locking requirements
602 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
603 Documenting locking requirements is a good t
604 necessarily the best choice. Instead of writ
605
606 /* Caller must hold foo->lock */
607 void func(struct foo *foo)
608 {
609 ...
610 }
611
612 Please use::
613
614 void func(struct foo *foo)
615 {
616 lockdep_assert_held(&foo->lock
617 ...
618 }
619
620 In PROVE_LOCKING kernels, lockdep_assert_hel
621 if the caller doesn't hold the lock. Commen
622
623 Bracket rules
624 ^^^^^^^^^^^^^
625
626 Brackets should be omitted only if the stateme
627 'while' etc. is truly a single line::
628
629 if (foo)
630 do_something();
631
632 The following is not considered to be a single
633 though C does not require brackets::
634
635 for (i = 0; i < end; i++)
636 if (foo[i])
637 do_something(foo[i]);
638
639 Adding brackets around the outer loop enhances
640
641 for (i = 0; i < end; i++) {
642 if (foo[i])
643 do_something(foo[i]);
644 }
645
646
647 Variable declarations
648 ^^^^^^^^^^^^^^^^^^^^^
649
650 The preferred ordering of variable declaration
651 function is reverse fir tree order::
652
653 struct long_struct_name *descriptive_n
654 unsigned long foo, bar;
655 unsigned int tmp;
656 int ret;
657
658 The above is faster to parse than the reverse
659
660 int ret;
661 unsigned int tmp;
662 unsigned long foo, bar;
663 struct long_struct_name *descriptive_n
664
665 And even more so than random ordering::
666
667 unsigned long foo, bar;
668 int ret;
669 struct long_struct_name *descriptive_n
670 unsigned int tmp;
671
672 Also please try to aggregate variables of the
673 line. There is no point in wasting screen spac
674
675 unsigned long a;
676 unsigned long b;
677 unsigned long c;
678 unsigned long d;
679
680 It's really sufficient to do::
681
682 unsigned long a, b, c, d;
683
684 Please also refrain from introducing line spli
685
686 struct long_struct_name *descriptive_n
687
688
689 struct foobar foo;
690
691 It's way better to move the initialization to
692 declarations::
693
694 struct long_struct_name *descriptive_n
695 struct foobar foo;
696
697 descriptive_name = container_of(bar, s
698
699
700 Variable types
701 ^^^^^^^^^^^^^^
702
703 Please use the proper u8, u16, u32, u64 types
704 to describe hardware or are used as arguments
705 hardware. These types are clearly defining the
706 truncation, expansion and 32/64-bit confusion.
707
708 u64 is also recommended in code which would be
709 kernels when 'unsigned long' would be used ins
710 situations 'unsigned long long' could be used
711 and also clearly shows that the operation is r
712 independent of the target CPU.
713
714 Please use 'unsigned int' instead of 'unsigned
715
716
717 Constants
718 ^^^^^^^^^
719
720 Please do not use literal (hexa)decimal number
721 Either use proper defines which have descripti
722 an enum.
723
724
725 Struct declarations and initializers
726 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
727
728 Struct declarations should align the struct me
729 fashion::
730
731 struct bar_order {
732 unsigned int guest_id;
733 int ordered_item;
734 struct menu *menu;
735 };
736
737 Please avoid documenting struct members within
738 this often results in strangely formatted comm
739 become obfuscated::
740
741 struct bar_order {
742 unsigned int guest_id; /* U
743 int ordered_item;
744 /* Pointer to a menu instance
745 struct menu *menu;
746 };
747
748 Instead, please consider using the kernel-doc
749 the struct declaration, which is easier to rea
750 of including the information in the kernel doc
751 follows::
752
753
754 /**
755 * struct bar_order - Description of a
756 * @guest_id: Unique guest i
757 * @ordered_item: The item numbe
758 * @menu: Pointer to the
759 * was ordered
760 *
761 * Supplementary information for using
762 *
763 * Note, that the struct member descri
764 * in a tabular fashion.
765 */
766 struct bar_order {
767 unsigned int guest_id;
768 int ordered_item;
769 struct menu *menu;
770 };
771
772 Static struct initializers must use C99 initia
773 aligned in a tabular fashion::
774
775 static struct foo statfoo = {
776 .a = 0,
777 .plain_integer = CONSTANT_DEF
778 .bar = &statbar,
779 };
780
781 Note that while C99 syntax allows the omission
782 we recommend the use of a comma on the last li
783 reordering and addition of new lines easier, a
784 patches slightly easier to read as well.
785
786 Line breaks
787 ^^^^^^^^^^^
788
789 Restricting line length to 80 characters makes
790 read. Consider breaking out code into helper
791 line breaking.
792
793 The 80 character rule is not a strict rule, so
794 breaking lines. Especially format strings shou
795
796 When splitting function declarations or functi
797 the first argument in the second line with the
798 line::
799
800 static int long_function_name(struct foobar
801 unsigned int o
802 {
803
804 if (!id) {
805 ret = longer_function_name(bar
806 off
807 ...
808
809 Namespaces
810 ^^^^^^^^^^
811
812 Function/variable namespaces improve readabili
813 grepping. These namespaces are string prefixes
814 function and variable names, including inlines
815 combine the subsystem and the component name s
816 'sched\_', 'irq\_', and 'mutex\_'.
817
818 This also includes static file scope functions
819 into globally visible driver templates - it's
820 to carry a good prefix as well, for backtrace
821
822 Namespace prefixes may be omitted for local st
823 variables. Truly local functions, only called
824 can have shorter descriptive names - our prima
825 and backtrace readability.
826
827 Please note that 'xxx_vendor\_' and 'vendor_xx
828 helpful for static functions in vendor-specifi
829 is already clear that the code is vendor-speci
830 names should only be for truly vendor-specific
831
832 As always apply common sense and aim for consi
833
834
835 Commit notifications
836 --------------------
837
838 The tip tree is monitored by a bot for new com
839 for each new commit to a dedicated mailing lis
840 (``linux-tip-commits@vger.kernel.org``) and Cc
841 mentioned in one of the commit tags. It uses t
842 Link tag at the end of the tag list to set the
843 the message is properly threaded with the patc
844
845 The tip maintainers and submaintainers try to
846 when merging a patch, but they sometimes forge
847 workflow of the moment. While the bot message
848 also implies a 'Thank you! Applied.'.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.