| 1 | |
| 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 (DTS) 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 | Maintainers
|
| 34 | -----------
|
| 35 |
|
| 36 | Clearly this is quite a wide range of topics, which no one person, or even
|
| 37 | small group of people are capable of maintaining. Instead, the SoC subsystem
|
| 38 | is comprised of many submaintainers (platform maintainers), each taking care of
|
| 39 | individual platforms and driver subdirectories.
|
| 40 | In this regard, "platform" usually refers to a series of SoCs from a given
|
| 41 | vendor, for example, Nvidia's series of Tegra SoCs. Many submaintainers operate
|
| 42 | on a vendor level, responsible for multiple product lines. For several reasons,
|
| 43 | including acquisitions/different business units in a company, things vary
|
| 44 | significantly here. The various submaintainers are documented in the
|
| 45 | MAINTAINERS file.
|
| 46 |
|
| 47 | Most of these submaintainers have their own trees where they stage patches,
|
| 48 | sending pull requests to the main SoC tree. These trees are usually, but not
|
| 49 | always, listed in MAINTAINERS.
|
| 50 |
|
| 51 | What the SoC tree is not, however, is a location for architecture-specific code
|
| 52 | changes. Each architecture has its own maintainers that are responsible for
|
| 53 | architectural details, CPU errata and the like.
|
| 54 |
|
| 55 | Submitting Patches for Given SoC
|
| 56 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 57 |
|
| 58 | All typical platform related patches should be sent via SoC submaintainers
|
| 59 | (platform-specific maintainers). This includes also changes to per-platform or
|
| 60 | shared defconfigs. Note that scripts/get_maintainer.pl might not provide
|
| 61 | correct addresses for the shared defconfig, so ignore its output and manually
|
| 62 | create CC-list based on MAINTAINERS file or use something like
|
| 63 | ``scripts/get_maintainer.pl -f drivers/soc/FOO/``.
|
| 64 |
|
| 65 | Submitting Patches to the Main SoC Maintainers
|
| 66 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 67 |
|
| 68 | The main SoC maintainers can be reached via the alias [email protected] only in
|
| 69 | following cases:
|
| 70 |
|
| 71 | 1. There are no platform-specific maintainers.
|
| 72 |
|
| 73 | 2. Platform-specific maintainers are unresponsive.
|
| 74 |
|
| 75 | 3. Introducing a completely new SoC platform. Such new SoC work should be sent
|
| 76 | first to common mailing lists, pointed out by scripts/get_maintainer.pl, for
|
| 77 | community review. After positive community review, work should be sent to
|
| 78 | [email protected] in one patchset containing new arch/foo/Kconfig entry, DTS
|
| 79 | files, MAINTAINERS file entry and optionally initial drivers with their
|
| 80 | Devicetree bindings. The MAINTAINERS file entry should list new
|
| 81 | platform-specific maintainers, who are going to be responsible for handling
|
| 82 | patches for the platform from now on.
|
| 83 |
|
| 84 | Note that the [email protected] is usually not the place to discuss the patches,
|
| 85 | thus work sent to this address should be already considered as acceptable by
|
| 86 | the community.
|
| 87 |
|
| 88 | Information for (new) Submaintainers
|
| 89 | ------------------------------------
|
| 90 |
|
| 91 | As new platforms spring up, they often bring with them new submaintainers,
|
| 92 | many of whom work for the silicon vendor, and may not be familiar with the
|
| 93 | process.
|
| 94 |
|
| 95 | Devicetree ABI Stability
|
| 96 | ~~~~~~~~~~~~~~~~~~~~~~~~
|
| 97 |
|
| 98 | Perhaps one of the most important things to highlight is that dt-bindings
|
| 99 | document the ABI between the devicetree and the kernel.
|
| 100 | Please read Documentation/devicetree/bindings/ABI.rst.
|
| 101 |
|
| 102 | If changes are being made to a DTS that are incompatible with old
|
| 103 | kernels, the DTS patch should not be applied until the driver is, or an
|
| 104 | appropriate time later. Most importantly, any incompatible changes should be
|
| 105 | clearly pointed out in the patch description and pull request, along with the
|
| 106 | expected impact on existing users, such as bootloaders or other operating
|
| 107 | systems.
|
| 108 |
|
| 109 | Driver Branch Dependencies
|
| 110 | ~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 111 |
|
| 112 | A common problem is synchronizing changes between device drivers and devicetree
|
| 113 | files. Even if a change is compatible in both directions, this may require
|
| 114 | coordinating how the changes get merged through different maintainer trees.
|
| 115 |
|
| 116 | Usually the branch that includes a driver change will also include the
|
| 117 | corresponding change to the devicetree binding description, to ensure they are
|
| 118 | in fact compatible. This means that the devicetree branch can end up causing
|
| 119 | warnings in the ``make dtbs_check`` step. If a devicetree change depends on
|
| 120 | missing additions to a header file in include/dt-bindings/, it will fail the
|
| 121 | ``make dtbs`` step and not get merged.
|
| 122 |
|
| 123 | There are multiple ways to deal with this:
|
| 124 |
|
| 125 | * Avoid defining custom macros in include/dt-bindings/ for hardware constants
|
| 126 | that can be derived from a datasheet -- binding macros in header files should
|
| 127 | only be used as a last resort if there is no natural way to define a binding
|
| 128 |
|
| 129 | * Use literal values in the devicetree file in place of macros even when a
|
| 130 | header is required, and change them to the named representation in a
|
| 131 | following release
|
| 132 |
|
| 133 | * Defer the devicetree changes to a release after the binding and driver have
|
| 134 | already been merged
|
| 135 |
|
| 136 | * Change the bindings in a shared immutable branch that is used as the base for
|
| 137 | both the driver change and the devicetree changes
|
| 138 |
|
| 139 | * Add duplicate defines in the devicetree file guarded by an #ifndef section,
|
| 140 | removing them in a later release
|
| 141 |
|
| 142 | Devicetree Naming Convention
|
| 143 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 144 |
|
| 145 | The general naming scheme for devicetree files is as follows. The aspects of a
|
| 146 | platform that are set at the SoC level, like CPU cores, are contained in a file
|
| 147 | named $soc.dtsi, for example, jh7100.dtsi. Integration details, that will vary
|
| 148 | from board to board, are described in $soc-$board.dts. An example of this is
|
| 149 | jh7100-beaglev-starlight.dts. Often many boards are variations on a theme, and
|
| 150 | frequently there are intermediate files, such as jh7100-common.dtsi, which sit
|
| 151 | between the $soc.dtsi and $soc-$board.dts files, containing the descriptions of
|
| 152 | common hardware.
|
| 153 |
|
| 154 | Some platforms also have System on Modules, containing an SoC, which are then
|
| 155 | integrated into several different boards. For these platforms, $soc-$som.dtsi
|
| 156 | and $soc-$som-$board.dts are typical.
|
| 157 |
|
| 158 | Directories are usually named after the vendor of the SoC at the time of its
|
| 159 | inclusion, leading to some historical directory names in the tree.
|
| 160 |
|
| 161 | Validating Devicetree Files
|
| 162 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 163 |
|
| 164 | ``make dtbs_check`` can be used to validate that devicetree files are compliant
|
| 165 | with the dt-bindings that describe the ABI. Please read the section
|
| 166 | "Running checks" of Documentation/devicetree/bindings/writing-schema.rst for
|
| 167 | more information on the validation of devicetrees.
|
| 168 |
|
| 169 | For new platforms, or additions to existing ones, ``make dtbs_check`` should not
|
| 170 | add any new warnings. For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is
|
| 171 | required to not add any new warnings.
|
| 172 |
|
| 173 | Additionally new code must not have any scripts/dtc/dt-check-style warnings in
|
| 174 | 'relaxed' mode and should have addressed most of the warnings in 'strict' mode
|
| 175 | (the latter mode might produce false positives).
|
| 176 |
|
| 177 | Branches and Pull Requests
|
| 178 | ~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 179 |
|
| 180 | Just as the main SoC tree has several branches, it is expected that
|
| 181 | submaintainers will do the same. Driver, defconfig and devicetree changes should
|
| 182 | all be split into separate branches and appear in separate pull requests to the
|
| 183 | SoC maintainers. Each branch should be usable by itself and avoid
|
| 184 | regressions that originate from dependencies on other branches.
|
| 185 |
|
| 186 | Small sets of patches can also be sent as separate emails to [email protected],
|
| 187 | grouped into the same categories.
|
| 188 |
|
| 189 | If changes do not fit into the normal patterns, there can be additional
|
| 190 | top-level branches, e.g. for a treewide rework, or the addition of new SoC
|
| 191 | platforms including dts files and drivers.
|
| 192 |
|
| 193 | Branches with a lot of changes can benefit from getting split up into separate
|
| 194 | topics branches, even if they end up getting merged into the same branch of the
|
| 195 | SoC tree. An example here would be one branch for devicetree warning fixes, one
|
| 196 | for a rework and one for newly added boards.
|
| 197 |
|
| 198 | Another common way to split up changes is to send an early pull request with the
|
| 199 | majority of the changes at some point between rc1 and rc4, following up with one
|
| 200 | or more smaller pull requests towards the end of the cycle that can add late
|
| 201 | changes or address problems identified while testing the first set.
|
| 202 |
|
| 203 | While there is no cut-off time for late pull requests, it helps to only send
|
| 204 | small branches as time gets closer to the merge window.
|
| 205 |
|
| 206 | Pull requests for bugfixes for the current release can be sent at any time, but
|
| 207 | again having multiple smaller branches is better than trying to combine too many
|
| 208 | patches into one pull request.
|
| 209 |
|
| 210 | The subject line of a pull request should begin with "[GIT PULL]" and made using
|
| 211 | a signed tag, rather than a branch. This tag should contain a short description
|
| 212 | summarising the changes in the pull request. For more detail on sending pull
|
| 213 | requests, please see Documentation/maintainer/pull-requests.rst.
|
| 214 |
|
| 215 | Defconfigs purpose
|
| 216 | ~~~~~~~~~~~~~~~~~~
|
| 217 |
|
| 218 | Defconfigs are primarily used by the kernel developers, because distros have
|
| 219 | their own configs. A change adding new CONFIG options to a defconfig should
|
| 220 | explain why the kernel developers in general would want such option, e.g. by
|
| 221 | providing a name of an upstream-supported machine/board using that new option.
|
| 222 | This implies that enabling options in defconfig for non-upstream machines shall
|
| 223 | not be accepted.
|