[lkml]   [2022]   [Apr]   [3]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
Patch in this message
Subject[PATCH 1/2] docs: dt: writing-bindings: describe typical cases
Add a chapter for caveats or typical mistakes.  Source: Rob Herring's
(Devicetree bindings maintainer) comments on LKML.

Signed-off-by: Krzysztof Kozlowski <>
.../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
 \ /
  Last update: 2022-04-03 10:19    [W:0.026 / U:9.640 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site