Difference between revisions of "Device Tree Reference"

From eLinux.org
Jump to: navigation, search
(move link to debug presentations from section "Debugging - random hints" to section "Debugging")
(remove top level header ("Reference Manual"), decrease each other header level by one)
Line 3: Line 3:
 
[[Device_Tree | Top Device Tree page]]
 
[[Device_Tree | Top Device Tree page]]
  
== Reference Manual ==
+
== Introduction ==
  
=== Introduction ===
+
== Device Tree Usage ==
 
 
=== Device Tree Usage ===
 
  
 
If Device Tree is new to you, start with [[Device_Tree_Usage | Device Tree Usage page]].
 
If Device Tree is new to you, start with [[Device_Tree_Usage | Device Tree Usage page]].
Line 16: Line 14:
 
[[Device_Tree_Usage | Device Tree Usage page]] was previously located at devicetree.org.
 
[[Device_Tree_Usage | Device Tree Usage page]] was previously located at devicetree.org.
  
=== Presentations, Papers, and Articles ===
+
== Presentations, Papers, and Articles ==
  
 
The
 
The
Line 22: Line 20:
 
page is organized by topic area and by date.
 
page is organized by topic area and by date.
  
=== Device Tree Mysteries ===
+
== Device Tree Mysteries ==
  
 
If you can not find a specific piece of information elsewhere, it might be on the [[Device_Tree_Mysteries]] page.
 
If you can not find a specific piece of information elsewhere, it might be on the [[Device_Tree_Mysteries]] page.
  
=== Linux Specific ===
+
== Linux Specific ==
  
 
[[Device_Tree_Linux | Device Tree Linux]]
 
[[Device_Tree_Linux | Device Tree Linux]]
  
=== Standards ===
+
== Standards ==
  
 
[[Media:Power_ePAPR_APPROVED_v1.1.pdf | Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1]]
 
[[Media:Power_ePAPR_APPROVED_v1.1.pdf | Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1]]
Line 38: Line 36:
 
name of Devicetree Specification Documentation.
 
name of Devicetree Specification Documentation.
  
=== Device Tree Source Format ===
+
== Device Tree Source Format ==
  
 
* [[Media:Power_ePAPR_APPROVED_v1.1.pdf | Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1]]
 
* [[Media:Power_ePAPR_APPROVED_v1.1.pdf | Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1]]
Line 53: Line 51:
 
*** [https://www.youtube.com/watch?v=uzBwHFjJ0vU YouTube video]
 
*** [https://www.youtube.com/watch?v=uzBwHFjJ0vU YouTube video]
  
=== Bindings ===
+
== Bindings ==
  
 
Bindings are documented in
 
Bindings are documented in
Line 59: Line 57:
 
* [[Device_Tree_Reference#Kernel_Source_Documentation | Linux kernel source tree]]
 
* [[Device_Tree_Reference#Kernel_Source_Documentation | Linux kernel source tree]]
  
=== Bindings Documentation in 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 files about device tree is available in the Linux kernel source at
Line 169: Line 167:
 
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/xillybus/xillybus.txt xillybus/xillybus.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]
  
=== Subsystem specific ===
+
== Subsystem specific ==
  
 
* gpio / pinctrl
 
* gpio / pinctrl
Line 179: Line 177:
 
* etc
 
* etc
  
=== Overlays ===
+
== Overlays ==
  
=== Device Tree Source Validation ===
+
== Device Tree Source Validation ==
  
=== Compiling source into .dtb (FDT binary blob) ===
+
== Compiling source into .dtb (FDT binary blob) ==
  
 
* via kernel make system
 
* via kernel make system
Line 197: Line 195:
 
* [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/manual.txt;hb=HEAD Documentation/manual.txt] Device Tree Compiler Manual
  
=== FDT format ===
+
== FDT format ==
  
 
Other names for Flattened Device Tree (FDT) are "binary blob" and ".dtb".
 
Other names for Flattened Device Tree (FDT) are "binary blob" and ".dtb".
Line 208: Line 206:
 
is a more expansive description of the format of FDT.
 
is a more expansive description of the format of FDT.
  
=== Install ===
+
== Install ==
  
 
* make dtbs_install
 
* make dtbs_install
Line 215: Line 213:
 
* many other ways to install ....
 
* many other ways to install ....
  
=== Boot loaders ===
+
== Boot loaders ==
  
=== Booting ===
+
== Booting ==
  
=== Debugging ===
+
== Debugging ==
  
 
(Also see [[Device_Tree_presentations_papers_articles#debug]].)
 
(Also see [[Device_Tree_presentations_papers_articles#debug]].)
Line 241: Line 239:
 
** deferred binding
 
** deferred binding
  
=== Debugging - random hints ===
+
== Debugging - random hints ==
  
 
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.
Line 269: Line 267:
 
  CFLAGS_fdt.o := -DDEBUG
 
  CFLAGS_fdt.o := -DDEBUG
  
=== Tools ===
+
== Tools ==
  
==== Linux kernel source tree ====
+
=== Linux kernel source tree ===
  
===== dtc =====
+
==== 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.
 
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 <tt>scripts/dtc/</tt> in the kernel source directory.  New versions are periodically pulled from the upstream project.
 
* The linux version of dtc is located in <tt>scripts/dtc/</tt> in the kernel source directory.  New versions are periodically pulled from the upstream project.
Line 284: Line 282:
 
* The Maintainers are listed in the file [https://git.kernel.org/?p=utils/dtc/dtc.git;a=blob_plain;f=README;hb=HEAD README]
 
* The Maintainers are listed in the file [https://git.kernel.org/?p=utils/dtc/dtc.git;a=blob_plain;f=README;hb=HEAD README]
  
===== dtx_diff =====
+
==== dtx_diff ====
 
dtx_diff has two modes of operation:
 
dtx_diff has two modes of operation:
 
* compare two dtX files
 
* compare two dtX files
Line 296: Line 294:
 
dtx_diff was merged in 4.6-rc1.
 
dtx_diff was merged in 4.6-rc1.
  
===== dt_to_config =====
+
==== 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 is a tool to provide information about the Linux kernel configuration options needed by a given device tree.
Line 306: Line 304:
 
dt_to_config was merged in 4.8-rc1.
 
dt_to_config was merged in 4.8-rc1.
  
==== external ====
+
=== external ===
  
===== EDK =====
+
==== EDK ====
 
* 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 314: Line 312:
 
  Automatic BSP Generation features of the tool, XPS"
 
  Automatic BSP Generation features of the tool, XPS"
  
=== other projects using Device Tree ===
+
== other projects using Device Tree ==
  
 
[https://wiki.freebsd.org/FlattenedDeviceTree FreeBSD FlattenedDeviceTree wiki]
 
[https://wiki.freebsd.org/FlattenedDeviceTree FreeBSD FlattenedDeviceTree wiki]
Line 320: Line 318:
 
[http://wiki.freebsd.org/FreeBSDArmBoards FreeBSDArmBoards wiki]
 
[http://wiki.freebsd.org/FreeBSDArmBoards FreeBSDArmBoards wiki]
  
=== Glossary ===
+
== Glossary ==
  
 
* .dtb - File name suffix, by convention, for compiled devicetree.
 
* .dtb - File name suffix, by convention, for compiled devicetree.

Revision as of 16:24, 27 September 2016


Top Device Tree page

Introduction

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

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

  • dtc compiler repository documentation
  • differences between ePAPR and the Linux dtc compiler
  • presentations

Bindings

Bindings are documented in

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:

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

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

Subsystem specific

  • gpio / pinctrl
  • interrupts
  • timers
  • etc

Overlays

Device Tree Source Validation

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

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 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/<kernel version>
  • many other ways to install ....

Boot loaders

Booting

Debugging

(Also see Device_Tree_presentations_papers_articles#debug.)

  • 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 "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

Tools

Linux kernel source tree

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.

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 "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 "Solving Device Tree Issues - part 2", LinuxCon Japan, July 2016, Frank Rowand .

dt_to_config was merged in 4.8-rc1.

external

EDK

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

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.

Definitions