On Tue, May 30, 2023 at 01:49:36PM +0100, Conor Dooley wrote: > diff --git a/Documentation/process/maintainer-soc.rst b/Documentation/process/maintainer-soc.rst > new file mode 100644 > index 000000000000..9683c7d199b2 > --- /dev/null > +++ b/Documentation/process/maintainer-soc.rst > @@ -0,0 +1,178 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +.. _maintainer-soc: > + > +============= > +SoC Subsystem > +============= > + > +Overview > +-------- > + > +The SoC subsystem is a place of aggregation for SoC-specific code. > +The main components of the subsystem are: > + > +* devicetrees for 32- & 64-bit ARM and RISC-V > +* 32-bit ARM board files (arch/arm/mach*) > +* 32- & 64-bit ARM defconfigs > +* SoC specific drivers across architectures, in particular for 32- & 64-bit > + ARM, RISC-V and Loongarch > + > +These "SoC specific drivers" do not include clock, GPIO etc drivers that have > +other top-level maintainers. The drivers/soc/ directory is generally meant > +for kernel-internal drivers that are used by other drivers to provide SoC > +specific functionality like identifying a SoC revision or interfacing with > +power domains. > + > +The SoC subsystem also serves as an intermediate location for changes to > +drivers/bus, drivers/firmware, drivers/reset and drivers/memory. The addition > +of new platforms, or the removal of existing ones, often go through the SoC > +tree as a dedicated branch covering multiple subsystems. > + > +The main SoC tree is housed on git.kernel.org: > + https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/ > + > +Clearly this is quite a wide range of topics, which no one person, or even > +small group of people are capable of maintaining. Instead, the SoC subsystem > +is comprised of many submaintainers, each taking care of individual platforms > +and driver sub-directories. > +In this regard, "platform" usually refers to a series of SoCs from a given > +vendor, for example, Nvidia's series of Tegra SoCs. Many submaintainers operate > +on a vendor level, responsible for multiple product lines. For several reasons, > +including acquisitions/different business units in a company, things vary > +significantly here. The various submaintainers are documented in the > +MAINTAINERS file. > + > +Most of these submaintainers have their own trees where they stage patches, > +sending pull requests to the main SoC tree. These trees are usually, but not > +always, listed in MAINTAINERS. The main SoC maintainers can be reached via the > +alias soc@xxxxxxxxxx if there is no platform-specific maintainer, or if they > +are unresponsive. > + > +What the SoC tree is not, however, is a location for architecture specific code > +changes. Each architecture has it's own maintainers that are responsible for > +architectural details, cpu errata and the like. > + > +Information for (new) Submaintainers > +------------------------------------ > + > +As new platforms spring up, they often bring with them new submaintainers, > +many of whom work for the silicon vendor, and may not be familiar with the > +process. > + > +Devicetree ABI Stability > +~~~~~~~~~~~~~~~~~~~~~~~~ > + > +Perhaps one of the most important things to highlight is that dt-bindings > +document the ABI between the devicetree and the kernel. Please see > +:ref:`devicetree-abi` more information on the ABI. > + > +If changes are being made to a devicetree that are incompatible with old > +kernels, the devicetree patch should not be applied until the driver is, or an Until the incompatible driver changes are merged? > +appropriate time later. Most importantly, any incompatible changes should be > +clearly pointed out in the patch description and pull request, along with the > +expected impact on existing users, such as bootloaders or other operating > +systems. > + > +Driver Branch Dependencies > +~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +A common problem is synchronizing changes between device drivers and devicetree > +files, even if a change is compatible in both directions, this may require > +coordinating how the changes get merged through different maintainer trees. > + > +Usually the branch that includes a driver change will also include the > +corresponding change to the devicetree binding description, to ensure they are > +in fact compatible. This means that the devicetree branch can end up causing > +warnings in the "make dtbs_check" step. If a devicetree change depends on > +missing additions to a header file in include/dt-bindings/, it will fail the > +"make dtbs" step and not get merged. Sounds like passing `make dtbs` is a merging requirement. > +Pull requests for bugfixes for the current release can be sent at any time, but > +again having multiple smaller branches is better than trying to combine too many > +patches into one pull request. > + > +The subject line of a pull request should begin with "[GIT PULL]" and made using > +a signed tag, rather than a branch. This tag should contain a short description > +summarising the changes in the pull request. For more detail on sending pull > +requests, please see :ref:`pullrequests`. As jon had said, I simply prefer to write the last cross-ref as: ``` ... For more details on sending pull requests, see Documentation/maintainer/pull-requests.rst. ``` Thanks. -- An old man doll... just what I always wanted! - Clara
Attachment:
signature.asc
Description: PGP signature
