Commit 44c8a51a authored by Krzysztof Kozlowski's avatar Krzysztof Kozlowski Committed by Rob Herring
Browse files

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: default avatarKrzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Signed-off-by: default avatarRob Herring <robh@kernel.org>
Link: https://lore.kernel.org/r/20220403081849.8051-1-krzysztof.kozlowski@linaro.org
parent d49b3ae4

Documentation/devicetree/bindings/writing-bindings.rst

+25 −0
Original line number Diff line number Diff line
@@ -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

====================