Documentation/devicetree/bindings/writing-bindings.rst

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/writing-bindings.rst

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/writing-bindings.rst
Extension
.rst
Size
6124 bytes
Lines
143
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

============================================================
DOs and DON'Ts for designing and writing Devicetree bindings
============================================================

This is a list of common review feedback items focused on binding design. With
every rule, there are exceptions and bindings have many gray areas.

For guidelines related to patches, see
Documentation/devicetree/bindings/submitting-patches.rst


Overall design
==============

- DO attempt to make bindings complete even if a driver doesn't support some
  features. For example, if a device has an interrupt, then include the
  'interrupts' property even if the driver is only polled mode.

- DON'T refer to Linux or "device driver" in bindings. Bindings should be
  based on what the hardware has, not what an OS and driver currently support.

- DO use node names matching the class of the device. Many standard names are
  defined in the DT Spec. If there isn't one, consider adding it.

- DO check that the example matches the documentation especially after making
  review changes.

- DON'T create nodes just for the sake of instantiating drivers. Multi-function
  devices only need child nodes when the child nodes have their own DT
  resources. A single node can be multiple providers (e.g. clocks and resets).

- DON'T treat device node names as a stable ABI, but instead use phandles or
  compatibles to find sibling devices. Exception: sub-nodes of given device
  could be treated as ABI, if explicitly documented in the bindings.

- DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
  hardware block should have a compatible string unique enough to infer the
  register layout of the entire block (at a minimum).

- DON'T use 'simple-mfd' compatible for non-trivial devices, where children
  depend on some resources from the parent. Similarly, 'simple-bus' should not
  be used for complex buses and even 'regs' property means device is not
  a simple bus.


Properties
==========

- DO make 'compatible' properties specific.

   - DON'T use wildcards or device-family names in compatible strings.

   - DO use fallback compatibles when devices are the same as or a superset of
     prior implementations. Fallback compatibles are applicable especially
     when sharing a programming interface or when able to discover the
     variants.

   - DON'T add fake fallback compatibles when software cannot use such to match
     and bind to a device, and still operate correctly.

   - DO use the commit message to explain why devices that may appear
     compatible in a diff (e.g. no differences in property use, same handling
     by the software) but are not made compatible in the binding, are not
     compatible.

   - DO add new compatibles in case there are new features or bugs.

   - DO use a SoC-specific compatible for all SoC devices, followed by a

Annotation

Implementation Notes