Difference between revisions of "Device Tree Reference"
(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 | + | ==== Linux kernel source tree ==== |
− | ** The linux version of dtc is | + | |
+ | * 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
Contents
- 1 Reference Manual
- 1.1 Introduction
- 1.2 Device Tree Usage
- 1.3 Device Tree Mysteries
- 1.4 Linux Specific
- 1.5 Standards
- 1.6 Linux Man pages
- 1.7 Kernel Source Documentation
- 1.8 Device Tree Source
- 1.9 Bindings
- 1.10 Subsystem specific
- 1.11 Overlays
- 1.12 Device Tree Source Validation
- 1.13 Compiling .dtb (FDT binary blob)
- 1.14 Install
- 1.15 Boot loaders
- 1.16 Booting
- 1.17 Debugging
- 1.18 Debugging - random hints
- 1.19 Tools
- 1.20 Glossary
- 1.21 Definitions
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
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:
- ABI/testing/sysfs-firmware-ofw
- description of /sys/firmware/devicetree/* on the target system
- 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/bindings/ABI.txt
- comments on stable binding and general bindings rules
- not yet mainline: devicetree/bindings/property-units.txt
- how to name properties which have a unit of measure
- devicetree/bindings/resource-names
- *-name properties containing an ordered list of names corresponding to another property
- devicetree/bindings/submitting-patches.txt
- important details for patch submitters and kernel maintainers
- devicetree/bindings/vendor-prefixes.txt
- vendor prefix registry
- devicetree/booting-without-of.txt
- original powerpc document on booting without Open Firmware
- devicetree/usage-model.txt
- information about different elements of bindings
Some subsystems have overview bindings descriptions under devicetree/bindings/:
- bus/mvebu.bus
- bus/simple-pm-bus.txt
- display/mipi-dsi-bus.txt
- dma/dma.txt
- gpio/gpio.txt
- hwlock/hwlock.txt
- iommu/iommu.txt
- lpddr2/lpddr2.txt
- mailbox/mailbox.txt
- memory-controllers/mvebu-devbus.txt
- mfd/mfd.txt
- mips/cavium/bootbus.txt
- mmc/mmc.txt
- pci/pci.txt
- pinctrl/pinctrl-bindings.txt
- power_supply/power_supply.txt
- pwm/pwm.txt
- regmap/regmap.txt
- regulator/regulator.txt
- reserved-memory/reserved-memory.txt
- reset/reset.txt
- spi/spi-bus.txt
- spmi/spmi.txt
- thermal/thermal.txt
- xillybus/xillybus.txt
Device Tree Source
- Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR) v1.1
- chapter 2 "The Device Tree"
- Appendix A "Device Tree Source Format (Version 1)"
- dtc compiler repository documentation
- Documentation/dts-format.txt Device Tree Source Format
- differences between ePAPR and the Linux dtc compiler
- presentations
- "Device Tree for Dummies", ELC 2014 by Thomas Petazzoni
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
- all configured .dtb
- via generated script in build directory
- arch/arm/boot/dts/.*.dtb.cmd
- arch/${ARCH}/boot/dts/.*.dtb.cmd
- Documentation/manual.txt Device Tree Compiler Manual
Install
- make dtbs_install
- installs in /boot/dtbs/<kernel version>
- many other ways to install ....
Boot loaders
Booting
Debugging
- tutorials
- "Solving Device Tree Issues" (updated), ELCE October 2015 by Frank Rowand
- 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
- 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 scripts/dtc/ in the kernel source directory. New versions are periodically pulled from the upstream project.
- The upstream project is maintained in
- Documentation
- Documentation/manual.txt Device Tree Compiler Manual
- Documentation/dts-format.txt Device Tree Source Format
- The Maintainers are listed in the file 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.
"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.