848 lines · 27.1 KB · Text
RawDownload
.. SPDX-License-Identifier: GPL-2.0 The tip tree handbook===================== What is the tip tree?--------------------- The tip tree is a collection of several subsystems and areas ofdevelopment. The tip tree is both a direct development tree and anaggregation tree for several sub-maintainer trees. The tip tree gitweb URLis: https://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git The tip tree contains the following subsystems:    - **x86 architecture**      The x86 architecture development takes place in the tip tree except     for the x86 KVM and XEN specific parts which are maintained in the     corresponding subsystems and routed directly to mainline from     there. It's still good practice to Cc the x86 maintainers on     x86-specific KVM and XEN patches.      Some x86 subsystems have their own maintainers in addition to the     overall x86 maintainers.  Please Cc the overall x86 maintainers on     patches touching files in arch/x86 even when they are not called out     by the MAINTAINER file.      Note, that ``x86@kernel.org`` is not a mailing list. It is merely a     mail alias which distributes mails to the x86 top-level maintainer     team. Please always Cc the Linux Kernel mailing list (LKML)     ``linux-kernel@vger.kernel.org``, otherwise your mail ends up only in     the private inboxes of the maintainers.    - **Scheduler**      Scheduler development takes place in the -tip tree, in the     sched/core branch - with occasional sub-topic trees for     work-in-progress patch-sets.    - **Locking and atomics**      Locking development (including atomics and other synchronization     primitives that are connected to locking) takes place in the -tip     tree, in the locking/core branch - with occasional sub-topic trees     for work-in-progress patch-sets.    - **Generic interrupt subsystem and interrupt chip drivers**:      - interrupt core development happens in the irq/core branch      - interrupt chip driver development also happens in the irq/core       branch, but the patches are usually applied in a separate maintainer       tree and then aggregated into irq/core    - **Time, timers, timekeeping, NOHZ and related chip drivers**:      - timekeeping, clocksource core, NTP and alarmtimer development       happens in the timers/core branch, but patches are usually applied in       a separate maintainer tree and then aggregated into timers/core      - clocksource/event driver development happens in the timers/core       branch, but patches are mostly applied in a separate maintainer tree       and then aggregated into timers/core    - **Performance counters core, architecture support and tooling**:      - perf core and architecture support development happens in the       perf/core branch      - perf tooling development happens in the perf tools maintainer       tree and is aggregated into the tip tree.    - **CPU hotplug core**    - **RAS core**      Mostly x86-specific RAS patches are collected in the tip ras/core     branch.    - **EFI core**      EFI development in the efi git tree. The collected patches are     aggregated in the tip efi/core branch.    - **RCU**      RCU development happens in the linux-rcu tree. The resulting changes     are aggregated into the tip core/rcu branch.    - **Various core code components**:        - debugobjects        - objtool        - random bits and pieces  Patch submission notes---------------------- Selecting the tree/branch^^^^^^^^^^^^^^^^^^^^^^^^^ In general, development against the head of the tip tree master branch isfine, but for the subsystems which are maintained separately, have theirown git tree and are only aggregated into the tip tree, development shouldtake place against the relevant subsystem tree or branch. Bug fixes which target mainline should always be applicable against themainline kernel tree. Potential conflicts against changes which are alreadyqueued in the tip tree are handled by the maintainers. Patch subject^^^^^^^^^^^^^ The tip tree preferred format for patch subject prefixes is'subsys/component:', e.g. 'x86/apic:', 'x86/mm/fault:', 'sched/fair:','genirq/core:'. Please do not use file names or complete file paths asprefix. 'git log path/to/file' should give you a reasonable hint in mostcases. The condensed patch description in the subject line should start with anuppercase letter and should be written in imperative tone.  Changelog^^^^^^^^^ The general rules about changelogs in the :ref:`Submitting patches guide<describe_changes>`, apply. The tip tree maintainers set value on following these rules, especially onthe request to write changelogs in imperative mood and not impersonatingcode or the execution of it. This is not just a whim of themaintainers. Changelogs written in abstract words are more precise andtend to be less confusing than those written in the form of novels. It's also useful to structure the changelog into several paragraphs and notlump everything together into a single one. A good structure is to explainthe context, the problem and the solution in separate paragraphs and thisorder. Examples for illustration:   Example 1::     x86/intel_rdt/mbm: Fix MBM overflow handler during hot cpu     When a CPU is dying, we cancel the worker and schedule a new worker on a    different CPU on the same domain. But if the timer is already about to    expire (say 0.99s) then we essentially double the interval.     We modify the hot cpu handling to cancel the delayed work on the dying    cpu and run the worker immediately on a different cpu in same domain. We    do not flush the worker because the MBM overflow worker reschedules the    worker on same CPU and scans the domain->cpu_mask to get the domain    pointer.   Improved version::     x86/intel_rdt/mbm: Fix MBM overflow handler during CPU hotplug     When a CPU is dying, the overflow worker is canceled and rescheduled on a    different CPU in the same domain. But if the timer is already about to    expire this essentially doubles the interval which might result in a non    detected overflow.     Cancel the overflow worker and reschedule it immediately on a different CPU    in the same domain. The work could be flushed as well, but that would    reschedule it on the same CPU.   Example 2::     time: POSIX CPU timers: Ensure that variable is initialized     If cpu_timer_sample_group returns -EINVAL, it will not have written into    *sample. Checking for cpu_timer_sample_group's return value precludes the    potential use of an uninitialized value of now in the following block.    Given an invalid clock_idx, the previous code could otherwise overwrite    *oldval in an undefined manner. This is now prevented. We also exploit    short-circuiting of && to sample the timer only if the result will    actually be used to update *oldval.   Improved version::     posix-cpu-timers: Make set_process_cpu_timer() more robust     Because the return value of cpu_timer_sample_group() is not checked,    compilers and static checkers can legitimately warn about a potential use    of the uninitialized variable 'now'. This is not a runtime issue as all    call sites hand in valid clock ids.     Also cpu_timer_sample_group() is invoked unconditionally even when the    result is not used because *oldval is NULL.     Make the invocation conditional and check the return value.   Example 3::     The entity can also be used for other purposes.     Let's rename it to be more generic.   Improved version::     The entity can also be used for other purposes.     Rename it to be more generic.  For complex scenarios, especially race conditions and memory orderingissues, it is valuable to depict the scenario with a table which showsthe parallelism and the temporal order of events. Here is an example::     CPU0                            CPU1    free_irq(X)                     interrupt X                                    spin_lock(desc->lock)                                    wake irq thread()                                    spin_unlock(desc->lock)    spin_lock(desc->lock)    remove action()    shutdown_irq()    release_resources()             thread_handler()    spin_unlock(desc->lock)           access released resources.                                      ^^^^^^^^^^^^^^^^^^^^^^^^^    synchronize_irq() Lockdep provides similar useful output to depict a possible deadlockscenario::     CPU0                                    CPU1    rtmutex_lock(&rcu->rt_mutex)      spin_lock(&rcu->rt_mutex.wait_lock)                                            local_irq_disable()                                            spin_lock(&timer->it_lock)                                            spin_lock(&rcu->mutex.wait_lock)    --> Interrupt        spin_lock(&timer->it_lock)  Function references in changelogs^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When a function is mentioned in the changelog, either the text body or thesubject line, please use the format 'function_name()'. Omitting thebrackets after the function name can be ambiguous::   Subject: subsys/component: Make reservation_count static   reservation_count is only used in reservation_stats. Make it static. The variant with brackets is more precise::   Subject: subsys/component: Make reservation_count() static   reservation_count() is only called from reservation_stats(). Make it  static.  Backtraces in changelogs^^^^^^^^^^^^^^^^^^^^^^^^ See :ref:`backtraces`. Ordering of commit tags^^^^^^^^^^^^^^^^^^^^^^^ To have a uniform view of the commit tags, the tip maintainers use thefollowing tag ordering scheme:  - Fixes: 12+char-SHA1 ("sub/sys: Original subject line")    A Fixes tag should be added even for changes which do not need to be   backported to stable kernels, i.e. when addressing a recently introduced   issue which only affects tip or the current head of mainline. These tags   are helpful to identify the original commit and are much more valuable   than prominently mentioning the commit which introduced a problem in the   text of the changelog itself because they can be automatically   extracted.    The following example illustrates the difference::      Commit        abcdef012345678 ("x86/xxx: Replace foo with bar")      left an unused instance of variable foo around. Remove it.      Signed-off-by: J.Dev <j.dev@mail>    Please say instead::      The recent replacement of foo with bar left an unused instance of     variable foo around. Remove it.      Fixes: abcdef012345678 ("x86/xxx: Replace foo with bar")     Signed-off-by: J.Dev <j.dev@mail>    The latter puts the information about the patch into the focus and   amends it with the reference to the commit which introduced the issue   rather than putting the focus on the original commit in the first place.  - Reported-by: ``Reporter <reporter@mail>``  - Closes: ``URL or Message-ID of the bug report this is fixing``  - Originally-by: ``Original author <original-author@mail>``  - Suggested-by: ``Suggester <suggester@mail>``  - Co-developed-by: ``Co-author <co-author@mail>``    Signed-off-by: ``Co-author <co-author@mail>``    Note, that Co-developed-by and Signed-off-by of the co-author(s) must   come in pairs.  - Signed-off-by: ``Author <author@mail>``    The first Signed-off-by (SOB) after the last Co-developed-by/SOB pair is the   author SOB, i.e. the person flagged as author by git.  - Signed-off-by: ``Patch handler <handler@mail>``    SOBs after the author SOB are from people handling and transporting   the patch, but were not involved in development. SOB chains should   reflect the **real** route a patch took as it was propagated to us,   with the first SOB entry signalling primary authorship of a single   author. Acks should be given as Acked-by lines and review approvals   as Reviewed-by lines.    If the handler made modifications to the patch or the changelog, then   this should be mentioned **after** the changelog text and **above**   all commit tags in the following format::      ... changelog text ends.      [ handler: Replaced foo by bar and updated changelog ]      First-tag: .....    Note the two empty new lines which separate the changelog text and the   commit tags from that notice.    If a patch is sent to the mailing list by a handler then the author has   to be noted in the first line of the changelog with::      From: Author <author@mail>      Changelog text starts here....    so the authorship is preserved. The 'From:' line has to be followed   by an empty newline. If that 'From:' line is missing, then the patch   would be attributed to the person who sent (transported, handled) it.   The 'From:' line is automatically removed when the patch is applied   and does not show up in the final git changelog. It merely affects   the authorship information of the resulting Git commit.  - Tested-by: ``Tester <tester@mail>``  - Reviewed-by: ``Reviewer <reviewer@mail>``  - Acked-by: ``Acker <acker@mail>``  - Cc: ``cc-ed-person <person@mail>``    If the patch should be backported to stable, then please add a '``Cc:   stable@vger.kernel.org``' tag, but do not Cc stable when sending your   mail.  - Link: ``https://link/to/information``    For referring to an email posted to the kernel mailing lists, please   use the lore.kernel.org redirector URL::      Link: https://lore.kernel.org/email-message-id@here    This URL should be used when referring to relevant mailing list   topics, related patch sets, or other notable discussion threads.   A convenient way to associate ``Link:`` trailers with the commit   message is to use markdown-like bracketed notation, for example::      A similar approach was attempted before as part of a different     effort [1], but the initial implementation caused too many     regressions [2], so it was backed out and reimplemented.      Link: https://lore.kernel.org/some-msgid@here # [1]     Link: https://bugzilla.example.org/bug/12345  # [2]    You can also use ``Link:`` trailers to indicate the origin of the   patch when applying it to your git tree. In that case, please use the   dedicated ``patch.msgid.link`` domain instead of ``lore.kernel.org``.   This practice makes it possible for automated tooling to identify   which link to use to retrieve the original patch submission. For   example::      Link: https://patch.msgid.link/patch-source-message-id@here Please do not use combined tags, e.g. ``Reported-and-tested-by``, asthey just complicate automated extraction of tags.  Links to documentation^^^^^^^^^^^^^^^^^^^^^^ Providing links to documentation in the changelog is a great help to laterdebugging and analysis.  Unfortunately, URLs often break very quicklybecause companies restructure their websites frequently.  Non-'volatile'exceptions include the Intel SDM and the AMD APM. Therefore, for 'volatile' documents, please create an entry in the kernelbugzilla https://bugzilla.kernel.org and attach a copy of these documentsto the bugzilla entry. Finally, provide the URL of the bugzilla entry inthe changelog. Patch resend or reminders^^^^^^^^^^^^^^^^^^^^^^^^^ See :ref:`resend_reminders`. Merge window^^^^^^^^^^^^ Please do not expect patches to be reviewed or merged by tipmaintainers around or during the merge window.  The trees are closedto all but urgent fixes during this time.  They reopen once the mergewindow closes and a new -rc1 kernel has been released. Large series should be submitted in mergeable state *at* *least* a weekbefore the merge window opens.  Exceptions are made for bug fixes and*sometimes* for small standalone drivers for new hardware or minimallyinvasive patches for hardware enablement. During the merge window, the maintainers instead focus on following theupstream changes, fixing merge window fallout, collecting bug fixes, andallowing themselves a breath. Please respect that. So called _urgent_ branches will be merged into mainline during thestabilization phase of each release.  Git^^^ The tip maintainers accept git pull requests from maintainers who providesubsystem changes for aggregation in the tip tree. Pull requests for new patch submissions are usually not accepted and do notreplace proper patch submission to the mailing list. The main reason forthis is that the review workflow is email based. If you submit a larger patch series it is helpful to provide a git branchin a private repository which allows interested people to easily pull theseries for testing. The usual way to offer this is a git URL in the coverletter of the patch series. Testing^^^^^^^ Code should be tested before submitting to the tip maintainers.  Anythingother than minor changes should be built, booted and tested withcomprehensive (and heavyweight) kernel debugging options enabled. These debugging options can be found in kernel/configs/x86_debug.configand can be added to an existing kernel config by running: 	make x86_debug.config Some of these options are x86-specific and can be left out when testingon other architectures. .. _maintainer-tip-coding-style: Coding style notes------------------ Comment style^^^^^^^^^^^^^ Sentences in comments start with an uppercase letter. Single line comments:: 	/* This is a single line comment */ Multi-line comments:: 	/*	 * This is a properly formatted	 * multi-line comment.	 *	 * Larger multi-line comments should be split into paragraphs.	 */ No tail comments (see below):   Please refrain from using tail comments. Tail comments disturb the  reading flow in almost all contexts, but especially in code::

Lines 1–500 of 848.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t