Device Tree

The Device Tree is a data structure for describing hardware. Mainline Linux uses it to activate and configure the drivers available in the kernel's binary (similar to script.bin for linux-sunxi). Mainline U-Boot is also migrating towards the device tree model.

= Sources for information =

Introduction
For a general introduction on device trees see:
 * elinux.org summary on Device Tree
 * Device tree for Dummies (PDF)
 * DeviceTree.org

In a nut shell, the kernel uses properties of the form compatible = ", " to identify a driver and initialize it with the configuration additionally provided by more attributes or sub-section.

Particular Drivers
Every driver has its particular parameters, documented in:


 * Documentation/devicetree/bindings

Complete Examples
Writing a device tree for your board, you might want to look at:


 * arch/arm/boot/dts

= Writing a Device Tree =

It is good to start with an example of a device which is close to the one you're working on. Trim down the original device's dts to what your device actually provides. If your device came with a fex file, check settings like the gpio for enabling the usb vbus in the fex file and adjust them in the dts file as necessary. Finally, work on activating drivers particular to your device. Again parameters might be taken over from a fex file.

Coding Style
Recently, coding style moved over from using a full node hierarchy to using label references in board dts files, see e.g. :

https://git.kernel.org/cgit/linux/kernel/git/mripard/linux.git/commit/?h=sunxi/dt-for-3.20&id=327f121fea91fd79d6b71f47a8e1bc62a7fd86e5

Note that the nodes should be sorted alphabetically.

= Get the Device-tree Compiler =

This program is usually called dtc. You can retrieve a standalone version, or install a distribution-provided package (see below for some examples).

For Gentoo
emerge dtc

For openSUSE
zypper install dtc

For Debian/Ubuntu
apt-get install device-tree-compiler

For Arch
pacman -S dtc

= Compiling the Device Tree =

Device tree sources in the kernel deviate from the regular syntax, by using the cpp preprocessor for includes and substitution. This proceeds as follows:

IDE= SRC=$IDE.dts TMP=$IDE.tmp.dts DST=$IDE.dtb

cpp -nostdinc -I include -undef -x assembler-with-cpp $SRC > $TMP dtc -O dtb -b 0 -o $DST $TMP rm $TMP

= Using the Device Tree =

To actually make the kernel use the device tree, see Mainline_Kernel_Howto.

= Adding a new device =

Add your &lt;device>.dts file to /arch/arm/boot/dts/ and include it to /arch/arm/boot/dts/Makefile as done in this patch. Help others by publishing your device tree as a patch.