Difference between revisions of "Device Tree Reference"

From eLinux.org
Jump to: navigation, search
(Kernel Source Documentation: remove "not yet mainline" comment, file now in mainline git)
(Kernel Source Documentation: add blank lines in wiki source for readability, no change in formatted page)
Line 57: Line 57:
 
* [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]
 
* [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]
 
** description of /sys/firmware/devicetree/* on the target system
 
** description of /sys/firmware/devicetree/* on the target system
 +
 
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/;hb=HEAD devicetree/bindings]
 
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/;hb=HEAD 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
 
** 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]
 
* [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]
 
** comments on stable binding and general bindings rules
 
** comments on stable binding and general bindings rules
 +
 
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/property-units.txt;hb=HEAD devicetree/bindings/property-units.txt]
 
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/property-units.txt;hb=HEAD devicetree/bindings/property-units.txt]
 
** how to name properties which have a unit of measure
 
** how to name properties which have a unit of measure
 +
 
* [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]
 
* [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]
 
** '''*'''-name properties containing an ordered list of names corresponding to another property
 
** '''*'''-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]
 
* [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'''
 
** 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]
 
* [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
 
** 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]
 
* [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
 
** 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]
 
* [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
 
** information about different elements of bindings

Revision as of 17:54, 25 June 2016


Top Device Tree page

Reference Manual

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.

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:

  • 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

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"

other projects using Device Tree

FreeBSDArmBoards

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