Device Tree Reference

Top Device Tree page

Device Tree Usage
If Device Tree is new to you, start with Device Tree Usage page. That page describes what Device Tree source looks like. It walks through building the source for a new machine. It describes the basic concepts, shows specific examples, and covers some advanced features.

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

Presentations, Papers, and Articles
The Device Tree presentations, papers, and articles page is organized by topic area and by date.

Device Tree Mysteries
If you can not find a specific piece of information elsewhere, it might be on the Device_Tree_Mysteries page.

Linux Specific
Device Tree Linux

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.

Device Tree Source Format

 * [[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


 * Undocumented
 * Device_Tree_Source_Undocumented contains some information not documented elsewhere

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

Bindings Documentation in Linux Kernel Source Tree
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 (in alphabetic order) 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


 * 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/changesets.txt
 * Description of changesets. Apply changes such that full set of changes is applied successfully or none are.


 * devicetree/dynamic-resolution-notes.txt
 * Implementation of resolver, used when applying overlays.


 * devicetree/of_unittest.txt
 * How data for device tree unit tests is added to the kernel


 * devicetree/overlay-notes.txt
 * How data for device tree unit tests is added to the kernel


 * devicetree/usage-model.txt
 * Implementation of overlay

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


 * bus/mvebu.bus
 * bus/simple-pm-bus.txt
 * clock/clock-bindings.txt
 * display/mipi-dsi-bus.txt
 * dma/dma.txt
 * gpio/gpio.txt
 * hwlock/hwlock.txt
 * iio/iio.txt
 * interrupt-controller/interrupts.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
 * phy/phy-bindings.txt
 * pinctrl/pinctrl-bindings.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

Subsystem specific

 * gpio / pinctrl


 * interrupts


 * timers


 * etc

Device Tree Source Validation
See device tree future work.

Compiling source into .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

FDT format
Other names for Flattened Device Tree (FDT) are "binary blob" and ".dtb".

The format of version 17 of the FDT is described in chapter 8, "Flat Device Tree Physical Structure" of the [[Media:Power_ePAPR_APPROVED_v1.1.pdf | ePAPR v1.1]].

Section "II - The DT block format" of booting-without-of.txt is a more expansive description of the format of FDT.

Install

 * make dtbs_install
 * installs in /boot/dtbs/


 * many other ways to install ....

Debugging
(Also see Device_Tree_presentations_papers_articles.)


 * 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/
 * scripts/dtc/dtx_diff
 * in the Linux kernel source tree as of 4.6-rc1
 * use cases, advantages, and things to be aware of are described in [[Media:Dt_debugging_elce_2015_151006_0421.pdf | "Solving Device Tree Issues"]] (updated), ELCE October 2015 by Frank Rowand (PDF). dtx_diff is referred to as "dtdiff" in this presentation.


 * 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

dtc
dtc (Device Tree Compiler) - 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 located in scripts/dtc/ in the kernel source directory. New versions are periodically pulled from the upstream project.
 * 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
 * Info on submitting patches is in section 1.1 of Documentation/manual.txt
 * Documentation
 * Documentation/manual.txt Device Tree Compiler Manual
 * Documentation/dts-format.txt Device Tree Source Format
 * The Maintainers are listed in the file README

dtx_diff
dtx_diff has two modes of operation:
 * compare two dtX files
 * compile a single dtX file (using the normal Linux includes and .config) then decompiles that into a device tree source file.

A dtX file can be a device tree source file, a device tree compiled file (aka .dtb, FDT, or device tree blob), or a file system based subtree (either /proc/device-tree on the target system, or /proc/device-tree can be tarred on the target system and untarred on the system containing dtx_diff).

Examples of how to use dtx_diff can be found in [[Media:Dt_debugging_elce_2015_151006_0421.pdf | "Solving Device Tree Issues" (updated), ELCE October 2015, Frank Rowand ]]. Note that dtx_diff was named 'dtdiff' in the presentation.

dtx_diff was merged in 4.6-rc1.

dt_to_config
dt_to_config is a tool to provide information about the Linux kernel configuration options needed by a given device tree.

dt_to_config can also report on whether the kernel configuration options are set correctly.

Examples of how to use dt_to_config and some limitations to be aware of can be found in [[Media:Dt_debugging_part_2.pdf | "Solving Device Tree Issues - part 2", LinuxCon Japan, July 2016, Frank Rowand ]].

dt_to_config was merged in 4.8-rc1.

dts-mode
From the github README.mkd: a quick attempt at getting basic highlighting for Device Tree syntax in emacs.

From the announcement: Today I cobbled together a rudimentary devicetree major mode for emacs. At this point it's pretty much limited to rather basic syntax highlighting but works fairly well all things considered. It can be found on Github[1]. Patches are of course quite welcome.

Project location on [github].

I am not an emacs user, so I would appreciate any feedback on how useful this tool is and additional information that could be added to this description (or if the tool is useless and should be removed from this page). Email me at frowand (dot) list (at) gmail (dot) com

EDK
"The device tree generator is a Xilinx EDK tool that plugs into the Automatic BSP Generation features of the tool, XPS"
 * Xilinx EDK device-tree generator - Generates an FDT from Xilinx FPGA design files.
 * http://xilinx.wikidot.com/device-tree-generator

linux kernel framework
Enable unit tests through config option CONFIG_OF_UNITTEST


 * Device Drivers ---> Device Tree and Open Firmware support ---> Device Tree runtime unit tests

The unit tests will be performed near the end of the boot sequence. The start of the tests is indicated by:


 * 1) dt-test ### start of unittest - you will see error messages

An example test result summary is:


 * 1) dt-test ### end of unittest - 148 passed, 0 failed

The unit tests are located in
 * drivers/of/unittest.c
 * drivers/of/unittest-data/

dtc
The dtc tests are located in the upstream dtc project (see Device_Tree_Reference).

build dtc: make build tests: make tests run tests: make check run tests with valgrind --tool=memcheck: make checkm run tests in verbose mode: make checkv

Each test will report PASS or FAIL.

An example test result summary is:

********** TEST SUMMARY *    Total testcases:	1565 *               PASS:	1565 *               FAIL:	0 *  Bad configuration:	0 * Strange test result:	0 **********

Other projects using Device Tree
FreeBSD FlattenedDeviceTree wiki

FreeBSDArmBoards wiki

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.