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;
Message-ID: <cca446b3-9b92-3191-ae0d-1bd7e552c90f@linaro.org>
Date:   Tue, 16 May 2023 11:06:41 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.11.0
Subject: Re: [PATCH v1] Documentation/process: add soc maintainer handbook
Content-Language: en-US
To:     Conor Dooley <conor.dooley@microchip.com>
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
References: <20230515-geometry-olympics-b0556ff8a5f7@spud>
 <cf1c6b8c-8a3f-eca1-948f-e41946d4c34c@linaro.org>
 <20230516-grader-dejected-df65cdc584b3@wendy>
From:   Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
In-Reply-To: <20230516-grader-dejected-df65cdc584b3@wendy>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 16/05/2023 10:57, Conor Dooley wrote:
> 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>
>>>
>>> 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@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-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!

Of course, all is in an immutable branch, but in which tree?

I talk about a case when driver tree, e.g. different clock maintainer,
takes the binding.

> 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.


Best regards,
Krzysztof