From 44c8a51a5f28436622fde18fd057c857b42ac28c Mon Sep 17 00:00:00 2001 From: Krzysztof Kozlowski Date: Sun, 3 Apr 2022 10:18:48 +0200 Subject: [PATCH] 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 Signed-off-by: Rob Herring Link: https://lore.kernel.org/r/20220403081849.8051-1-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 18d9e06..5465ece 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.7.4