Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Tue, 16 May 2023 09:57:29 +0100
From:   Conor Dooley <conor.dooley@microchip.com>
To:     Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
CC:     Conor Dooley <conor@kernel.org>, <soc@kernel.org>,
        Arnd Bergmann <arnd@arndb.de>,
        Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        Conor Dooley <conor+dt@kernel.org>,
        Jonathan Corbet <corbet@lwn.net>,
        Olof Johansson <olof@lixom.net>,
        Palmer Dabbelt <palmer@dabbelt.com>,
        <devicetree@vger.kernel.org>, <linux-kernel@vger.kernel.org>,
        <linux-doc@vger.kernel.org>,
        <linux-arm-kernel@lists.infradead.org>,
        <linux-riscv@lists.infradead.org>
Subject: Re: [PATCH v1] Documentation/process: add soc maintainer handbook
Message-ID: <20230516-grader-dejected-df65cdc584b3@wendy>
References: <20230515-geometry-olympics-b0556ff8a5f7@spud>
 <cf1c6b8c-8a3f-eca1-948f-e41946d4c34c@linaro.org>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha256;
        protocol="application/pgp-signature"; boundary="4AsXPhTNlfzE8BRW"
Content-Disposition: inline
In-Reply-To: <cf1c6b8c-8a3f-eca1-948f-e41946d4c34c@linaro.org>
Precedence: bulk

--4AsXPhTNlfzE8BRW
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Tue, May 16, 2023 at 10:31:19AM +0200, Krzysztof Kozlowski wrote:
> On 15/05/2023 21:20, Conor Dooley wrote:
> > From: Conor Dooley <conor.dooley@microchip.com>
> >=20
> > Arnd suggested that adding maintainer handbook for the SoC "subsystem"
> > would be helpful in trying to bring on board maintainers for the various
> > new platforms cropping up in RISC-V land.
> >=20
> > Add a document briefly describing the role of the SoC subsystem and some
> > basic advice for (new) platform maintainers.
> >=20
> > Suggested-by: Arnd Bergmann <arnd@arndb.de>
> > Signed-off-by: Conor Dooley <conor.dooley@microchip.com>

> > +devicetree ABI stability
> > +~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Perhaps one of the most important things to highlight is that dt-bindi=
ngs
> > +document the ABI between the devicetree and the kernel.  Once dt-bindi=
ngs have
> > +been merged (and appear in a release of the kernel) they are set in st=
one, and
> > +any changes made must be compatible with existing devicetrees.  This m=
eans that,
> > +when changing properties, a "new" kernel must still be able to handle =
an old
> > +devicetree.  For many systems the devicetree is provided by firmware, =
and
> > +upgrading to a newer kernel cannot cause regressions.  Ideally, the in=
verse is
> > +also true, and a new devicetree will also be compatible with an old ke=
rnel,
> > +although this is often not possible.
>=20
> I would prefer to skip it and instead: enhance
> Documentation/devicetree/bindings/ABI.rst and then reference it here.

Sure.

> > +Driver branch dependencies
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +A common problem is synchronizing changes between device drivers and d=
evicetree
> > +files, even if a change is compatible in both directions, this may req=
uire
> > +coordinating how the changes get merged through different maintainer t=
rees.
> > +
> > +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 depend=
s on
> > +missing additions to a header file in include/dt-bindings/, it will fa=
il the
> > +"make dtbs" step and not get merged.
> > +
> > +There are multiple ways to deal with this:
> > +
> > + - Avoid defining custom macros in include/dt-bindings/ for hardware c=
onstants
> > +   that can be derived from a datasheet -- binding macros in header fi=
le should
> > +   only be used as a last resort if there is no natural way to define =
a binding
> > +
> > + - Use literal values in the devicetree file in place of macros even w=
hen a
> > +   header is required, and change them to the named representation in a
> > +   following release
>=20
> I actually prefer such solution:
>=20
>  - Duplicate defines in the devicetree file hidden by #ifndef section
> and remove them later in a following release
>=20
> We can keep both, but mine above leads to cleaner changes in DTS file.

I think all of the options involved are either a bit ugly, or a bit of a
pain in the hole.

> > + - Defer the devicetree changes to a release after the binding and dri=
ver have
> > +   already been merged
> > +
> > + - Change the bindings in a shared immutable branch that is used as th=
e base for
> > +   both the driver change and the devicetree changes
>=20
> The policy told to me some time ago was that no merges from driver
> branch or tree are allowed towards DTS branch, even if they come only
> with binding header change. There are exceptions for this, e.g. [1], but
> that would mean we need to express here rules for cross-tree merges.

I've got away with having an immutable branch for dt-binding headers!
That said, Arnd did actually have a look at this (and suggested some
changes) before I sent it & did not cry fowl about this section. IIRC,
this is actually his wording, not mine.

> > +Branches and Pull Requests
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~

> > +The subject line of a pull request should begin with "[GIT PULL]" and =
made using
> > +a tag, rather than a branch.  This tag should contain a short descript=
ion
>=20
> a signed tag

I initially had that explicit wording, but I dropped it when I added the
ref to the pull requests doc since that talks about signing. It's
probably better to be explicit & re-adding it is trivial.

Thanks,
Conor.

--4AsXPhTNlfzE8BRW
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iHUEABYIAB0WIQRh246EGq/8RLhDjO14tDGHoIJi0gUCZGNFeQAKCRB4tDGHoIJi
0pVzAQDd5V7DgF90rg528xBUxStaRxmF6i407yxUeQeYhn6oLAEA3Y5P0rASKrya
rg86ohacmT7OJLEcXa37wLmEIY0TnAI=
=GTpg
-----END PGP SIGNATURE-----

--4AsXPhTNlfzE8BRW--