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 treat device node names as a stable ABI, but instead use phandles or 35 compatibles to find sibling devices. Exception: sub-nodes of given device 36 could be treated as ABI, if explicitly documented in the bindings. 37 38- DON'T use 'syscon' alone without a specific compatible string. A 'syscon' 39 hardware block should have a compatible string unique enough to infer the 40 register layout of the entire block (at a minimum). 41 42- DON'T use 'simple-mfd' compatible for non-trivial devices, where children 43 depend on some resources from the parent. Similarly, 'simple-bus' should not 44 be used for complex buses and even 'regs' property means device is not 45 a simple bus. 46 47 48Properties 49========== 50 51- DO make 'compatible' properties specific. 52 53 - DON'T use wildcards or device-family names in compatible strings. 54 55 - DO use fallback compatibles when devices are the same as or a superset of 56 prior implementations. 57 58 - DO add new compatibles in case there are new features or bugs. 59 60 - DO use a SoC-specific compatible for all SoC devices, followed by a 61 fallback if appropriate. SoC-specific compatibles are also preferred for 62 the fallbacks. 63 64 - DON'T use bus suffixes to encode the type of interface device is using. 65 The parent bus node already implies that interface. DON'T add the type of 66 device, if the device cannot be anything else. 67 68- DO use a vendor prefix on device-specific property names. Consider if 69 properties could be common among devices of the same class. Check other 70 existing bindings for similar devices. 71 72- DON'T redefine common properties. Just reference the definition and define 73 constraints specific to the device. 74 75- DON'T add properties to avoid a specific compatible. DON'T add properties if 76 they are implied by (deducible from) the compatible. 77 78- DO use common property unit suffixes for properties with scientific units. 79 Recommended suffixes are listed at 80 https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml 81 82- DO define properties in terms of constraints. How many entries? What are 83 possible values? What is the order? All these constraints represent the ABI 84 as well. 85 86- DON'T make changes that break the ABI without explicit and detailed rationale 87 for why the changes have to be made and their impact. ABI impact goes beyond 88 the Linux kernel, because it also covers other open-source upstream projects. 89 90 91Typical cases and caveats 92========================= 93 94- Phandle entries, like clocks/dmas/interrupts/resets, should always be 95 explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is 96 more than one phandle. When used, both of these fields need the same 97 constraints (e.g. list of items). 98 99- For names used in {clock,dma,interrupt,reset}-names, do not add any suffix, 100 e.g.: "tx" instead of "txirq" (for interrupt). 101 102- Properties without schema types (e.g. without standard suffix or not defined 103 by schema) need the type, even if this is an enum. 104 105- If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use 106 "unevaluatedProperties:false". In other cases, usually use 107 "additionalProperties:false". 108 109- For sub-blocks/components of bigger device (e.g. SoC blocks) use rather 110 device-based compatible (e.g. SoC-based compatible), instead of custom 111 versioning of that component. 112 For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2". 113 114- "syscon" is not a generic property. Use vendor and type, e.g. 115 "vendor,power-manager-syscon". 116 117- Do not add instance index (IDs) properties or custom OF aliases. If the 118 devices have different programming model, they might need different 119 compatibles. If such devices use some other device in a different way, e.g. 120 they program the phy differently, use cell/phandle arguments. 121 122- Bindings files should be named like compatible: vendor,device.yaml. In case 123 of multiple compatibles in the binding, use one of the fallbacks or a more 124 generic name, yet still matching compatible style. 125 126Board/SoC .dts Files 127==================== 128 129- DO put all MMIO devices under a bus node and not at the top-level. 130 131- DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit 132 platforms don't need all devices to have 64-bit address and size. 133