1.. SPDX-License-Identifier: GPL-2.0 2 3============= 4SoC Subsystem 5============= 6 7Overview 8-------- 9 10The SoC subsystem is a place of aggregation for SoC-specific code. 11The 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 19These "SoC-specific drivers" do not include clock, GPIO etc drivers that have 20other top-level maintainers. The drivers/soc/ directory is generally meant 21for kernel-internal drivers that are used by other drivers to provide SoC- 22specific functionality like identifying an SoC revision or interfacing with 23power domains. 24 25The SoC subsystem also serves as an intermediate location for changes to 26drivers/bus, drivers/firmware, drivers/reset and drivers/memory. The addition 27of new platforms, or the removal of existing ones, often go through the SoC 28tree as a dedicated branch covering multiple subsystems. 29 30The main SoC tree is housed on git.kernel.org: 31 https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/ 32 33Clearly this is quite a wide range of topics, which no one person, or even 34small group of people are capable of maintaining. Instead, the SoC subsystem 35is comprised of many submaintainers, each taking care of individual platforms 36and driver subdirectories. 37In this regard, "platform" usually refers to a series of SoCs from a given 38vendor, for example, Nvidia's series of Tegra SoCs. Many submaintainers operate 39on a vendor level, responsible for multiple product lines. For several reasons, 40including acquisitions/different business units in a company, things vary 41significantly here. The various submaintainers are documented in the 42MAINTAINERS file. 43 44Most of these submaintainers have their own trees where they stage patches, 45sending pull requests to the main SoC tree. These trees are usually, but not 46always, listed in MAINTAINERS. The main SoC maintainers can be reached via the 47alias soc@kernel.org if there is no platform-specific maintainer, or if they 48are unresponsive. 49 50What the SoC tree is not, however, is a location for architecture-specific code 51changes. Each architecture has its own maintainers that are responsible for 52architectural details, CPU errata and the like. 53 54Information for (new) Submaintainers 55------------------------------------ 56 57As new platforms spring up, they often bring with them new submaintainers, 58many of whom work for the silicon vendor, and may not be familiar with the 59process. 60 61Devicetree ABI Stability 62~~~~~~~~~~~~~~~~~~~~~~~~ 63 64Perhaps one of the most important things to highlight is that dt-bindings 65document the ABI between the devicetree and the kernel. 66Please read Documentation/devicetree/bindings/ABI.rst. 67 68If changes are being made to a devicetree that are incompatible with old 69kernels, the devicetree patch should not be applied until the driver is, or an 70appropriate time later. Most importantly, any incompatible changes should be 71clearly pointed out in the patch description and pull request, along with the 72expected impact on existing users, such as bootloaders or other operating 73systems. 74 75Driver Branch Dependencies 76~~~~~~~~~~~~~~~~~~~~~~~~~~ 77 78A common problem is synchronizing changes between device drivers and devicetree 79files. Even if a change is compatible in both directions, this may require 80coordinating how the changes get merged through different maintainer trees. 81 82Usually the branch that includes a driver change will also include the 83corresponding change to the devicetree binding description, to ensure they are 84in fact compatible. This means that the devicetree branch can end up causing 85warnings in the "make dtbs_check" step. If a devicetree change depends on 86missing additions to a header file in include/dt-bindings/, it will fail the 87"make dtbs" step and not get merged. 88 89There are multiple ways to deal with this: 90 91* Avoid defining custom macros in include/dt-bindings/ for hardware constants 92 that can be derived from a datasheet -- binding macros in header files should 93 only be used as a last resort if there is no natural way to define a binding 94 95* Use literal values in the devicetree file in place of macros even when a 96 header is required, and change them to the named representation in a 97 following release 98 99* Defer the devicetree changes to a release after the binding and driver have 100 already been merged 101 102* Change the bindings in a shared immutable branch that is used as the base for 103 both the driver change and the devicetree changes 104 105* Add duplicate defines in the devicetree file guarded by an #ifndef section, 106 removing them in a later release 107 108Devicetree Naming Convention 109~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 110 111The general naming scheme for devicetree files is as follows. The aspects of a 112platform that are set at the SoC level, like CPU cores, are contained in a file 113named $soc.dtsi, for example, jh7100.dtsi. Integration details, that will vary 114from board to board, are described in $soc-$board.dts. An example of this is 115jh7100-beaglev-starlight.dts. Often many boards are variations on a theme, and 116frequently there are intermediate files, such as jh7100-common.dtsi, which sit 117between the $soc.dtsi and $soc-$board.dts files, containing the descriptions of 118common hardware. 119 120Some platforms also have System on Modules, containing an SoC, which are then 121integrated into several different boards. For these platforms, $soc-$som.dtsi 122and $soc-$som-$board.dts are typical. 123 124Directories are usually named after the vendor of the SoC at the time of its 125inclusion, leading to some historical directory names in the tree. 126 127Validating Devicetree Files 128~~~~~~~~~~~~~~~~~~~~~~~~~~~ 129 130``make dtbs_check`` can be used to validate that devicetree files are compliant 131with the dt-bindings that describe the ABI. Please read the section 132"Running checks" of Documentation/devicetree/bindings/writing-schema.rst for 133more information on the validation of devicetrees. 134 135For new platforms, or additions to existing ones, ``make dtbs_check`` should not 136add any new warnings. For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is 137required to not add any new warnings. 138If in any doubt about a devicetree change, reach out to the devicetree 139maintainers. 140 141Branches and Pull Requests 142~~~~~~~~~~~~~~~~~~~~~~~~~~ 143 144Just as the main SoC tree has several branches, it is expected that 145submaintainers will do the same. Driver, defconfig and devicetree changes should 146all be split into separate branches and appear in separate pull requests to the 147SoC maintainers. Each branch should be usable by itself and avoid 148regressions that originate from dependencies on other branches. 149 150Small sets of patches can also be sent as separate emails to soc@kernel.org, 151grouped into the same categories. 152 153If changes do not fit into the normal patterns, there can be additional 154top-level branches, e.g. for a treewide rework, or the addition of new SoC 155platforms including dts files and drivers. 156 157Branches with a lot of changes can benefit from getting split up into separate 158topics branches, even if they end up getting merged into the same branch of the 159SoC tree. An example here would be one branch for devicetree warning fixes, one 160for a rework and one for newly added boards. 161 162Another common way to split up changes is to send an early pull request with the 163majority of the changes at some point between rc1 and rc4, following up with one 164or more smaller pull requests towards the end of the cycle that can add late 165changes or address problems identified while testing the first set. 166 167While there is no cut-off time for late pull requests, it helps to only send 168small branches as time gets closer to the merge window. 169 170Pull requests for bugfixes for the current release can be sent at any time, but 171again having multiple smaller branches is better than trying to combine too many 172patches into one pull request. 173 174The subject line of a pull request should begin with "[GIT PULL]" and made using 175a signed tag, rather than a branch. This tag should contain a short description 176summarising the changes in the pull request. For more detail on sending pull 177requests, please see Documentation/maintainer/pull-requests.rst. 178