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.

= Compiling the Device Tree =

The syntax device tree sources in the kernel deviates from its regular syntax by using the cpp-preprocessor for includes and substition. 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

Note: A quick way to rebuild the device tree blobs for any enabled board(s) is to use the command  from an already configured kernel source directory.

= 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.