]>
Commit | Line | Data |
---|---|---|
e7728fcf MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ============================================================ | |
b06ce821 | 4 | DOs and DON'Ts for designing and writing Devicetree bindings |
e7728fcf | 5 | ============================================================ |
b06ce821 RH |
6 | |
7 | This is a list of common review feedback items focused on binding design. With | |
8 | every rule, there are exceptions and bindings have many gray areas. | |
9 | ||
10 | For guidelines related to patches, see | |
858e6845 | 11 | Documentation/devicetree/bindings/submitting-patches.rst |
b06ce821 RH |
12 | |
13 | ||
14 | Overall design | |
e7728fcf | 15 | ============== |
b06ce821 RH |
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 | ||
39 | Properties | |
e7728fcf | 40 | ========== |
b06ce821 RH |
41 | |
42 | - DO make 'compatible' properties specific. DON'T use wildcards in compatible | |
43 | strings. DO use fallback compatibles when devices are the same as or a subset | |
44 | of prior implementations. DO add new compatibles in case there are new | |
45 | features or bugs. | |
46 | ||
37ef2c34 | 47 | - DO use a vendor prefix on device-specific property names. Consider if |
b06ce821 RH |
48 | properties could be common among devices of the same class. Check other |
49 | existing bindings for similar devices. | |
50 | ||
51 | - DON'T redefine common properties. Just reference the definition and define | |
52 | constraints specific to the device. | |
53 | ||
54 | - DO use common property unit suffixes for properties with scientific units. | |
d0413118 | 55 | Recommended suffixes are listed at |
fbd2251d | 56 | https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml |
b06ce821 RH |
57 | |
58 | - DO define properties in terms of constraints. How many entries? What are | |
59 | possible values? What is the order? | |
60 | ||
44c8a51a KK |
61 | Typical cases and caveats |
62 | ========================= | |
63 | ||
64 | - Phandle entries, like clocks/dmas/interrupts/resets, should always be | |
65 | explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is | |
66 | more than one phandle. When used, both of these fields need the same | |
67 | constraints (e.g. list of items). | |
68 | ||
69 | - For names used in {clock,dma,interrupt,reset}-names, do not add any suffix, | |
70 | e.g.: "tx" instead of "txirq" (for interrupt). | |
71 | ||
72 | - Properties without schema types (e.g. without standard suffix or not defined | |
73 | by schema) need the type, even if this is an enum. | |
74 | ||
75 | - If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use | |
76 | "unevaluatedProperties:false". In other cases, usually use | |
77 | "additionalProperties:false". | |
78 | ||
79 | - For sub-blocks/components of bigger device (e.g. SoC blocks) use rather | |
80 | device-based compatible (e.g. SoC-based compatible), instead of custom | |
81 | versioning of that component. | |
82 | For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2". | |
83 | ||
84 | - "syscon" is not a generic property. Use vendor and type, e.g. | |
85 | "vendor,power-manager-syscon". | |
b06ce821 RH |
86 | |
87 | Board/SoC .dts Files | |
e7728fcf | 88 | ==================== |
b06ce821 RH |
89 | |
90 | - DO put all MMIO devices under a bus node and not at the top-level. | |
91 | ||
92 | - DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit | |
93 | platforms don't need all devices to have 64-bit address and size. |