210 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=============4SoC Subsystem5=============6 7Overview8--------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-V14* 32-bit ARM board files (arch/arm/mach*)15* 32- & 64-bit ARM defconfigs16* SoC-specific drivers across architectures, in particular for 32- & 64-bit17 ARM, RISC-V and Loongarch18 19These "SoC-specific drivers" do not include clock, GPIO etc drivers that have20other top-level maintainers. The drivers/soc/ directory is generally meant21for kernel-internal drivers that are used by other drivers to provide SoC-22specific functionality like identifying an SoC revision or interfacing with23power domains.24 25The SoC subsystem also serves as an intermediate location for changes to26drivers/bus, drivers/firmware, drivers/reset and drivers/memory. The addition27of new platforms, or the removal of existing ones, often go through the SoC28tree 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 33Maintainers34-----------35 36Clearly this is quite a wide range of topics, which no one person, or even37small group of people are capable of maintaining. Instead, the SoC subsystem38is comprised of many submaintainers (platform maintainers), each taking care of39individual platforms and driver subdirectories.40In this regard, "platform" usually refers to a series of SoCs from a given41vendor, for example, Nvidia's series of Tegra SoCs. Many submaintainers operate42on a vendor level, responsible for multiple product lines. For several reasons,43including acquisitions/different business units in a company, things vary44significantly here. The various submaintainers are documented in the45MAINTAINERS 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 not49always, listed in MAINTAINERS.50 51What the SoC tree is not, however, is a location for architecture-specific code52changes. Each architecture has its own maintainers that are responsible for53architectural details, CPU errata and the like.54 55Submitting Patches for Given SoC56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~57 58All typical platform related patches should be sent via SoC submaintainers59(platform-specific maintainers). This includes also changes to per-platform or60shared defconfigs (scripts/get_maintainer.pl might not provide correct61addresses in such case).62 63Submitting Patches to the Main SoC Maintainers64~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~65 66The main SoC maintainers can be reached via the alias soc@kernel.org only in67following 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 sent74 first to common mailing lists, pointed out by scripts/get_maintainer.pl, for75 community review. After positive community review, work should be sent to76 soc@kernel.org in one patchset containing new arch/foo/Kconfig entry, DTS77 files, MAINTAINERS file entry and optionally initial drivers with their78 Devicetree bindings. The MAINTAINERS file entry should list new79 platform-specific maintainers, who are going to be responsible for handling80 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 by84the community.85 86Information for (new) Submaintainers87------------------------------------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 the91process.92 93Devicetree ABI Stability94~~~~~~~~~~~~~~~~~~~~~~~~95 96Perhaps one of the most important things to highlight is that dt-bindings97document 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 old101kernels, the devicetree patch should not be applied until the driver is, or an102appropriate time later. Most importantly, any incompatible changes should be103clearly pointed out in the patch description and pull request, along with the104expected impact on existing users, such as bootloaders or other operating105systems.106 107Driver Branch Dependencies108~~~~~~~~~~~~~~~~~~~~~~~~~~109 110A common problem is synchronizing changes between device drivers and devicetree111files. Even if a change is compatible in both directions, this may require112coordinating how the changes get merged through different maintainer trees.113 114Usually the branch that includes a driver change will also include the115corresponding change to the devicetree binding description, to ensure they are116in fact compatible. This means that the devicetree branch can end up causing117warnings in the "make dtbs_check" step. If a devicetree change depends on118missing additions to a header file in include/dt-bindings/, it will fail the119"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 constants124 that can be derived from a datasheet -- binding macros in header files should125 only be used as a last resort if there is no natural way to define a binding126 127* Use literal values in the devicetree file in place of macros even when a128 header is required, and change them to the named representation in a129 following release130 131* Defer the devicetree changes to a release after the binding and driver have132 already been merged133 134* Change the bindings in a shared immutable branch that is used as the base for135 both the driver change and the devicetree changes136 137* Add duplicate defines in the devicetree file guarded by an #ifndef section,138 removing them in a later release139 140Devicetree Naming Convention141~~~~~~~~~~~~~~~~~~~~~~~~~~~~142 143The general naming scheme for devicetree files is as follows. The aspects of a144platform that are set at the SoC level, like CPU cores, are contained in a file145named $soc.dtsi, for example, jh7100.dtsi. Integration details, that will vary146from board to board, are described in $soc-$board.dts. An example of this is147jh7100-beaglev-starlight.dts. Often many boards are variations on a theme, and148frequently there are intermediate files, such as jh7100-common.dtsi, which sit149between the $soc.dtsi and $soc-$board.dts files, containing the descriptions of150common hardware.151 152Some platforms also have System on Modules, containing an SoC, which are then153integrated into several different boards. For these platforms, $soc-$som.dtsi154and $soc-$som-$board.dts are typical.155 156Directories are usually named after the vendor of the SoC at the time of its157inclusion, leading to some historical directory names in the tree.158 159Validating Devicetree Files160~~~~~~~~~~~~~~~~~~~~~~~~~~~161 162``make dtbs_check`` can be used to validate that devicetree files are compliant163with the dt-bindings that describe the ABI. Please read the section164"Running checks" of Documentation/devicetree/bindings/writing-schema.rst for165more information on the validation of devicetrees.166 167For new platforms, or additions to existing ones, ``make dtbs_check`` should not168add any new warnings. For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is169required to not add any new warnings.170If in any doubt about a devicetree change, reach out to the devicetree171maintainers.172 173Branches and Pull Requests174~~~~~~~~~~~~~~~~~~~~~~~~~~175 176Just as the main SoC tree has several branches, it is expected that177submaintainers will do the same. Driver, defconfig and devicetree changes should178all be split into separate branches and appear in separate pull requests to the179SoC maintainers. Each branch should be usable by itself and avoid180regressions 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 additional186top-level branches, e.g. for a treewide rework, or the addition of new SoC187platforms including dts files and drivers.188 189Branches with a lot of changes can benefit from getting split up into separate190topics branches, even if they end up getting merged into the same branch of the191SoC tree. An example here would be one branch for devicetree warning fixes, one192for a rework and one for newly added boards.193 194Another common way to split up changes is to send an early pull request with the195majority of the changes at some point between rc1 and rc4, following up with one196or more smaller pull requests towards the end of the cycle that can add late197changes 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 send200small branches as time gets closer to the merge window.201 202Pull requests for bugfixes for the current release can be sent at any time, but203again having multiple smaller branches is better than trying to combine too many204patches into one pull request.205 206The subject line of a pull request should begin with "[GIT PULL]" and made using207a signed tag, rather than a branch. This tag should contain a short description208summarising the changes in the pull request. For more detail on sending pull209requests, please see Documentation/maintainer/pull-requests.rst.210