Difference between revisions of "Device Tree Reference"

From eLinux.org
Jump to: navigation, search
(add Device Tree Mysteries section)
(Tools: split into linux kernel vs external, add dtc info, add dtx_diff)
Line 223: Line 223:
 
=== Tools ===
 
=== Tools ===
  
* 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.
+
==== Linux kernel source tree ====
** The linux version of dtc is maintained in <tt>scripts/dtc/</tt> in the kernel source directory.
+
 
 +
* 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 upstream project is maintained in
 
** The upstream project is maintained in
 
*** https://git.kernel.org/cgit/utils/dtc/dtc.git
 
*** https://git.kernel.org/cgit/utils/dtc/dtc.git
Line 232: Line 234:
 
*** [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
 
*** [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]
 
** 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 - 1) compares two dtX files, 2) compiles 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).
 +
 +
==== external ====
 +
 
* 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

Revision as of 12:06, 24 June 2016


Top Device Tree page

Reference Manual

Introduction

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.

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.

Linux Man pages

Linux man pages are a work in progress.

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

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:

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

Device Tree Source

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

Bindings

Bindings are documented in

Subsystem specific

  • gpio / pinctrl
  • interrupts
  • timers
  • etc

Overlays

Device Tree Source Validation

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

Install

  • make dtbs_install
    • installs in /boot/dtbs/<kernel version>
  • many other ways to install ....

Boot loaders

Booting

Debugging

  • 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

Linux kernel source tree

  • dtx_diff - 1) compares two dtX files, 2) compiles 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).

external

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

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