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@xxxxxxxxxxxxx> > > > > 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. > > > > Add a document briefly describing the role of the SoC subsystem and some > > basic advice for (new) platform maintainers. > > > > Suggested-by: Arnd Bergmann <arnd@xxxxxxxx> > > Signed-off-by: Conor Dooley <conor.dooley@xxxxxxxxxxxxx> > > +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. Once dt-bindings have > > +been merged (and appear in a release of the kernel) they are set in stone, and > > +any changes made must be compatible with existing devicetrees. This means 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 inverse is > > +also true, and a new devicetree will also be compatible with an old kernel, > > +although this is often not possible. > > 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 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. > > + > > +There are multiple ways to deal with this: > > + > > + - Avoid defining custom macros in include/dt-bindings/ for hardware constants > > + that can be derived from a datasheet -- binding macros in header file 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 when a > > + header is required, and change them to the named representation in a > > + following release > > I actually prefer such solution: > > - Duplicate defines in the devicetree file hidden by #ifndef section > and remove them later in a following release > > 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 driver have > > + already been merged > > + > > + - Change the bindings in a shared immutable branch that is used as the base for > > + both the driver change and the devicetree changes > > 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 description > > 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.
Attachment:
signature.asc
Description: PGP signature
