€•       Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ*/translations/zh_CN/process/maintainer-tip”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/zh_TW/process/maintainer-tip”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/it_IT/process/maintainer-tip”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/ja_JP/process/maintainer-tip”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/ko_KR/process/maintainer-tip”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/sp_SP/process/maintainer-tip”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒD/var/lib/git/docbuild/linux/Documentation/process/maintainer-tip.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒThe tip tree handbook”h]”hŒThe tip tree handbook”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒWhat is the tip tree?”h]”hŒWhat is the tip tree?”…””}”(hhÌhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhÉhžhhŸh³h KubhŒ	paragraph”“”)”}”(hX  The tip tree is a collection of several subsystems and areas of
development. The tip tree is both a direct development tree and an
aggregation tree for several sub-maintainer trees. The tip tree gitweb URL
is: https://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git”h]”(hŒÒThe tip tree is a collection of several subsystems and areas of
development. The tip tree is both a direct development tree and an
aggregation tree for several sub-maintainer trees. The tip tree gitweb URL
is: ”…””}”(hhÜhžhhŸNh NubhŒ	reference”“”)”}”(hŒ;https://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git”h]”hŒ;https://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git”…””}”(hhæhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”hèuh1hähhÜubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K	hhÉhžhubhÛ)”}”(hŒ/The tip tree contains the following subsystems:”h]”hŒ/The tip tree contains the following subsystems:”…””}”(hhûhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KhhÉhžhubhŒblock_quote”“”)”}”(hX  - **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

”h]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hXO  **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.
”h]”(hÛ)”}”(hŒ**x86 architecture**”h]”hŒstrong”“”)”}”(hj  h]”hŒx86 architecture”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khj  ubhÛ)”}”(hX#  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.”h]”hX%  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.”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khj  ubhÛ)”}”(hŒá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.”h]”hŒá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.”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khj  ubhÛ)”}”(hX0  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.”h]”(hŒNote, that ”…””}”(hjO  hžhhŸNh NubhŒliteral”“”)”}”(hŒ``x86@kernel.org``”h]”hŒx86@kernel.org”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjO  ubhŒ¦ 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)
”…””}”(hjO  hžhhŸNh NubjX  )”}”(hŒ ``linux-kernel@vger.kernel.org``”h]”hŒlinux-kernel@vger.kernel.org”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjO  ubhŒM, otherwise your mail ends up only in
the private inboxes of the maintainers.”…””}”(hjO  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hŒŸ**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.
”h]”(hÛ)”}”(hŒ**Scheduler**”h]”j  )”}”(hj  h]”hŒ	Scheduler”…””}”(hj‘  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K#hj‰  ubhÛ)”}”(hŒScheduler development takes place in the -tip tree, in the
sched/core branch - with occasional sub-topic trees for
work-in-progress patch-sets.”h]”hŒScheduler development takes place in the -tip tree, in the
sched/core branch - with occasional sub-topic trees for
work-in-progress patch-sets.”…””}”(hj¤  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K%hj‰  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hX   **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.
”h]”(hÛ)”}”(hŒ**Locking and atomics**”h]”j  )”}”(hj¾  h]”hŒLocking and atomics”…””}”(hjÀ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¼  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K)hj¸  ubhÛ)”}”(hŒæ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.”h]”hŒæ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.”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K+hj¸  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hX+  **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
”h]”(hÛ)”}”(hŒ;**Generic interrupt subsystem and interrupt chip drivers**:”h]”(j  )”}”(hŒ:**Generic interrupt subsystem and interrupt chip drivers**”h]”hŒ6Generic interrupt subsystem and interrupt chip drivers”…””}”(hjï  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjë  ubhŒ:”…””}”(hjë  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K0hjç  ubj  )”}”(hhh]”(j  )”}”(hŒ:interrupt core development happens in the irq/core branch
”h]”hÛ)”}”(hŒ9interrupt core development happens in the irq/core branch”h]”hŒ9interrupt core development happens in the irq/core branch”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K2hj
  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hŒ«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
”h]”hÛ)”}”(hŒª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”h]”hŒª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”…””}”(hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K4hj"  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j  hŸh³h K2hjç  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hXº  **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
”h]”(hÛ)”}”(hŒ=**Time, timers, timekeeping, NOHZ and related chip drivers**:”h]”(j  )”}”(hŒ<**Time, timers, timekeeping, NOHZ and related chip drivers**”h]”hŒ8Time, timers, timekeeping, NOHZ and related chip drivers”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjL  ubhŒ:”…””}”(hjL  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K8hjH  ubj  )”}”(hhh]”(j  )”}”(hŒÄ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
”h]”hÛ)”}”(hŒÃ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”h]”hŒÃ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”…””}”(hjo  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K:hjk  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjh  ubj  )”}”(hŒª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
”h]”hÛ)”}”(hŒ©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”h]”hŒ©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”…””}”(hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K>hjƒ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjh  ubeh}”(h]”h ]”h"]”h$]”h&]”j@  jA  uh1j  hŸh³h K:hjH  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hX  **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.
”h]”(hÛ)”}”(hŒ@**Performance counters core, architecture support and tooling**:”h]”(j  )”}”(hŒ?**Performance counters core, architecture support and tooling**”h]”hŒ;Performance counters core, architecture support and tooling”…””}”(hj¯  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj«  ubhŒ:”…””}”(hj«  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KBhj§  ubj  )”}”(hhh]”(j  )”}”(hŒOperf core and architecture support development happens in the
perf/core branch
”h]”hÛ)”}”(hŒNperf core and architecture support development happens in the
perf/core branch”h]”hŒNperf core and architecture support development happens in the
perf/core branch”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KDhjÊ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjÇ  ubj  )”}”(hŒhperf tooling development happens in the perf tools maintainer
tree and is aggregated into the tip tree.
”h]”hÛ)”}”(hŒgperf tooling development happens in the perf tools maintainer
tree and is aggregated into the tip tree.”h]”hŒgperf tooling development happens in the perf tools maintainer
tree and is aggregated into the tip tree.”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KGhjâ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjÇ  ubeh}”(h]”h ]”h"]”h$]”h&]”j@  jA  uh1j  hŸh³h KDhj§  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hŒ**CPU hotplug core**
”h]”hÛ)”}”(hŒ**CPU hotplug core**”h]”j  )”}”(hj  h]”hŒCPU hotplug core”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj
  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KJhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hŒX**RAS core**

Mostly x86-specific RAS patches are collected in the tip ras/core
branch.
”h]”(hÛ)”}”(hŒ**RAS core**”h]”j  )”}”(hj-  h]”hŒRAS core”…””}”(hj/  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj+  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KLhj'  ubhÛ)”}”(hŒIMostly x86-specific RAS patches are collected in the tip ras/core
branch.”h]”hŒIMostly x86-specific RAS patches are collected in the tip ras/core
branch.”…””}”(hjB  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KNhj'  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hŒt**EFI core**

EFI development in the efi git tree. The collected patches are
aggregated in the tip efi/core branch.
”h]”(hÛ)”}”(hŒ**EFI core**”h]”j  )”}”(hj\  h]”hŒEFI core”…””}”(hj^  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjZ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KQhjV  ubhÛ)”}”(hŒeEFI development in the efi git tree. The collected patches are
aggregated in the tip efi/core branch.”h]”hŒeEFI development in the efi git tree. The collected patches are
aggregated in the tip efi/core branch.”…””}”(hjq  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KShjV  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hŒ{**RCU**

RCU development happens in the linux-rcu tree. The resulting changes
are aggregated into the tip core/rcu branch.
”h]”(hÛ)”}”(hŒ**RCU**”h]”j  )”}”(hj‹  h]”hŒRCU”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj‰  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KVhj…  ubhÛ)”}”(hŒqRCU development happens in the linux-rcu tree. The resulting changes
are aggregated into the tip core/rcu branch.”h]”hŒqRCU development happens in the linux-rcu tree. The resulting changes
are aggregated into the tip core/rcu branch.”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KXhj…  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubj  )”}”(hŒ^**Various core code components**:

  - debugobjects

  - objtool

  - random bits and pieces

”h]”(hÛ)”}”(hŒ!**Various core code components**:”h]”(j  )”}”(hŒ **Various core code components**”h]”hŒVarious core code components”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¸  ubhŒ:”…””}”(hj¸  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K[hj´  ubj
  )”}”(hŒ5- debugobjects

- objtool

- random bits and pieces

”h]”j  )”}”(hhh]”(j  )”}”(hŒdebugobjects
”h]”hÛ)”}”(hŒdebugobjects”h]”hŒdebugobjects”…””}”(hjß  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K]hjÛ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjØ  ubj  )”}”(hŒobjtool
”h]”hÛ)”}”(hŒobjtool”h]”hŒobjtool”…””}”(hj÷  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K_hjó  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjØ  ubj  )”}”(hŒrandom bits and pieces

”h]”hÛ)”}”(hŒrandom bits and pieces”h]”hŒrandom bits and pieces”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kahj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjØ  ubeh}”(h]”h ]”h"]”h$]”h&]”j@  jA  uh1j  hŸh³h K]hjÔ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j	  hŸh³h K]hj´  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”j@  jA  uh1j  hŸh³h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j	  hŸh³h KhhÉhžhubeh}”(h]”Œwhat-is-the-tip-tree”ah ]”h"]”Œwhat is the tip tree?”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒPatch submission notes”h]”hŒPatch submission notes”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjI  hžhhŸh³h Keubhµ)”}”(hhh]”(hº)”}”(hŒSelecting the tree/branch”h]”hŒSelecting the tree/branch”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjZ  hžhhŸh³h KhubhÛ)”}”(hX  In general, development against the head of the tip tree master branch is
fine, but for the subsystems which are maintained separately, have their
own git tree and are only aggregated into the tip tree, development should
take place against the relevant subsystem tree or branch.”h]”hX  In general, development against the head of the tip tree master branch is
fine, but for the subsystems which are maintained separately, have their
own git tree and are only aggregated into the tip tree, development should
take place against the relevant subsystem tree or branch.”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KjhjZ  hžhubhÛ)”}”(hŒÊBug fixes which target mainline should always be applicable against the
mainline kernel tree. Potential conflicts against changes which are already
queued in the tip tree are handled by the maintainers.”h]”hŒÊBug fixes which target mainline should always be applicable against the
mainline kernel tree. Potential conflicts against changes which are already
queued in the tip tree are handled by the maintainers.”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KohjZ  hžhubeh}”(h]”Œselecting-the-tree-branch”ah ]”h"]”Œselecting the tree/branch”ah$]”h&]”uh1h´hjI  hžhhŸh³h Khubhµ)”}”(hhh]”(hº)”}”(hŒPatch subject”h]”hŒPatch subject”…””}”(hj’  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h KtubhÛ)”}”(hX  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 as
prefix. 'git log path/to/file' should give you a reasonable hint in most
cases.”h]”hX1  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 as
prefix. â€˜git log path/to/fileâ€™ should give you a reasonable hint in most
cases.”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kvhj  hžhubhÛ)”}”(hŒƒThe condensed patch description in the subject line should start with an
uppercase letter and should be written in imperative tone.”h]”hŒƒThe condensed patch description in the subject line should start with an
uppercase letter and should be written in imperative tone.”…””}”(hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K|hj  hžhubeh}”(h]”Œpatch-subject”ah ]”h"]”Œpatch subject”ah$]”h&]”uh1h´hjI  hžhhŸh³h Ktubhµ)”}”(hhh]”(hº)”}”(hŒ	Changelog”h]”hŒ	Changelog”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÄ  hžhhŸh³h KubhÛ)”}”(hŒdThe general rules about changelogs in the :ref:`Submitting patches guide
<describe_changes>`, apply.”h]”(hŒ*The general rules about changelogs in the ”…””}”(hjÕ  hžhhŸNh Nubh)”}”(hŒ2:ref:`Submitting patches guide
<describe_changes>`”h]”hŒinline”“”)”}”(hjß  h]”hŒSubmitting patches guide”…””}”(hjã  hžhhŸNh Nubah}”(h]”h ]”(Œxref”Œstd”Œstd-ref”eh"]”h$]”h&]”uh1já  hjÝ  ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”Œprocess/maintainer-tip”Œ	refdomain”jî  Œreftype”Œref”Œrefexplicit”ˆŒrefwarn”ˆŒ	reftarget”Œdescribe_changes”uh1hhŸh³h KƒhjÕ  ubhŒ, apply.”…””}”(hjÕ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KƒhjÄ  hžhubhÛ)”}”(hXZ  The tip tree maintainers set value on following these rules, especially on
the request to write changelogs in imperative mood and not impersonating
code or the execution of it. This is not just a whim of the
maintainers. Changelogs written in abstract words are more precise and
tend to be less confusing than those written in the form of novels.”h]”hXZ  The tip tree maintainers set value on following these rules, especially on
the request to write changelogs in imperative mood and not impersonating
code or the execution of it. This is not just a whim of the
maintainers. Changelogs written in abstract words are more precise and
tend to be less confusing than those written in the form of novels.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K†hjÄ  hžhubhÛ)”}”(hŒçIt's also useful to structure the changelog into several paragraphs and not
lump everything together into a single one. A good structure is to explain
the context, the problem and the solution in separate paragraphs and this
order.”h]”hŒéItâ€™s also useful to structure the changelog into several paragraphs and not
lump everything together into a single one. A good structure is to explain
the context, the problem and the solution in separate paragraphs and this
order.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KŒhjÄ  hžhubhÛ)”}”(hŒExamples for illustration:”h]”hŒExamples for illustration:”…””}”(hj(  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K‘hjÄ  hžhubj
  )”}”(hXY	  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.

”h]”(hÛ)”}”(hŒExample 1::”h]”hŒ
Example 1:”…””}”(hj:  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K“hj6  ubhŒliteral_block”“”)”}”(hX-  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.”h]”hX-  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.”…””}”hjJ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h K•hj6  ubhÛ)”}”(hŒImproved version::”h]”hŒImproved version:”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K¡hj6  ubjI  )”}”(hXÞ  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.”h]”hXÞ  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.”…””}”hjf  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h K£hj6  ubhÛ)”}”(hŒExample 2::”h]”hŒ
Example 2:”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K®hj6  ubjI  )”}”(hX  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.”h]”hX  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.”…””}”hj‚  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h K°hj6  ubhÛ)”}”(hŒImproved version::”h]”hŒImproved version:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kºhj6  ubjI  )”}”(hXç  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.”h]”hXç  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.”…””}”hjž  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h K¼hj6  ubhÛ)”}”(hŒExample 3::”h]”hŒ
Example 3:”…””}”(hj¬  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÈhj6  ubjI  )”}”(hŒTThe entity can also be used for other purposes.

Let's rename it to be more generic.”h]”hŒTThe entity can also be used for other purposes.

Let's rename it to be more generic.”…””}”hjº  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h KÊhj6  ubhÛ)”}”(hŒImproved version::”h]”hŒImproved version:”…””}”(hjÈ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÎhj6  ubjI  )”}”(hŒNThe entity can also be used for other purposes.

Rename it to be more generic.”h]”hŒNThe entity can also be used for other purposes.

Rename it to be more generic.”…””}”hjÖ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h KÐhj6  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j	  hŸh³h K“hjÄ  hžhubhÛ)”}”(hŒÓFor complex scenarios, especially race conditions and memory ordering
issues, it is valuable to depict the scenario with a table which shows
the parallelism and the temporal order of events. Here is an example::”h]”hŒÒFor complex scenarios, especially race conditions and memory ordering
issues, it is valuable to depict the scenario with a table which shows
the parallelism and the temporal order of events. Here is an example:”…””}”(hjê  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÕhjÄ  hžhubjI  )”}”(hXá  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()”h]”hXá  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()”…””}”hjø  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h KÙhjÄ  hžhubhÛ)”}”(hŒOLockdep provides similar useful output to depict a possible deadlock
scenario::”h]”hŒNLockdep provides similar useful output to depict a possible deadlock
scenario:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KæhjÄ  hžhubjI  )”}”(hXd  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)”h]”hXd  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)”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h KéhjÄ  hžhubeh}”(h]”Œ	changelog”ah ]”h"]”Œ	changelog”ah$]”h&]”uh1h´hjI  hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ!Function references in changelogs”h]”hŒ!Function references in changelogs”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj*  hžhhŸh³h KôubhÛ)”}”(hŒÂWhen a function is mentioned in the changelog, either the text body or the
subject line, please use the format 'function_name()'. Omitting the
brackets after the function name can be ambiguous::”h]”hŒÅWhen a function is mentioned in the changelog, either the text body or the
subject line, please use the format â€˜function_name()â€™. Omitting the
brackets after the function name can be ambiguous:”…””}”(hj;  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Köhj*  hžhubjI  )”}”(hŒ~Subject: subsys/component: Make reservation_count static

reservation_count is only used in reservation_stats. Make it static.”h]”hŒ~Subject: subsys/component: Make reservation_count static

reservation_count is only used in reservation_stats. Make it static.”…””}”hjI  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Kúhj*  hžhubhÛ)”}”(hŒ+The variant with brackets is more precise::”h]”hŒ*The variant with brackets is more precise:”…””}”(hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kþhj*  hžhubjI  )”}”(hŒˆSubject: subsys/component: Make reservation_count() static

reservation_count() is only called from reservation_stats(). Make it
static.”h]”hŒˆSubject: subsys/component: Make reservation_count() static

reservation_count() is only called from reservation_stats(). Make it
static.”…””}”hje  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M hj*  hžhubeh}”(h]”Œ!function-references-in-changelogs”ah ]”h"]”Œ!function references in changelogs”ah$]”h&]”uh1h´hjI  hžhhŸh³h Kôubhµ)”}”(hhh]”(hº)”}”(hŒBacktraces in changelogs”h]”hŒBacktraces in changelogs”…””}”(hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj{  hžhhŸh³h MubhÛ)”}”(hŒSee :ref:`backtraces`.”h]”(hŒSee ”…””}”(hjŒ  hžhhŸNh Nubh)”}”(hŒ:ref:`backtraces`”h]”jâ  )”}”(hj–  h]”hŒ
backtraces”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”(jí  Œstd”Œstd-ref”eh"]”h$]”h&]”uh1já  hj”  ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”jú  Œ	refdomain”j¢  Œreftype”Œref”Œrefexplicit”‰Œrefwarn”ˆj   Œ
backtraces”uh1hhŸh³h M	hjŒ  ubhŒ.”…””}”(hjŒ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M	hj{  hžhubeh}”(h]”Œbacktraces-in-changelogs”ah ]”h"]”Œbacktraces in changelogs”ah$]”h&]”uh1h´hjI  hžhhŸh³h Mubhµ)”}”(hhh]”(hº)”}”(hŒOrdering of commit tags”h]”hŒOrdering of commit tags”…””}”(hjÉ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÆ  hžhhŸh³h MubhÛ)”}”(hŒeTo have a uniform view of the commit tags, the tip maintainers use the
following tag ordering scheme:”h]”hŒeTo have a uniform view of the commit tags, the tip maintainers use the
following tag ordering scheme:”…””}”(hj×  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MhjÆ  hžhubj
  )”}”(hXy  - 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 a 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
”h]”j  )”}”(hhh]”(j  )”}”(hXq  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.
”h]”(hÛ)”}”(hŒ6Fixes: 12+char-SHA1 ("sub/sys: Original subject line")”h]”hŒ:Fixes: 12+char-SHA1 (â€œsub/sys: Original subject lineâ€)”…””}”(hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjì  ubhÛ)”}”(hX°  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.”h]”hX°  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.”…””}”(hjþ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjì  ubhÛ)”}”(hŒ2The following example illustrates the difference::”h]”hŒ1The following example illustrates the difference:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjì  ubjI  )”}”(hŒš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>”h]”hŒš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>”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Mhjì  ubhÛ)”}”(hŒPlease say instead::”h]”hŒPlease say instead:”…””}”(hj(  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M%hjì  ubjI  )”}”(hŒ½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>”h]”hŒ½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>”…””}”hj6  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M'hjì  ubhÛ)”}”(hŒÑ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.”h]”hŒÑ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.”…””}”(hjD  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M-hjì  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒ*Reported-by: ``Reporter <reporter@mail>``
”h]”hÛ)”}”(hŒ)Reported-by: ``Reporter <reporter@mail>``”h]”(hŒReported-by: ”…””}”(hj\  hžhhŸNh NubjX  )”}”(hŒ``Reporter <reporter@mail>``”h]”hŒReporter <reporter@mail>”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj\  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M1hjX  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒ?Closes: ``URL or Message-ID of the bug report this is fixing``
”h]”hÛ)”}”(hŒ>Closes: ``URL or Message-ID of the bug report this is fixing``”h]”(hŒCloses: ”…””}”(hj‚  hžhhŸNh NubjX  )”}”(hŒ6``URL or Message-ID of the bug report this is fixing``”h]”hŒ2URL or Message-ID of the bug report this is fixing”…””}”(hjŠ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj‚  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M3hj~  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒ:Originally-by: ``Original author <original-author@mail>``
”h]”hÛ)”}”(hŒ9Originally-by: ``Original author <original-author@mail>``”h]”(hŒOriginally-by: ”…””}”(hj¨  hžhhŸNh NubjX  )”}”(hŒ*``Original author <original-author@mail>``”h]”hŒ&Original author <original-author@mail>”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj¨  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M5hj¤  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒ-Suggested-by: ``Suggester <suggester@mail>``
”h]”hÛ)”}”(hŒ,Suggested-by: ``Suggester <suggester@mail>``”h]”(hŒSuggested-by: ”…””}”(hjÎ  hžhhŸNh NubjX  )”}”(hŒ``Suggester <suggester@mail>``”h]”hŒSuggester <suggester@mail>”…””}”(hjÖ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjÎ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M7hjÊ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒµ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.
”h]”(hÛ)”}”(hŒ/Co-developed-by: ``Co-author <co-author@mail>``”h]”(hŒCo-developed-by: ”…””}”(hjô  hžhhŸNh NubjX  )”}”(hŒ``Co-author <co-author@mail>``”h]”hŒCo-author <co-author@mail>”…””}”(hjü  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjô  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M9hjð  ubhÛ)”}”(hŒ-Signed-off-by: ``Co-author <co-author@mail>``”h]”(hŒSigned-off-by: ”…””}”(hj  hžhhŸNh NubjX  )”}”(hŒ``Co-author <co-author@mail>``”h]”hŒCo-author <co-author@mail>”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M;hjð  ubhÛ)”}”(hŒTNote, that Co-developed-by and Signed-off-by of the co-author(s) must
come in pairs.”h]”hŒTNote, that Co-developed-by and Signed-off-by of the co-author(s) must
come in pairs.”…””}”(hj,  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M=hjð  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒ¬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.
”h]”(hÛ)”}”(hŒ'Signed-off-by: ``Author <author@mail>``”h]”(hŒSigned-off-by: ”…””}”(hjD  hžhhŸNh NubjX  )”}”(hŒ``Author <author@mail>``”h]”hŒAuthor <author@mail>”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjD  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M@hj@  ubhÛ)”}”(hŒ‚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.”h]”hŒ‚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.”…””}”(hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MBhj@  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hXk  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 a 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.
”h]”(hÛ)”}”(hŒ/Signed-off-by: ``Patch handler <handler@mail>``”h]”(hŒSigned-off-by: ”…””}”(hjx  hžhhŸNh NubjX  )”}”(hŒ ``Patch handler <handler@mail>``”h]”hŒPatch handler <handler@mail>”…””}”(hj€  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjx  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MEhjt  ubhÛ)”}”(hXg  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.”h]”(hŒ“SOBs after the author SOB are from people handling and transporting
the patch, but were not involved in development. SOB chains should
reflect the ”…””}”(hj”  hžhhŸNh Nubj  )”}”(hŒ**real**”h]”hŒreal”…””}”(hjœ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj”  ubhŒÌ 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.”…””}”(hj”  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MGhjt  ubhÛ)”}”(hŒ³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::”h]”(hŒ_If the handler made modifications to the patch or the changelog, then
this should be mentioned ”…””}”(hj´  hžhhŸNh Nubj  )”}”(hŒ	**after**”h]”hŒafter”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj´  ubhŒ the changelog text and ”…””}”(hj´  hžhhŸNh Nubj  )”}”(hŒ	**above**”h]”hŒabove”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj´  ubhŒ)
all commit tags in the following format:”…””}”(hj´  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MNhjt  ubjI  )”}”(hŒb... changelog text ends.

[ handler: Replaced foo by bar and updated changelog ]

First-tag: .....”h]”hŒb... changelog text ends.

[ handler: Replaced foo by bar and updated changelog ]

First-tag: .....”…””}”hjæ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h MRhjt  ubhÛ)”}”(hŒdNote the two empty new lines which separate the changelog text and the
commit tags from that notice.”h]”hŒdNote the two empty new lines which separate the changelog text and the
commit tags from that notice.”…””}”(hjô  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MXhjt  ubhÛ)”}”(hŒ}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::”h]”hŒ|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:”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M[hjt  ubjI  )”}”(hŒ:From: Author <author@mail>

Changelog text starts here....”h]”hŒ:From: Author <author@mail>

Changelog text starts here....”…””}”hj	  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M^hjt  ubhÛ)”}”(hXŒ  so the authorship is preserved. The 'From:' line has to be followed
by a 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.”h]”hX˜  so the authorship is preserved. The â€˜From:â€™ line has to be followed
by a 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.”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mbhjt  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒ$Tested-by: ``Tester <tester@mail>``
”h]”hÛ)”}”(hŒ#Tested-by: ``Tester <tester@mail>``”h]”(hŒTested-by: ”…””}”(hj6	  hžhhŸNh NubjX  )”}”(hŒ``Tester <tester@mail>``”h]”hŒTester <tester@mail>”…””}”(hj>	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj6	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mihj2	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒ*Reviewed-by: ``Reviewer <reviewer@mail>``
”h]”hÛ)”}”(hŒ)Reviewed-by: ``Reviewer <reviewer@mail>``”h]”(hŒReviewed-by: ”…””}”(hj\	  hžhhŸNh NubjX  )”}”(hŒ``Reviewer <reviewer@mail>``”h]”hŒReviewer <reviewer@mail>”…””}”(hjd	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj\	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MkhjX	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒ!Acked-by: ``Acker <acker@mail>``
”h]”hÛ)”}”(hŒ Acked-by: ``Acker <acker@mail>``”h]”(hŒ
Acked-by: ”…””}”(hj‚	  hžhhŸNh NubjX  )”}”(hŒ``Acker <acker@mail>``”h]”hŒAcker <acker@mail>”…””}”(hjŠ	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj‚	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mmhj~	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hŒ¶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.
”h]”(hÛ)”}”(hŒ"Cc: ``cc-ed-person <person@mail>``”h]”(hŒCc: ”…””}”(hj¨	  hžhhŸNh NubjX  )”}”(hŒ``cc-ed-person <person@mail>``”h]”hŒcc-ed-person <person@mail>”…””}”(hj°	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj¨	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mohj¤	  ubhÛ)”}”(hŒ‘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.”h]”(hŒBIf the patch should be backported to stable, then please add a â€˜”…””}”(hjÄ	  hžhhŸNh NubjX  )”}”(hŒ``Cc:
stable@vger.kernel.org``”h]”hŒCc:
stable@vger.kernel.org”…””}”(hjÌ	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjÄ	  ubhŒ5â€™ tag, but do not Cc stable when sending your
mail.”…””}”(hjÄ	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mqhj¤	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubj  )”}”(hX“  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
”h]”(hÛ)”}”(hŒ%Link: ``https://link/to/information``”h]”(hŒLink: ”…””}”(hjî	  hžhhŸNh NubjX  )”}”(hŒ``https://link/to/information``”h]”hŒhttps://link/to/information”…””}”(hjö	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjî	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Muhjê	  ubhÛ)”}”(hŒmFor referring to an email posted to the kernel mailing lists, please
use the lore.kernel.org redirector URL::”h]”hŒlFor referring to an email posted to the kernel mailing lists, please
use the lore.kernel.org redirector URL:”…””}”(hj

  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mwhjê	  ubjI  )”}”(hŒ3Link: https://lore.kernel.org/email-message-id@here”h]”hŒ3Link: https://lore.kernel.org/email-message-id@here”…””}”hj
  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Mzhjê	  ubhÛ)”}”(hX  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::”h]”(hŒŸ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 ”…””}”(hj&
  hžhhŸNh NubjX  )”}”(hŒ	``Link:``”h]”hŒLink:”…””}”(hj.
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj&
  ubhŒZ trailers with the commit
message is to use markdown-like bracketed notation, for example:”…””}”(hj&
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M|hjê	  ubjI  )”}”(hX  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]”h]”hX  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]”…””}”hjF
  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Mhjê	  ubhÛ)”}”(hXZ  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::”h]”(hŒYou can also use ”…””}”(hjT
  hžhhŸNh NubjX  )”}”(hŒ	``Link:``”h]”hŒLink:”…””}”(hj\
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjT
  ubhŒx trailers to indicate the origin of the
patch when applying it to your git tree. In that case, please use the
dedicated ”…””}”(hjT
  hžhhŸNh NubjX  )”}”(hŒ``patch.msgid.link``”h]”hŒpatch.msgid.link”…””}”(hjn
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjT
  ubhŒ domain instead of ”…””}”(hjT
  hžhhŸNh NubjX  )”}”(hŒ``lore.kernel.org``”h]”hŒlore.kernel.org”…””}”(hj€
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hjT
  ubhŒ.
This practice makes it possible for automated tooling to identify
which link to use to retrieve the original patch submission. For
example:”…””}”(hjT
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mˆhjê	  ubjI  )”}”(hŒ;Link: https://patch.msgid.link/patch-source-message-id@here”h]”hŒ;Link: https://patch.msgid.link/patch-source-message-id@here”…””}”hj˜
  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Mhjê	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubeh}”(h]”h ]”h"]”h$]”h&]”j@  jA  uh1j  hŸh³h Mhjå  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j	  hŸh³h MhjÆ  hžhubhÛ)”}”(hŒwPlease do not use combined tags, e.g. ``Reported-and-tested-by``, as
they just complicate automated extraction of tags.”h]”(hŒ&Please do not use combined tags, e.g. ”…””}”(hj¸
  hžhhŸNh NubjX  )”}”(hŒ``Reported-and-tested-by``”h]”hŒReported-and-tested-by”…””}”(hjÀ
  hžhhŸNh Nubah•Ž¶      }”(h]”h ]”h"]”h$]”h&]”uh1jW  hj¸
  ubhŒ7, as
they just complicate automated extraction of tags.”…””}”(hj¸
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M‘hjÆ  hžhubeh}”(h]”Œordering-of-commit-tags”ah ]”h"]”Œordering of commit tags”ah$]”h&]”uh1h´hjI  hžhhŸh³h Mubhµ)”}”(hhh]”(hº)”}”(hŒLinks to documentation”h]”hŒLinks to documentation”…””}”(hjã
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjà
  hžhhŸh³h M–ubhÛ)”}”(hX  Providing links to documentation in the changelog is a great help to later
debugging and analysis.  Unfortunately, URLs often break very quickly
because companies restructure their websites frequently.  Non-'volatile'
exceptions include the Intel SDM and the AMD APM.”h]”hX  Providing links to documentation in the changelog is a great help to later
debugging and analysis.  Unfortunately, URLs often break very quickly
because companies restructure their websites frequently.  Non-â€˜volatileâ€™
exceptions include the Intel SDM and the AMD APM.”…””}”(hjñ
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M˜hjà
  hžhubhÛ)”}”(hŒëTherefore, for 'volatile' documents, please create an entry in the kernel
bugzilla https://bugzilla.kernel.org and attach a copy of these documents
to the bugzilla entry. Finally, provide the URL of the bugzilla entry in
the changelog.”h]”(hŒWTherefore, for â€˜volatileâ€™ documents, please create an entry in the kernel
bugzilla ”…””}”(hjÿ
  hžhhŸNh Nubhå)”}”(hŒhttps://bugzilla.kernel.org”h]”hŒhttps://bugzilla.kernel.org”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j	  uh1hähjÿ
  ubhŒ} and attach a copy of these documents
to the bugzilla entry. Finally, provide the URL of the bugzilla entry in
the changelog.”…””}”(hjÿ
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjà
  hžhubeh}”(h]”Œlinks-to-documentation”ah ]”h"]”Œlinks to documentation”ah$]”h&]”uh1h´hjI  hžhhŸh³h M–ubhµ)”}”(hhh]”(hº)”}”(hŒPatch resend or reminders”h]”hŒPatch resend or reminders”…””}”(hj+  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj(  hžhhŸh³h M£ubhÛ)”}”(hŒSee :ref:`resend_reminders`.”h]”(hŒSee ”…””}”(hj9  hžhhŸNh Nubh)”}”(hŒ:ref:`resend_reminders`”h]”jâ  )”}”(hjC  h]”hŒresend_reminders”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”(jí  Œstd”Œstd-ref”eh"]”h$]”h&]”uh1já  hjA  ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”jú  Œ	refdomain”jO  Œreftype”Œref”Œrefexplicit”‰Œrefwarn”ˆj   Œresend_reminders”uh1hhŸh³h M¥hj9  ubhŒ.”…””}”(hj9  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¥hj(  hžhubeh}”(h]”Œpatch-resend-or-reminders”ah ]”h"]”Œpatch resend or reminders”ah$]”h&]”uh1h´hjI  hžhhŸh³h M£ubhµ)”}”(hhh]”(hº)”}”(hŒMerge window”h]”hŒMerge window”…””}”(hjv  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjs  hžhhŸh³h M¨ubhÛ)”}”(hŒþPlease do not expect patches to be reviewed or merged by tip
maintainers around or during the merge window.  The trees are closed
to all but urgent fixes during this time.  They reopen once the merge
window closes and a new -rc1 kernel has been released.”h]”hŒþPlease do not expect patches to be reviewed or merged by tip
maintainers around or during the merge window.  The trees are closed
to all but urgent fixes during this time.  They reopen once the merge
window closes and a new -rc1 kernel has been released.”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mªhjs  hžhubhÛ)”}”(hŒþLarge series should be submitted in mergeable state *at* *least* a week
before the merge window opens.  Exceptions are made for bug fixes and
*sometimes* for small standalone drivers for new hardware or minimally
invasive patches for hardware enablement.”h]”(hŒ4Large series should be submitted in mergeable state ”…””}”(hj’  hžhhŸNh NubhŒemphasis”“”)”}”(hŒ*at*”h]”hŒat”…””}”(hjœ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jš  hj’  ubhŒ ”…””}”(hj’  hžhhŸNh Nubj›  )”}”(hŒ*least*”h]”hŒleast”…””}”(hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jš  hj’  ubhŒN a week
before the merge window opens.  Exceptions are made for bug fixes and
”…””}”(hj’  hžhhŸNh Nubj›  )”}”(hŒ*sometimes*”h]”hŒ	sometimes”…””}”(hjÀ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jš  hj’  ubhŒe for small standalone drivers for new hardware or minimally
invasive patches for hardware enablement.”…””}”(hj’  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¯hjs  hžhubhÛ)”}”(hŒÃDuring the merge window, the maintainers instead focus on following the
upstream changes, fixing merge window fallout, collecting bug fixes, and
allowing themselves a breath. Please respect that.”h]”hŒÃDuring the merge window, the maintainers instead focus on following the
upstream changes, fixing merge window fallout, collecting bug fixes, and
allowing themselves a breath. Please respect that.”…””}”(hjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M´hjs  hžhubhÛ)”}”(hŒhSo called _urgent_ branches will be merged into mainline during the
stabilization phase of each release.”h]”hŒhSo called _urgent_ branches will be merged into mainline during the
stabilization phase of each release.”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¸hjs  hžhubeh}”(h]”Œmerge-window”ah ]”h"]”Œmerge window”ah$]”h&]”uh1h´hjI  hžhhŸh³h M¨ubhµ)”}”(hhh]”(hº)”}”(hŒGit”h]”hŒGit”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjü  hžhhŸh³h M½ubhÛ)”}”(hŒ|The tip maintainers accept git pull requests from maintainers who provide
subsystem changes for aggregation in the tip tree.”h]”hŒ|The tip maintainers accept git pull requests from maintainers who provide
subsystem changes for aggregation in the tip tree.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¿hjü  hžhubhÛ)”}”(hŒÅPull requests for new patch submissions are usually not accepted and do not
replace proper patch submission to the mailing list. The main reason for
this is that the review workflow is email based.”h]”hŒÅPull requests for new patch submissions are usually not accepted and do not
replace proper patch submission to the mailing list. The main reason for
this is that the review workflow is email based.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÂhjü  hžhubhÛ)”}”(hŒùIf you submit a larger patch series it is helpful to provide a git branch
in a private repository which allows interested people to easily pull the
series for testing. The usual way to offer this is a git URL in the cover
letter of the patch series.”h]”hŒùIf you submit a larger patch series it is helpful to provide a git branch
in a private repository which allows interested people to easily pull the
series for testing. The usual way to offer this is a git URL in the cover
letter of the patch series.”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÆhjü  hžhubeh}”(h]”Œgit”ah ]”h"]”Œgit”ah$]”h&]”uh1h´hjI  hžhhŸh³h M½ubhµ)”}”(hhh]”(hº)”}”(hŒTesting”h]”hŒTesting”…””}”(hjB  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj?  hžhhŸh³h MÌubhÛ)”}”(hŒÌCode should be tested before submitting to the tip maintainers.  Anything
other than minor changes should be built, booted and tested with
comprehensive (and heavyweight) kernel debugging options enabled.”h]”hŒÌCode should be tested before submitting to the tip maintainers.  Anything
other than minor changes should be built, booted and tested with
comprehensive (and heavyweight) kernel debugging options enabled.”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÎhj?  hžhubhÛ)”}”(hŒThese debugging options can be found in kernel/configs/x86_debug.config
and can be added to an existing kernel config by running:”h]”hŒThese debugging options can be found in kernel/configs/x86_debug.config
and can be added to an existing kernel config by running:”…””}”(hj^  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÒhj?  hžhubj
  )”}”(hŒmake x86_debug.config
”h]”hÛ)”}”(hŒmake x86_debug.config”h]”hŒmake x86_debug.config”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÕhjl  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j	  hŸh³h MÕhj?  hžhubhÛ)”}”(hŒ_Some of these options are x86-specific and can be left out when testing
on other architectures.”h]”hŒ_Some of these options are x86-specific and can be left out when testing
on other architectures.”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M×hj?  hžhubhŒtarget”“”)”}”(hŒ .. _maintainer-tip-coding-style:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œmaintainer-tip-coding-style”uh1j’  h MÚhj?  hžhhŸh³ubeh}”(h]”Œtesting”ah ]”h"]”Œtesting”ah$]”h&]”uh1h´hjI  hžhhŸh³h MÌubeh}”(h]”Œpatch-submission-notes”ah ]”h"]”Œpatch submission notes”ah$]”h&]”uh1h´hh¶hžhhŸh³h Keubhµ)”}”(hhh]”(hº)”}”(hŒCoding style notes”h]”hŒCoding style notes”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj°  hžhhŸh³h MÝubhµ)”}”(hhh]”(hº)”}”(hŒComment style”h]”hŒComment style”…””}”(hjÄ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÁ  hžhhŸh³h MàubhÛ)”}”(hŒ5Sentences in comments start with an uppercase letter.”h]”hŒ5Sentences in comments start with an uppercase letter.”…””}”(hjÒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MâhjÁ  hžhubhÛ)”}”(hŒSingle line comments::”h]”hŒSingle line comments:”…””}”(hjà  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MähjÁ  hžhubjI  )”}”(hŒ#/* This is a single line comment */”h]”hŒ#/* This is a single line comment */”…””}”hjî  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h MæhjÁ  hžhubhÛ)”}”(hŒMulti-line comments::”h]”hŒMulti-line comments:”…””}”(hjü  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MèhjÁ  hžhubjI  )”}”(hŒ/*
 * This is a properly formatted
 * multi-line comment.
 *
 * Larger multi-line comments should be split into paragraphs.
 */”h]”hŒ/*
 * This is a properly formatted
 * multi-line comment.
 *
 * Larger multi-line comments should be split into paragraphs.
 */”…””}”hj
  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h MêhjÁ  hžhubhÛ)”}”(hŒNo tail comments (see below):”h]”hŒNo tail comments (see below):”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MñhjÁ  hžhubj
  )”}”(hXú  Please refrain from using tail comments. Tail comments disturb the
reading flow in almost all contexts, but especially in code::

      if (somecondition_is_true) /* Don't put a comment here */
              dostuff(); /* Neither here */

      seed = MAGIC_CONSTANT; /* Nor here */

Use freestanding comments instead::

      /* This condition is not obvious without a comment */
      if (somecondition_is_true) {
              /* This really needs to be documented */
              dostuff();
      }

      /* This magic initialization needs a comment. Maybe not? */
      seed = MAGIC_CONSTANT;

Use C++ style, tail comments when documenting structs in headers to
achieve a more compact layout and better readability::

      // eax
      u32     x2apic_shift    :  5, // Number of bits to shift APIC ID right
                                    // for the topology ID at the next level
                              : 27; // Reserved
      // ebx
      u32     num_processors  : 16, // Number of processors at current level
                              : 16; // Reserved

versus::

      /* eax */
              /*
               * Number of bits to shift APIC ID right for the topology ID
               * at the next level
               */
       u32     x2apic_shift    :  5,
               /* Reserved */
                               : 27;

      /* ebx */
              /* Number of processors at current level */
      u32     num_processors  : 16,
              /* Reserved */
                              : 16;
”h]”(hÛ)”}”(hŒ€Please refrain from using tail comments. Tail comments disturb the
reading flow in almost all contexts, but especially in code::”h]”hŒPlease refrain from using tail comments. Tail comments disturb the
reading flow in almost all contexts, but especially in code:”…””}”(hj*  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Móhj&  ubjI  )”}”(hŒ†if (somecondition_is_true) /* Don't put a comment here */
        dostuff(); /* Neither here */

seed = MAGIC_CONSTANT; /* Nor here */”h]”hŒ†if (somecondition_is_true) /* Don't put a comment here */
        dostuff(); /* Neither here */

seed = MAGIC_CONSTANT; /* Nor here */”…””}”hj8  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Möhj&  ubhÛ)”}”(hŒ#Use freestanding comments instead::”h]”hŒ"Use freestanding comments instead:”…””}”(hjF  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mûhj&  ubjI  )”}”(hŒì/* This condition is not obvious without a comment */
if (somecondition_is_true) {
        /* This really needs to be documented */
        dostuff();
}

/* This magic initialization needs a comment. Maybe not? */
seed = MAGIC_CONSTANT;”h]”hŒì/* This condition is not obvious without a comment */
if (somecondition_is_true) {
        /* This really needs to be documented */
        dostuff();
}

/* This magic initialization needs a comment. Maybe not? */
seed = MAGIC_CONSTANT;”…””}”hjT  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Mýhj&  ubhÛ)”}”(hŒzUse C++ style, tail comments when documenting structs in headers to
achieve a more compact layout and better readability::”h]”hŒyUse C++ style, tail comments when documenting structs in headers to
achieve a more compact layout and better readability:”…””}”(hjb  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhj&  ubjI  )”}”(hX6  // eax
u32     x2apic_shift    :  5, // Number of bits to shift APIC ID right
                              // for the topology ID at the next level
                        : 27; // Reserved
// ebx
u32     num_processors  : 16, // Number of processors at current level
                        : 16; // Reserved”h]”hX6  // eax
u32     x2apic_shift    :  5, // Number of bits to shift APIC ID right
                              // for the topology ID at the next level
                        : 27; // Reserved
// ebx
u32     num_processors  : 16, // Number of processors at current level
                        : 16; // Reserved”…””}”hjp  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M	hj&  ubhÛ)”}”(hŒversus::”h]”hŒversus:”…””}”(hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhj&  ubjI  )”}”(hXj  /* eax */
        /*
         * Number of bits to shift APIC ID right for the topology ID
         * at the next level
         */
 u32     x2apic_shift    :  5,
         /* Reserved */
                         : 27;

/* ebx */
        /* Number of processors at current level */
u32     num_processors  : 16,
        /* Reserved */
                        : 16;”h]”hXj  /* eax */
        /*
         * Number of bits to shift APIC ID right for the topology ID
         * at the next level
         */
 u32     x2apic_shift    :  5,
         /* Reserved */
                         : 27;

/* ebx */
        /* Number of processors at current level */
u32     num_processors  : 16,
        /* Reserved */
                        : 16;”…””}”hjŒ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Mhj&  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j	  hŸh³h MóhjÁ  hžhubhÛ)”}”(hŒComment the important things:”h]”hŒComment the important things:”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M"hjÁ  hžhubj
  )”}”(hX+  Comments should be added where the operation is not obvious. Documenting
the obvious is just a distraction::

      /* Decrement refcount and check for zero */
      if (refcount_dec_and_test(&p->refcnt)) {
              do;
              lots;
              of;
              magic;
              things;
      }

Instead, comments should explain the non-obvious details and document
constraints::

      if (refcount_dec_and_test(&p->refcnt)) {
              /*
               * Really good explanation why the magic things below
               * need to be done, ordering and locking constraints,
               * etc..
               */
              do;
              lots;
              of;
              magic;
              /* Needs to be the last operation because ... */
              things;
      }
”h]”(hÛ)”}”(hŒlComments should be added where the operation is not obvious. Documenting
the obvious is just a distraction::”h]”hŒkComments should be added where the operation is not obvious. Documenting
the obvious is just a distraction:”…””}”(hj²  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M$hj®  ubjI  )”}”(hŒ›/* Decrement refcount and check for zero */
if (refcount_dec_and_test(&p->refcnt)) {
        do;
        lots;
        of;
        magic;
        things;
}”h]”hŒ›/* Decrement refcount and check for zero */
if (refcount_dec_and_test(&p->refcnt)) {
        do;
        lots;
        of;
        magic;
        things;
}”…””}”hjÀ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M'hj®  ubhÛ)”}”(hŒSInstead, comments should explain the non-obvious details and document
constraints::”h]”hŒRInstead, comments should explain the non-obvious details and document
constraints:”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M0hj®  ubjI  )”}”(hXL  if (refcount_dec_and_test(&p->refcnt)) {
        /*
         * Really good explanation why the magic things below
         * need to be done, ordering and locking constraints,
         * etc..
         */
        do;
        lots;
        of;
        magic;
        /* Needs to be the last operation because ... */
        things;
}”h]”hXL  if (refcount_dec_and_test(&p->refcnt)) {
        /*
         * Really good explanation why the magic things below
         * need to be done, ordering and locking constraints,
         * etc..
         */
        do;
        lots;
        of;
        magic;
        /* Needs to be the last operation because ... */
        things;
}”…””}”hjÜ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M3hj®  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j	  hŸh³h M$hjÁ  hžhubhÛ)”}”(hŒ Function documentation comments:”h]”hŒ Function documentation comments:”…””}”(hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MAhjÁ  hžhubj
  )”}”(hXC  To document functions and their arguments please use kernel-doc format
and not free form comments::

      /**
       * magic_function - Do lots of magic stuff
       * @magic:      Pointer to the magic data to operate on
       * @offset:     Offset in the data array of @magic
       *
       * Deep explanation of mysterious things done with @magic along
       * with documentation of the return values.
       *
       * Note, that the argument descriptors above are arranged
       * in a tabular fashion.
       */

This applies especially to globally visible functions and inline
functions in public header files. It might be overkill to use kernel-doc
format for every (static) function which needs a tiny explanation. The
usage of descriptive function names often replaces these tiny comments.
Apply common sense as always.

”h]”(hÛ)”}”(hŒcTo document functions and their arguments please use kernel-doc format
and not free form comments::”h]”hŒbTo document functions and their arguments please use kernel-doc format
and not free form comments:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MChjþ  ubjI  )”}”(hXb  /**
 * magic_function - Do lots of magic stuff
 * @magic:      Pointer to the magic data to operate on
 * @offset:     Offset in the data array of @magic
 *
 * Deep explanation of mysterious things done with @magic along
 * with documentation of the return values.
 *
 * Note, that the argument descriptors above are arranged
 * in a tabular fashion.
 */”h]”hXb  /**
 * magic_function - Do lots of magic stuff
 * @magic:      Pointer to the magic data to operate on
 * @offset:     Offset in the data array of @magic
 *
 * Deep explanation of mysterious things done with @magic along
 * with documentation of the return values.
 *
 * Note, that the argument descriptors above are arranged
 * in a tabular fashion.
 */”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h MFhjþ  ubhÛ)”}”(hX6  This applies especially to globally visible functions and inline
functions in public header files. It might be overkill to use kernel-doc
format for every (static) function which needs a tiny explanation. The
usage of descriptive function names often replaces these tiny comments.
Apply common sense as always.”h]”hX6  This applies especially to globally visible functions and inline
functions in public header files. It might be overkill to use kernel-doc
format for every (static) function which needs a tiny explanation. The
usage of descriptive function names often replaces these tiny comments.
Apply common sense as always.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MRhjþ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j	  hŸh³h MChjÁ  hžhubeh}”(h]”Œcomment-style”ah ]”h"]”Œcomment style”ah$]”h&]”uh1h´hj°  hžhhŸh³h Màubhµ)”}”(hhh]”(hº)”}”(hŒ Documenting locking requirements”h]”hŒ Documenting locking requirements”…””}”(hj=  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj:  hžhhŸh³h MZubj
  )”}”(hXä  Documenting locking requirements is a good thing, but comments are not
necessarily the best choice. Instead of writing::

      /* Caller must hold foo->lock */
      void func(struct foo *foo)
      {
              ...
      }

Please use::

      void func(struct foo *foo)
      {
              lockdep_assert_held(&foo->lock);
              ...
      }

In PROVE_LOCKING kernels, lockdep_assert_held() emits a warning
if the caller doesn't hold the lock.  Comments can't do that.
”h]”(hÛ)”}”(hŒxDocumenting locking requirements is a good thing, but comments are not
necessarily the best choice. Instead of writing::”h]”hŒwDocumenting locking requirements is a good thing, but comments are not
necessarily the best choice. Instead of writing:”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M[hjK  ubjI  )”}”(hŒK/* Caller must hold foo->lock */
void func(struct foo *foo)
{
        ...
}”h]”hŒK/* Caller must hold foo->lock */
void func(struct foo *foo)
{
        ...
}”…””}”hj]  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M^hjK  ubhÛ)”}”(hŒPlease use::”h]”hŒPlease use:”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MdhjK  ubjI  )”}”(hŒSvoid func(struct foo *foo)
{
        lockdep_assert_held(&foo->lock);
        ...
}”h]”hŒSvoid func(struct foo *foo)
{
        lockdep_assert_held(&foo->lock);
        ...
}”…””}”hjy  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h MfhjK  ubhÛ)”}”(hŒ}In PROVE_LOCKING kernels, lockdep_assert_held() emits a warning
if the caller doesn't hold the lock.  Comments can't do that.”h]”hŒIn PROVE_LOCKING kernels, lockdep_assert_held() emits a warning
if the caller doesnâ€™t hold the lock.  Comments canâ€™t do that.”…””}”(hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MlhjK  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j	  hŸh³h M[hj:  hžhubeh}”(h]”Œ documenting-locking-requirements”ah ]”h"]”Œ documenting locking requirements”ah$]”h&]”uh1h´hj°  hžhhŸh³h MZubhµ)”}”(hhh]”(hº)”}”(hŒBracket rules”h]”hŒBracket rules”…””}”(hj¦  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj£  hžhhŸh³h MpubhÛ)”}”(hŒqBrackets should be omitted only if the statement which follows 'if', 'for',
'while' etc. is truly a single line::”h]”hŒ|Brackets should be omitted only if the statement which follows â€˜ifâ€™, â€˜forâ€™,
â€˜whileâ€™ etc. is truly a single line:”…””}”(hj´  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mrhj£  hžhubjI  )”}”(hŒ if (foo)
        do_something();”h]”hŒ if (foo)
        do_something();”…””}”hjÂ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Muhj£  hžhubhÛ)”}”(hŒgThe following is not considered to be a single line statement even
though C does not require brackets::”h]”hŒfThe following is not considered to be a single line statement even
though C does not require brackets:”…””}”(hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mxhj£  hžhubjI  )”}”(hŒSfor (i = 0; i < end; i++)
        if (foo[i])
                do_something(foo[i]);”h]”hŒSfor (i = 0; i < end; i++)
        if (foo[i])
                do_something(foo[i]);”…””}”hjÞ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M{hj£  hžhubhÛ)”}”(hŒAAdding brackets around the outer loop enhances the reading flow::”h]”hŒ@Adding brackets around the outer loop enhances the reading flow:”…””}”(hjì  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhj£  hžhubjI  )”}”(hŒWfor (i = 0; i < end; i++) {
        if (foo[i])
                do_something(foo[i]);
}”h]”hŒWfor (i = 0; i < end; i++) {
        if (foo[i])
                do_something(foo[i]);
}”…””}”hjú  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Mhj£  hžhubeh}”(h]”Œbracket-rules”ah ]”h"]”Œbracket rules”ah$]”h&]”uh1h´hj°  hžhhŸh³h Mpubhµ)”}”(hhh]”(hº)”}”(hŒVariable declarations”h]”hŒVariable declarations”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h MˆubhÛ)”}”(hŒjThe preferred ordering of variable declarations at the beginning of a
function is reverse fir tree order::”h]”hŒiThe preferred ordering of variable declarations at the beginning of a
function is reverse fir tree order:”…””}”(hj!  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MŠhj  hžhubjI  )”}”(hŒ]struct long_struct_name *descriptive_name;
unsigned long foo, bar;
unsigned int tmp;
int ret;”h]”hŒ]struct long_struct_name *descriptive_name;
unsigned long foo, bar;
unsigned int tmp;
int ret;”…””}”hj/  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Mhj  hžhubhÛ)”}”(hŒ8The above is faster to parse than the reverse ordering::”h]”hŒ7The above is faster to parse than the reverse ordering:”…””}”(hj=  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M’hj  hžhubjI  )”}”(hŒ]int ret;
unsigned int tmp;
unsigned long foo, bar;
struct long_struct_name *descriptive_name;”h]”hŒ]int ret;
unsigned int tmp;
unsigned long foo, bar;
struct long_struct_name *descriptive_name;”…””}”hjK  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M”hj  hžhubhÛ)”}”(hŒ'And even more so than random ordering::”h]”hŒ&And even more so than random ordering:”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M™hj  hžhubjI  )”}”(hŒ]unsigned long foo, bar;
int ret;
struct long_struct_name *descriptive_name;
unsigned int tmp;”h]”hŒ]unsigned long foo, bar;
int ret;
struct long_struct_name *descriptive_name;
unsigned int tmp;”…””}”hjg  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M›hj  hžhubhÛ)”}”(hŒwAlso please try to aggregate variables of the same type into a single
line. There is no point in wasting screen space::”h]”hŒvAlso please try to aggregate variables of the same type into a single
line. There is no point in wasting screen space:”…””}”(hju  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M hj  hžhubjI  )”}”(hŒCunsigned long a;
unsigned long b;
unsigned long c;
unsigned long d;”h]”hŒCunsigned long a;
unsigned long b;
unsigned long c;
unsigned long d;”…””}”hjƒ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M£hj  hžhubhÛ)”}”(hŒIt's really sufficient to do::”h]”hŒItâ€™s really sufficient to do:”…””}”(hj‘  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¨hj  hžhubjI  )”}”(hŒunsigned long a, b, c, d;”h]”hŒunsigned long a, b, c, d;”…””}”hjŸ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h Mªhj  hžhubhÛ)”}”(hŒKPlease also refrain from introducing line splits in variable declarations::”h]”hŒJPlease also refrain from introducing line splits in variable declarations:”…””}”(hj­  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¬hj  hžhubjI  )”}”(hŒÎstruct long_struct_name *descriptive_name = container_of(bar,
                                              struct long_struct_name,
                                              member);
struct foobar foo;”h]”hŒÎstruct long_struct_name *descriptive_name = container_of(bar,
                                              struct long_struct_name,
                                              member);
struct foobar foo;”…””}”hj»  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M®hj  hžhubhÛ)”}”(hŒVIt's way better to move the initialization to a separate line after the
declarations::”h]”hŒWItâ€™s way better to move the initialization to a separate line after the
declarations:”…””}”(hjÉ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M³hj  hžhubjI  )”}”(hŒ…struct long_struct_name *descriptive_name;
struct foobar foo;

descriptive_name = container_of(bar, struct long_struct_name, member);”h]”hŒ…struct long_struct_name *descriptive_name;
struct foobar foo;

descriptive_name = container_of(bar, struct long_struct_name, member);”…””}”hj×  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M¶hj  hžhubeh}”(h]”Œvariable-declarations”ah ]”h"]”Œvariable declarations”ah$]”h&]”uh1h´hj°  hžhhŸh³h Mˆubhµ)”}”(hhh]”(hº)”}”(hŒVariable types”h]”hŒVariable types”…””}”(hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjí  hžhhŸh³h M½ubhÛ)”}”(hX  Please use the proper u8, u16, u32, u64 types for variables which are meant
to describe hardware or are used as arguments for functions which access
hardware. These types are clearly defining the bit width and avoid
truncation, expansion and 32/64-bit confusion.”h]”hX  Please use the proper u8, u16, u32, u64 types for variables which are meant
to describe hardware or are used as arguments for functions which access
hardware. These types are clearly defining the bit width and avoid
truncation, expansion and 32/64-bit confusion.”…””}”(hjþ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M¿hjí  hžhubhÛ)”}”(hX7  u64 is also recommended in code which would become ambiguous for 32-bit
kernels when 'unsigned long' would be used instead. While in such
situations 'unsigned long long' could be used as well, u64 is shorter
and also clearly shows that the operation is required to be 64 bits wide
independent of the target CPU.”h]”hX?  u64 is also recommended in code which would become ambiguous for 32-bit
kernels when â€˜unsigned longâ€™ would be used instead. While in such
situations â€˜unsigned long longâ€™ could be used as well, u64 is shorter
and also clearly shows that the operation is required to be 64 bits wide
independent of the target CPU.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÄhjí  hžhubhÛ)”}”(hŒ0Please use 'unsigned int' instead of 'unsigned'.”h]”hŒ8Please use â€˜unsigned intâ€™ instead of â€˜unsignedâ€™.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÊhjí  hžhubeh}”(h]”Œvariable-types”ah ]”h"]”Œvariable types”ah$]”h&]”uh1h´hj°  hžhhŸh³h M½ubhµ)”}”(hhh]”(hº)”}”(hŒ	Constants”h]”hŒ	Constants”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj0  hžhhŸh³h MÎubhÛ)”}”(hŒšPlease do not use literal (hexa)decimal numbers in code or initializers.
Either use proper defines which have descriptive names or consider using
an enum.”h]”hŒšPlease do not use literal (hexa)decimal numbers in code or initializers.
Either use proper defines which have descriptive names or consider using
an enum.”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MÐhj0  hžhubeh}”(h]”Œ	constants”ah ]”h"]”Œ	constants”ah$]”h&]”uh1h´hj°  hžhhŸh³h MÎubhµ)”}”(hhh]”(hº)”}”(hŒ$Struct declarations and initializers”h]”hŒ$Struct declarations and initializers”…””}”(hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjW  hžhhŸh³h MÖubhÛ)”}”(hŒOStruct declarations should align the struct member names in a tabular
fashion::”h]”hŒNStruct declarations should align the struct member names in a tabular
fashion:”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MØhjW  hžhubjI  )”}”(hŒ|struct bar_order {
        unsigned int    guest_id;
        int             ordered_item;
        struct menu     *menu;
};”h]”hŒ|struct bar_order {
        unsigned int    guest_id;
        int             ordered_item;
        struct menu     *menu;
};”…””}”hjv  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h MÛhjW  hžhubhÛ)”}”(hŒ¥Please avoid documenting struct members within the declaration, because
this often results in strangely formatted comments and the struct members
become obfuscated::”h]”hŒ¤Please avoid documenting struct members within the declaration, because
this often results in strangely formatted comments and the struct members
become obfuscated:”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MáhjW  hžhubjI  )”}”(hŒÙstruct bar_order {
        unsigned int    guest_id; /* Unique guest id */
        int             ordered_item;
        /* Pointer to a menu instance which contains all the drinks */
        struct menu     *menu;
};”h]”hŒÙstruct bar_order {
        unsigned int    guest_id; /* Unique guest id */
        int             ordered_item;
        /* Pointer to a menu instance which contains all the drinks */
        struct menu     *menu;
};”…””}”hj’  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h MåhjW  hžhubhÛ)”}”(hŒëInstead, please consider using the kernel-doc format in a comment preceding
the struct declaration, which is easier to read and has the added advantage
of including the information in the kernel documentation, for example, as
follows::”h]”hŒêInstead, please consider using the kernel-doc format in a comment preceding
the struct declaration, which is easier to read and has the added advantage
of including the information in the kernel documentation, for example, as
follows:”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MìhjW  hžhubjI  )”}”(hX  /**
 * struct bar_order - Description of a bar order
 * @guest_id:           Unique guest id
 * @ordered_item:       The item number from the menu
 * @menu:               Pointer to the menu from which the item
 *                      was ordered
 *
 * Supplementary information for using the struct.
 *
 * Note, that the struct member descriptors above are arranged
 * in a tabular fashion.
 */
struct bar_order {
        unsigned int    guest_id;
        int             ordered_item;
        struct menu     *menu;
};”h]”hX  /**
 * struct bar_order - Description of a bar order
 * @guest_id:           Unique guest id
 * @ordered_item:       The item number from the menu
 * @menu:               Pointer to the menu from which the item
 *                      was ordered
 *
 * Supplementary information for using the struct.
 *
 * Note, that the struct member descriptors above are arranged
 * in a tabular fashion.
 */
struct bar_order {
        unsigned int    guest_id;
        int             ordered_item;
        struct menu     *menu;
};”…””}”hj®  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h MòhjW  hžhubhÛ)”}”(hŒfStatic struct initializers must use C99 initializers and should also be
aligned in a tabular fashion::”h]”hŒeStatic struct initializers must use C99 initializers and should also be
aligned in a tabular fashion:”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MhjW  hžhubjI  )”}”(hŒ”static struct foo statfoo = {
        .a              = 0,
        .plain_integer  = CONSTANT_DEFINE_OR_ENUM,
        .bar            = &statbar,
};”h]”hŒ”static struct foo statfoo = {
        .a              = 0,
        .plain_integer  = CONSTANT_DEFINE_OR_ENUM,
        .bar            = &statbar,
};”…””}”hjÊ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h MhjW  hžhubhÛ)”}”(hŒðNote that while C99 syntax allows the omission of the final comma,
we recommend the use of a comma on the last line because it makes
reordering and addition of new lines easier, and makes such future
patches slightly easier to read as well.”h]”hŒðNote that while C99 syntax allows the omission of the final comma,
we recommend the use of a comma on the last line because it makes
reordering and addition of new lines easier, and makes such future
patches slightly easier to read as well.”…””}”(hjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MhjW  hžhubeh}”(h]”Œ$struct-declarations-and-initializers”ah ]”h"]”Œ$struct declarations and initializers”ah$]”h&]”uh1h´hj°  hžhhŸh³h MÖubhµ)”}”(hhh]”(hº)”}”(hŒLine breaks”h]”hŒLine breaks”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjî  hžhhŸh³h MubhÛ)”}”(hŒ¥Restricting line length to 80 characters makes deeply indented code hard to
read.  Consider breaking out code into helper functions to avoid excessive
line breaking.”h]”hŒ¥Restricting line length to 80 characters makes deeply indented code hard to
read.  Consider breaking out code into helper functions to avoid excessive
line breaking.”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjî  hžhubhÛ)”}”(hŒThe 80 character rule is not a strict rule, so please use common sense when
breaking lines. Especially format strings should never be broken up.”h]”hŒThe 80 character rule is not a strict rule, so please use common sense when
breaking lines. Especially format strings should never be broken up.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjî  hžhubhÛ)”}”(hŒ›When splitting function declarations or function calls, then please align
the first argument in the second line with the first argument in the first
line::”h]”hŒšWhen splitting function declarations or function calls, then please align
the first argument in the second line with the first argument in the first
line:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Mhjî  hžhubjI  )”}”(hX  static int long_function_name(struct foobar *barfoo, unsigned int id,
                              unsigned int offset)
{

      if (!id) {
              ret = longer_function_name(barfoo, DEFAULT_BARFOO_ID,
                                         offset);
      ...”h]”hX  static int long_function_name(struct foobar *barfoo, unsigned int id,
                              unsigned int offset)
{

      if (!id) {
              ret = longer_function_name(barfoo, DEFAULT_BARFOO_ID,
                                         offset);
      ...”…””}”hj)  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jH  hŸh³h M hjî  hžhubeh}”(h]”Œline-breaks”ah ]”h"]”Œline breaks”ah$]”h&]”uh1h´hj°  hžhhŸh³h Mubhµ)”}”(hhh]”(hº)”}”(hŒ
Namespaces”h]”hŒ
Namespaces”…””}”(hjB  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj?  hžhhŸh³h M*ubhÛ)”}”(hX/  Function/variable namespaces improve readability and allow easy
grepping. These namespaces are string prefixes for globally visible
function and variable names, including inlines. These prefixes should
combine the subsystem and the component name such as 'x86_comp\_',
'sched\_', 'irq\_', and 'mutex\_'.”h]”hX?  Function/variable namespaces improve readability and allow easy
grepping. These namespaces are string prefixes for globally visible
function and variable names, including inlines. These prefixes should
combine the subsystem and the component name such as â€˜x86_comp _â€™,
â€˜sched _â€™, â€˜irq _â€™, and â€˜mutex _â€™.”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M,hj?  hžhubhÛ)”}”(hŒÉThis also includes static file scope functions that are immediately put
into globally visible driver templates - it's useful for those symbols
to carry a good prefix as well, for backtrace readability.”h]”hŒËThis also includes static file scope functions that are immediately put
into globally visible driver templates - itâ€™s useful for those symbols
to carry a good prefix as well, for backtrace readability.”…””}”(hj^  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M2hj?  hžhubhÛ)”}”(hŒìNamespace prefixes may be omitted for local static functions and
variables. Truly local functions, only called by other local functions,
can have shorter descriptive names - our primary concern is greppability
and backtrace readability.”h]”hŒìNamespace prefixes may be omitted for local static functions and
variables. Truly local functions, only called by other local functions,
can have shorter descriptive names - our primary concern is greppability
and backtrace readability.”…””}”(hjl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M6hj?  hžhubhÛ)”}”(hX  Please note that 'xxx_vendor\_' and 'vendor_xxx_` prefixes are not
helpful for static functions in vendor-specific files. After all, it
is already clear that the code is vendor-specific. In addition, vendor
names should only be for truly vendor-specific functionality.”h]”hX  Please note that â€˜xxx_vendor _â€™ and â€˜vendor_xxx_` prefixes are not
helpful for static functions in vendor-specific files. After all, it
is already clear that the code is vendor-specific. In addition, vendor
names should only be for truly vendor-specific functionality.”…””}”(hjz  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M;hj?  hžhubhÛ)”}”(hŒEAs always apply common sense and aim for consistency and readability.”h]”hŒEAs always apply common sense and aim for consistency and readability.”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h M@hj?  hžhubeh}”(h]”Œ
namespaces”ah ]”h"]”Œ
namespaces”ah$]”h&]”uh1h´hj°  hžhhŸh³h M*ubeh}”(h]”(Œcoding-style-notes”jŸ  eh ]”h"]”(Œcoding style notes”Œmaintainer-tip-coding-style”eh$]”h&]”uh1h´hh¶hžhhŸh³h MÝŒexpect_referenced_by_name”}”j¤  j”  sŒexpect_referenced_by_id”}”jŸ  j”  subhµ)”}”(hhh]”(hº)”}”(hŒCommit notifications”h]”hŒCommit notifications”…””}”(hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj«  hžhhŸh³h MDubhÛ)”}”(hX–  The tip tree is monitored by a bot for new commits. The bot sends an email
for each new commit to a dedicated mailing list
(``linux-tip-commits@vger.kernel.org``) and Cc's all people who are
mentioned in one of the commit tags. It uses the email message ID from the
Link tag at the end of the tag list to set the In-Reply-To email header so
the message is properly threaded with the patch submission email.”h]”(hŒ|The tip tree is monitored by a bot for new commits. The bot sends an email
for each new commit to a dedicated mailing list
(”…””}”(hj¼  hžhhŸNh NubjX  )”}”(hŒ%``linux-tip-commits@vger.kernel.org``”h]”hŒ!linux-tip-commits@vger.kernel.org”…””}”(hjÄ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jW  hj¼  ubhŒ÷) and Ccâ€™s all people who are
mentioned in one of the commit tags. It uses the email message ID from the
Link tag at the end of the tag list to set the In-Reply-To email header so
the message is properly threaded with the patch submission email.”…””}”(hj¼  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MFhj«  hžhubhÛ)”}”(hŒøThe tip maintainers and submaintainers try to reply to the submitter
when merging a patch, but they sometimes forget or it does not fit the
workflow of the moment. While the bot message is purely mechanical, it
also implies a 'Thank you! Applied.'.”h]”hŒüThe tip maintainers and submaintainers try to reply to the submitter
when merging a patch, but they sometimes forget or it does not fit the
workflow of the moment. While the bot message is purely mechanical, it
also implies a â€˜Thank you! Applied.â€™.”…””}”(hjÜ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h MMhj«  hžhubeh}”(h]”Œcommit-notifications”ah ]”h"]”Œcommit notifications”ah$]”h&]”uh1h´hh¶hžhhŸh³h MDubeh}”(h]”Œthe-tip-tree-handbook”ah ]”h"]”Œthe tip tree handbook”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”jŸ  ]”j”  asŒnameids”}”(j÷  jô  jF  jC  j­  jª  jŒ  j‰  jÁ  j¾  j'  j$  jx  ju  jÃ  jÀ  jÝ
  jÚ
  j%  j"  jp  jm  jù  jö  j<  j9  j¥  j¢  j¤  jŸ  j£  j   j7  j4  j   j  j  j
  jê  jç  j-  j*  jT  jQ  jë  jè  j<  j9  j›  j˜  jï  jì  uŒ	nametypes”}”(j÷  ‰jF  ‰j­  ‰jŒ  ‰jÁ  ‰j'  ‰jx  ‰jÃ  ‰jÝ
  ‰j%  ‰jp  ‰jù  ‰j<  ‰j¥  ‰j¤  ˆj£  ‰j7  ‰j   ‰j  ‰jê  ‰j-  ‰jT  ‰jë  ‰j<  ‰j›  ‰jï  ‰uh}”(jô  h¶jC  hÉjª  jI  j‰  jZ  j¾  j  j$  jÄ  ju  j*  jÀ  j{  jÚ
  jÆ  j"  jà
  jm  j(  jö  js  j9  jü  j¢  j?  jŸ  j°  j   j°  j4  jÁ  j  j:  j
  j£  jç  j  j*  jí  jQ  j0  jè  jW  j9  jî  j˜  j?  jì  j«  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”hŒsystem_message”“”)”}”(hhh]”hÛ)”}”(hhh]”hŒAHyperlink target "maintainer-tip-coding-style" is not referenced.”…””}”hj‡  sbah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhj„  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h³Œline”MÚuh1j‚  ubaŒtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.