Commit | Line | Data |
---|---|---|
b06ce821 RH |
1 | DOs and DON'Ts for designing and writing Devicetree bindings |
2 | ||
3 | This is a list of common review feedback items focused on binding design. With | |
4 | every rule, there are exceptions and bindings have many gray areas. | |
5 | ||
6 | For guidelines related to patches, see | |
7 | Documentation/devicetree/bindings/submitting-patches.txt | |
8 | ||
9 | ||
10 | Overall design | |
11 | ||
12 | - DO attempt to make bindings complete even if a driver doesn't support some | |
13 | features. For example, if a device has an interrupt, then include the | |
14 | 'interrupts' property even if the driver is only polled mode. | |
15 | ||
16 | - DON'T refer to Linux or "device driver" in bindings. Bindings should be | |
17 | based on what the hardware has, not what an OS and driver currently support. | |
18 | ||
19 | - DO use node names matching the class of the device. Many standard names are | |
20 | defined in the DT Spec. If there isn't one, consider adding it. | |
21 | ||
22 | - DO check that the example matches the documentation especially after making | |
23 | review changes. | |
24 | ||
25 | - DON'T create nodes just for the sake of instantiating drivers. Multi-function | |
26 | devices only need child nodes when the child nodes have their own DT | |
27 | resources. A single node can be multiple providers (e.g. clocks and resets). | |
28 | ||
29 | - DON'T use 'syscon' alone without a specific compatible string. A 'syscon' | |
30 | hardware block should have a compatible string unique enough to infer the | |
31 | register layout of the entire block (at a minimum). | |
32 | ||
33 | ||
34 | Properties | |
35 | ||
36 | - DO make 'compatible' properties specific. DON'T use wildcards in compatible | |
37 | strings. DO use fallback compatibles when devices are the same as or a subset | |
38 | of prior implementations. DO add new compatibles in case there are new | |
39 | features or bugs. | |
40 | ||
41 | - DO use a vendor prefix on device specific property names. Consider if | |
42 | properties could be common among devices of the same class. Check other | |
43 | existing bindings for similar devices. | |
44 | ||
45 | - DON'T redefine common properties. Just reference the definition and define | |
46 | constraints specific to the device. | |
47 | ||
48 | - DO use common property unit suffixes for properties with scientific units. | |
49 | See property-units.txt. | |
50 | ||
51 | - DO define properties in terms of constraints. How many entries? What are | |
52 | possible values? What is the order? | |
53 | ||
54 | ||
55 | Board/SoC .dts Files | |
56 | ||
57 | - DO put all MMIO devices under a bus node and not at the top-level. | |
58 | ||
59 | - DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit | |
60 | platforms don't need all devices to have 64-bit address and size. |