€•ªƒ      Œ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-soc”Œ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-soc”Œ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-soc”Œ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-soc”Œ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-soc”Œ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-soc”Œ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-soc.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒSoC Subsystem”h]”hŒSoC Subsystem”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒOverview”h]”hŒOverview”…””}”(hhÌhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhÉhžhhŸh³h KubhŒ	paragraph”“”)”}”(hŒlThe SoC subsystem is a place of aggregation for SoC-specific code.
The main components of the subsystem are:”h]”hŒlThe SoC subsystem is a place of aggregation for SoC-specific code.
The main components of the subsystem are:”…””}”(hhÜhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K
hhÉhžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ1devicetrees (DTS) for 32- & 64-bit ARM and RISC-V”h]”hÛ)”}”(hhóh]”hŒ1devicetrees (DTS) for 32- & 64-bit ARM and RISC-V”…””}”(hhõhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khhñubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhhìhžhhŸh³h Nubhð)”}”(hŒ'32-bit ARM board files (arch/arm/mach*)”h]”hÛ)”}”(hj
  h]”hŒ'32-bit ARM board files (arch/arm/mach*)”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhhìhžhhŸh³h Nubhð)”}”(hŒ32- & 64-bit ARM defconfigs”h]”hÛ)”}”(hj!  h]”hŒ32- & 64-bit ARM defconfigs”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhhìhžhhŸh³h Nubhð)”}”(hŒdSoC-specific drivers across architectures, in particular for 32- & 64-bit
ARM, RISC-V and Loongarch
”h]”hÛ)”}”(hŒcSoC-specific drivers across architectures, in particular for 32- & 64-bit
ARM, RISC-V and Loongarch”h]”hŒcSoC-specific drivers across architectures, in particular for 32- & 64-bit
ARM, RISC-V and Loongarch”…””}”(hj:  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khj6  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhhìhžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1hêhŸh³h KhhÉhžhubhÛ)”}”(hX>  These "SoC-specific drivers" do not include clock, GPIO etc drivers that have
other top-level maintainers. The drivers/soc/ directory is generally meant
for kernel-internal drivers that are used by other drivers to provide SoC-
specific functionality like identifying an SoC revision or interfacing with
power domains.”h]”hXB  These â€œSoC-specific driversâ€ do not include clock, GPIO etc drivers that have
other top-level maintainers. The drivers/soc/ directory is generally meant
for kernel-internal drivers that are used by other drivers to provide SoC-
specific functionality like identifying an SoC revision or interfacing with
power domains.”…””}”(hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KhhÉhžhubhÛ)”}”(hX  The SoC subsystem also serves as an intermediate location for changes to
drivers/bus, drivers/firmware, drivers/reset and drivers/memory.  The addition
of new platforms, or the removal of existing ones, often go through the SoC
tree as a dedicated branch covering multiple subsystems.”h]”hX  The SoC subsystem also serves as an intermediate location for changes to
drivers/bus, drivers/firmware, drivers/reset and drivers/memory.  The addition
of new platforms, or the removal of existing ones, often go through the SoC
tree as a dedicated branch covering multiple subsystems.”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KhhÉhžhubhŒdefinition_list”“”)”}”(hhh]”hŒdefinition_list_item”“”)”}”(hŒlThe main SoC tree is housed on git.kernel.org:
https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/
”h]”(hŒterm”“”)”}”(hŒ.The main SoC tree is housed on git.kernel.org:”h]”hŒ.The main SoC tree is housed on git.kernel.org:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j}  hŸh³h Khjy  ubhŒ
definition”“”)”}”(hhh]”hÛ)”}”(hŒ<https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/”h]”hŒ	reference”“”)”}”(hj”  h]”hŒ<https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j”  uh1j–  hj’  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjy  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jw  hŸh³h Khjt  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jr  hhÉhžhhŸh³h Nubeh}”(h]”Œoverview”ah ]”h"]”Œoverview”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒMaintainers”h]”hŒMaintainers”…””}”(hjÉ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÆ  hžhhŸh³h K"ubhÛ)”}”(hX§  Clearly this is quite a wide range of topics, which no one person, or even
small group of people are capable of maintaining.  Instead, the SoC subsystem
is comprised of many submaintainers (platform maintainers), each taking care of
individual platforms and driver subdirectories.
In this regard, "platform" usually refers to a series of SoCs from a given
vendor, for example, Nvidia's series of Tegra SoCs.  Many submaintainers operate
on a vendor level, responsible for multiple product lines.  For several reasons,
including acquisitions/different business units in a company, things vary
significantly here.  The various submaintainers are documented in the
MAINTAINERS file.”h]”hX­  Clearly this is quite a wide range of topics, which no one person, or even
small group of people are capable of maintaining.  Instead, the SoC subsystem
is comprised of many submaintainers (platform maintainers), each taking care of
individual platforms and driver subdirectories.
In this regard, â€œplatformâ€ usually refers to a series of SoCs from a given
vendor, for example, Nvidiaâ€™s series of Tegra SoCs.  Many submaintainers operate
on a vendor level, responsible for multiple product lines.  For several reasons,
including acquisitions/different business units in a company, things vary
significantly here.  The various submaintainers are documented in the
MAINTAINERS file.”…””}”(hj×  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K$hjÆ  hžhubhÛ)”}”(hŒ¸Most of these submaintainers have their own trees where they stage patches,
sending pull requests to the main SoC tree.  These trees are usually, but not
always, listed in MAINTAINERS.”h]”hŒ¸Most of these submaintainers have their own trees where they stage patches,
sending pull requests to the main SoC tree.  These trees are usually, but not
always, listed in MAINTAINERS.”…””}”(hjå  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K/hjÆ  hžhubhÛ)”}”(hŒÌWhat the SoC tree is not, however, is a location for architecture-specific code
changes.  Each architecture has its own maintainers that are responsible for
architectural details, CPU errata and the like.”h]”hŒÌWhat the SoC tree is not, however, is a location for architecture-specific code
changes.  Each architecture has its own maintainers that are responsible for
architectural details, CPU errata and the like.”…””}”(hjó  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K3hjÆ  hžhubhµ)”}”(hhh]”(hº)”}”(hŒ Submitting Patches for Given SoC”h]”hŒ Submitting Patches for Given SoC”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h K8ubhÛ)”}”(hX¤  All typical platform related patches should be sent via SoC submaintainers
(platform-specific maintainers).  This includes also changes to per-platform or
shared defconfigs. Note that scripts/get_maintainer.pl might not provide
correct addresses for the shared defconfig, so ignore its output and manually
create CC-list based on MAINTAINERS file or use something like
``scripts/get_maintainer.pl -f drivers/soc/FOO/``).”h]”(hXq  All typical platform related patches should be sent via SoC submaintainers
(platform-specific maintainers).  This includes also changes to per-platform or
shared defconfigs. Note that scripts/get_maintainer.pl might not provide
correct addresses for the shared defconfig, so ignore its output and manually
create CC-list based on MAINTAINERS file or use something like
”…””}”(hj  hžhhŸNh NubhŒliteral”“”)”}”(hŒ1``scripts/get_maintainer.pl -f drivers/soc/FOO/``”h]”hŒ-scripts/get_maintainer.pl -f drivers/soc/FOO/”…””}”(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  hžhubeh}”(h]”Œ submitting-patches-for-given-soc”ah ]”h"]”Œ submitting patches for given soc”ah$]”h&]”uh1h´hjÆ  hžhhŸh³h K8ubhµ)”}”(hhh]”(hº)”}”(hŒ.Submitting Patches to the Main SoC Maintainers”h]”hŒ.Submitting Patches to the Main SoC Maintainers”…””}”(hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj<  hžhhŸh³h KBubhÛ)”}”(hŒ]The main SoC maintainers can be reached via the alias soc@kernel.org only in
following cases:”h]”(hŒ6The main SoC maintainers can be reached via the alias ”…””}”(hjM  hžhhŸNh Nubj—  )”}”(hŒsoc@kernel.org”h]”hŒsoc@kernel.org”…””}”(hjU  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:soc@kernel.org”uh1j–  hjM  ubhŒ only in
following cases:”…””}”(hjM  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KDhj<  hžhubhŒenumerated_list”“”)”}”(hhh]”(hð)”}”(hŒ,There are no platform-specific maintainers.
”h]”hÛ)”}”(hŒ+There are no platform-specific maintainers.”h]”hŒ+There are no platform-specific maintainers.”…””}”(hjx  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KGhjt  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhjq  hžhhŸh³h Nubhð)”}”(hŒ0Platform-specific maintainers are unresponsive.
”h]”hÛ)”}”(hŒ/Platform-specific maintainers are unresponsive.”h]”hŒ/Platform-specific maintainers are unresponsive.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KIhjŒ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhjq  hžhhŸh³h Nubhð)”}”(hX*  Introducing a completely new SoC platform.  Such new SoC work should be sent
first to common mailing lists, pointed out by scripts/get_maintainer.pl, for
community review.  After positive community review, work should be sent to
soc@kernel.org in one patchset containing new arch/foo/Kconfig entry, DTS
files, MAINTAINERS file entry and optionally initial drivers with their
Devicetree bindings.  The MAINTAINERS file entry should list new
platform-specific maintainers, who are going to be responsible for handling
patches for the platform from now on.
”h]”hÛ)”}”(hX)  Introducing a completely new SoC platform.  Such new SoC work should be sent
first to common mailing lists, pointed out by scripts/get_maintainer.pl, for
community review.  After positive community review, work should be sent to
soc@kernel.org in one patchset containing new arch/foo/Kconfig entry, DTS
files, MAINTAINERS file entry and optionally initial drivers with their
Devicetree bindings.  The MAINTAINERS file entry should list new
platform-specific maintainers, who are going to be responsible for handling
patches for the platform from now on.”h]”(hŒåIntroducing a completely new SoC platform.  Such new SoC work should be sent
first to common mailing lists, pointed out by scripts/get_maintainer.pl, for
community review.  After positive community review, work should be sent to
”…””}”(hj¨  hžhhŸNh Nubj—  )”}”(hŒsoc@kernel.org”h]”hŒsoc@kernel.org”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:soc@kernel.org”uh1j–  hj¨  ubhX6   in one patchset containing new arch/foo/Kconfig entry, DTS
files, MAINTAINERS file entry and optionally initial drivers with their
Devicetree bindings.  The MAINTAINERS file entry should list new
platform-specific maintainers, who are going to be responsible for handling
patches for the platform from now on.”…””}”(hj¨  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KKhj¤  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhjq  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1jo  hj<  hžhhŸh³h KGubhÛ)”}”(hŒ©Note that the soc@kernel.org is usually not the place to discuss the patches,
thus work sent to this address should be already considered as acceptable by
the community.”h]”(hŒNote that the ”…””}”(hjÛ  hžhhŸNh Nubj—  )”}”(hŒsoc@kernel.org”h]”hŒsoc@kernel.org”…””}”(hjã  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:soc@kernel.org”uh1j–  hjÛ  ubhŒ is usually not the place to discuss the patches,
thus work sent to this address should be already considered as acceptable by
the community.”…””}”(hjÛ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KThj<  hžhubeh}”(h]”Œ.submitting-patches-to-the-main-soc-maintainers”ah ]”h"]”Œ.submitting patches to the main soc maintainers”ah$]”h&]”uh1h´hjÆ  hžhhŸh³h KBubeh}”(h]”Œmaintainers”ah ]”h"]”Œmaintainers”ah$]”h&]”uh1h´hh¶hžhhŸh³h K"ubhµ)”}”(hhh]”(hº)”}”(hŒ$Information for (new) Submaintainers”h]”hŒ$Information for (new) Submaintainers”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h KYubhÛ)”}”(hŒžAs new platforms spring up, they often bring with them new submaintainers,
many of whom work for the silicon vendor, and may not be familiar with the
process.”h]”hŒžAs new platforms spring up, they often bring with them new submaintainers,
many of whom work for the silicon vendor, and may not be familiar with the
process.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K[hj  hžhubhµ)”}”(hhh]”(hº)”}”(hŒDevicetree ABI Stability”h]”hŒDevicetree ABI Stability”…””}”(hj/  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj,  hžhhŸh³h K`ubhÛ)”}”(hŒ¸Perhaps one of the most important things to highlight is that dt-bindings
document the ABI between the devicetree and the kernel.
Please read Documentation/devicetree/bindings/ABI.rst.”h]”hŒ¸Perhaps one of the most important things to highlight is that dt-bindings
document the ABI between the devicetree and the kernel.
Please read Documentation/devicetree/bindings/ABI.rst.”…””}”(hj=  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kbhj,  hžhubhÛ)”}”(hXx  If changes are being made to a DTS that are incompatible with old
kernels, the DTS patch should not be applied until the driver is, or an
appropriate time later.  Most importantly, any incompatible changes should be
clearly pointed out in the patch description and pull request, along with the
expected impact on existing users, such as bootloaders or other operating
systems.”h]”hXx  If changes are being made to a DTS that are incompatible with old
kernels, the DTS patch should not be applied until the driver is, or an
appropriate time later.  Most importantly, any incompatible changes should be
clearly pointed out in the patch description and pull request, along with the
expected impact on existing users, such as bootloaders or other operating
systems.”…””}”(hjK  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kfhj,  hžhubeh}”(h]”Œdevicetree-abi-stability”ah ]”h"]”Œdevicetree abi stability”ah$]”h&]”uh1h´hj  hžhhŸh³h K`ubhµ)”}”(hhh]”(hº)”}”(hŒDriver Branch Dependencies”h]”hŒDriver Branch Dependencies”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hja  hžhhŸh³h KnubhÛ)”}”(hŒæA common problem is synchronizing changes between device drivers and devicetree
files. Even if a change is compatible in both directions, this may require
coordinating how the changes get merged through different maintainer trees.”h]”hŒæA common problem is synchronizing changes between device drivers and devicetree
files. Even if a change is compatible in both directions, this may require
coordinating how the changes get merged through different maintainer trees.”…””}”(hjr  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kphja  hžhubhÛ)”}”(hX¤  Usually the branch that includes a driver change will also include the
corresponding change to the devicetree binding description, to ensure they are
in fact compatible.  This means that the devicetree branch can end up causing
warnings in the ``make dtbs_check`` step.  If a devicetree change depends on
missing additions to a header file in include/dt-bindings/, it will fail the
``make dtbs`` step and not get merged.”h]”(hŒôUsually the branch that includes a driver change will also include the
corresponding change to the devicetree binding description, to ensure they are
in fact compatible.  This means that the devicetree branch can end up causing
warnings in the ”…””}”(hj€  hžhhŸNh Nubj  )”}”(hŒ``make dtbs_check``”h]”hŒmake dtbs_check”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj€  ubhŒw step.  If a devicetree change depends on
missing additions to a header file in include/dt-bindings/, it will fail the
”…””}”(hj€  hžhhŸNh Nubj  )”}”(hŒ``make dtbs``”h]”hŒ	make dtbs”…””}”(hjš  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj€  ubhŒ step and not get merged.”…””}”(hj€  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kthja  hžhubhÛ)”}”(hŒ*There are multiple ways to deal with this:”h]”hŒ*There are multiple ways to deal with this:”…””}”(hj²  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K{hja  hžhubhë)”}”(hhh]”(hð)”}”(hŒçAvoid defining custom macros in include/dt-bindings/ for hardware constants
that can be derived from a datasheet -- binding macros in header files should
only be used as a last resort if there is no natural way to define a binding
”h]”hÛ)”}”(hŒæAvoid defining custom macros in include/dt-bindings/ for hardware constants
that can be derived from a datasheet -- binding macros in header files should
only be used as a last resort if there is no natural way to define a binding”h]”hŒæAvoid defining custom macros in include/dt-bindings/ for hardware constants
that can be derived from a datasheet -- binding macros in header files should
only be used as a last resort if there is no natural way to define a binding”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K}hjÃ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhjÀ  hžhhŸh³h Nubhð)”}”(hŒ Use literal values in the devicetree file in place of macros even when a
header is required, and change them to the named representation in a
following release
”h]”hÛ)”}”(hŒŸUse literal values in the devicetree file in place of macros even when a
header is required, and change them to the named representation in a
following release”h]”hŒŸUse literal values in the devicetree file in place of macros even when a
header is required, and change them to the named representation in a
following release”…””}”(hjß  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KhjÛ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhjÀ  hžhhŸh³h Nubhð)”}”(hŒ`Defer the devicetree changes to a release after the binding and driver have
already been merged
”h]”hÛ)”}”(hŒ_Defer the devicetree changes to a release after the binding and driver have
already been merged”h]”hŒ_Defer the devicetree changes to a release after the binding and driver have
already been merged”…””}”(hj÷  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K…hjó  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhjÀ  hžhhŸh³h Nubhð)”}”(hŒ€Change the bindings in a shared immutable branch that is used as the base for
both the driver change and the devicetree changes
”h]”hÛ)”}”(hŒChange the bindings in a shared immutable branch that is used as the base for
both the driver change and the devicetree changes”h]”hŒChange the bindings in a shared immutable branch that is used as the base for
both the driver change and the devicetree changes”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kˆhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhjÀ  hžhhŸh³h Nubhð)”}”(hŒmAdd duplicate defines in the devicetree file guarded by an #ifndef section,
removing them in a later release
”h]”hÛ)”}”(hŒlAdd duplicate defines in the devicetree file guarded by an #ifndef section,
removing them in a later release”h]”hŒlAdd duplicate defines in the devicetree file guarded by an #ifndef section,
removing them in a later release”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K‹hj#  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hïhjÀ  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jT  jU  uh1hêhŸh³h K}hja  hžhubeh}”(h]”Œdriver-branch-dependencies”ah ]”h"]”Œdriver branch dependencies”ah$]”h&]”uh1h´hj  hžhhŸh³h Knubhµ)”}”(hhh]”(hº)”}”(hŒDevicetree Naming Convention”h]”hŒDevicetree Naming Convention”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjI  hžhhŸh³h KubhÛ)”}”(hX=  The general naming scheme for devicetree files is as follows.  The aspects of a
platform that are set at the SoC level, like CPU cores, are contained in a file
named $soc.dtsi, for example, jh7100.dtsi.  Integration details, that will vary
from board to board, are described in $soc-$board.dts.  An example of this is
jh7100-beaglev-starlight.dts.  Often many boards are variations on a theme, and
frequently there are intermediate files, such as jh7100-common.dtsi, which sit
between the $soc.dtsi and $soc-$board.dts files, containing the descriptions of
common hardware.”h]”hX=  The general naming scheme for devicetree files is as follows.  The aspects of a
platform that are set at the SoC level, like CPU cores, are contained in a file
named $soc.dtsi, for example, jh7100.dtsi.  Integration details, that will vary
from board to board, are described in $soc-$board.dts.  An example of this is
jh7100-beaglev-starlight.dts.  Often many boards are variations on a theme, and
frequently there are intermediate files, such as jh7100-common.dtsi, which sit
between the $soc.dtsi and $soc-$board.dts files, containing the descriptions of
common hardware.”…””}”(hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K‘hjI  hžhubhÛ)”}”(hŒÁSome platforms also have System on Modules, containing an SoC, which are then
integrated into several different boards. For these platforms, $soc-$som.dtsi
and $soc-$som-$board.dts are typical.”h]”hŒÁSome platforms also have System on Modules, containing an SoC, which are then
integrated into several different boards. For these platforms, $soc-$som.dtsi
and $soc-$som-$board.dts are typical.”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KšhjI  hžhubhÛ)”}”(hŒDirectories are usually named after the vendor of the SoC at the time of its
inclusion, leading to some historical directory names in the tree.”h]”hŒDirectories are usually named after the vendor of the SoC at the time of its
inclusion, leading to some historical directory names in the tree.”…””}”(hjv  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KžhjI  hžhubeh}”(h]”Œdevicetree-naming-convention”ah ]”h"]”Œdevicetree naming convention”ah$]”h&]”uh1h´hj  hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒValidating Devicetree Files”h]”hŒValidating Devicetree Files”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjŒ  hžhhŸh³h K¢ubhÛ)”}”(hX  ``make dtbs_check`` can be used to validate that devicetree files are compliant
with the dt-bindings that describe the ABI.  Please read the section
"Running checks" of Documentation/devicetree/bindings/writing-schema.rst for
more information on the validation of devicetrees.”h]”(j  )”}”(hŒ``make dtbs_check``”h]”hŒmake dtbs_check”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubhX   can be used to validate that devicetree files are compliant
with the dt-bindings that describe the ABI.  Please read the section
â€œRunning checksâ€ of Documentation/devicetree/bindings/writing-schema.rst for
more information on the validation of devicetrees.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K¤hjŒ  hžhubhÛ)”}”(hX  For new platforms, or additions to existing ones, ``make dtbs_check`` should not
add any new warnings.  For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is
required to not add any new warnings.
If in any doubt about a devicetree change, reach out to the devicetree
maintainers.”h]”(hŒ2For new platforms, or additions to existing ones, ”…””}”(hj¹  hžhhŸNh Nubj  )”}”(hŒ``make dtbs_check``”h]”hŒmake dtbs_check”…””}”(hjÁ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¹  ubhŒ? should not
add any new warnings.  For RISC-V and Samsung SoC, ”…””}”(hj¹  hžhhŸNh Nubj  )”}”(hŒ``make dtbs_check W=1``”h]”hŒmake dtbs_check W=1”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj¹  ubhŒ} is
required to not add any new warnings.
If in any doubt about a devicetree change, reach out to the devicetree
maintainers.”…””}”(hj¹  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K©hjŒ  hžhubeh}”(h]”Œvalidating-devicetree-files”ah ]”h"]”Œvalidating devicetree files”ah$]”h&]”uh1h´hj  hžhhŸh³h K¢ubhµ)”}”(hhh]”(hº)”}”(hŒBranches and Pull Requests”h]”hŒBranches and Pull Requests”…””}”(hjö  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjó  hžhhŸh³h K°ubhÛ)”}”(hXg  Just as the main SoC tree has several branches, it is expected that
submaintainers will do the same. Driver, defconfig and devicetree changes should
all be split into separate branches and appear in separate pull requests to the
SoC maintainers.  Each branch should be usable by itself and avoid
regressions that originate from dependencies on other branches.”h]”hXg  Just as the main SoC tree has several branches, it is expected that
submaintainers will do the same. Driver, defconfig and devicetree changes should
all be split into separate branches and appear in separate pull requests to the
SoC maintainers.  Each branch should be usable by itself and avoid
regressions that originate from dependencies on other branches.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K²hjó  hžhubhÛ)”}”(hŒnSmall sets of patches can also be sent as separate emails to soc@kernel.org,
grouped into the same categories.”h]”(hŒ=Small sets of patches can also be sent as separate emails to ”…””}”(hj  hžhhŸNh Nubj—  )”}”(hŒsoc@kernel.org”h]”hŒsoc@kernel.org”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:soc@kernel.org”uh1j–  hj  ubhŒ#,
grouped into the same categories.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K¸hjó  hžhubhÛ)”}”(hŒ½If changes do not fit into the normal patterns, there can be additional
top-level branches, e.g. for a treewide rework, or the addition of new SoC
platforms including dts files and drivers.”h]”hŒ½If changes do not fit into the normal patterns, there can be additional
top-level branches, e.g. for a treewide rework, or the addition of new SoC
platforms including dts files and drivers.”…””}”(hj4  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K»hjó  hžhubhÛ)”}”(hX  Branches with a lot of changes can benefit from getting split up into separate
topics branches, even if they end up getting merged into the same branch of the
SoC tree.  An example here would be one branch for devicetree warning fixes, one
for a rework and one for newly added boards.”h]”hX  Branches with a lot of changes can benefit from getting split up into separate
topics branches, even if they end up getting merged into the same branch of the
SoC tree.  An example here would be one branch for devicetree warning fixes, one
for a rework and one for newly added boards.”…””}”(hjB  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K¿hjó  hžhubhÛ)”}”(hX2  Another common way to split up changes is to send an early pull request with the
majority of the changes at some point between rc1 and rc4, following up with one
or more smaller pull requests towards the end of the cycle that can add late
changes or address problems identified while testing the first set.”h]”hX2  Another common way to split up changes is to send an early pull request with the
majority of the changes at some point between rc1 and rc4, following up with one
or more smaller pull requests towards the end of the cycle that can add late
changes or address problems identified while testing the first set.”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÄhjó  hžhubhÛ)”}”(hŒ„While there is no cut-off time for late pull requests, it helps to only send
small branches as time gets closer to the merge window.”h]”hŒ„While there is no cut-off time for late pull requests, it helps to only send
small branches as time gets closer to the merge window.”…””}”(hj^  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÉhjó  hžhubhÛ)”}”(hŒ¿Pull requests for bugfixes for the current release can be sent at any time, but
again having multiple smaller branches is better than trying to combine too many
patches into one pull request.”h]”hŒ¿Pull requests for bugfixes for the current release can be sent at any time, but
again having multiple smaller branches is better than trying to combine too many
patches into one pull request.”…””}”(hjl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÌhjó  hžhubhÛ)”}”(hX0  The subject line of a pull request should begin with "[GIT PULL]" and made using
a signed tag, rather than a branch.  This tag should contain a short description
summarising the changes in the pull request.  For more detail on sending pull
requests, please see Documentation/maintainer/pull-requests.rst.”h]”hX4  The subject line of a pull request should begin with â€œ[GIT PULL]â€ and made using
a signed tag, rather than a branch.  This tag should contain a short description
summarising the changes in the pull request.  For more detail on sending pull
requests, please see Documentation/maintainer/pull-requests.rst.”…””}”(hjz  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KÐhjó  hžhubeh}”(h]”Œbranches-and-pull-requests”ah ]”h"]”Œbranches and pull requests”ah$]”h&]”uh1h´hj  hžhhŸh³h K°ubeh}”(h]”Œ"information-for-new-submaintainers”ah ]”h"]”Œ$information for (new) submaintainers”ah$]”h&]”uh1h´hh¶hžhhŸh³h KYubeh}”(h]”Œsoc-subsystem”ah ]”h"]”Œsoc subsystem”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(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”}”Œnameids”}”(j  jš  jÃ  jÀ  j
  j  j9  j6  j  jÿ  j•  j’  j^  j[  jF  jC  j‰  j†  jð  jí  j  jŠ  uŒ	nametypes”}”(j  ‰jÃ  ‰j
  ‰j9  ‰j  ‰j•  ‰j^  ‰jF  ‰j‰  ‰jð  ‰j  ‰uh}”(jš  h¶jÀ  hÉj  jÆ  j6  j  jÿ  j<  j’  j  j[  j,  jC  ja  j†  jI  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”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.