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.

2. 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”;

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

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