Devicetree

The devicetree (device tree, DT) is a tree structure that describes the hardware register layout and configuration of a device. In the Linux kernel, as well as in other DT-using projects like U-Boot, it is the primary method of discovering peripherals on embedded platforms such as ARM.

Devicetrees are written in a plaintext format known as the Device Tree Source (DTS) format. The DTS is later compiled into a Device Tree Blob (DTB); in this form, it can be loaded by software/firmware.

Devicetrees are validated using devicetree schema, which is described in DT bindings; see /Bindings for more information.

Introduction

An SoC (System-on-Chip) comprises of many subcomponents: timer, clock controller, I2C/SPI controller, GPIO, interrupt controller, SDHCI storage, USB, and so on. Each needs its own driver, and for most parts the exact implementation differs between chip manufacturers. Most of them expose a static range of addresses in MMIO (memory-mapped IO) space that the system can use to communicate with them.

Additionally, there may be other peripherals connected to the system - often through a bus like I2C or SPI, or as a simple device controlled by a GPIO.

On a standard x86 system, peripherals are usually autodetected, either through ACPI, or by being on a bus like PCI or USB. On most embedded platforms like ARM, however, there is no such autodetection method, and the hardware needs to be described manually.

The solution for this, used by both the Linux kernel, as well as a variety of other projects like U-Boot, is the devicetree.

The following is a very simple example DTS (device tree source):

/dts-v1/;

/ {
	#address-cells = <1>;
	#size-cells = <1>;

	my_node: node1@1000 {
		compatible = "vendor,foo";
		reg = <0x1000 0x54>;
		vendor,bar-factor = <0x2a>;
	};

	i2c-controller@3000 {
		compatible = "vendor,foobar-i2c";
		reg = <0x3000 0x800>;
		
		#address-cells = <1>;
		#size-cells = <0>;
		
		sensor@10 {
			compatible = "vendor,baz-sensor";
			reg = <0x10>;
		};
	};
};

For a full guide to DTS syntax, see /DTS syntax.

The devicetree acts like a map of the hardware; it describes where each component is in register space, and stores configuration values for them. It also describes components located on buses like I2C and SPI, and can carry some metadata about the board/device (like the RAM size/base address, model code or chassis type).

Devicetrees are written in the DTS (Device Tree Source) format; the source file can then be compiled into a DTB (Device Tree Blob), which software can parse to get all the necessary information about a given platform.

On modern systems, the bootloader loads the DTB into a set place in memory; the Linux kernel then decodes the information from the DTB and initializes all the components based on it. (On 32-bit ARM, which predates widespread adoption of DTBs and DTB-capable bootloaders, an alternative mechanism exists in Linux to load a DTB appended to the kernel image).

History

The initial version of the devicetree standard was developed as part of the OpenFirmware initiative; from this standard, the Flattened Device Tree (FDT) emerged and was adopted by the Linux kernel for PowerPC platforms. Around 2009, discussions began to include FDT support for ARM[1]. It was eventually added and first device trees began to appear in 2011[2], although the format didn't see wider usage (especially in vendor kernels) until around 2013/2014.

Nowadays, the devicetree standard is managed by devicetree.org; they maintain the latest version of the Devicetree Specification and the related set of core DT schema.

Before the introduction of devicetrees, ARM kernels used board files. These were C files stored in arch/arm/mach-* which served a similar purpose to devicetrees - they contained structures for defining component configuration ("platform data"). Unlike device trees however, they could also define C functions, since they were regular C sources compiled into the kernel. Board files technically still exist (citation needed?), but are no longer in wide use.

Devicetree sources in the Linux kernel

TODO

Verifying DTS files

The Linux kernel has tools for making sure that device tree sources (DTS) use the bindings correctly. These are useful when writing device sources; getting the DT checks to pass is also mandatory for upstream inclusion of a DTS.

To verify all DTS files built with the selected defconfig options, run:

$ make dtbs_check

To verify a specific DTS, build the DTB target directly and provide the CHECK_DTBS=y option:

$ make CHECK_DTBS=y qcom/sm8450-hdk.dtb

You can also test a DTS against a specific subset of bindings by providing the DT_SCHEMA_FILES variable as mentioned in the previous section:

$ make CHECK_DTBS=y DT_SCHEMA_FILES=trivial-devices.yaml qcom/sm8450-hdk.dtb

Working with DTC

The dtc tool handles compiling DTS files into DTBs, as well as decompiling DTBs back into DTS. (TODO: add instructions)

See also

• From Linux kernel documentation:
  • Devicetree Sources (DTS) Coding Style
• On elinux.org:
  • Device Tree Reference
  • Device Tree Usage

References

todo enable refs extension

[1] https://www.mail-archive.com/[email protected]/msg01721.html [2] https://github.com/torvalds/linux/commit/b85a3ef4ac65169b65fd2fe9bec7912bbf475ba4