1.. SPDX-License-Identifier: GPL-2.0
2
3============================================================
4DOs and DON'Ts for designing and writing Devicetree bindings
5============================================================
6
7This is a list of common review feedback items focused on binding design. With
8every rule, there are exceptions and bindings have many gray areas.
9
10For guidelines related to patches, see
11Documentation/devicetree/bindings/submitting-patches.rst
12
13
14Overall design
15==============
16
17- DO attempt to make bindings complete even if a driver doesn't support some
18  features. For example, if a device has an interrupt, then include the
19  'interrupts' property even if the driver is only polled mode.
20
21- DON'T refer to Linux or "device driver" in bindings. Bindings should be
22  based on what the hardware has, not what an OS and driver currently support.
23
24- DO use node names matching the class of the device. Many standard names are
25  defined in the DT Spec. If there isn't one, consider adding it.
26
27- DO check that the example matches the documentation especially after making
28  review changes.
29
30- DON'T create nodes just for the sake of instantiating drivers. Multi-function
31  devices only need child nodes when the child nodes have their own DT
32  resources. A single node can be multiple providers (e.g. clocks and resets).
33
34- DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
35  hardware block should have a compatible string unique enough to infer the
36  register layout of the entire block (at a minimum).
37
38
39Properties
40==========
41
42- DO make 'compatible' properties specific.
43
44   - DON'T use wildcards or device-family names in compatible strings.
45
46   - DO use fallback compatibles when devices are the same as or a superset of
47     prior implementations.
48
49   - DO add new compatibles in case there are new features or bugs.
50
51   - DO use a SoC-specific compatible for all SoC devices, followed by a
52     fallback if appropriate. SoC-specific compatibles are also preferred for
53     the fallbacks.
54
55   - DON'T use bus suffixes to encode the type of interface device is using.
56     The parent bus node already implies that interface.  DON'T add the type of
57     device, if the device cannot be anything else.
58
59- DO use a vendor prefix on device-specific property names. Consider if
60  properties could be common among devices of the same class. Check other
61  existing bindings for similar devices.
62
63- DON'T redefine common properties. Just reference the definition and define
64  constraints specific to the device.
65
66- DON'T add properties to avoid a specific compatible. DON'T add properties if
67  they are implied by (deducible from) the compatible.
68
69- DO use common property unit suffixes for properties with scientific units.
70  Recommended suffixes are listed at
71  https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml
72
73- DO define properties in terms of constraints. How many entries? What are
74  possible values? What is the order? All these constraints represent the ABI
75  as well.
76
77- DON'T make changes that break the ABI without explicit and detailed rationale
78  for why the changes have to be made and their impact. ABI impact goes beyond
79  the Linux kernel, because it also covers other open-source upstream projects.
80
81
82Typical cases and caveats
83=========================
84
85- Phandle entries, like clocks/dmas/interrupts/resets, should always be
86  explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is
87  more than one phandle. When used, both of these fields need the same
88  constraints (e.g. list of items).
89
90- For names used in {clock,dma,interrupt,reset}-names, do not add any suffix,
91  e.g.: "tx" instead of "txirq" (for interrupt).
92
93- Properties without schema types (e.g. without standard suffix or not defined
94  by schema) need the type, even if this is an enum.
95
96- If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use
97  "unevaluatedProperties:false". In other cases, usually use
98  "additionalProperties:false".
99
100- For sub-blocks/components of bigger device (e.g. SoC blocks) use rather
101  device-based compatible (e.g. SoC-based compatible), instead of custom
102  versioning of that component.
103  For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2".
104
105- "syscon" is not a generic property. Use vendor and type, e.g.
106  "vendor,power-manager-syscon".
107
108- Do not add instance index (IDs) properties or custom OF aliases.  If the
109  devices have different programming model, they might need different
110  compatibles.  If such devices use some other device in a different way, e.g.
111  they program the phy differently, use cell/phandle arguments.
112
113- Bindings files should be named like compatible: vendor,device.yaml. In case
114  of multiple compatibles in the binding, use one of the fallbacks or a more
115  generic name, yet still matching compatible style.
116
117Board/SoC .dts Files
118====================
119
120- DO put all MMIO devices under a bus node and not at the top-level.
121
122- DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit
123  platforms don't need all devices to have 64-bit address and size.
124