[PATCH 1/2] docs: dt: writing-bindings: describe typical cases

[PATCH 1/2] docs: dt: writing-bindings: describe typical cases

[Krzysztof Kozlowski]

Add a chapter for caveats or typical mistakes.  Source: Rob Herring's
(Devicetree bindings maintainer) comments on LKML.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
 .../devicetree/bindings/writing-bindings.rst  | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
index 18d9e0689d49..5465eced2af1 100644
--- a/Documentation/devicetree/bindings/writing-bindings.rst
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -58,6 +58,31 @@ Properties
 - DO define properties in terms of constraints. How many entries? What are
   possible values? What is the order?
 
+Typical cases and caveats
+=========================
+
+- Phandle entries, like clocks/dmas/interrupts/resets, should always be
+  explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is
+  more than one phandle. When used, both of these fields need the same
+  constraints (e.g.  list of items).
+
+- For names used in {clock,dma,interrupt,reset}-names, do not add any suffix,
+  e.g.: "tx" instead of "txirq" (for interrupt).
+
+- Properties without schema types (e.g. without standard suffix or not defined
+  by schema) need the type, even if this is an enum.
+
+- If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use
+  "unevaluatedProperties:false". In other cases, usually use
+  "additionalProperties:false".
+
+- For sub-blocks/components of bigger device (e.g. SoC blocks) use rather
+  device-based compatible (e.g. SoC-based compatible), instead of custom
+  versioning of that component.
+  For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2".
+
+- "syscon" is not a generic property. Use vendor and type, e.g.
+  "vendor,power-manager-syscon".
 
 Board/SoC .dts Files
 ====================
-- 
2.32.0

[PATCH 2/2] docs: dt: writing-schema: mention coding style

[Krzysztof Kozlowski]

Mention the usage of YAML coding style.  Describe explicitly that
four-space indentation in DTS examples is preferred, because:
1. The YAML's default two-space indentation for DTS code makes it
   significantly less readable.
2. Linux coding style tabs would introduce inconsistency (entire file is
   indented with spaces).
3. On the other hand, eight spaces would not align with example's
   opening '  - |' part.  Four spaces makes the code nicely aligned with
   it.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
---
 .../devicetree/bindings/example-schema.yaml        | 14 +++++++-------
 .../devicetree/bindings/writing-schema.rst         |  6 ++++++
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml
index 80a28781845d..8e1a8b19d429 100644
--- a/Documentation/devicetree/bindings/example-schema.yaml
+++ b/Documentation/devicetree/bindings/example-schema.yaml
@@ -249,13 +249,13 @@ examples:
   # be overridden or an appropriate parent bus node should be shown (such as on
   # i2c buses).
   #
-  # Any includes used have to be explicitly included.
+  # Any includes used have to be explicitly included. Use 4-space indentation.
   - |
     node@1000 {
-          compatible = "vendor,soc4-ip", "vendor,soc1-ip";
-          reg = <0x1000 0x80>,
-                <0x3000 0x80>;
-          reg-names = "core", "aux";
-          interrupts = <10>;
-          interrupt-controller;
+        compatible = "vendor,soc4-ip", "vendor,soc1-ip";
+        reg = <0x1000 0x80>,
+              <0x3000 0x80>;
+        reg-names = "core", "aux";
+        interrupts = <10>;
+        interrupt-controller;
     };
diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
index 95ecf55559e5..2916edf829db 100644
--- a/Documentation/devicetree/bindings/writing-schema.rst
+++ b/Documentation/devicetree/bindings/writing-schema.rst
@@ -108,6 +108,12 @@ The YAML Devicetree format also makes all string values an array and scalar
 values a matrix (in order to define groupings) even when only a single value
 is present. Single entries in schemas are fixed up to match this encoding.
 
+Coding style
+------------
+
+Use YAML coding style (two-space indentation). For DTS examples in the schema,
+preferred is four-space indentation.
+
 Testing
 -------
 
-- 
2.32.0

Re: [PATCH 2/2] docs: dt: writing-schema: mention coding style

[Rob Herring]

On Sun, 03 Apr 2022 10:18:49 +0200, Krzysztof Kozlowski wrote:
> Mention the usage of YAML coding style.  Describe explicitly that
> four-space indentation in DTS examples is preferred, because:
> 1. The YAML's default two-space indentation for DTS code makes it
>    significantly less readable.
> 2. Linux coding style tabs would introduce inconsistency (entire file is
>    indented with spaces).
> 3. On the other hand, eight spaces would not align with example's
>    opening '  - |' part.  Four spaces makes the code nicely aligned with
>    it.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
>  .../devicetree/bindings/example-schema.yaml        | 14 +++++++-------
>  .../devicetree/bindings/writing-schema.rst         |  6 ++++++
>  2 files changed, 13 insertions(+), 7 deletions(-)
> 

Applied, thanks!

Re: [PATCH 1/2] docs: dt: writing-bindings: describe typical cases

[Rob Herring]

On Sun, 03 Apr 2022 10:18:48 +0200, Krzysztof Kozlowski wrote:
> Add a chapter for caveats or typical mistakes.  Source: Rob Herring's
> (Devicetree bindings maintainer) comments on LKML.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
> ---
>  .../devicetree/bindings/writing-bindings.rst  | 25 +++++++++++++++++++
>  1 file changed, 25 insertions(+)
> 

Applied, thanks!