1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ============================================== 3 ============================================================
4 DOs and DON'Ts for designing and writing Devic 4 DOs and DON'Ts for designing and writing Devicetree bindings
5 ============================================== 5 ============================================================
6 6
7 This is a list of common review feedback items 7 This is a list of common review feedback items focused on binding design. With
8 every rule, there are exceptions and bindings 8 every rule, there are exceptions and bindings have many gray areas.
9 9
10 For guidelines related to patches, see 10 For guidelines related to patches, see
11 Documentation/devicetree/bindings/submitting-p 11 Documentation/devicetree/bindings/submitting-patches.rst
12 12
13 13
14 Overall design 14 Overall design
15 ============== 15 ==============
16 16
17 - DO attempt to make bindings complete even if 17 - DO attempt to make bindings complete even if a driver doesn't support some
18 features. For example, if a device has an in 18 features. For example, if a device has an interrupt, then include the
19 'interrupts' property even if the driver is 19 'interrupts' property even if the driver is only polled mode.
20 20
21 - DON'T refer to Linux or "device driver" in b 21 - DON'T refer to Linux or "device driver" in bindings. Bindings should be
22 based on what the hardware has, not what an 22 based on what the hardware has, not what an OS and driver currently support.
23 23
24 - DO use node names matching the class of the 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, 25 defined in the DT Spec. If there isn't one, consider adding it.
26 26
27 - DO check that the example matches the docume 27 - DO check that the example matches the documentation especially after making
28 review changes. 28 review changes.
29 29
30 - DON'T create nodes just for the sake of inst 30 - DON'T create nodes just for the sake of instantiating drivers. Multi-function
31 devices only need child nodes when the child 31 devices only need child nodes when the child nodes have their own DT
32 resources. A single node can be multiple pro 32 resources. A single node can be multiple providers (e.g. clocks and resets).
33 33
34 - DON'T use 'syscon' alone without a specific 34 - DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
35 hardware block should have a compatible stri 35 hardware block should have a compatible string unique enough to infer the
36 register layout of the entire block (at a mi 36 register layout of the entire block (at a minimum).
37 37
38 38
39 Properties 39 Properties
40 ========== 40 ==========
41 41
42 - DO make 'compatible' properties specific. DO 42 - DO make 'compatible' properties specific. DON'T use wildcards in compatible
43 strings. DO use fallback compatibles when de 43 strings. DO use fallback compatibles when devices are the same as or a subset
44 of prior implementations. DO add new compati 44 of prior implementations. DO add new compatibles in case there are new
45 features or bugs. 45 features or bugs.
46 46
47 - DO use a vendor prefix on device-specific pr 47 - DO use a vendor prefix on device-specific property names. Consider if
48 properties could be common among devices of 48 properties could be common among devices of the same class. Check other
49 existing bindings for similar devices. 49 existing bindings for similar devices.
50 50
51 - DON'T redefine common properties. Just refer 51 - DON'T redefine common properties. Just reference the definition and define
52 constraints specific to the device. 52 constraints specific to the device.
53 53
54 - DO use common property unit suffixes for pro 54 - DO use common property unit suffixes for properties with scientific units.
55 Recommended suffixes are listed at 55 Recommended suffixes are listed at
56 https://github.com/devicetree-org/dt-schema/ 56 https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml
57 57
58 - DO define properties in terms of constraints 58 - DO define properties in terms of constraints. How many entries? What are
59 possible values? What is the order? 59 possible values? What is the order?
60 60
61 Typical cases and caveats 61 Typical cases and caveats
62 ========================= 62 =========================
63 63
64 - Phandle entries, like clocks/dmas/interrupts 64 - Phandle entries, like clocks/dmas/interrupts/resets, should always be
65 explicitly ordered. Include the {clock,dma,i 65 explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is
66 more than one phandle. When used, both of th 66 more than one phandle. When used, both of these fields need the same
67 constraints (e.g. list of items). 67 constraints (e.g. list of items).
68 68
69 - For names used in {clock,dma,interrupt,reset 69 - For names used in {clock,dma,interrupt,reset}-names, do not add any suffix,
70 e.g.: "tx" instead of "txirq" (for interrupt 70 e.g.: "tx" instead of "txirq" (for interrupt).
71 71
72 - Properties without schema types (e.g. withou 72 - Properties without schema types (e.g. without standard suffix or not defined
73 by schema) need the type, even if this is an 73 by schema) need the type, even if this is an enum.
74 74
75 - If schema includes other schema (e.g. /schem 75 - If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use
76 "unevaluatedProperties:false". In other case 76 "unevaluatedProperties:false". In other cases, usually use
77 "additionalProperties:false". 77 "additionalProperties:false".
78 78
79 - For sub-blocks/components of bigger device ( 79 - For sub-blocks/components of bigger device (e.g. SoC blocks) use rather
80 device-based compatible (e.g. SoC-based comp 80 device-based compatible (e.g. SoC-based compatible), instead of custom
81 versioning of that component. 81 versioning of that component.
82 For example use "vendor,soc1234-i2c" instead 82 For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2".
83 83
84 - "syscon" is not a generic property. Use vend 84 - "syscon" is not a generic property. Use vendor and type, e.g.
85 "vendor,power-manager-syscon". 85 "vendor,power-manager-syscon".
86 86
87 Board/SoC .dts Files 87 Board/SoC .dts Files
88 ==================== 88 ====================
89 89
90 - DO put all MMIO devices under a bus node and 90 - DO put all MMIO devices under a bus node and not at the top-level.
91 91
92 - DO use non-empty 'ranges' to limit the size 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- 93 platforms don't need all devices to have 64-bit address and size.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.