Understanding Linux Device Tree Syntax (DTS)

DTB = Devicetree blob. Compact binary representation of the devicetree.
DTC = Devicetree compiler. An open source tool used to create DTB files from DTS files.
DTS = Devicetree syntax. A textual representation of a devicetree consumed by the DTC. See Appendix A Devicetree Source Format (version 1)

A boot program (bootloader) loads a devicetree into a client program’s memory and passes a pointer to the devicetree to the client (kernel).

A devicetree is a tree data structure with nodes that describe the devices in a system. Each node has property/value pairs that describe the characteristics of the device being represented. Each node has exactly one parent except for the root node, which has no parent.

device tree {
    node1 (device1) { property = value }
    node2 (device2) -> property/value pair
}

Device tree structure & conventions

Node Names

Each node in the devicetree is named according to the following convention:
node-name@unit-address

The node-name => component specifies the name of the node. It shall be 1 to 31 characters in length.
The unit-address => component of the name is specific to the bus type on which the node sits.

/ {
	cpus:cpus {
		cpu0:cpu@0 {
		}
		cpu1:cpu@1 {
		}
	}
	memory@0 {
	}
	serial@c81004c0 {
	}
}

in above “/” indicates root node.

Path Names

The convention for specifying a device path is:
/node-name-1/node-name-2/node-name-N

The path to the root node is /.

Properties

Each node in the devicetree has properties that describe the characteristics of the node. Properties consist of a name and a value.

Property Names – Property names are strings of 1 to 31 characters.

Property Value – A property value is an array of zero or more bytes that contain information associated with the property.

  • < empty > – Value is empty. Used for conveying true-false information.
  • < u32 > – A 32-bit integer in big-endian format.
  • < u64 > – Represents a 64-bit integer in big-endian format.
  • < string > – Strings are printable and null-terminated.
  • < prop-encoded-array > – Format is specific to the property.
  • < phandle > – A < u32 > value. A phandle value is a way to reference another node in the devicetree. Any node that can be referenced defines a phandle property with a unique < u32 > value. That number is used for the value of properties with a phandle value type.
  • A list of values concatenated together.

Standard Properties

  1. compatible
    Property Name – compatible
    Value Type – < stringlist >

The compatible property value consists of one or more strings that define the specific programming model for the device. This list of strings should be used by a client program for device driver selection.

The recommended format is “manufacturer,model”, where manufacturer is a string describing the name of the manufacturer (such as a stock ticker symbol), and model specifies the model number.

Example:
compatible = “fsl,mpc8641”, “ns16550”;
In this example, an operating system would first try to locate a device driver that supported fsl,mpc8641. If a driver was not found, it would then try to locate a driver that supported the more general ns16550 device type.

  1. model
    Property Name – model
    Value type – < string >

The model property value is a < string > that specifies the manufacturer’s model number of the device.
The recommended format is: “manufacturer,model”, where manufacturer is a string describing the name of the manufacturer (such as a stock ticker symbol), and model specifies the model number.

Example:
model = “fsl,MPC8349EMITX”;

  1. phandle
    Property name – phandle
    Property Value – < u32 >

Reference – https://devicetree-specification.readthedocs.io/en/latest/

Leave a Comment