0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ============================================================
0004 DOs and DON'Ts for designing and writing Devicetree bindings
0005 ============================================================
0006
0007 This is a list of common review feedback items focused on binding design. With
0008 every rule, there are exceptions and bindings have many gray areas.
0009
0010 For guidelines related to patches, see
0011 Documentation/devicetree/bindings/submitting-patches.rst
0012
0013
0014 Overall design
0015 ==============
0016
0017 - DO attempt to make bindings complete even if a driver doesn't support some
0018 features. For example, if a device has an interrupt, then include the
0019 'interrupts' property even if the driver is only polled mode.
0020
0021 - DON'T refer to Linux or "device driver" in bindings. Bindings should be
0022 based on what the hardware has, not what an OS and driver currently support.
0023
0024 - DO use node names matching the class of the device. Many standard names are
0025 defined in the DT Spec. If there isn't one, consider adding it.
0026
0027 - DO check that the example matches the documentation especially after making
0028 review changes.
0029
0030 - DON'T create nodes just for the sake of instantiating drivers. Multi-function
0031 devices only need child nodes when the child nodes have their own DT
0032 resources. A single node can be multiple providers (e.g. clocks and resets).
0033
0034 - DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
0035 hardware block should have a compatible string unique enough to infer the
0036 register layout of the entire block (at a minimum).
0037
0038
0039 Properties
0040 ==========
0041
0042 - DO make 'compatible' properties specific. DON'T use wildcards in compatible
0043 strings. DO use fallback compatibles when devices are the same as or a subset
0044 of prior implementations. DO add new compatibles in case there are new
0045 features or bugs.
0046
0047 - DO use a vendor prefix on device-specific property names. Consider if
0048 properties could be common among devices of the same class. Check other
0049 existing bindings for similar devices.
0050
0051 - DON'T redefine common properties. Just reference the definition and define
0052 constraints specific to the device.
0053
0054 - DO use common property unit suffixes for properties with scientific units.
0055 Recommended suffixes are listed at
0056 https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml
0057
0058 - DO define properties in terms of constraints. How many entries? What are
0059 possible values? What is the order?
0060
0061 Typical cases and caveats
0062 =========================
0063
0064 - Phandle entries, like clocks/dmas/interrupts/resets, should always be
0065 explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is
0066 more than one phandle. When used, both of these fields need the same
0067 constraints (e.g. list of items).
0068
0069 - For names used in {clock,dma,interrupt,reset}-names, do not add any suffix,
0070 e.g.: "tx" instead of "txirq" (for interrupt).
0071
0072 - Properties without schema types (e.g. without standard suffix or not defined
0073 by schema) need the type, even if this is an enum.
0074
0075 - If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use
0076 "unevaluatedProperties:false". In other cases, usually use
0077 "additionalProperties:false".
0078
0079 - For sub-blocks/components of bigger device (e.g. SoC blocks) use rather
0080 device-based compatible (e.g. SoC-based compatible), instead of custom
0081 versioning of that component.
0082 For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2".
0083
0084 - "syscon" is not a generic property. Use vendor and type, e.g.
0085 "vendor,power-manager-syscon".
0086
0087 Board/SoC .dts Files
0088 ====================
0089
0090 - DO put all MMIO devices under a bus node and not at the top-level.
0091
0092 - DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit
0093 platforms don't need all devices to have 64-bit address and size.
