Difference between revisions of "Device Tree Reference"

From eLinux.org
Jump to: navigation, search
(move debugging section from Device_Tree)
(move "standards" and "kernel source documentation" from Device_Tree)
Line 18: Line 18:
  
 
[[Linux Drivers Device Tree Guide]]
 
[[Linux Drivers Device Tree Guide]]
 +
 +
=== Standards ===
 +
 +
[[Media:Power_ePAPR_APPROVED_v1.1.pdf | Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1]]
 +
<br>Source: https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/
 +
 +
=== 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
 +
[https://git.kernel.org/?p=/linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation Documentation]
 +
 +
Some especially useful files are:
 +
* [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
 +
* [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
 +
* [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
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/property-units.txt;hb=HEAD not yet mainline: devicetree/bindings/property-units.txt]
 +
** 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]
 +
** '''*'''-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]
  
 
=== Device Tree Source ===
 
=== Device Tree Source ===

Revision as of 12:51, 9 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.

Miscellaneous Tips

Linux Drivers Device Tree Guide

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/

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/:

Device Tree Source

  • presentations

Bindings

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> ???? -- is this useful ???
  • 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

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

man pages

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