On 22 May 2023, at 22:34, Conor Dooley <conor@xxxxxxxxxx> wrote: > > On Tue, May 16, 2023 at 10:31:19AM +0200, Krzysztof Kozlowski wrote: >> On 15/05/2023 21:20, Conor Dooley wrote: > >>> +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. >> >>> + >>> +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 >>> +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. > > I'm not really sure that I like this truncated section so much, but here > it is... I kept the last paragraph intact as it does not talk about the > ABI, but rather exceptions of submaintainers. > > 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` for devicetree ABI rules. > > 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 > 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. Do you have an opinion on acknowledging the existence of other OSes here? Jess
