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