Documentation/process/maintainer-soc.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =============
   4 SoC Subsystem
   5 =============
   6
   7 Overview
   8 --------
   9
  10 The SoC subsystem is a place of aggregation for SoC-specific code.
  11 The main components of the subsystem are:
  12
  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
  18
  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-
  22 specific functionality like identifying an SoC revision or interfacing with
  23 power domains.
  24
  25 The SoC subsystem also serves as an intermediate location for changes to
  26 drivers/bus, drivers/firmware, drivers/reset and drivers/memory.  The addition
  27 of new platforms, or the removal of existing ones, often go through the SoC
  28 tree as a dedicated branch covering multiple subsystems.
  29
  30 The main SoC tree is housed on git.kernel.org:
  31   https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/
  32
  33 Maintainers
  34 -----------
  35
  36 Clearly this is quite a wide range of topics, which no one person, or even
  37 small group of people are capable of maintaining.  Instead, the SoC subsystem
  38 is comprised of many submaintainers (platform maintainers), each taking care of
  39 individual platforms and driver subdirectories.
  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
  42 on a vendor level, responsible for multiple product lines.  For several reasons,
  43 including acquisitions/different business units in a company, things vary
  44 significantly here.  The various submaintainers are documented in the
  45 MAINTAINERS file.
  46
  47 Most of these submaintainers have their own trees where they stage patches,
  48 sending pull requests to the main SoC tree.  These trees are usually, but not
  49 always, listed in MAINTAINERS.
  50
  51 What the SoC tree is not, however, is a location for architecture-specific code
  52 changes.  Each architecture has its own maintainers that are responsible for
  53 architectural details, CPU errata and the like.
  54
  55 Submitting Patches for Given SoC
  56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57
  58 All typical platform related patches should be sent via SoC submaintainers
  59 (platform-specific maintainers).  This includes also changes to per-platform or
  60 shared defconfigs (scripts/get_maintainer.pl might not provide correct
  61 addresses in such case).
  62
  63 Submitting Patches to the Main SoC Maintainers
  64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65
  66 The main SoC maintainers can be reached via the alias soc@kernel.org only in
  67 following cases:
  68
  69 1. There are no platform-specific maintainers.
  70
  71 2. Platform-specific maintainers are unresponsive.
  72
  73 3. Introducing a completely new SoC platform.  Such new SoC work should be sent
  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
  77    files, MAINTAINERS file entry and optionally initial drivers with their
  78    Devicetree bindings.  The MAINTAINERS file entry should list new
  79    platform-specific maintainers, who are going to be responsible for handling
  80    patches for the platform from now on.
  81
  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
  84 the community.
  85
  86 Information for (new) Submaintainers
  87 ------------------------------------
  88
  89 As new platforms spring up, they often bring with them new submaintainers,
  90 many of whom work for the silicon vendor, and may not be familiar with the
  91 process.
  92
  93 Devicetree ABI Stability
  94 ~~~~~~~~~~~~~~~~~~~~~~~~
  95
  96 Perhaps one of the most important things to highlight is that dt-bindings
  97 document the ABI between the devicetree and the kernel.
  98 Please read Documentation/devicetree/bindings/ABI.rst.
  99
 100 If changes are being made to a devicetree that are incompatible with old
 101 kernels, the devicetree patch should not be applied until the driver is, or an
 102 appropriate time later.  Most importantly, any incompatible changes should be
 103 clearly pointed out in the patch description and pull request, along with the
 104 expected impact on existing users, such as bootloaders or other operating
 105 systems.
 106
 107 Driver Branch Dependencies
 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 109
 110 A common problem is synchronizing changes between device drivers and devicetree
 111 files. Even if a change is compatible in both directions, this may require
 112 coordinating how the changes get merged through different maintainer trees.
 113
 114 Usually the branch that includes a driver change will also include the
 115 corresponding change to the devicetree binding description, to ensure they are
 116 in fact compatible.  This means that the devicetree branch can end up causing
 117 warnings in the "make dtbs_check" step.  If a devicetree change depends on
 118 missing additions to a header file in include/dt-bindings/, it will fail the
 119 "make dtbs" step and not get merged.
 120
 121 There are multiple ways to deal with this:
 122
 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
 126
 127 * Use literal values in the devicetree file in place of macros even when a
 128   header is required, and change them to the named representation in a
 129   following release
 130
 131 * Defer the devicetree changes to a release after the binding and driver have
 132   already been merged
 133
 134 * Change the bindings in a shared immutable branch that is used as the base for
 135   both the driver change and the devicetree changes
 136
 137 * Add duplicate defines in the devicetree file guarded by an #ifndef section,
 138   removing them in a later release
 139
 140 Devicetree Naming Convention
 141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 142
 143 The general naming scheme for devicetree files is as follows.  The aspects of a
 144 platform that are set at the SoC level, like CPU cores, are contained in a file
 145 named $soc.dtsi, for example, jh7100.dtsi.  Integration details, that will vary
 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
 150 common hardware.
 151
 152 Some platforms also have System on Modules, containing an SoC, which are then
 153 integrated into several different boards. For these platforms, $soc-$som.dtsi
 154 and $soc-$som-$board.dts are typical.
 155
 156 Directories are usually named after the vendor of the SoC at the time of its
 157 inclusion, leading to some historical directory names in the tree.
 158
 159 Validating Devicetree Files
 160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 161
 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
 165 more information on the validation of devicetrees.
 166
 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
 171 maintainers.
 172
 173 Branches and Pull Requests
 174 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 175
 176 Just as the main SoC tree has several branches, it is expected that
 177 submaintainers will do the same. Driver, defconfig and devicetree changes should
 178 all be split into separate branches and appear in separate pull requests to the
 179 SoC maintainers.  Each branch should be usable by itself and avoid
 180 regressions that originate from dependencies on other branches.
 181
 182 Small sets of patches can also be sent as separate emails to soc@kernel.org,
 183 grouped into the same categories.
 184
 185 If changes do not fit into the normal patterns, there can be additional
 186 top-level branches, e.g. for a treewide rework, or the addition of new SoC
 187 platforms including dts files and drivers.
 188
 189 Branches with a lot of changes can benefit from getting split up into separate
 190 topics branches, even if they end up getting merged into the same branch of the
 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.
 193
 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
 196 or more smaller pull requests towards the end of the cycle that can add late
 197 changes or address problems identified while testing the first set.
 198
 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.
 201
 202 Pull requests for bugfixes for the current release can be sent at any time, but
 203 again having multiple smaller branches is better than trying to combine too many
 204 patches into one pull request.
 205
 206 The subject line of a pull request should begin with "[GIT PULL]" and made using
 207 a signed tag, rather than a branch.  This tag should contain a short description
 208 summarising the changes in the pull request.  For more detail on sending pull
 209 requests, please see Documentation/maintainer/pull-requests.rst.