Difference between revisions of "Device Tree Reference"

From eLinux.org
Jump to: navigation, search
(Device Tree Source Format)
(Device-tree Mailing List: add lore archive)
 
(49 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
[[Category:Device_tree]]
 
[[Category:Device_tree]]
 
[[Device_Tree | Top Device Tree page]]
 
  
 
== Introduction ==
 
== Introduction ==
Line 13: Line 11:
  
 
[[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.
 +
 +
== What Is Device Tree ==
 +
 +
The primary purpose of Device Tree in Linux is to provide a way to describe non-discoverable hardware. This information was previously hard coded in source code.
 +
 +
Some more background on what Device Tree is, advantages, and competing solutions, see
 +
[[Device_Tree_What_It_Is | this page.]]
 +
Most of the contents of this page was previously located at Device_Tree, which now
 +
redirects to Device_Tree_Reference.
 +
 +
== Request for Documentation Suggestions ==
 +
 +
If you have any comments or suggestions about the Device Tree documentation on elinux.org, please send them
 +
to frowand (dot) list (at) gmail (dot) com
 +
 +
I am currently trying to make the information more organized, more comprehensive, and a more
 +
complete index of information available elsewhere.  I am looking for comments on what is
 +
incorrect, incomplete, or missing.  I would appreciate pointers to good documentation,
 +
tutorials, etc that I can link to.
 +
 +
== History ==
 +
 +
* [[Device_tree_history | How device tree got into Linux and how it has evolved]]
 +
 +
== Future ==
 +
 +
* [[Device_tree_future | How device tree is changing and where it is headed]]
 +
** Includes Linux Plumbers conference, Kernel Summit, etc
 +
* [[Frank's_Evolving_Overlay_Thoughts | Frank's thoughts on what is needed to complete basic overlay support]]
 +
 +
== Device Tree Related Communications ==
 +
 +
=== Device-Tree irc ===
 +
 +
The Device Tree irc channel is #devicetree on freenode.net.
 +
 +
You are likely to find many people connected to the channel, but many
 +
of them are not actively monitoring traffic.  There may be a delay of
 +
several days or weeks before a question or comment is acknowledged.
 +
 +
As of 08/28/18: "Due to the persistent ongoing spam, all new connections
 +
are being set +R (block messages from unidentified users)..."
 +
 +
This means that the "/join" command will not succeed until you
 +
register your nick with freenode.  For instructions on how to
 +
register, see https://freenode.net/kb/answer/registration
 +
 +
=== Device-tree Mailing List ===
 +
 +
This list contained all devicetree related discussion until February 2014.
 +
At that time, the devicetree.spec and devicetree.compiler lists were
 +
created to provide lower volume lists for those specific topic areas.
 +
 +
Additional archive added in 2019:
 +
 +
  https://lore.kernel.org/linux-devicetree/
 +
    (the git clone seems to have entries beginning July 29, 2008)
 +
    git clone --mirror https://lore.kernel.org/linux-devicetree/0 linux-devicetree/git/0.git
 +
    public inbox mirroring also available
 +
 +
After July 2013:
 +
 +
  http://vger.kernel.org/vger-lists.html#devicetree
 +
  archive: http://www.spinics.net/lists/devicetree/
 +
  archive: http://dir.gmane.org/gmane.linux.drivers.devicetree
 +
 +
Up through July 2013:
 +
 +
  https://lists.ozlabs.org/listinfo/devicetree-discuss
 +
  archive: https://lists.ozlabs.org/pipermail/devicetree-discuss/
 +
  archive: http://news.gmane.org/gmane.linux.drivers.devicetree
 +
 +
===  Core devicetree binding / Devicetree Specification Mailing List ===
 +
 +
Created February 2014.
 +
 +
The devicetree.spec list is for "core" binding discussions; anything that
 +
affects entire subsystems or the kinds of things that would make sense
 +
to be added to the <s>ePAPR</s> Devicetree Specification.
 +
 +
Individual device bindings continue to be posted to
 +
devicetree@vger.kernel.org, but anything affecting subsystems or
 +
generic patterns should be posted to this list.
 +
 +
After April 28, 2016:
 +
 +
The creation and updating of the
 +
[[Device_tree_future#Devicetree_Specification | Devicetree Specification]]
 +
is also discussed on this list.
 +
 +
  http://vger.kernel.org/vger-lists.html#devicetree-spec
 +
 +
  archive: http://dir.gmane.org/gmane.comp.devicetree.spec
 +
  archive: https://www.spinics.net/lists/devicetree-spec/
 +
 +
=== Device-tree Compiler and Tools Mailing List ===
 +
 +
Created February 2014.
 +
 +
The devicetree.compiler list is for discussion related to dtc and other tools.
 +
 +
It is specifically for discussing dt tooling topics
 +
(parsing, schema validation, data format, etc).
 +
 +
  http://vger.kernel.org/vger-lists.html#devicetree-compiler
 +
 +
  archive: https://www.spinics.net/lists/devicetree-compiler/
 +
 +
<!--
 +
Now gone:
 +
  archive: http://dir.gmane.org/gmane.comp.devicetree.compiler
 +
-->
  
 
== Presentations, Papers, and Articles ==
 
== Presentations, Papers, and Articles ==
Line 29: Line 139:
  
 
== Standards ==
 
== Standards ==
 +
 +
 +
[https://www.devicetree.org/specifications/ Devicetree Specification Release 0.2], located on the
 +
[https://www.devicetree.org/specifications/ devicetree.org web site]
 +
'''has superseded the ePAPR for the Linux kernel'''.  The specification is meant to be OS independent.
 +
The Linux kernel devicetree maintainers are actively involved in the specification process.
 +
 +
The Devicetree Specification [[Device_tree_future#Devicetree_Specification | will continue to be updated]].
 +
 +
[[Media:LoPAPR_DRAFT_v11_24March2016.pdf | Open Power Foundation Linux on Power Architecture Platform Reference (LoPAPR), v1.1, 24 march 2016]]
 +
<br>Source: https://members.openpowerfoundation.org/document/dl/469
  
 
[[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]]
 
<br>Source: https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/
 
<br>Source: https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/
  
[[Device_tree_future#Devicetree_Specification | The ePAPR is currently being updated]] with a new
+
== Device Tree Source Format ==
name of Devicetree Specification Documentation.
 
  
== Device Tree Source Format ==
+
* [https://www.devicetree.org/specifications/ Devicetree Specification Release 0.2]
 +
** chapter 2 "The Devicetree"
 +
** chapter 6 "Devicetree Source Format (version 1)"
  
 
* [[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]]
 +
** '''superseded by the Devicetree Specification'''
 
** chapter 2 "The Device Tree"
 
** chapter 2 "The Device Tree"
 
** Appendix A "Device Tree Source Format (Version 1)"
 
** Appendix A "Device Tree Source Format (Version 1)"
Line 44: Line 167:
 
* dtc compiler repository documentation
 
* dtc compiler repository documentation
 
** [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
* differences between ePAPR and the Linux dtc compiler
+
 
 +
* [[Device_Tree_Linux#Linux_vs_ePAPR_Version_1.1 | differences between ePAPR and the Linux dtc compiler]]
  
 
* presentations
 
* presentations
Line 68: Line 192:
 
[https://git.kernel.org/?p=/linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings Documentation/devicetree/bindings]
 
[https://git.kernel.org/?p=/linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings Documentation/devicetree/bindings]
  
 +
'''
 +
Before submitting a binding patch, read these:
 +
 +
* [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/writing-bindings.txt;hb=HEAD devicetree/bindings/writing-bindings.txt]
 +
** DOs and DON'Ts for designing and writing Devicetree bindings
 +
 +
* [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'''
 +
'''
 
Some especially useful files (in alphabetic order) are:
 
Some especially useful files (in alphabetic order) are:
  
Line 75: Line 211:
 
* [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]
 
** 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]
Line 83: Line 216:
  
 
* [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]
 
** 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]
 
** 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/changesets.txt;hb=HEAD devicetree/changesets.txt]
 
** Description of changesets.  Apply changes such that full set of changes is applied successfully or none are.
 
 
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/dynamic-resolution-notes.txt;hb=HEAD devicetree/dynamic-resolution-notes.txt]
 
** Implementation of resolver, used when applying overlays.
 
 
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/of_unittest.txt;hb=HEAD devicetree/of_unittest.txt]
 
** How data for device tree unit tests is added to the kernel
 
 
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/overlay-notes.txt;hb=HEAD devicetree/overlay-notes.txt]
 
** How data for device tree unit tests is added to the kernel
 
 
* [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]
 
** Implementation of overlay
 
  
 
Some subsystems have overview bindings descriptions under devicetree/bindings/:
 
Some subsystems have overview bindings descriptions under devicetree/bindings/:
Line 169: Line 281:
 
* [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/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]
 
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/bindings/xillybus/xillybus.txt xillybus/xillybus.txt]
 +
 +
== Other Documentation in Linux Kernel Source Tree ==
 +
 +
* [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/changesets.txt;hb=HEAD devicetree/changesets.txt]
 +
** Description of changesets.  Apply changes such that full set of changes is applied successfully or none are.
 +
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/dynamic-resolution-notes.txt;hb=HEAD devicetree/dynamic-resolution-notes.txt]
 +
** Implementation of resolver, used when applying overlays.
 +
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/of_unittest.txt;hb=HEAD devicetree/of_unittest.txt]
 +
** How data for device tree unit tests is added to the kernel
 +
 +
* [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/devicetree/overlay-notes.txt;hb=HEAD devicetree/overlay-notes.txt]
 +
** Kernel internal implementation notes on overlays
 +
 +
* [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]
 +
** Overview of: Linux and the Device Tree
  
 
== Subsystem specific ==
 
== Subsystem specific ==
Line 181: Line 313:
  
 
== Overlays ==
 
== Overlays ==
 +
 +
=== Mainline Linux Support ===
 +
 +
Run time overlay apply and run time overlay remove from user space
 +
are not supported in the mainline kernel.  There are out of tree
 +
patches to implement this feature via an overlay manager.  The
 +
overlay manager is used successfully by many users for specific
 +
overlays on specific boards with specific environments and use cases.
 +
However, there are many issues with the Linux kernel overlay
 +
implementation due to incomplete and incorrect code.  The overlay
 +
manager has not been accepted in mainline due to these issues.  Once
 +
these issues are resolved, it is expected that some method of run time
 +
overlay apply and overlay removal from user space will be supported by
 +
the Linux kernel.
 +
 +
There is a possibility that overlay apply and overlay remove support
 +
could be phased in slowly, feature by feature, as specific  issues are
 +
resolved.
 +
 +
* [[Frank's_Evolving_Overlay_Thoughts | Frank's thoughts on what is needed to complete basic overlay support]]
 +
 +
=== Boot Loader Support ===
 +
 +
An alternative to Linux kernel run time overlay apply is boot loader
 +
overlay apply.  For example, U-Boot supports overlay apply.  This
 +
method of overlay apply avoids the complications and issues of
 +
run time Linux kernel overlay apply.  This method is likely to
 +
be more robust and less problematic than run time Linux kernel
 +
overlay apply and is thus the recommended technique.
 +
 +
=== Overlay Source Format ===
 +
 +
In early overlay days, much of the overlay metadata was hand coded in
 +
the overlay source file.  The current dtc compiler in the Linux kernel
 +
source tree eliminates the need for this hand coding.  It is expected
 +
that the Linux kernel overlay apply code will at some time in the future
 +
refuse to apply an overlay compiled from source with hand coded metadata.
 +
The metadata includes fragment nodes and nodes with names beginning
 +
with an underscore, such as __overlay__, __fixup__, __local_fixup__,
 +
and __symbols__.
 +
 +
For examples of transforming overlay source from the hand coded
 +
metadata form, see slides 29 - 34 of the
 +
[[Media:Elce 2018 dt bof.pdf | ELCE 2018 Devicetree BoF [PDF]]].
  
 
== Device Tree Source Validation ==
 
== Device Tree Source Validation ==
 +
 +
See device tree [[Device_tree_future#Devicetree_Validation | future validation work.]]
 +
 +
The most basic validation is warnings from the dtc compiler.  Noisy checks
 +
are disabled by default.  Enable the noisy checks by specifying 'W=1' on
 +
the make command line.
  
 
== Compiling source into .dtb (FDT binary blob) ==
 
== Compiling source into .dtb (FDT binary blob) ==
  
* via kernel make system
+
[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
** all configured .dtb
 
*** make dtbs
 
** specific .dtb
 
*** make arch/arm/boot/dts/qcom-apq8074-dragonboard.dtb
 
  
* via generated script in build directory
+
=== via Linux kernel make system ===
** arch/arm/boot/dts/.*.dtb.cmd
 
** arch/${ARCH}/boot/dts/.*.dtb.cmd
 
  
* [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
+
==== All configured .dtb ====
 +
<pre>
 +
make dtbs
 +
</pre>
 +
 
 +
==== A specific .dtb ====
 +
 
 +
This is an example of compiling arch/arm/boot/dts/qcom-msm8960-cdp.dts
 +
 
 +
The make target is the name of the .dts file, with ".dts" changed to ".dtb".
 +
 
 +
Check that the config option that enables the dtb is set, for example:
 +
 
 +
<pre>
 +
arch/arm/boot/dts/Makefile:
 +
 +
  dtb-$(CONFIG_ARCH_QCOM) += \
 +
        ...
 +
        qcom-msm8960-cdp.dtb \
 +
        ...
 +
 
 +
$ grep CONFIG_ARCH_QCOM .config
 +
CONFIG_ARCH_QCOM=y
 +
</pre>
 +
 
 +
Either specify the correct architecture in the make command (or export the ARCH)
 +
 
 +
<pre>
 +
export ARCH="arm"
 +
make qcom-msm8960-cdp.dtb
 +
</pre>
 +
<pre>
 +
ARCH="arm" make qcom-msm8960-cdp.dtb
 +
</pre>
 +
 
 +
=== via generated script in build directory ===
 +
 
 +
After a .dtb has been built by the Linux kernel make system, files containing the precise build
 +
commands will remain in the build directory:
 +
 
 +
* arch/arm/boot/dts/.*.dtb.cmd
 +
* arch/${ARCH}/boot/dts/.*.dtb.cmd
  
 
== 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".
 +
 +
The format of version 17 of the FDT is described in chapter 5, "Flat Devicetree Physical Structure"
 +
of the [https://www.devicetree.org/specifications/ Devicetree Specification Release 0.2].
  
 
The format of version 17 of the FDT is described in chapter 8, "Flat Device Tree Physical Structure"
 
The format of version 17 of the FDT is described in chapter 8, "Flat Device Tree Physical Structure"
of the [[Media:Power_ePAPR_APPROVED_v1.1.pdf | ePAPR v1.1]].
+
of the [[Media:Power_ePAPR_APPROVED_v1.1.pdf | ePAPR v1.1]] ('''superseded by the Devicetree Specification''').
  
 
Section "II - The DT block format" of
 
Section "II - The DT block format" of
Line 234: Line 454:
 
*** use cases, advantages, and things to be aware of are described in [[Media:Dt_debugging_elce_2015_151006_0421.pdf | "Solving Device Tree Issues"]] (updated), ELCE October 2015 by Frank Rowand (PDF).  dtx_diff is referred to as "dtdiff" in this presentation.
 
*** use cases, advantages, and things to be aware of are described in [[Media:Dt_debugging_elce_2015_151006_0421.pdf | "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
+
* locating source file and line for nodes and properties
 +
** scripts/dtc/dtx_diff --annotate
 +
*** in the Linux kernel source tree as of 5.0-rc1
 +
*** useful for 'dtx_diff DTx'
 +
*** not useful for 'dtx_diff DTx_1 DTx_2'
  
 
* boot time messages
 
* boot time messages
Line 270: Line 494:
 
  CFLAGS_fdt.o := -DDEBUG
 
  CFLAGS_fdt.o := -DDEBUG
  
== Tools ==
+
== Tools in Linux kernel source tree ==
  
=== Linux kernel source tree ===
+
=== dtc (in kernel) ===
 
 
==== 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.
* The upstream project is maintained in
+
** dtc is built by the Linux kernel build process as a dependency when needed.  If you want to explicitly build it in the Linux kernel source tree, use the command: make scripts
** https://git.kernel.org/cgit/utils/dtc/dtc.git
+
* Information about the upstream project is in a [[Device_Tree_Reference#dtc_.28upstream_project.29 | nearby section]].
** git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
 
** Info on submitting patches is in section 1.1 of Documentation/manual.txt
 
* Documentation
 
 
** [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
 
** [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 ====
+
=== 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 515:
 
[[Media:Dt_debugging_elce_2015_151006_0421.pdf |  "Solving Device Tree Issues" (updated), ELCE October 2015, Frank Rowand ]].  Note that dtx_diff was named 'dtdiff' in the presentation.
 
[[Media:Dt_debugging_elce_2015_151006_0421.pdf |  "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.
+
dtx_diff was merged in 4.6-rc1
  
==== dt_to_config ====
+
--annotate was merged in 5.0-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 is a tool to provide information about the Linux kernel configuration options needed by a given device tree.
Line 308: Line 529:
 
dt_to_config was merged in 4.8-rc1.
 
dt_to_config was merged in 4.8-rc1.
  
=== external ===
+
== Tools external to Linux kernel source tree ==
  
==== dts-mode ====
+
=== dtc (upstream project) ===
 +
The dtc (Device Tree Compiler) upstream project is periodically pulled into the Linux kernel source tree.
 +
The upstream project is maintained in
 +
* https://git.kernel.org/cgit/utils/dtc/dtc.git
 +
* git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
 +
 
 +
Info on submitting patches is in section 1.1 of Documentation/manual.txt
 +
 
 +
Building dtc, fdtdump, and other tools in the upstream project:
 +
* make
 +
 
 +
=== dts-mode ===
  
 
From the github README.mkd: a quick attempt at getting basic highlighting for Device Tree syntax in emacs.
 
From the github README.mkd: a quick attempt at getting basic highlighting for Device Tree syntax in emacs.
Line 325: Line 557:
 
removed from this page).  Email me at frowand (dot) list (at) gmail (dot) com
 
removed from this page).  Email me at frowand (dot) list (at) gmail (dot) com
  
==== 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
 
  "The device tree generator is a Xilinx EDK tool that plugs into the
 
  "The device tree generator is a Xilinx EDK tool that plugs into the
 
  Automatic BSP Generation features of the tool, XPS"
 
  Automatic BSP Generation features of the tool, XPS"
 +
 +
=== fdtdump ===
 +
 +
fdtdump is a tool to convert an FDT (flattened device tree, aka device tree blob) to source.
 +
 +
The dtc compiler is an alternate tool that also has an option to convert an FDT to source
 +
(-O dts).
 +
 +
fdtdump differs in some ways from "dtc -O dts":
 +
* fdtdump prints the FDT header as a source comment.
 +
* The format of data differs in appearance (number of hex digits printed) but both formats result in the same FDT when compiled.
 +
* The --scan option of fdtdump will search through a file that embeds an FDT, attempting to find the FDT.  The embedded FDT will be converted to dts.
 +
 +
An unmaintained version of the source of fdtdump exists in the Linux kernel source tree.
 +
There is no makefile entry to build fdtdump in the Linux kernel source tree.  fdtdump
 +
may be removed from the Linux kernel source tree in the future.
 +
 +
fdtdump is located in the [[Device_Tree_Reference#dtc_.28upstream_project.29 | dtc project]] and
 +
can easily be built there.
  
 
== Testing ==
 
== Testing ==
Line 354: Line 605:
 
=== dtc ===
 
=== dtc ===
  
The dtc tests are located in the upstream dtc project (see [[Device_Tree_Reference#dtc]]).
+
The dtc tests are located in the upstream dtc project (see [[Device_Tree_Reference#dtc_.28upstream_project.29 | dtc (upstream project)]]).
  
 
  build dtc:
 
  build dtc:
     make
+
     make dtc
 
   
 
   
 
  build tests:
 
  build tests:
Line 384: Line 635:
  
 
== Other projects using Device Tree ==
 
== Other projects using Device Tree ==
 +
 +
=== barebox ===
 +
 +
barebox bootloader
 +
 +
User manual: [https://www.barebox.org/doc/latest/user/devicetree.html Devicetree support]
 +
 +
=== BSD ===
 +
 +
BSD operating system
  
 
[https://wiki.freebsd.org/FlattenedDeviceTree FreeBSD FlattenedDeviceTree wiki]
 
[https://wiki.freebsd.org/FlattenedDeviceTree FreeBSD FlattenedDeviceTree wiki]
  
 
[http://wiki.freebsd.org/FreeBSDArmBoards FreeBSDArmBoards wiki]
 
[http://wiki.freebsd.org/FreeBSDArmBoards FreeBSDArmBoards wiki]
 +
 +
=== U-Boot ===
 +
 +
U-Boot bootloader
 +
 +
http://www.denx.de/wiki/U-Boot/UBootFdtInfo
 +
 +
http://www.crashcourse.ca/wiki/index.php/U-Boot_and_device_trees
 +
 +
=== Zephyr ===
 +
 +
Zephyr RTOS
 +
 +
[[Device_Tree_presentations_papers_articles#Zephyr | presentations on elinux.org]]
  
 
== Glossary ==
 
== Glossary ==

Latest revision as of 18:39, 9 December 2019


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.

What Is Device Tree

The primary purpose of Device Tree in Linux is to provide a way to describe non-discoverable hardware. This information was previously hard coded in source code.

Some more background on what Device Tree is, advantages, and competing solutions, see this page. Most of the contents of this page was previously located at Device_Tree, which now redirects to Device_Tree_Reference.

Request for Documentation Suggestions

If you have any comments or suggestions about the Device Tree documentation on elinux.org, please send them to frowand (dot) list (at) gmail (dot) com

I am currently trying to make the information more organized, more comprehensive, and a more complete index of information available elsewhere. I am looking for comments on what is incorrect, incomplete, or missing. I would appreciate pointers to good documentation, tutorials, etc that I can link to.

History

Future

Device Tree Related Communications

Device-Tree irc

The Device Tree irc channel is #devicetree on freenode.net.

You are likely to find many people connected to the channel, but many of them are not actively monitoring traffic. There may be a delay of several days or weeks before a question or comment is acknowledged.

As of 08/28/18: "Due to the persistent ongoing spam, all new connections
are being set +R (block messages from unidentified users)..."

This means that the "/join" command will not succeed until you
register your nick with freenode.  For instructions on how to
register, see https://freenode.net/kb/answer/registration

Device-tree Mailing List

This list contained all devicetree related discussion until February 2014. At that time, the devicetree.spec and devicetree.compiler lists were created to provide lower volume lists for those specific topic areas.

Additional archive added in 2019:

 https://lore.kernel.org/linux-devicetree/
   (the git clone seems to have entries beginning July 29, 2008)
   git clone --mirror https://lore.kernel.org/linux-devicetree/0 linux-devicetree/git/0.git
   public inbox mirroring also available

After July 2013:

 http://vger.kernel.org/vger-lists.html#devicetree
 archive: http://www.spinics.net/lists/devicetree/
 archive: http://dir.gmane.org/gmane.linux.drivers.devicetree

Up through July 2013:

 https://lists.ozlabs.org/listinfo/devicetree-discuss
 archive: https://lists.ozlabs.org/pipermail/devicetree-discuss/
 archive: http://news.gmane.org/gmane.linux.drivers.devicetree

Core devicetree binding / Devicetree Specification Mailing List

Created February 2014.

The devicetree.spec list is for "core" binding discussions; anything that affects entire subsystems or the kinds of things that would make sense to be added to the ePAPR Devicetree Specification.

Individual device bindings continue to be posted to devicetree@vger.kernel.org, but anything affecting subsystems or generic patterns should be posted to this list.

After April 28, 2016:

The creation and updating of the Devicetree Specification is also discussed on this list.

 http://vger.kernel.org/vger-lists.html#devicetree-spec
 archive: http://dir.gmane.org/gmane.comp.devicetree.spec
 archive: https://www.spinics.net/lists/devicetree-spec/

Device-tree Compiler and Tools Mailing List

Created February 2014.

The devicetree.compiler list is for discussion related to dtc and other tools.

It is specifically for discussing dt tooling topics (parsing, schema validation, data format, etc).

 http://vger.kernel.org/vger-lists.html#devicetree-compiler
 archive: https://www.spinics.net/lists/devicetree-compiler/


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

Devicetree Specification Release 0.2, located on the devicetree.org web site has superseded the ePAPR for the Linux kernel. The specification is meant to be OS independent. The Linux kernel devicetree maintainers are actively involved in the specification process.

The Devicetree Specification will continue to be updated.

Open Power Foundation Linux on Power Architecture Platform Reference (LoPAPR), v1.1, 24 march 2016
Source: https://members.openpowerfoundation.org/document/dl/469

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/

Device Tree Source Format

  • 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

Before submitting a binding patch, read these:

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

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

Other Documentation in Linux Kernel Source Tree

  • devicetree/changesets.txt
    • Description of changesets. Apply changes such that full set of changes is applied successfully or none are.

Subsystem specific

  • gpio / pinctrl
  • interrupts
  • timers
  • etc

Overlays

Mainline Linux Support

Run time overlay apply and run time overlay remove from user space are not supported in the mainline kernel. There are out of tree patches to implement this feature via an overlay manager. The overlay manager is used successfully by many users for specific overlays on specific boards with specific environments and use cases. However, there are many issues with the Linux kernel overlay implementation due to incomplete and incorrect code. The overlay manager has not been accepted in mainline due to these issues. Once these issues are resolved, it is expected that some method of run time overlay apply and overlay removal from user space will be supported by the Linux kernel.

There is a possibility that overlay apply and overlay remove support could be phased in slowly, feature by feature, as specific issues are resolved.

Boot Loader Support

An alternative to Linux kernel run time overlay apply is boot loader overlay apply. For example, U-Boot supports overlay apply. This method of overlay apply avoids the complications and issues of run time Linux kernel overlay apply. This method is likely to be more robust and less problematic than run time Linux kernel overlay apply and is thus the recommended technique.

Overlay Source Format

In early overlay days, much of the overlay metadata was hand coded in the overlay source file. The current dtc compiler in the Linux kernel source tree eliminates the need for this hand coding. It is expected that the Linux kernel overlay apply code will at some time in the future refuse to apply an overlay compiled from source with hand coded metadata. The metadata includes fragment nodes and nodes with names beginning with an underscore, such as __overlay__, __fixup__, __local_fixup__, and __symbols__.

For examples of transforming overlay source from the hand coded metadata form, see slides 29 - 34 of the ELCE 2018 Devicetree BoF [PDF].

Device Tree Source Validation

See device tree future validation work.

The most basic validation is warnings from the dtc compiler. Noisy checks are disabled by default. Enable the noisy checks by specifying 'W=1' on the make command line.

Compiling source into .dtb (FDT binary blob)

Documentation/manual.txt Device Tree Compiler Manual

via Linux kernel make system

All configured .dtb

make dtbs

A specific .dtb

This is an example of compiling arch/arm/boot/dts/qcom-msm8960-cdp.dts

The make target is the name of the .dts file, with ".dts" changed to ".dtb".

Check that the config option that enables the dtb is set, for example:

arch/arm/boot/dts/Makefile:
 
  dtb-$(CONFIG_ARCH_QCOM) += \
         ...
         qcom-msm8960-cdp.dtb \
         ...

$ grep CONFIG_ARCH_QCOM .config
CONFIG_ARCH_QCOM=y

Either specify the correct architecture in the make command (or export the ARCH)

export ARCH="arm"
make qcom-msm8960-cdp.dtb
ARCH="arm" make qcom-msm8960-cdp.dtb

via generated script in build directory

After a .dtb has been built by the Linux kernel make system, files containing the precise build commands will remain in the 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 5, "Flat Devicetree Physical Structure" of the Devicetree Specification Release 0.2.

The format of version 17 of the FDT is described in chapter 8, "Flat Device Tree Physical Structure" of the ePAPR v1.1 (superseded by the Devicetree Specification).

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 file and line for nodes and properties
    • scripts/dtc/dtx_diff --annotate
      • in the Linux kernel source tree as of 5.0-rc1
      • useful for 'dtx_diff DTx'
      • not useful for 'dtx_diff DTx_1 DTx_2'
  • 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 in Linux kernel source tree

dtc (in kernel)

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.
    • dtc is built by the Linux kernel build process as a dependency when needed. If you want to explicitly build it in the Linux kernel source tree, use the command: make scripts
  • Information about the upstream project is in a nearby section.
  • The Maintainers are listed in the file README

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

--annotate was merged in 5.0-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.

Tools external to Linux kernel source tree

dtc (upstream project)

The dtc (Device Tree Compiler) upstream project is periodically pulled into the Linux kernel source tree. The upstream project is maintained in

Info on submitting patches is in section 1.1 of Documentation/manual.txt

Building dtc, fdtdump, and other tools in the upstream project:

  • make

dts-mode

From the github README.mkd: a quick attempt at getting basic highlighting for Device Tree syntax in emacs.

From the announcement: Today I cobbled together a rudimentary devicetree major mode for emacs. At this point it's pretty much limited to rather basic syntax highlighting but works fairly well all things considered. It can be found on Github[1]. Patches are of course quite welcome.

Project location on [github].

I am not an emacs user, so I would appreciate any feedback on how useful this tool is and additional information that could be added to this description (or if the tool is useless and should be removed from this page). Email me at frowand (dot) list (at) gmail (dot) com

EDK

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

fdtdump

fdtdump is a tool to convert an FDT (flattened device tree, aka device tree blob) to source.

The dtc compiler is an alternate tool that also has an option to convert an FDT to source (-O dts).

fdtdump differs in some ways from "dtc -O dts":

  • fdtdump prints the FDT header as a source comment.
  • The format of data differs in appearance (number of hex digits printed) but both formats result in the same FDT when compiled.
  • The --scan option of fdtdump will search through a file that embeds an FDT, attempting to find the FDT. The embedded FDT will be converted to dts.

An unmaintained version of the source of fdtdump exists in the Linux kernel source tree. There is no makefile entry to build fdtdump in the Linux kernel source tree. fdtdump may be removed from the Linux kernel source tree in the future.

fdtdump is located in the dtc project and can easily be built there.

Testing

linux kernel framework

Enable unit tests through config option CONFIG_OF_UNITTEST

  • Device Drivers ---> Device Tree and Open Firmware support ---> Device Tree runtime unit tests

The unit tests will be performed near the end of the boot sequence. The start of the tests is indicated by:

### dt-test ### start of unittest - you will see error messages

An example test result summary is:

### dt-test ### end of unittest - 148 passed, 0 failed

The unit tests are located in

  • drivers/of/unittest.c
  • drivers/of/unittest-data/

dtc

The dtc tests are located in the upstream dtc project (see dtc (upstream project)).

build dtc:
   make dtc

build tests:
   make tests

run tests:
   make check

run tests with valgrind --tool=memcheck:
   make checkm

run tests in verbose mode:
   make checkv

Each test will report PASS or FAIL.

An example test result summary is:

********** TEST SUMMARY
*     Total testcases:	1565
*                PASS:	1565
*                FAIL:	0
*   Bad configuration:	0
* Strange test result:	0
**********

Other projects using Device Tree

barebox

barebox bootloader

User manual: Devicetree support

BSD

BSD operating system

FreeBSD FlattenedDeviceTree wiki

FreeBSDArmBoards wiki

U-Boot

U-Boot bootloader

http://www.denx.de/wiki/U-Boot/UBootFdtInfo

http://www.crashcourse.ca/wiki/index.php/U-Boot_and_device_trees

Zephyr

Zephyr RTOS

presentations on elinux.org

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