Loading...
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.
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.