Documentation/devicetree/bindings/dts-coding-style.rst

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/dts-coding-style.rst

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/dts-coding-style.rst
Extension
.rst
Size
5940 bytes
Lines
214
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

=====================================
Devicetree Sources (DTS) Coding Style
=====================================

When writing Devicetree Sources (DTS) please observe below guidelines.  They
should be considered complementary to any rules expressed already in
the Devicetree Specification and the dtc compiler (including W=1 and W=2
builds).

Individual architectures and subarchitectures can define additional rules,
making the coding style stricter.

Naming and Valid Characters
---------------------------

The Devicetree Specification allows a broad range of characters in node
and property names, but this coding style narrows the range down to achieve
better code readability.

1. Node and property names can use only the following characters:

   * Lowercase characters: [a-z]
   * Digits: [0-9]
   * Dash: -

2. Labels can use only the following characters:

   * Lowercase characters: [a-z]
   * Digits: [0-9]
   * Underscore: _

3. Unless a bus defines differently, unit addresses shall use lowercase
   hexadecimal digits, without leading zeros (padding).

4. Hex values in properties, e.g. "reg", shall use lowercase hex.  The address
   part can be padded with leading zeros.

Example::

	gpi_dma2: dma-controller@a00000 {
		compatible = "qcom,sm8550-gpi-dma", "qcom,sm6350-gpi-dma";
		reg = <0x0 0x00a00000 0x0 0x60000>;
	}

Order of Nodes
--------------

1. Nodes on any bus, thus using unit addresses for children, shall be
   ordered by unit address in ascending order.
   Alternatively for some subarchitectures, nodes of the same type can be
   grouped together, e.g. all I2C controllers one after another even if this
   breaks unit address ordering.

2. Nodes without unit addresses shall be ordered alpha-numerically by the node
   name.  For a few node types, they can be ordered by the main property, e.g.
   pin configuration states ordered by value of "pins" property.

3. When extending nodes in the board DTS via &label, the entries shall be
   ordered either alpha-numerically or by keeping the order from DTSI, where
   the choice depends on the subarchitecture.

The above-described ordering rules are easy to enforce during review, reduce
chances of conflicts for simultaneous additions of new nodes to a file and help
in navigating through the DTS source.

Example::

	/* SoC DTSI */

Annotation

Implementation Notes