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 33Maintainers 34----------- 35 36Clearly this is quite a wide range of topics, which no one person, or even 37small group of people are capable of maintaining. Instead, the SoC subsystem 38is comprised of many submaintainers (platform maintainers), each taking care of 39individual platforms and driver subdirectories. 40In this regard, "platform" usually refers to a series of SoCs from a given 41vendor, for example, Nvidia's series of Tegra SoCs. Many submaintainers operate 42on a vendor level, responsible for multiple product lines. For several reasons, 43including acquisitions/different business units in a company, things vary 44significantly here. The various submaintainers are documented in the 45MAINTAINERS file. 46 47Most of these submaintainers have their own trees where they stage patches, 48sending pull requests to the main SoC tree. These trees are usually, but not 49always, listed in MAINTAINERS. 50 51What the SoC tree is not, however, is a location for architecture-specific code 52changes. Each architecture has its own maintainers that are responsible for 53architectural details, CPU errata and the like. 54 55Submitting Patches for Given SoC 56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 57 58All typical platform related patches should be sent via SoC submaintainers 59(platform-specific maintainers). This includes also changes to per-platform or 60shared defconfigs (scripts/get_maintainer.pl might not provide correct 61addresses in such case). 62 63Submitting Patches to the Main SoC Maintainers 64~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 65 66The main SoC maintainers can be reached via the alias soc@kernel.org only in 67following cases: 68 691. There are no platform-specific maintainers. 70 712. Platform-specific maintainers are unresponsive. 72 733. 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 82Note that the soc@kernel.org is usually not the place to discuss the patches, 83thus work sent to this address should be already considered as acceptable by 84the community. 85 86Information for (new) Submaintainers 87------------------------------------ 88 89As new platforms spring up, they often bring with them new submaintainers, 90many of whom work for the silicon vendor, and may not be familiar with the 91process. 92 93Devicetree ABI Stability 94~~~~~~~~~~~~~~~~~~~~~~~~ 95 96Perhaps one of the most important things to highlight is that dt-bindings 97document the ABI between the devicetree and the kernel. 98Please read Documentation/devicetree/bindings/ABI.rst. 99 100If changes are being made to a devicetree that are incompatible with old 101kernels, the devicetree patch should not be applied until the driver is, or an 102appropriate time later. Most importantly, any incompatible changes should be 103clearly pointed out in the patch description and pull request, along with the 104expected impact on existing users, such as bootloaders or other operating 105systems. 106 107Driver Branch Dependencies 108~~~~~~~~~~~~~~~~~~~~~~~~~~ 109 110A common problem is synchronizing changes between device drivers and devicetree 111files. Even if a change is compatible in both directions, this may require 112coordinating how the changes get merged through different maintainer trees. 113 114Usually the branch that includes a driver change will also include the 115corresponding change to the devicetree binding description, to ensure they are 116in fact compatible. This means that the devicetree branch can end up causing 117warnings in the "make dtbs_check" step. If a devicetree change depends on 118missing additions to a header file in include/dt-bindings/, it will fail the 119"make dtbs" step and not get merged. 120 121There 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 140Devicetree Naming Convention 141~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 142 143The general naming scheme for devicetree files is as follows. The aspects of a 144platform that are set at the SoC level, like CPU cores, are contained in a file 145named $soc.dtsi, for example, jh7100.dtsi. Integration details, that will vary 146from board to board, are described in $soc-$board.dts. An example of this is 147jh7100-beaglev-starlight.dts. Often many boards are variations on a theme, and 148frequently there are intermediate files, such as jh7100-common.dtsi, which sit 149between the $soc.dtsi and $soc-$board.dts files, containing the descriptions of 150common hardware. 151 152Some platforms also have System on Modules, containing an SoC, which are then 153integrated into several different boards. For these platforms, $soc-$som.dtsi 154and $soc-$som-$board.dts are typical. 155 156Directories are usually named after the vendor of the SoC at the time of its 157inclusion, leading to some historical directory names in the tree. 158 159Validating Devicetree Files 160~~~~~~~~~~~~~~~~~~~~~~~~~~~ 161 162``make dtbs_check`` can be used to validate that devicetree files are compliant 163with the dt-bindings that describe the ABI. Please read the section 164"Running checks" of Documentation/devicetree/bindings/writing-schema.rst for 165more information on the validation of devicetrees. 166 167For new platforms, or additions to existing ones, ``make dtbs_check`` should not 168add any new warnings. For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is 169required to not add any new warnings. 170If in any doubt about a devicetree change, reach out to the devicetree 171maintainers. 172 173Branches and Pull Requests 174~~~~~~~~~~~~~~~~~~~~~~~~~~ 175 176Just as the main SoC tree has several branches, it is expected that 177submaintainers will do the same. Driver, defconfig and devicetree changes should 178all be split into separate branches and appear in separate pull requests to the 179SoC maintainers. Each branch should be usable by itself and avoid 180regressions that originate from dependencies on other branches. 181 182Small sets of patches can also be sent as separate emails to soc@kernel.org, 183grouped into the same categories. 184 185If changes do not fit into the normal patterns, there can be additional 186top-level branches, e.g. for a treewide rework, or the addition of new SoC 187platforms including dts files and drivers. 188 189Branches with a lot of changes can benefit from getting split up into separate 190topics branches, even if they end up getting merged into the same branch of the 191SoC tree. An example here would be one branch for devicetree warning fixes, one 192for a rework and one for newly added boards. 193 194Another common way to split up changes is to send an early pull request with the 195majority of the changes at some point between rc1 and rc4, following up with one 196or more smaller pull requests towards the end of the cycle that can add late 197changes or address problems identified while testing the first set. 198 199While there is no cut-off time for late pull requests, it helps to only send 200small branches as time gets closer to the merge window. 201 202Pull requests for bugfixes for the current release can be sent at any time, but 203again having multiple smaller branches is better than trying to combine too many 204patches into one pull request. 205 206The subject line of a pull request should begin with "[GIT PULL]" and made using 207a signed tag, rather than a branch. This tag should contain a short description 208summarising the changes in the pull request. For more detail on sending pull 209requests, please see Documentation/maintainer/pull-requests.rst. 210