Notes about DTS

Tree Structure.

Node name

node-name@unit-address

The unit-address component of the name is specific to the bus type on which the node sits. The unit-address must match the first address specified in the reg property of the node. If the node has no reg property, the @unit-address must be omitted and the node-name alone differentiates the node from other nodes at the same level in the tree.

Properties

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

DTSpec specifies a set of standard properties for device nodes.

compatible = <stringlist>
model = <string>
phandle = <u32>
status = <string>
#address-cells, #size-cells = <u32>
reg = <prop-encodes-array> (encoded as an arbitrary number of (address, length) pairs)
virtual-reg = <u32>
ranges = <empty> / <prop-encoded-array>
dma-ranges = <empty> / <prop-encoded-array>
dma-coherent;
dma-noncoherent;

Interrupts and Interrupt Mapping

The physical wiring of an interrupt source to an interrupt controller is represented in the devicetree with the interrupt-parent property.

Each interrupt generating device contains an interrupts property with a value describing one or more interrupt sources for that device.

The #interrupt-cells property is used by the root of an interrupt domain to define the number of <u32> values needed to encode an interrupt specifier.

This is the interrupt tree example.

Properties for Interrupt generating devices

interrupts = <prop-encoded-array> 
	example: interrupts = <0xA 8>  // interrupt number and level/sense information
interrupt-parent = <phandle>
interrupts-extended = <phandle> <prop-encoded-array> // connected to multi interrupt controllers
	example: pic #interrupt-cells is 2, gic #interrupt-cells = 1
	  interrupts-extended = <&pic 0xA 8>, <&gic 0xda>

Properties for Interrupt Controllers

#interrupt-cells = <u32>
interrupt-controller; // defines a node as an interrupt controller node

Interrupt Nexus Properties

An interrupt nexus node shall have an #interrupt-cells property

interrupt-map = <prop-encoded-array>
interrupt-map-mask = <prop-encoded-array>
#interrupt-cells = <u32>

Interrupt mapping example:

The following shows the representation of a fragment of a devicetree with a PCI bus controller and a sample interrupt map for describing the interrupt routing for two PCI slots (IDSEL 0x11,0x12). The INTA, INTB, INTC, and INTD pins for slots 1 and 2 are wired to the Open PIC interrupt controller.

soc {
	compatible = "simple-bus";
	#address-cells = <1>;
	#size-cells = <1>;
	open_pic: interrupt-controller@13370000 {
		reg = <0x13370000 0x100>;
		clock-frequency = <0>; 
		interrupt-controller;
		#address-cells = <0>;
		#interrupt-cells = <2>;
	};
 
	pci: pci@47110000 {
		reg = <0x47110000 0x100>;
		#interrupt-cells = <1>;
		#size-cells = <2>;
		#address-cells = <3>;
		interrupt-map-mask = <0xf800 0 0 7>;
		interrupt-map = <
			/* IDSEL 0x11 - PCI slot 1 */ 
			0x8800 0 0 1 &open_pic 2 1 /* INTA */ 
			0x8800 0 0 2 &open_pic 3 1 /* INTB */ 
			0x8800 0 0 3 &open_pic 4 1 /* INTC */ 
			0x8800 0 0 4 &open_pic 1 1 /* INTD */
			/* IDSEL 0x12 - PCI slot 2 */ 
			0x9000 0 0 1 &open_pic 3 1 /* INTA */ 
			0x9000 0 0 2 &open_pic 4 1 /* INTB */ 
			0x9000 0 0 3 &open_pic 1 1 /* INTC */ 
			0x9000 0 0 4 &open_pic 2 1 /* INTD */
		>;
	};
};

• child unit address: 0x8800 0 0
• child interrupt specifier: 1
• interrupt parent: &open-pic
• parent unit address: (empty because #address-cells = <0> in the open-pic node)
• parent interrupt specifier: 2 1

Nexus nodes and specifier mapping

A nexus node shall have a #<specifier>-cells property, where <specifier> is some space such as ‘gpio’, ‘clock’, ‘reset’, etc.

<specifier>-map = <prop-encoded-array>

<specifier>-map-mask = <prop-encoded-array>

<specifier>-map-pass-thru = <prop-encodes-array>

#<specifier>-cells = <u32>

DTS Format

Other source files can be included from a DTS file. The name of include files should end with ‘.dtsi’. Included files can in turn include additional files.

/include/ "FILE"

Labels

Labels to be attached to any node or property value in the devicetree. Phandle and path references can be automatically generated by referencing a label instead of explicityly specifying a phandle value or the full path to a node. Labels are only used in devicetree source format and are not encoded into the DTB binary

[label:] node-name[@unit-address] {
	[properties definitions]
	[child nodes]
};
 
[properties definitions] =>
[label:] property-name[ = value];

File layout

/dts-v1/;
[memory reservations]
/ {
	[property definitions]
	[child nodes]
};

C style /* */ and C++ style // comments are supported.