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

Line 447:

*** 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.

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.

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.

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.

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__.

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.

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).

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.

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

fdtdump

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.