[PATCH 1/2] docs: dt: submitting-patches: Document sending DTS patches

[PATCH 1/2] docs: dt: submitting-patches: Document sending DTS patches

[Krzysztof Kozlowski]

Document two rules already widely used and enforced by DT maintainers
and SoC platform maintainers:

1. DTS patches should be placed at the end of driver patchset to
   indicate no dependencies of driver code on DTS.

2. DTS patches should be applied via SoC platform maintainers, because
   it is a driver-independent hardware description.  However some
   driver maintainers are reluctant to pick up portions of patchsets and
   prefer to take entire set at once.  For such cases, the DTS portion
   should be split into separate patchset, so it will not end up in the
   driver subsystem integration tree.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
 .../bindings/submitting-patches.rst           | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
index a64f21a5f299..f3e23e69a638 100644
--- a/Documentation/devicetree/bindings/submitting-patches.rst
+++ b/Documentation/devicetree/bindings/submitting-patches.rst
@@ -54,11 +54,22 @@ I. For patch submitters
      followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864
      ("checkpatch: add DT compatible string documentation checks"). ]
 
-  7) If a documented compatible string is not yet matched by the
+  7) DTS is treated in general as driver-independent hardware description, thus
+     any DTS patches, regardless whether using existing or new bindings, should
+     be placed at the end of patchset to indicate no dependency of drivers on
+     the DTS.  DTS will be anyway applied through separate tree or branch, so
+     different order would indicate the serie is non-bisectable.
+
+     If a driver subsystem maintainer prefers to apply entire set, instead of
+     their relevant portion of patchset, please split the DTS patches into
+     separate patchset with a reference in changelog or cover letter to the
+     bindings submission on the mailing list.
+
+  8) If a documented compatible string is not yet matched by the
      driver, the documentation should also include a compatible
      string that is matched by the driver.
 
-  8) Bindings are actively used by multiple projects other than the Linux
+  9) Bindings are actively used by multiple projects other than the Linux
      Kernel, extra care and consideration may need to be taken when making changes
      to existing bindings.
 
@@ -79,6 +90,10 @@ II. For kernel maintainers
   3) For a series going though multiple trees, the binding patch should be
      kept with the driver using the binding.
 
+  4) The DTS files should however never be applied via driver subsystem tree,
+     but always via platform SoC trees on dedicated branches (see also
+     Documentation/process/maintainer-soc.rst).
+
 III. Notes
 ==========
 
-- 
2.43.0

[PATCH 2/2] docs: process: maintainer-soc-clean-dts: linux-next is decisive

[Krzysztof Kozlowski]

Devicetree bindings patches go usually via driver subsystem tree, so
obviously testing only SoC branches would result in new dtbs_check
warnings.  Mention that linux-next branch is decisice for zero-warnings
rule.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
 Documentation/process/maintainer-soc-clean-dts.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst
index 1b32430d0cfc..5423fb7d6047 100644
--- a/Documentation/process/maintainer-soc-clean-dts.rst
+++ b/Documentation/process/maintainer-soc-clean-dts.rst
@@ -17,8 +17,9 @@ Strict DTS DT Schema and dtc Compliance
 No changes to the SoC platform Devicetree sources (DTS files) should introduce
 new ``make dtbs_check W=1`` warnings.  Warnings in a new board DTS, which are
 results of issues in an included DTSI file, are considered existing, not new
-warnings.  The platform maintainers have automation in place which should point
-out any new warnings.
+warnings.  For series split between different trees (DT bindings go via driver
+subsystem tree), warnings on linux-next are decisive.  The platform maintainers
+have automation in place which should point out any new warnings.
 
 If a commit introducing new warnings gets accepted somehow, the resulting
 issues shall be fixed in reasonable time (e.g. within one release) or the
-- 
2.43.0

Re: [PATCH 1/2] docs: dt: submitting-patches: Document sending DTS patches

[Laurent Pinchart]

Hi Krzysztof,

On Tue, Feb 25, 2025 at 07:48:21PM +0100, Krzysztof Kozlowski wrote:
> Document two rules already widely used and enforced by DT maintainers
> and SoC platform maintainers:
> 
> 1. DTS patches should be placed at the end of driver patchset to
>    indicate no dependencies of driver code on DTS.
> 
> 2. DTS patches should be applied via SoC platform maintainers, because
>    it is a driver-independent hardware description.  However some
>    driver maintainers are reluctant to pick up portions of patchsets and
>    prefer to take entire set at once.  For such cases, the DTS portion
>    should be split into separate patchset, so it will not end up in the
>    driver subsystem integration tree.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

This matches my understanding of the current (and best) practices, so

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

> ---
>  .../bindings/submitting-patches.rst           | 19 +++++++++++++++++--
>  1 file changed, 17 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
> index a64f21a5f299..f3e23e69a638 100644
> --- a/Documentation/devicetree/bindings/submitting-patches.rst
> +++ b/Documentation/devicetree/bindings/submitting-patches.rst
> @@ -54,11 +54,22 @@ I. For patch submitters
>       followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864
>       ("checkpatch: add DT compatible string documentation checks"). ]
>  
> -  7) If a documented compatible string is not yet matched by the
> +  7) DTS is treated in general as driver-independent hardware description, thus
> +     any DTS patches, regardless whether using existing or new bindings, should
> +     be placed at the end of patchset to indicate no dependency of drivers on
> +     the DTS.  DTS will be anyway applied through separate tree or branch, so
> +     different order would indicate the serie is non-bisectable.
> +
> +     If a driver subsystem maintainer prefers to apply entire set, instead of
> +     their relevant portion of patchset, please split the DTS patches into
> +     separate patchset with a reference in changelog or cover letter to the
> +     bindings submission on the mailing list.
> +
> +  8) If a documented compatible string is not yet matched by the
>       driver, the documentation should also include a compatible
>       string that is matched by the driver.
>  
> -  8) Bindings are actively used by multiple projects other than the Linux
> +  9) Bindings are actively used by multiple projects other than the Linux
>       Kernel, extra care and consideration may need to be taken when making changes
>       to existing bindings.
>  
> @@ -79,6 +90,10 @@ II. For kernel maintainers
>    3) For a series going though multiple trees, the binding patch should be
>       kept with the driver using the binding.
>  
> +  4) The DTS files should however never be applied via driver subsystem tree,
> +     but always via platform SoC trees on dedicated branches (see also
> +     Documentation/process/maintainer-soc.rst).
> +
>  III. Notes
>  ==========
>  
> -- 
> 2.43.0
> 
> 

-- 
Regards,

Laurent Pinchart

Re: [PATCH 2/2] docs: process: maintainer-soc-clean-dts: linux-next is decisive

[Rob Herring]

On Tue, Feb 25, 2025 at 07:48:22PM +0100, Krzysztof Kozlowski wrote:
> Devicetree bindings patches go usually via driver subsystem tree, so
> obviously testing only SoC branches would result in new dtbs_check
> warnings.  Mention that linux-next branch is decisice for zero-warnings
> rule.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
>  Documentation/process/maintainer-soc-clean-dts.rst | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst
> index 1b32430d0cfc..5423fb7d6047 100644
> --- a/Documentation/process/maintainer-soc-clean-dts.rst
> +++ b/Documentation/process/maintainer-soc-clean-dts.rst
> @@ -17,8 +17,9 @@ Strict DTS DT Schema and dtc Compliance
>  No changes to the SoC platform Devicetree sources (DTS files) should introduce
>  new ``make dtbs_check W=1`` warnings.  Warnings in a new board DTS, which are
>  results of issues in an included DTSI file, are considered existing, not new
> -warnings.  The platform maintainers have automation in place which should point
> -out any new warnings.
> +warnings.  For series split between different trees (DT bindings go via driver
> +subsystem tree), warnings on linux-next are decisive.  The platform maintainers
> +have automation in place which should point out any new warnings.

I see a lot of warnings due to dependencies (both bindings and other dts 
changes) not be applied yet (or applied but not in linux-next). I've 
been filtering those out, but maybe they're useful? Some are things like 
missing labels, so dtc fails. I think that gets run enough a failure 
report on it isn't too useful.

Rob

Re: [PATCH 1/2] docs: dt: submitting-patches: Document sending DTS patches

[Rob Herring]

On Tue, Feb 25, 2025 at 07:48:21PM +0100, Krzysztof Kozlowski wrote:
> Document two rules already widely used and enforced by DT maintainers
> and SoC platform maintainers:
> 
> 1. DTS patches should be placed at the end of driver patchset to
>    indicate no dependencies of driver code on DTS.
> 
> 2. DTS patches should be applied via SoC platform maintainers, because
>    it is a driver-independent hardware description.  However some
>    driver maintainers are reluctant to pick up portions of patchsets and
>    prefer to take entire set at once.  For such cases, the DTS portion
>    should be split into separate patchset, so it will not end up in the
>    driver subsystem integration tree.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
>  .../bindings/submitting-patches.rst           | 19 +++++++++++++++++--
>  1 file changed, 17 insertions(+), 2 deletions(-)

I've applied both patches.

Rob

Re: [PATCH 2/2] docs: process: maintainer-soc-clean-dts: linux-next is decisive

[Krzysztof Kozlowski]

On 26/02/2025 16:29, Rob Herring wrote:
> On Tue, Feb 25, 2025 at 07:48:22PM +0100, Krzysztof Kozlowski wrote:
>> Devicetree bindings patches go usually via driver subsystem tree, so
>> obviously testing only SoC branches would result in new dtbs_check
>> warnings.  Mention that linux-next branch is decisice for zero-warnings
>> rule.
>>
>> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
>> ---
>>  Documentation/process/maintainer-soc-clean-dts.rst | 5 +++--
>>  1 file changed, 3 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst
>> index 1b32430d0cfc..5423fb7d6047 100644
>> --- a/Documentation/process/maintainer-soc-clean-dts.rst
>> +++ b/Documentation/process/maintainer-soc-clean-dts.rst
>> @@ -17,8 +17,9 @@ Strict DTS DT Schema and dtc Compliance
>>  No changes to the SoC platform Devicetree sources (DTS files) should introduce
>>  new ``make dtbs_check W=1`` warnings.  Warnings in a new board DTS, which are
>>  results of issues in an included DTSI file, are considered existing, not new
>> -warnings.  The platform maintainers have automation in place which should point
>> -out any new warnings.
>> +warnings.  For series split between different trees (DT bindings go via driver
>> +subsystem tree), warnings on linux-next are decisive.  The platform maintainers
>> +have automation in place which should point out any new warnings.
> 
> I see a lot of warnings due to dependencies (both bindings and other dts 
> changes) not be applied yet (or applied but not in linux-next). I've 
> been filtering those out, but maybe they're useful? Some are things like 
> missing labels, so dtc fails. I think that gets run enough a failure 
> report on it isn't too useful.
Maintainer-soc-clean-dts is an opt-in and so far only two guys in kernel
opted-in: for Arm/Arm64 one Samsung dude and for other archs only the
Risc-v guy.

Total coincidence is that these two do the DT bindings reviews...

I would say most of such warnings are very useful, just the question is
how much of false positives you have. For example LKP (Kernel test
robot) was sending reports on maintainer branches, but that had too many
false reports due to missing bindings going via different tree, e.g.
driver subsystem tree.

Best regards,
Krzysztof