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