Difference between revisions of "Device Tree"

From eLinux.org
Jump to: navigation, search
m (typo)
(redirect still does not work. Needed braces around target page.)
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
#REDIRECT [[Device_Tree_Reference]]
== Technical Information ==
[[Device_Tree_Reference | Device Tree Reference]]
'''is where to find technical information about Device Tree.'''
== 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.
== Introduction ==
The core reason for the existence of Device Tree in Linux is to provide a way
to describe non-discoverable hardware.  This information was previously hard
coded in source code.
Device Tree data can be represented in several different formats.
It is derived from the device tree format used by Open Firmware to
encapsulate platform information.
The device tree data is typically created and maintained in a human readable format
in .dts source files and .dtsi source include files.  The Linux build system
pre-processes the source with cpp.
The device tree source is compiled into a binary format contained in a .dtb blob file.
The format of the data in the .dtb blob file is commonly referred to as a Flattened Device Tree (FDT).
The Linux operating system uses the device tree data to find and register the devices
in the system.  The FDT is accessed in the raw form during the very early phases of boot, but
is expanded into a kernel internal data structure known as the Expanded Device Tree (EDT)
for more efficient access
for later phases of the boot and after the system has completed booting.
Currently the Linux kernel can read device tree information in the ARM, x86,
Microblaze, PowerPC, and Sparc architectures.  There is interest in extending support for
device trees to other platforms, to unify the handling of platform description
across kernel architectures.
=== The Flattened Device Tree is... ===
The Flattened Device Tree (FDT) is a data structure.  Nothing more.
It describes a machine hardware configuration.  It is
derived from the device tree format used by Open Firmware.  The format is expressive and able to describe
most board design aspects including:
* the number and type of CPUs
* base addresses and size of RAM
* busses and bridges
* peripheral device connections
* interrupt controllers and IRQ line connections
* pin multiplexing
Just like initrd images, an FDT image can either be statically linked into the kernel or passed to the kernel
at boot time.
=== The Flattened Device Tree is not... ===
* is not a solution to all board port problems
** Nothing will eliminate all board specific drivers for custom and complex boards.
* is not a firmware interface
** It might be part of a generic firmware interface, but on its own the device tree is just a data structure.
** does not replace ATAGS... but an FDT image can be passed via an ATAG.
** See "Competing Solutions" below
* is not intended to be a universal interface.
** It is a useful data structure which solves several problems, but whether or not to use it is still up to the board port author.
* is not an invasive change
** <strike> No requirement to use FDT approach in a board port </strike>
** Device Tree is required for new board support in the ARM architecture.
** No requirement to convert existing board ports
** No requirement to modify existing firmware
=== 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]]
== Advantages ==
=== for distributions ===
* potentially fewer kernel images needed on an installer image (ie. for ARM netbooks)
** Ship one FDT image per machine (<4k/machine) instead of 1 kernel image per machine (~1-2MB/machine) with a small number of sub-arch kernel images (ie. ARM11, CortexA8, CortexA9, etc).
** Becomes feasible for current installer image to boot on future hardware platforms using same chipset.
** Note: FDT is only part of the solution here.  Some boot software is still required to select and pass in the correct FDT image.
=== for System on Chip (SoC) vendors ===
* Reduce or eliminate effort needed to write machine support code (ie arch/arm/mach-*).  Focus on device driver development instead.
=== for board designers ===
* Reduce effort required to port.
** SoC vendor supplied reference design binaries may also be bootable on custom machine.
* No need to allocate a new global ARM machine id for each new board variant.
** Use the device tree <vendor>,<boardname> namespace instead
* Most board specific code changes constrained to device tree file and device drivers.
* Example: Xilinx FPGA toolchain has a tool to generate a device tree source file from the FPGA design files.
** Since the hardware description is constrained to the device tree source, FPGA engineers can test design changes without getting involved with kernel code.
** Alternately, kernel coders don't need to manually extract design changes from the FPGA design files.
=== for embedded Linux ecosystem ===
* smaller amount of board support code to merge
* greater likelyhood of mainline support for boards from "uninterested" vendors
* greater ability to correct poor board support by fixing or replacing broken FDT images.
=== for firmware/bootloader developers ===
* reduce impact of getting board description wrong (FDT stored as a separate image instead of statically linked into firmware).  If initial release gets the board description wrong, then it is easily updated without a risky reflash of firmware.
* expressive format to describe related board variants without allocating new machine numbers or new ATAGs.
* Note: The FDT isn't a replacement to ATAGS, but does supplement them.
=== Other advantages ===
* Device tree source and FDTs can easily be machine generated and/or modified.
** Xilinx FPGA tools do device tree source generation
** U-Boot firmware can inspect and modify an FDT image before booting
== Competing Solutions ==
=== board specific data structures ===
Some platforms use board-specific C data structures for passing data
from the bootloader to the kernel.  Notable here is embedded PowerPC
support before standardizing on the FDT data format.
Experience with PowerPC demonstrated that using a custom C data
structure is certainly an expedient solution for small amounts of data,
but it causes maintainability issues in the long term and it doesn't
make any attempt to solve the problem of describing the board
configuration as a whole.  Special cases tend to grow and there is no
way for the kernel to determine what specific version of the data
structure is passed to it.  PowerPCs board info structure ended up being
a mess of #ifdefs and ugly hacks, and it still only passed a handful of
data like memory size and Ethernet MAC addresses.
ATAGs have the elegance of providing an well defined namespace for
passing individual data items (memory regions, initrd address, etc) and
the operating system can reliably decode them.  However, only a dozen or
so ATAGs are defined and is not expressive enough to describe the board
design.  Using ATAGs essentially requires a separate machine number to
be allocated for each board variant, even if they are based on the same
That being said, an ATAG is an ideal method for passing an FDT image to
the kernel in the same way an ATAG is used to pass the initrd address.
=== ACPI ===
Firmware providing the [http://en.wikipedia.org/wiki/Advanced_Configuration_and_Power_Interface Advanced Configuration and Power Interface] exports a hardware description in the form of the Differentiated System Description Table (DSDT).  ACPI is found on x86 compatible systems and has its roots in the original IBM PC BIOS.
=== UEFI ===
The [http://en.wikipedia.org/wiki/Extensible_Firmware_Interface Extensible Firmware Interface] is an interface specification for passing control from a platforms firmware to the operating system.  It was designed by Intel as a replacement for the PC BIOS interface.
ARM holdings is a [http://www.uefi.org/join/list member] of the [http://www.uefi.org/home United EFI Forum].  It is conceivable that there will be an ARM implementation of UEFI.
Some information about UEFI on ARM can be found at
* Linaro: [https://wiki.linaro.org/ARM/UEFI UEFI] ("The Linaro Enterprise Group is now championing UEFI within Linaro.")
* ARM: [https://community.arm.com/docs/DOC-10472 FAQ: Where do I obtain UEFI support for ARM Platforms?]
=== Open Firmware ===
[http://en.wikipedia.org/wiki/Open_Firmware Open Firmware] is a firmware interface specification designed by Sun in the late 1980's, and ported to many architectures.  It specifies a runtime OS client interface, an cross platform device interface ([http://www.openfirmware.info/Forth/FCode FCode]), a user interface, and the Device Tree layout for describing the machine.
FDT is to Open Firmware what DSDT is to ACPI.  The FDT reuses Open Firmware's established device tree layout.  In fact, Linux PowerPC support uses the same codebase to support both Open Firmware and FDT platforms.
=== Some Notes on the Competing Solutions ===
Most of the competing solutions listed above provided feature rich firmware interfaces including both machine description and runtime services.  Conversely, the FDT is only a data structure and doesn't specify any firmware interface details.  Board ports using the FDT are typically booted from simple firmware implementations like U-Boot and don't provide any form of runtime services.
A common design goal of the feature rich firmware interfaces is to provide an abstract boot interface that factors away the differences between different hardware platforms, at least enough for the OS to initialize its own native device drivers.  The idea is to be able to boot 'old' OS images on 'new' hardware, like how a Linux LiveCD image doesn't have explicit knowledge of the hardware configuration, but relies on the information provided to it by firmware.
Typical design goals for embedded firmware is to a) boot the OS as quickly as possible, b) upgrade the OS image, and maybe c) provide some low level debug support during initial board bringup.  Focus tends to shift away from firmware once the OS is bootable since the kernel drivers the hardware directly (doesn't depend on firmware runtime services).  In fact, firmware updates are discouraged due to the risk of rendering a board unbootable.  ACPI, UEFI and OpenFirmware solutions, while arguably 'better', often don't boot as fast, and are more complex than required by the embedded system.  In this regard the FDT approach has the advantage due to its simplicity.  ie. the FDT provides an equivalently expressive way to describe hardware, but it works with existing firmware and can be updated without reflashing firmware.
== Resources ==
=== Documentation ===
[[Device_Tree_Reference | Device Tree Reference]]
'''is where to find technical details about Device Tree.'''
=== Presentations, Papers and Articles ===
[[Device Tree presentations papers articles | Device Tree presentations, papers, and articles]]
page is organized by topic area and by date.
=== Device-Tree irc ===
The Device Tree irc channel is #devicetree on freenode.net.
=== 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.
After July 2013:
  archive: http://www.spinics.net/lists/devicetree/
  archive: http://dir.gmane.org/gmane.linux.drivers.devicetree
Up through July 2013:
  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 ePAPR.
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.
  archive: http://dir.gmane.org/gmane.comp.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).
  archive: http://dir.gmane.org/gmane.comp.devicetree.compiler

Latest revision as of 16:46, 11 December 2016