Documentation/process/maintainer-soc.rst

1 .. SPDX-License-Identifier: GPL-2.0
8 --------
10 The SoC subsystem is a place of aggregation for SoC-specific code.
13 * devicetrees for 32- & 64-bit ARM and RISC-V
14 * 32-bit ARM board files (arch/arm/mach*)
15 * 32- & 64-bit ARM defconfigs
16 * SoC-specific drivers across architectures, in particular for 32- & 64-bit
17   ARM, RISC-V and Loongarch
19 These "SoC-specific drivers" do not include clock, GPIO etc drivers that have
20 other top-level maintainers. The drivers/soc/ directory is generally meant
21 for kernel-internal drivers that are used by other drivers to provide SoC-
25 The SoC subsystem also serves as an intermediate location for changes to
34 -----------
36 Clearly this is quite a wide range of topics, which no one person, or even
38 is comprised of many submaintainers (platform maintainers), each taking care of
40 In this regard, "platform" usually refers to a series of SoCs from a given
41 vendor, for example, Nvidia's series of Tegra SoCs.  Many submaintainers operate
48 sending pull requests to the main SoC tree.  These trees are usually, but not
51 What the SoC tree is not, however, is a location for architecture-specific code
59 (platform-specific maintainers).  This includes also changes to per-platform or
63 Submitting Patches to the Main SoC Maintainers
69 1. There are no platform-specific maintainers.
71 2. Platform-specific maintainers are unresponsive.
74    first to common mailing lists, pointed out by scripts/get_maintainer.pl, for
75    community review.  After positive community review, work should be sent to
76    soc@kernel.org in one patchset containing new arch/foo/Kconfig entry, DTS
79    platform-specific maintainers, who are going to be responsible for handling
82 Note that the soc@kernel.org is usually not the place to discuss the patches,
83 thus work sent to this address should be already considered as acceptable by
87 ------------------------------------
90 many of whom work for the silicon vendor, and may not be familiar with the
96 Perhaps one of the most important things to highlight is that dt-bindings
100 If changes are being made to a devicetree that are incompatible with old
115 corresponding change to the devicetree binding description, to ensure they are
118 missing additions to a header file in include/dt-bindings/, it will fail the
121 There are multiple ways to deal with this:
123 * Avoid defining custom macros in include/dt-bindings/ for hardware constants
124   that can be derived from a datasheet -- binding macros in header files should
125   only be used as a last resort if there is no natural way to define a binding
128   header is required, and change them to the named representation in a
131 * Defer the devicetree changes to a release after the binding and driver have
146 from board to board, are described in $soc-$board.dts.  An example of this is
147 jh7100-beaglev-starlight.dts.  Often many boards are variations on a theme, and
148 frequently there are intermediate files, such as jh7100-common.dtsi, which sit
149 between the $soc.dtsi and $soc-$board.dts files, containing the descriptions of
153 integrated into several different boards. For these platforms, $soc-$som.dtsi
154 and $soc-$som-$board.dts are typical.
157 inclusion, leading to some historical directory names in the tree.
162 ``make dtbs_check`` can be used to validate that devicetree files are compliant
163 with the dt-bindings that describe the ABI.  Please read the section
164 "Running checks" of Documentation/devicetree/bindings/writing-schema.rst for
167 For new platforms, or additions to existing ones, ``make dtbs_check`` should not
168 add any new warnings.  For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is
169 required to not add any new warnings.
170 If in any doubt about a devicetree change, reach out to the devicetree
178 all be split into separate branches and appear in separate pull requests to the
182 Small sets of patches can also be sent as separate emails to soc@kernel.org,
186 top-level branches, e.g. for a treewide rework, or the addition of new SoC
191 SoC tree.  An example here would be one branch for devicetree warning fixes, one
192 for a rework and one for newly added boards.
194 Another common way to split up changes is to send an early pull request with the
195 majority of the changes at some point between rc1 and rc4, following up with one
199 While there is no cut-off time for late pull requests, it helps to only send
200 small branches as time gets closer to the merge window.
203 again having multiple smaller branches is better than trying to combine too many
204 patches into one pull request.
209 requests, please see Documentation/maintainer/pull-requests.rst.