[PATCH v2 0/4] docs: dt: Document established practices: compatible and file naming, subjects

[PATCH v2 0/4] docs: dt: Document established practices: compatible and file naming, subjects

[Krzysztof Kozlowski]

v1 was only one patch, here:
https://lore.kernel.org/linux-devicetree/20250710085814.21810-2-krzysztof.kozlowski@linaro.org/

Changes in v2:
1. Rephrase - use YAML instead of schema, add another example for
   conversion.

2. Three new patches (2-4).

Best regards,
Krzysztof

---
Krzysztof Kozlowski (4):
      docs: dt: submitting-patches: Avoid 'YAML' in the subject and add an example
      docs: dt: writing-bindings: Document compatible and filename naming
      docs: dt: writing-bindings: Document discouraged instance IDs
      docs: dt: writing-schema: Document preferred order of properties

 Documentation/devicetree/bindings/submitting-patches.rst | 12 ++++++++++--
 Documentation/devicetree/bindings/writing-bindings.rst   | 13 +++++++++++++
 Documentation/devicetree/bindings/writing-schema.rst     |  3 +++
 3 files changed, 26 insertions(+), 2 deletions(-)
---
base-commit: a62b7a37e6fcf4a675b1548e7c168b96ec836442
change-id: 20250713-dt-bindings-docs-a9d320095699

Best regards,
-- 
Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

[PATCH v2 1/4] docs: dt: submitting-patches: Avoid 'YAML' in the subject and add an example

[Krzysztof Kozlowski]

Patches adding new device bindings should avoid 'YAML' keyword in the
subject, because all bindings are supposed to be in DT schema format,
which uses YAML.  The DT schema is welcomed only in case of patches
doing conversion.  Effectively people get confused that subject should
not contain anything else than device name after the prefix, so add two
recommended examples.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

---

Changes in v2:
1. Rephrase - use YAML instead of schema, add another example for
   conversion.
---
 Documentation/devicetree/bindings/submitting-patches.rst | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
index f3e23e69a6389e7e5d8db66af5060978ecff8a9d..46d0b036c97eb531dec95ef52261988d3bfa3aad 100644
--- a/Documentation/devicetree/bindings/submitting-patches.rst
+++ b/Documentation/devicetree/bindings/submitting-patches.rst
@@ -21,8 +21,16 @@ I. For patch submitters
        "<binding dir>: dt-bindings: ..."
 
      The 80 characters of the subject are precious. It is recommended to not
-     use "Documentation" or "doc" because that is implied. All bindings are
-     docs. Repeating "binding" again should also be avoided.
+     use "Documentation", "doc" or "YAML" because that is implied. All
+     bindings are docs and all new bindings are supposed to be in Devicetree
+     schema format.  Repeating "binding" again should also be avoided, so for
+     a new device it is often enough for example::
+
+       "dt-bindings: iio: adc: Add ROHM BD79100G"
+
+     Conversion of other formats to DT schema::
+
+       "dt-bindings: iio: adc: adi,ad7476: Convert to DT schema"
 
   2) DT binding files are written in DT schema format using json-schema
      vocabulary and YAML file format. The DT binding files must pass validation

-- 
2.43.0

[PATCH v2 2/4] docs: dt: writing-bindings: Document compatible and filename naming

[Krzysztof Kozlowski]

Document established Devicetree bindings maintainers review practices:

1. Compatibles should not use bus suffixes to encode the type of
   interface, because the parent bus node defines that interface, e.g.
   "vendor,device" instead of "vendor,device-i2c" + "vendor,device-spi".

2. If the compatible represents the device as a whole, it should not
   contain the type of device in the name.

3. Filenames should match compatible.  The best if match is 100%, but if
   binding has multiple compatibles, then one of the fallbacks should be
   used.  Alternatively a genericish name is allowed if it follows
   "vendor,device" style.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

---

Changes in v2:
1. New patch
---
 Documentation/devicetree/bindings/writing-bindings.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index a2d2afd099c0bd922cf12dcf49f5dffe6da748f1..e63de88385b5bc5859d8d9fca82bcf30380f3e73 100644
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -52,6 +52,10 @@ Properties
      fallback if appropriate. SoC-specific compatibles are also preferred for
      the fallbacks.
 
+   - DON'T use bus suffixes to encode the type of interface device is using.
+     The parent bus node already implies that interface.  DON'T add the type of
+     device, if the device cannot be anything else.
+
 - DO use a vendor prefix on device-specific property names. Consider if
   properties could be common among devices of the same class. Check other
   existing bindings for similar devices.
@@ -101,6 +105,10 @@ Typical cases and caveats
 - "syscon" is not a generic property. Use vendor and type, e.g.
   "vendor,power-manager-syscon".
 
+- Bindings files should be named like compatible: vendor,device.yaml. In case
+  of multiple compatibles in the binding, use one of the fallbacks or a more
+  generic name, yet still matching compatible style.
+
 Board/SoC .dts Files
 ====================
 

-- 
2.43.0

[PATCH v2 3/4] docs: dt: writing-bindings: Document discouraged instance IDs

[Krzysztof Kozlowski]

Document established Devicetree bindings maintainers review practice:
instance indexes, either as properties or as custom new OF alias, are
not accepted.  Recommended way is to use, depending on the
situation/hardware: different compatible, cell arguments or syscon
phandle arguments.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

---

Changes in v2:
1. New patch
---
 Documentation/devicetree/bindings/writing-bindings.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index e63de88385b5bc5859d8d9fca82bcf30380f3e73..f8e0293a7c0621a343a493d448624bff916ba021 100644
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -105,6 +105,11 @@ Typical cases and caveats
 - "syscon" is not a generic property. Use vendor and type, e.g.
   "vendor,power-manager-syscon".
 
+- Do not add instance index (IDs) properties or custom OF aliases.  If the
+  devices have different programming model, they might need different
+  compatibles.  If such devices use some other device in a different way, e.g.
+  they program the phy differently, use cell/phandle arguments.
+
 - Bindings files should be named like compatible: vendor,device.yaml. In case
   of multiple compatibles in the binding, use one of the fallbacks or a more
   generic name, yet still matching compatible style.

-- 
2.43.0

[PATCH v2 4/4] docs: dt: writing-schema: Document preferred order of properties

[Krzysztof Kozlowski]

Document established Devicetree bindings maintainers review practice:
using DTS coding style property order in both 'properties' and
'required' secions.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

---

Changes in v2:
1. New patch
---
 Documentation/devicetree/bindings/writing-schema.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
index fc73072f12fc58dbaf3dea3eb8cc79cfac0341c8..470d1521fa174f4fac29004b95a9b1a8c37071d9 100644
--- a/Documentation/devicetree/bindings/writing-schema.rst
+++ b/Documentation/devicetree/bindings/writing-schema.rst
@@ -171,6 +171,9 @@ Coding style
 Use YAML coding style (two-space indentation). For DTS examples in the schema,
 preferred is four-space indentation.
 
+Place entries in 'properties' and 'required' sections in the same order, using
+style from Documentation/devicetree/bindings/dts-coding-style.rst.
+
 Testing
 -------
 

-- 
2.43.0

Re: [PATCH v2 1/4] docs: dt: submitting-patches: Avoid 'YAML' in the subject and add an example

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 2576 bytes --]

On Sun, Jul 13, 2025 at 02:46:36PM +0200, Krzysztof Kozlowski wrote:
> Patches adding new device bindings should avoid 'YAML' keyword in the
> subject, because all bindings are supposed to be in DT schema format,
> which uses YAML.  The DT schema is welcomed only in case of patches
> doing conversion.  Effectively people get confused that subject should
> not contain anything else than device name after the prefix, so add two
> recommended examples.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> ---
> 
> Changes in v2:
> 1. Rephrase - use YAML instead of schema, add another example for
>    conversion.
> ---
>  Documentation/devicetree/bindings/submitting-patches.rst | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
> index f3e23e69a6389e7e5d8db66af5060978ecff8a9d..46d0b036c97eb531dec95ef52261988d3bfa3aad 100644
> --- a/Documentation/devicetree/bindings/submitting-patches.rst
> +++ b/Documentation/devicetree/bindings/submitting-patches.rst
> @@ -21,8 +21,16 @@ I. For patch submitters
>         "<binding dir>: dt-bindings: ..."
>  
>       The 80 characters of the subject are precious. It is recommended to not
> -     use "Documentation" or "doc" because that is implied. All bindings are
> -     docs. Repeating "binding" again should also be avoided.
> +     use "Documentation", "doc" or "YAML" because that is implied. All
                                                                     ^
> +     bindings are docs and all new bindings are supposed to be in Devicetree
> +     schema format.  Repeating "binding" again should also be avoided, so for
                      ^^
I like the change, but I would like to note that you've got inconsistent
double space v single space after a full stop. The document seems to
mostly be confused about that and uses both. No clue which of the two it
should be, just wanted to mention it :)

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>


> +     a new device it is often enough for example::
> +
> +       "dt-bindings: iio: adc: Add ROHM BD79100G"
> +
> +     Conversion of other formats to DT schema::
> +
> +       "dt-bindings: iio: adc: adi,ad7476: Convert to DT schema"
>  
>    2) DT binding files are written in DT schema format using json-schema
>       vocabulary and YAML file format. The DT binding files must pass validation
> 
> -- 
> 2.43.0
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 2/4] docs: dt: writing-bindings: Document compatible and filename naming

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 2435 bytes --]

On Sun, Jul 13, 2025 at 02:46:37PM +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practices:
> 
> 1. Compatibles should not use bus suffixes to encode the type of
>    interface, because the parent bus node defines that interface, e.g.
>    "vendor,device" instead of "vendor,device-i2c" + "vendor,device-spi".
> 
> 2. If the compatible represents the device as a whole, it should not
>    contain the type of device in the name.
> 
> 3. Filenames should match compatible.  The best if match is 100%, but if
>    binding has multiple compatibles, then one of the fallbacks should be
>    used.  Alternatively a genericish name is allowed if it follows
>    "vendor,device" style.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

> 
> ---
> 
> Changes in v2:
> 1. New patch
> ---
>  Documentation/devicetree/bindings/writing-bindings.rst | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
> index a2d2afd099c0bd922cf12dcf49f5dffe6da748f1..e63de88385b5bc5859d8d9fca82bcf30380f3e73 100644
> --- a/Documentation/devicetree/bindings/writing-bindings.rst
> +++ b/Documentation/devicetree/bindings/writing-bindings.rst
> @@ -52,6 +52,10 @@ Properties
>       fallback if appropriate. SoC-specific compatibles are also preferred for
>       the fallbacks.
>  
> +   - DON'T use bus suffixes to encode the type of interface device is using.
> +     The parent bus node already implies that interface.  DON'T add the type of
> +     device, if the device cannot be anything else.
> +
>  - DO use a vendor prefix on device-specific property names. Consider if
>    properties could be common among devices of the same class. Check other
>    existing bindings for similar devices.
> @@ -101,6 +105,10 @@ Typical cases and caveats
>  - "syscon" is not a generic property. Use vendor and type, e.g.
>    "vendor,power-manager-syscon".
>  
> +- Bindings files should be named like compatible: vendor,device.yaml. In case
> +  of multiple compatibles in the binding, use one of the fallbacks or a more
> +  generic name, yet still matching compatible style.
> +
>  Board/SoC .dts Files
>  ====================
>  
> 
> -- 
> 2.43.0
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 3/4] docs: dt: writing-bindings: Document discouraged instance IDs

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 503 bytes --]

On Sun, Jul 13, 2025 at 02:46:38PM +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practice:
> instance indexes, either as properties or as custom new OF alias, are
> not accepted.  Recommended way is to use, depending on the
> situation/hardware: different compatible, cell arguments or syscon
> phandle arguments.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 4/4] docs: dt: writing-schema: Document preferred order of properties

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 365 bytes --]

On Sun, Jul 13, 2025 at 02:46:39PM +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practice:
> using DTS coding style property order in both 'properties' and
> 'required' secions.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 1/4] docs: dt: submitting-patches: Avoid 'YAML' in the subject and add an example

[Rob Herring (Arm)]

On Sun, 13 Jul 2025 14:46:36 +0200, Krzysztof Kozlowski wrote:
> Patches adding new device bindings should avoid 'YAML' keyword in the
> subject, because all bindings are supposed to be in DT schema format,
> which uses YAML.  The DT schema is welcomed only in case of patches
> doing conversion.  Effectively people get confused that subject should
> not contain anything else than device name after the prefix, so add two
> recommended examples.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> ---
> 
> Changes in v2:
> 1. Rephrase - use YAML instead of schema, add another example for
>    conversion.
> ---
>  Documentation/devicetree/bindings/submitting-patches.rst | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
> 

Applied, thanks!

Re: [PATCH v2 2/4] docs: dt: writing-bindings: Document compatible and filename naming

[Rob Herring (Arm)]

On Sun, 13 Jul 2025 14:46:37 +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practices:
> 
> 1. Compatibles should not use bus suffixes to encode the type of
>    interface, because the parent bus node defines that interface, e.g.
>    "vendor,device" instead of "vendor,device-i2c" + "vendor,device-spi".
> 
> 2. If the compatible represents the device as a whole, it should not
>    contain the type of device in the name.
> 
> 3. Filenames should match compatible.  The best if match is 100%, but if
>    binding has multiple compatibles, then one of the fallbacks should be
>    used.  Alternatively a genericish name is allowed if it follows
>    "vendor,device" style.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> ---
> 
> Changes in v2:
> 1. New patch
> ---
>  Documentation/devicetree/bindings/writing-bindings.rst | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 

Applied, thanks!

Re: [PATCH v2 3/4] docs: dt: writing-bindings: Document discouraged instance IDs

[Rob Herring (Arm)]

On Sun, 13 Jul 2025 14:46:38 +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practice:
> instance indexes, either as properties or as custom new OF alias, are
> not accepted.  Recommended way is to use, depending on the
> situation/hardware: different compatible, cell arguments or syscon
> phandle arguments.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> ---
> 
> Changes in v2:
> 1. New patch
> ---
>  Documentation/devicetree/bindings/writing-bindings.rst | 5 +++++
>  1 file changed, 5 insertions(+)
> 

Applied, thanks!

Re: [PATCH v2 4/4] docs: dt: writing-schema: Document preferred order of properties

[Rob Herring (Arm)]

On Sun, 13 Jul 2025 14:46:39 +0200, Krzysztof Kozlowski wrote:
> Document established Devicetree bindings maintainers review practice:
> using DTS coding style property order in both 'properties' and
> 'required' secions.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> 
> ---
> 
> Changes in v2:
> 1. New patch
> ---
>  Documentation/devicetree/bindings/writing-schema.rst | 3 +++
>  1 file changed, 3 insertions(+)
> 

Applied, thanks!