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 fo
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, i
17 ARM, RISC-V and Loongarch
18
19 These "SoC-specific drivers" do not include cl
20 other top-level maintainers. The drivers/soc/
21 for kernel-internal drivers that are used by o
22 specific functionality like identifying an SoC
23 power domains.
24
25 The SoC subsystem also serves as an intermedia
26 drivers/bus, drivers/firmware, drivers/reset a
27 of new platforms, or the removal of existing o
28 tree as a dedicated branch covering multiple s
29
30 The main SoC tree is housed on git.kernel.org:
31 https://git.kernel.org/pub/scm/linux/kernel/
32
33 Clearly this is quite a wide range of topics,
34 small group of people are capable of maintaini
35 is comprised of many submaintainers, each taki
36 and driver subdirectories.
37 In this regard, "platform" usually refers to a
38 vendor, for example, Nvidia's series of Tegra
39 on a vendor level, responsible for multiple pr
40 including acquisitions/different business unit
41 significantly here. The various submaintainer
42 MAINTAINERS file.
43
44 Most of these submaintainers have their own tr
45 sending pull requests to the main SoC tree. T
46 always, listed in MAINTAINERS. The main SoC m
47 alias soc@kernel.org if there is no platform-s
48 are unresponsive.
49
50 What the SoC tree is not, however, is a locati
51 changes. Each architecture has its own mainta
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 w
58 many of whom work for the silicon vendor, and
59 process.
60
61 Devicetree ABI Stability
62 ~~~~~~~~~~~~~~~~~~~~~~~~
63
64 Perhaps one of the most important things to hi
65 document the ABI between the devicetree and th
66 Please read Documentation/devicetree/bindings/
67
68 If changes are being made to a devicetree that
69 kernels, the devicetree patch should not be ap
70 appropriate time later. Most importantly, any
71 clearly pointed out in the patch description a
72 expected impact on existing users, such as boo
73 systems.
74
75 Driver Branch Dependencies
76 ~~~~~~~~~~~~~~~~~~~~~~~~~~
77
78 A common problem is synchronizing changes betw
79 files. Even if a change is compatible in both
80 coordinating how the changes get merged throug
81
82 Usually the branch that includes a driver chan
83 corresponding change to the devicetree binding
84 in fact compatible. This means that the devic
85 warnings in the "make dtbs_check" step. If a
86 missing additions to a header file in include/
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-b
92 that can be derived from a datasheet -- bind
93 only be used as a last resort if there is no
94
95 * Use literal values in the devicetree file in
96 header is required, and change them to the n
97 following release
98
99 * Defer the devicetree changes to a release af
100 already been merged
101
102 * Change the bindings in a shared immutable br
103 both the driver change and the devicetree ch
104
105 * Add duplicate defines in the devicetree file
106 removing them in a later release
107
108 Devicetree Naming Convention
109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
110
111 The general naming scheme for devicetree files
112 platform that are set at the SoC level, like C
113 named $soc.dtsi, for example, jh7100.dtsi. In
114 from board to board, are described in $soc-$bo
115 jh7100-beaglev-starlight.dts. Often many boar
116 frequently there are intermediate files, such
117 between the $soc.dtsi and $soc-$board.dts file
118 common hardware.
119
120 Some platforms also have System on Modules, co
121 integrated into several different boards. For
122 and $soc-$som-$board.dts are typical.
123
124 Directories are usually named after the vendor
125 inclusion, leading to some historical director
126
127 Validating Devicetree Files
128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
129
130 ``make dtbs_check`` can be used to validate th
131 with the dt-bindings that describe the ABI. P
132 "Running checks" of Documentation/devicetree/b
133 more information on the validation of devicetr
134
135 For new platforms, or additions to existing on
136 add any new warnings. For RISC-V and Samsung
137 required to not add any new warnings.
138 If in any doubt about a devicetree change, rea
139 maintainers.
140
141 Branches and Pull Requests
142 ~~~~~~~~~~~~~~~~~~~~~~~~~~
143
144 Just as the main SoC tree has several branches
145 submaintainers will do the same. Driver, defco
146 all be split into separate branches and appear
147 SoC maintainers. Each branch should be usable
148 regressions that originate from dependencies o
149
150 Small sets of patches can also be sent as sepa
151 grouped into the same categories.
152
153 If changes do not fit into the normal patterns
154 top-level branches, e.g. for a treewide rework
155 platforms including dts files and drivers.
156
157 Branches with a lot of changes can benefit fro
158 topics branches, even if they end up getting m
159 SoC tree. An example here would be one branch
160 for a rework and one for newly added boards.
161
162 Another common way to split up changes is to s
163 majority of the changes at some point between
164 or more smaller pull requests towards the end
165 changes or address problems identified while t
166
167 While there is no cut-off time for late pull r
168 small branches as time gets closer to the merg
169
170 Pull requests for bugfixes for the current rel
171 again having multiple smaller branches is bett
172 patches into one pull request.
173
174 The subject line of a pull request should begi
175 a signed tag, rather than a branch. This tag
176 summarising the changes in the pull request.
177 requests, please see Documentation/maintainer/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.