Device Tree Reference

Top Device Tree page

Device Tree Usage
The Device Tree Usage page was previously located at devicetree.org

It walks through how to write a device tree for a new machine.

It is intended to provide an overview of device tree concepts and how they are used to describe a machine.

Miscellaneous Tips
Linux Drivers Device Tree Guide

Standards
[[Media:Power_ePAPR_APPROVED_v1.1.pdf | Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1]] Source: https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/

The ePAPR is currently being updated with a new name of Devicetree Specification Documentation.

Kernel Source Documentation
The device tree core source files under drivers/of/ contain DocBook format comments, but there is not yet a DocBook document that includes them.

Documentation files about device tree is available in the Linux kernel source at Documentation/devicetree

Specific bindings specifications are located in the Linux kernel source at: Documentation/devicetree/bindings

Some especially useful files are:
 * ABI/testing/sysfs-firmware-ofw
 * description of /sys/firmware/devicetree/* on the target system
 * devicetree/bindings
 * the bindings directory has details about the syntax and expected elements for each device type representable in the dts and used by kernel frameworks and drivers
 * devicetree/bindings/ABI.txt
 * comments on stable binding and general bindings rules
 * not yet mainline: devicetree/bindings/property-units.txt
 * how to name properties which have a unit of measure
 * devicetree/bindings/resource-names
 * *-name properties containing an ordered list of names corresponding to another property
 * devicetree/bindings/submitting-patches.txt
 * important details for patch submitters and kernel maintainers
 * devicetree/bindings/vendor-prefixes.txt
 * vendor prefix registry
 * devicetree/booting-without-of.txt
 * original powerpc document on booting without Open Firmware
 * devicetree/usage-model.txt
 * information about different elements of bindings

Some subsystems have overview bindings descriptions under devicetree/bindings/:


 * bus/mvebu.bus
 * bus/simple-pm-bus.txt
 * display/mipi-dsi-bus.txt
 * dma/dma.txt
 * gpio/gpio.txt
 * hwlock/hwlock.txt
 * iommu/iommu.txt
 * lpddr2/lpddr2.txt
 * mailbox/mailbox.txt
 * memory-controllers/mvebu-devbus.txt
 * mfd/mfd.txt
 * mips/cavium/bootbus.txt
 * mmc/mmc.txt


 * pci/pci.txt
 * power_supply/power_supply.txt
 * pwm/pwm.txt
 * regmap/regmap.txt
 * regulator/regulator.txt
 * reserved-memory/reserved-memory.txt
 * reset/reset.txt
 * spi/spi-bus.txt
 * spmi/spmi.txt
 * thermal/thermal.txt
 * xillybus/xillybus.txt

Device Tree Source

 * [[Media:Power_ePAPR_APPROVED_v1.1.pdf | Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1]]
 * chapter 2 "The Device Tree"
 * Appendix A "Device Tree Source Format (Version 1)"


 * dtc compiler repository documentation
 * Documentation/dts-format.txt Device Tree Source Format
 * differences between ePAPR and the Linux dtc compiler


 * presentations
 * "Device Tree for Dummies", ELC 2014 by Thomas Petazzoni
 * [[Media:petazzoni-device-tree-dummies_0.pdf | PDF]]
 * YouTube video

Bindings
Bindings are documented in
 * Standards documents
 * Linux kernel source tree

Subsystem specific

 * gpio / pinctrl


 * interrupts


 * timers


 * etc

Compiling .dtb (FDT binary blob)

 * via kernel make system
 * all configured .dtb
 * make dtbs
 * specific .dtb
 * make arch/arm/boot/dts/qcom-apq8074-dragonboard.dtb


 * via generated script in build directory
 * arch/arm/boot/dts/.*.dtb.cmd
 * arch/${ARCH}/boot/dts/.*.dtb.cmd


 * Documentation/manual.txt Device Tree Compiler Manual

Install

 * make dtbs_install
 * installs in /boot/dtbs/


 * many other ways to install ....

Debugging

 * tutorials
 * "Solving Device Tree Issues" (updated), ELCE October 2015 by Frank Rowand
 * [[Media:Dt_debugging_elce_2015_151006_0421.pdf | PDF slides]]
 * Supporting Resources (patches, etc)


 * diffing .dts, .dtb, /proc/devicetree/


 * locating source location for properties


 * boot time messages
 * device creation
 * driver registration
 * binding driver to device
 * deferred binding

Debugging - random hints
You can set CONFIG_PROC_DEVICETREE to be able to see the device tree information in /proc after booting. Build the kernel with this option set to 'Y', boot the kernel, then 'cd /proc/device-tree'

/proc/device-tree still does not exist. Now what??? Is CONFIG_PROC_FS enabled? Is CONFIG_OF enabled? Does /sys/firmware/devicetree/base exist? (Note that this path is not an ABI, but currently  /proc/devicetree is a soft link to this location.) Did the bootloader load a devicetree? (Check the boot console or use dmesg to print the boot messages.)

For newer kernels where the CONFIG_PROC_DEVICETREE option does not exist, /proc/device-tree will be created if CONFIG_PROC_FS is set to 'Y'.

You might also try CONFIG_DEBUG_DRIVER=Y.

Also, often, you can set the line: "#define DEBUG 1" to an individual C file, to produce add debug statements to the routines in that file. This will activate any pr_debug lines in the source for that file.

Alternatively, you can add the following to drivers/of/Makefile:

CFLAGS_base.o := -DDEBUG CFLAGS_device.o := -DDEBUG CFLAGS_platform.o := -DDEBUG CFLAGS_fdt.o := -DDEBUG

Tools
"The device tree generator is a Xilinx EDK tool that plugs into the Automatic BSP Generation features of the tool, XPS"
 * Device Tree Compiler (dtc) - converts between the human editable device tree source "dts" format and the compact device tree blob "dtb" representation usable by the kernel or assembler source. dtc is also a dtb decompiler.
 * The linux version of dtc is maintained in scripts/dtc/ in the kernel source directory.
 * The upstream project is maintained in
 * https://git.kernel.org/cgit/utils/dtc/dtc.git
 * git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
 * Documentation
 * Documentation/manual.txt Device Tree Compiler Manual
 * Documentation/dts-format.txt Device Tree Source Format
 * The Maintainers are listed in the file README
 * Xilinx EDK device-tree generator - Generates an FDT from Xilinx FPGA design files.
 * http://xilinx.wikidot.com/device-tree-generator

Man pages
man pages are a work in progress.

The current version of the pages can be downloaded or built locally.

Glossary

 * .dtb - File name suffix, by convention, for compiled devicetree.
 * .dts - File name suffix, by convention, for devicetree source.
 * .dtsi - File name suffix, by convention, for devicetree source to be included by a .dts or .dtsi file.
 * Binary Blob - File containing a compiled devicetree.
 * dtc - Devicetree compiler.
 * EDT Expanded Device Tree - A copy of an FDT, but converted to kernel data structures, in the kernel memory space.
 * FDT Flattened Device Tree - A copy of a binary blob in the kernel memory space.