Difference between revisions of "Device Tree"

From eLinux.org
Jump to: navigation, search
(Debugging: Newer kernels do not have CONFIG_PROC_DEVICETREE. Do not cat /proc/device-tree)
(Kernel Source Documentation: add some bus bindings)
(34 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
[[Category:Bootloader]]
 +
[[Category:Device_tree]]
 +
[[Category:Kernel]]
 +
 +
== Request for Documentation Suggestions ==
 +
 +
If you have any comments or suggestions about the Device Tree documentation on elinux.org, please send them
 +
to frank.rowand@sonymobile.com
 +
 +
I am currently trying to make the information more organized, more comprehensive, and a more
 +
complete index of information available elsewhere.  I am looking for comments on what is
 +
incorrect, incomplete, or missing.  I would appreciate pointers to good documentation,
 +
tutorials, etc that I can link to.
 +
 
== Introduction ==
 
== Introduction ==
  
Line 49: Line 63:
 
** No requirement to convert existing board ports
 
** No requirement to convert existing board ports
 
** No requirement to modify existing firmware
 
** No requirement to modify existing firmware
 +
 +
=== History ===
 +
 +
* [[Device_tree_history | How device tree got into Linux and how it has evolved]]
 +
 +
=== Future ===
 +
 +
* [[Device_tree_future | How device tree is changing and where it is headed]]
  
 
== Advantages ==
 
== Advantages ==
Line 133: Line 155:
  
 
== Resources ==
 
== Resources ==
=== Wiki and in-kernel documentation ===
+
 
 +
=== Standards ===
 +
[[Media:Power_ePAPR_APPROVED_v1.1.pdf | Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1]]
 +
 
 +
=== Wiki ===
 
The main device Tree wiki is at: http://www.devicetree.org/Main_Page
 
The main device Tree wiki is at: http://www.devicetree.org/Main_Page
  
Line 140: Line 166:
 
  "last modified" date at the bottom of the page (currently 23 October 2010) when comparing
 
  "last modified" date at the bottom of the page (currently 23 October 2010) when comparing
 
  to other resources.)
 
  to other resources.)
 +
=== Kernel Source Documentation ===
  
Documentation about device tree is available in the Linux kernel 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.
directory: Documentation/devicetree.  See
+
 
https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree
+
Documentation files about device tree is available in the Linux kernel source at
 +
[https://git.kernel.org/?p=/linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation Documentation]
  
 
Some especially useful files are:
 
Some especially useful files are:
* ABI.txt: comments on stable binding and general bindings rules
+
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/ABI/testing/sysfs-firmware-ofw;hb=HEAD ABI/testing/sysfs-firmware-ofw]
* resource-names.txt: -name properties containing an ordered list of names corresponding to another property
+
** description of /sys/firmware/devicetree/* on the target system
* usage-model.txt: information about different elements of bindings
+
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/;hb=HEAD devicetree/bindings]
* vendor-prefixes.txt: vendor prefix registry
+
** 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
* 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
+
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/ABI.txt;hb=HEAD devicetree/bindings/ABI.txt]
* bindings/submitting-patches.txt: important details for
+
** comments on stable binding and general bindings rules
** patch submitters
+
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/resource-names.txt;hb=HEAD devicetree/bindings/resource-names]
** kernel maintainers
+
** '''*'''-name properties containing an ordered list of names corresponding to another property
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/submitting-patches.txt;hb=HEAD devicetree/bindings/submitting-patches.txt]
 +
** important details for '''patch submitters''' and '''kernel maintainers'''
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/vendor-prefixes.txt;hb=HEAD devicetree/bindings/vendor-prefixes.txt]
 +
** vendor prefix registry
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/booting-without-of.txt;hb=HEAD devicetree/booting-without-of.txt]
 +
** original powerpc document on booting without Open Firmware
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/usage-model.txt;hb=HEAD devicetree/usage-model.txt]
 +
** information about different elements of bindings
 +
 
 +
Some subsystems have overview bindings descriptions under devicetree/bindings/:
 +
<!--
 +
creating this list:
 +
 
 +
cd Documentation/devicetree/bindings
 +
 
 +
(1)
 +
export a="[https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/"
 +
for k in `ls -1`; do if [[ -d $k ]] ; then for j in `ls $k/$k.txt 2>/dev/null` ; do echo "* ${a}devicetree/bindings/$j $j]"; done ; fi; done
 +
 
 +
Then commented out nios2.
 +
 
 +
There is a deeper directory structure, but no overview bindings docs.
 +
Verified by visual inspection of:  ls */*/*
 +
 
 +
(2)
 +
find . | grep bus.txt
 +
 
 +
 
 +
-->
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/bus/mvebu-mbus.txt bus/mvebu.bus]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/bus/simple-pm-bus.txt bus/simple-pm-bus.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/display/mipi-dsi-bus.txt display/mipi-dsi-bus.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/dma/dma.txt dma/dma.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/gpio/gpio.txt gpio/gpio.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/hwlock/hwlock.txt hwlock/hwlock.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/iommu/iommu.txt iommu/iommu.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/lpddr2/lpddr2.txt lpddr2/lpddr2.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/mailbox/mailbox.txt mailbox/mailbox.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/memory-controllers/mvebu-devbus.txt memory-controllers/mvebu-devbus.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/mfd/mfd.txt mfd/mfd.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/mips/cavium/bootbus.txt mips/cavium/bootbus.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/mmc/mmc.txt mmc/mmc.txt]
 +
<!-- nios2 is an SOC
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/nios2/nios2.txt nios2/nios2.txt]
 +
-->
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/pci/pci.txt pci/pci.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/power_supply/power_supply.txt power_supply/power_supply.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/pwm/pwm.txt pwm/pwm.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/regmap/regmap.txt regmap/regmap.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/regulator/regulator.txt regulator/regulator.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt reserved-memory/reserved-memory.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/reset/reset.txt reset/reset.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/spi/spi-bus.txt spi/spi-bus.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/spmi/spmi.txt spmi/spmi.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/thermal/thermal.txt thermal/thermal.txt]
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/xillybus/xillybus.txt xillybus/xillybus.txt]
  
 
=== FAQ, tips and/or best practices ===
 
=== FAQ, tips and/or best practices ===
Line 159: Line 243:
  
 
=== Presentations, Papers and Articles ===
 
=== Presentations, Papers and Articles ===
* "The Device Tree as a Stable ABI: A Fairy Tale?", ELC 2015 by Thomas Petazzoni
+
See the [[Device Tree presentations papers articles]] page
** http://elinux.org/images/0/0a/The_Device_Tree_as_a_Stable_ABI-_A_Fairy_Tale%3F.pdf
 
* "Device Tree for Dummies", ELC 2014 by Thomas Petazzoni
 
** [[Media:petazzoni-device-tree-dummies_0.pdf|PDF]]
 
** [https://www.youtube.com/watch?v=uzBwHFjJ0vU YouTube video]
 
* [https://lwn.net/Articles/572692/ Device trees I: Are we having fun yet?] - Neil Brown, LWN.net November 2013
 
* [https://lwn.net/Articles/573409/ Device trees II: The harder parts] - Neil Brown, LWN.net November 2013
 
* "Device Tree for Dummies", ELC Europe 2013 by Thomas Petazzoni
 
** [[Media:Elce2013-petazzoni-devicetree-for-dummies.pdf|PDF]]
 
** [https://www.youtube.com/watch?v=m_NyYEBxfn8 YouTube video]
 
* "Transactional Device Tree & Overlays: Making Reconfigurable Hardware Work", ELC Europe 2014 by Pantelis Antoniou
 
** [[Media:Antoniou--transactional_device_tree_and_overlays.pdf]]
 
* "devicetree: Kernel Internals and Practical Troubleshooting", ELC Europe 2014 by Frank Rowand
 
** [[Media:Rowand--devicetree_kernel_internals.pdf]]
 
* "Device Tree, the Disaster so Far", ELC Europe 2013 by Mark Rutland
 
** [[Media:Rutland-presentation_3.pdf]]
 
** [https://www.youtube.com/watch?v=xamjHjjyeBI YouTube video]
 
* "Best Practices for Long Term Support and Security of the Device-Tree (DT)" ELC Europe 2013 by Alison Chaiken
 
** [[Media:Chaiken-DT_ELCE_2013.pdf]]
 
* "Board file to Device Tree Migration" ELC Europe 2013 by Pantelis Antoniou
 
** [[Media:ELCE2013_-_DT_War.pdf]]
 
* "ARM support in the Linux kernel", Presented at FOSDEM 2013 by Thomas Petazzoni
 
** https://archive.fosdem.org/2013/schedule/event/arm_in_the_linux_kernel/attachments/slides/273/export/events/attachments/arm_in_the_linux_kernel/slides/273/arm_support_kernel.pdf
 
** Has good material on how device tree is part of the overall ARM architecture refactoring, with some details on how it is used
 
* "Linux kernel: consolidation in the ARM architecture support" - Libre Software Meeting, 2013 by Thomas Petazzoni
 
** http://free-electrons.com/pub/conferences/2012/lsm/arm-kernel-consolidation/arm-kernel-consolidation.pdf
 
* "Experiences With Device Tree Support Development For ARM-Based SOC's", Thomas P. Abraham, ELC 2012
 
** [[Media:Experiences_With_Device_Tree_Support_Development_For_ARM-Based_SOC%27s.pdf]]
 
** slides and videos for ELC 2012: http://free-electrons.com/blog/elc-2012-videos/
 
* "Device Tree Status Report", Grant Likely, ELC Europe 2011
 
** Slides and videos for ELC Europe 2011: http://free-electrons.com/blog/elce-2011-videos/
 
 
 
===== Notes on various sub-systems that device-tree describes =====
 
* "Pin Control Subsystem – Building Pins and GPIO from the ground up" - Presented at Linaro Connect, 2013 by Linus Walleij
 
** http://www.df.lth.se/~triad/papers/pincontrol.pdf
 
 
 
==== older stuff ====
 
There is documentation describing device tree support (with information current as of 2006) in the
 
Linux kernel source tree at:
 
[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/powerpc/booting-without-of.txt;hb=HEAD Documentation/powerpc/booting-without-of.txt]
 
 
 
* "Using the Device Tree to Describe Embedded Hardware" - Grant Likely, Embedded Linux Conference, 2008
 
** http://www.celinux.org/elc08_presentations/glikely--device-tree.pdf
 
* "A Symphony of Flavours: Using the device tree to describe embedded hardware" - Grant Likely and Josh Boyer - paper for OLS 2008
 
** http://ols.fedoraproject.org/OLS/Reprints-2008/likely2-reprint.pdf
 
* Note from Device Tree Birds of a Feature session at OLS 2008:
 
**http://lists.ozlabs.org/pipermail/devicetree-discuss/2008-July/000004.html
 
* Links to the Open Firmware device tree bindings and recommended practices which also apply to the FDT:
 
** http://www.openfirmware.info/Bindings
 
* A view from outside from the FreeBSD ARM community:
 
** http://wiki.freebsd.org/FreeBSDArmBoards
 
  
 
=== Tools ===
 
=== Tools ===
Line 217: Line 251:
 
*** https://git.kernel.org/cgit/utils/dtc/dtc.git
 
*** https://git.kernel.org/cgit/utils/dtc/dtc.git
 
*** git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
 
*** git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
 +
** Documentation
 +
*** [https://git.kernel.org/?p=utils/dtc/dtc.git;a=blob_plain;f=Documentation/manual.txt;hb=HEAD Documentation/manual.txt] Device Tree Compiler Manual
 +
*** [https://git.kernel.org/?p=utils/dtc/dtc.git;a=blob_plain;f=Documentation/dts-format.txt;hb=HEAD Documentation/dts-format.txt] Device Tree Source Format
 +
** The Maintainers are listed in the file [https://git.kernel.org/?p=utils/dtc/dtc.git;a=blob_plain;f=README;hb=HEAD README]
 
* Xilinx EDK device-tree generator - Generates an FDT from Xilinx FPGA design files.
 
* Xilinx EDK device-tree generator - Generates an FDT from Xilinx FPGA design files.
 
** http://xilinx.wikidot.com/device-tree-generator
 
** http://xilinx.wikidot.com/device-tree-generator
Line 223: Line 261:
  
 
=== Debugging ===
 
=== Debugging ===
 +
 +
The current best reference is '"Solving Device Tree Issues" (updated), ELCE October 2015 by Frank Rowand' on the [[Device Tree presentations papers articles]] page.
 +
 
You can set CONFIG_PROC_DEVICETREE to be able to see the device tree information in /proc after booting.
 
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'
 
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
 
For newer kernels where the CONFIG_PROC_DEVICETREE option does not exist, /proc/device-tree will be
Line 246: Line 295:
  
 
=== Device-tree Mailing List ===
 
=== Device-tree Mailing List ===
 +
 +
This list contained all devicetree related discussion until February 2014.
 +
At that time, the devicetree.spec and devicetree.compiler lists were
 +
created to provide lower volume lists for those specific topic areas.
  
 
After July 2013:
 
After July 2013:
Line 251: Line 304:
 
   http://vger.kernel.org/vger-lists.html#devicetree
 
   http://vger.kernel.org/vger-lists.html#devicetree
 
   archive: http://www.spinics.net/lists/devicetree/
 
   archive: http://www.spinics.net/lists/devicetree/
 +
  archive: http://dir.gmane.org/gmane.linux.drivers.devicetree
  
 
Up through July 2013:
 
Up through July 2013:
  
 
   https://lists.ozlabs.org/listinfo/devicetree-discuss
 
   https://lists.ozlabs.org/listinfo/devicetree-discuss
 +
  archive: https://lists.ozlabs.org/pipermail/devicetree-discuss/
 
   archive: http://news.gmane.org/gmane.linux.drivers.devicetree
 
   archive: http://news.gmane.org/gmane.linux.drivers.devicetree
  
=== Mailing list discussion ===
+
=== Core devicetree binding Mailing List ===
Recent discussion of "Flattened Device Tree" work on linux-embedded mailing list:
 
http://www.mail-archive.com/linux-embedded@vger.kernel.org/msg01721.html
 
  
Russel King is against adding support for FDT to the ARM platform:
+
Created February 2014.
http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/01942.html
 
(see whole thread for interesting discussion)
 
  
But maybe Russel can be convinced: http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/03618.html
+
The devicetree.spec list is for "core" binding discussions; anything that
 +
affects entire subsystems or the kinds of things that would make sense
 +
to be added to ePAPR.
  
David Gibson defends FDT:
+
Individual device bindings continue to be posted to
http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/02304.html
+
devicetree@vger.kernel.org, but anything affecting subsystems or
[[Category:Bootloader]]
+
generic patterns should be posted to this list.
[[Category:Kernel]]
+
 
 +
  http://vger.kernel.org/vger-lists.html#devicetree-spec
 +
  archive: http://dir.gmane.org/gmane.comp.devicetree.spec
 +
 
 +
=== Device-tree Compiler and Tools Mailing List ===
 +
 
 +
Created February 2014.
 +
 
 +
The devicetree.compiler list is for discussion related to dtc and other tools.
 +
 
 +
It is specifically for discussing dt tooling topics
 +
(parsing, schema validation, data format, etc).
 +
 
 +
  http://vger.kernel.org/vger-lists.html#devicetree-compiler
 +
  archive: http://dir.gmane.org/gmane.comp.devicetree.compiler

Revision as of 18:27, 24 November 2015


Request for Documentation Suggestions

If you have any comments or suggestions about the Device Tree documentation on elinux.org, please send them to frank.rowand@sonymobile.com

I am currently trying to make the information more organized, more comprehensive, and a more complete index of information available elsewhere. I am looking for comments on what is incorrect, incomplete, or missing. I would appreciate pointers to good documentation, tutorials, etc that I can link to.

Introduction

Device Tree data can be represented in several different formats. It is derived from the device tree format used by Open Firmware to encapsulate platform information and convey it to the Linux operating system. The device tree data is typically created and maintained in a human readable format in .dts source files and .dtsi source include files. The Linux build system pre-processes the source with cpp.

The device tree source is compiled into a binary format contained in a .dtb blob file. The format of the data in the .dtb blob file is commonly referred to as a Flattened Device Tree (FDT). The Linux operating system uses the device tree data to find and register the devices in the system. The FDT is accessed in the raw form during the very early phases of boot, but is expanded into a kernel internal data structure for more efficient access for later phases of the boot and after the system has completed booting.

Currently the Linux kernel can read device tree information in the ARM, x86, Microblaze, PowerPC, and Sparc architectures. There is interest in extending support for device trees to other platforms, to unify the handling of platform description across kernel architectures.

The Flattened Device Tree is...

The Flattened Device Tree (FDT) is a data structure. Nothing more.

It describes a machine hardware configuration. It is derived from the device tree format used by Open Firmware. The format is expressive and able to describe most board design aspects including:

  • the number and type of CPUs,
  • base addresses and size of RAM,
  • busses and bridges,
  • peripheral device connections, and
  • interrupt controllers and IRQ line connections.

Just like initrd images, an FDT image can either be statically linked into the kernel or passed to the kernel at boot time.

The Flattened Device Tree is not...

  • is not a solution to all board port problems
    • Nothing will eliminate all board specific drivers for custom and complex boards.
  • is not a firmware interface
    • It might be part of a generic firmware interface, but on its own the device tree is just a data structure.
    • does not replace ATAGS... but an FDT image can be passed via an ATAG.
    • See "Competing Solutions" below
  • is not intended to be a universal interface.
    • It is a useful data structure which solves several problems, but whether or not to use it is still up to the board port author.
  • is not an invasive change
    • No requirement to use FDT approach in a board port
    • Device Tree is required for new board support in the ARM architecture.
    • No requirement to convert existing board ports
    • No requirement to modify existing firmware

History

Future

Advantages

for distributions

  • potentially fewer kernel images needed on an installer image (ie. for ARM netbooks)
    • Ship one FDT image per machine (<4k/machine) instead of 1 kernel image per machine (~1-2MB/machine) with a small number of sub-arch kernel images (ie. ARM11, CortexA8, CortexA9, etc).
    • Becomes feasible for current installer image to boot on future hardware platforms using same chipset.
    • Note: FDT is only part of the solution here. Some boot software is still required to select and pass in the correct FDT image.

for System on Chip (SoC) vendors

  • Reduce or eliminate effort needed to write machine support code (ie arch/arm/mach-*). Focus on device driver development instead.

for board designers

  • Reduce effort required to port.
    • SoC vendor supplied reference design binaries may also be bootable on custom machine.
  • No need to allocate a new global ARM machine id for each new board variant.
    • Use the device tree <vendor>,<boardname> namespace instead
  • Most board specific code changes constrained to device tree file and device drivers.
  • Example: Xilinx FPGA toolchain has a tool to generate a device tree source file from the FPGA design files.
    • Since the hardware description is constrained to the device tree source, FPGA engineers can test design changes without getting involved with kernel code.
    • Alternately, kernel coders don't need to manually extract design changes from the FPGA design files.

for embedded Linux ecosystem

  • smaller amount of board support code to merge
  • greater likelyhood of mainline support for boards from "uninterested" vendors
  • greater ability to correct poor board support by fixing or replacing broken FDT images.

for firmware/bootloader developers

  • reduce impact of getting board description wrong (FDT stored as a separate image instead of statically linked into firmware). If initial release gets the board description wrong, then it is easily updated without a risky reflash of firmware.
  • expressive format to describe related board variants without allocating new machine numbers or new ATAGs.
  • Note: The FDT isn't a replacement to ATAGS, but does supplement them.

Other advantages

  • Device tree source and FDTs can easily be machine generated and/or modified.
    • Xilinx FPGA tools do device tree source generation
    • U-Boot firmware can inspect and modify an FDT image before booting

Competing Solutions

board specific data structures

Some platforms use board-specific C data structures for passing data from the bootloader to the kernel. Notable here is embedded PowerPC support before standardizing on the FDT data format.

Experience with PowerPC demonstrated that using a custom C data structure is certainly an expedient solution for small amounts of data, but it causes maintainability issues in the long term and it doesn't make any attempt to solve the problem of describing the board configuration as a whole. Special cases tend to grow and there is no way for the kernel to determine what specific version of the data structure is passed to it. PowerPCs board info structure ended up being a mess of #ifdefs and ugly hacks, and it still only passed a handful of data like memory size and Ethernet MAC addresses.

ATAGs have the elegance of providing an well defined namespace for passing individual data items (memory regions, initrd address, etc) and the operating system can reliably decode them. However, only a dozen or so ATAGs are defined and is not expressive enough to describe the board design. Using ATAGs essentially requires a separate machine number to be allocated for each board variant, even if they are based on the same design.

That being said, an ATAG is an ideal method for passing an FDT image to the kernel in the same way an ATAG is used to pass the initrd address.

ACPI

Firmware providing the Advanced Configuration and Power Interface exports a hardware description in the form of the Differentiated System Description Table (DSDT). ACPI is found on x86 compatible systems and has its roots in the original IBM PC BIOS.

UEFI

The Extensible Firmware Interface is an interface specification for passing control from a platforms firmware to the operating system. It was designed by Intel as a replacement for the PC BIOS interface.

ARM holdings is a member of the United EFI Forum. It is conceivable that there will be an ARM implementation of UEFI.

Open Firmware

Open Firmware is a firmware interface specification designed by Sun in the late 1980's, and ported to many architectures. It specifies a runtime OS client interface, an cross platform device interface (FCode), a user interface, and the Device Tree layout for describing the machine.

FDT is to Open Firmware what DSDT is to ACPI. The FDT reuses Open Firmware's established device tree layout. In fact, Linux PowerPC support uses the same codebase to support both Open Firmware and FDT platforms.

Some Notes on the Competing Solutions

Most of the competing solutions listed above provided feature rich firmware interfaces including both machine description and runtime services. Conversely, the FDT is only a data structure and doesn't specify any firmware interface details. Board ports using the FDT are typically booted from simple firmware implementations like U-Boot and don't provide any form of runtime services.

A common design goal of the feature rich firmware interfaces is to provide an abstract boot interface that factors away the differences between different hardware platforms, at least enough for the OS to initialize its own native device drivers. The idea is to be able to boot 'old' OS images on 'new' hardware, like how a Linux LiveCD image doesn't have explicit knowledge of the hardware configuration, but relies on the information provided to it by firmware.

Typical design goals for embedded firmware is to a) boot the OS as quickly as possible, b) upgrade the OS image, and maybe c) provide some low level debug support during initial board bringup. Focus tends to shift away from firmware once the OS is bootable since the kernel drivers the hardware directly (doesn't depend on firmware runtime services). In fact, firmware updates are discouraged due to the risk of rendering a board unbootable. ACPI, UEFI and OpenFirmware solutions, while arguably 'better', often don't boot as fast, and are more complex than required by the embedded system. In this regard the FDT approach has the advantage due to its simplicity. ie. the FDT provides an equivalently expressive way to describe hardware, but it works with existing firmware and can be updated without reflashing firmware.

Resources

Standards

Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1

Wiki

The main device Tree wiki is at: http://www.devicetree.org/Main_Page

http://www.devicetree.org/Device_Tree_Usage is an excellent introduction to device tree
concepts and the representation of those concepts in device tree source.  (But check the
"last modified" date at the bottom of the page (currently 23 October 2010) when comparing
to other resources.)

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

Some especially useful files are:

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

FAQ, tips and/or best practices

See the Linux Drivers Device Tree Guide.

Presentations, Papers and Articles

See the Device Tree presentations papers articles page

Tools

"The device tree generator is a Xilinx EDK tool that plugs into the
Automatic BSP Generation features of the tool, XPS"

Debugging

The current best reference is '"Solving Device Tree Issues" (updated), ELCE October 2015 by Frank Rowand' on the Device Tree presentations papers articles page.

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

Device-Tree irc

The Device Tree irc channel is #devicetree on freenode.net.

Device-tree Mailing List

This list contained all devicetree related discussion until February 2014. At that time, the devicetree.spec and devicetree.compiler lists were created to provide lower volume lists for those specific topic areas.

After July 2013:

 http://vger.kernel.org/vger-lists.html#devicetree
 archive: http://www.spinics.net/lists/devicetree/
 archive: http://dir.gmane.org/gmane.linux.drivers.devicetree

Up through July 2013:

 https://lists.ozlabs.org/listinfo/devicetree-discuss
 archive: https://lists.ozlabs.org/pipermail/devicetree-discuss/
 archive: http://news.gmane.org/gmane.linux.drivers.devicetree

Core devicetree binding Mailing List

Created February 2014.

The devicetree.spec list is for "core" binding discussions; anything that affects entire subsystems or the kinds of things that would make sense to be added to ePAPR.

Individual device bindings continue to be posted to devicetree@vger.kernel.org, but anything affecting subsystems or generic patterns should be posted to this list.

 http://vger.kernel.org/vger-lists.html#devicetree-spec
 archive: http://dir.gmane.org/gmane.comp.devicetree.spec

Device-tree Compiler and Tools Mailing List

Created February 2014.

The devicetree.compiler list is for discussion related to dtc and other tools.

It is specifically for discussing dt tooling topics (parsing, schema validation, data format, etc).

 http://vger.kernel.org/vger-lists.html#devicetree-compiler
 archive: http://dir.gmane.org/gmane.comp.devicetree.compiler