Please note that User Registration has been temporarily disabled due to a recent increase in automated registrations. If anyone needs an account, please request one here: RequestAccount. Thanks for your patience!--Wmat (talk)
Please email User:Wmat if you experience any issues with the Request Account form.

Difference between revisions of "Device Trees"

From eLinux.org
Jump to: navigation, search
(for board designers)
m (Changed 'datum' to its plural 'data')
(12 intermediate revisions by 2 users not shown)
Line 7: Line 7:
  
 
Currently the Linux kernel can read device tree information in the x86,
 
Currently the Linux kernel can read device tree information in the x86,
PowerPC and Sparc architectures.  There is interest in extending support for
+
Microblaze, PowerPC, and Sparc architectures.  There is interest in extending support for
 
device trees to other platforms, to unify the handling of platform description
 
device trees to other platforms, to unify the handling of platform description
 
across kernel architectures.
 
across kernel architectures.
  
The Linux kernel includes a "compiler" which takes a device tree description
+
=== The Flattened Device Tree is... ===
in "dts" format and produces a binary, "dtb", format, suitable for linking
+
into the kernel.  See <tt>scripts/dtc</tt> in the kernel source directory.
+
 
+
There is documentation describing device tree support (with information current as of 2006) in the
+
Linux kernel source tree at:
+
[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/powerpc/booting-without-of.txt;hb=HEAD Documentation/powerpc/booting-without-of.txt]
+
 
+
== The Flattened Device Tree is... ==
+
 
The Flattened Device Tree (FDT) is a data structure.  Nothing more.
 
The Flattened Device Tree (FDT) is a data structure.  Nothing more.
  
Line 33: Line 25:
 
Just like initrd images, an FDT image can either be statically linked into the kernel or passed to the kernel
 
Just like initrd images, an FDT image can either be statically linked into the kernel or passed to the kernel
 
at boot time.
 
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
 +
** No requirement to use FDT approach in a board port
 +
** No requirement to convert existing board ports
 +
** No requirement to modify existing firmware
  
 
== Advantages ==
 
== Advantages ==
Line 42: Line 48:
  
 
=== for System on Chip (SoC) vendors ===
 
=== for System on Chip (SoC) vendors ===
* Reduce or eliminate need to write machine support code (arch/arm/mach-*).  Focus on device driver development instead.
+
* Reduce or eliminate effort needed to write machine support code (ie arch/arm/mach-*).  Focus on device driver development instead.
  
 
=== for board designers ===
 
=== for board designers ===
* Reduce effort required to port. SoC vendor supplied board port for reference design may also be bootable on custom machine.
+
* Reduce effort required to port.
* No need to allocate a new global ARM machine id for each new board design.
+
** 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 FDT <vendor>,<boardname> namespace instead
 
** Use the FDT <vendor>,<boardname> namespace instead
 
* Most board specific code changes constrained to FDT file and device drivers.
 
* Most board specific code changes constrained to FDT file and device drivers.
* Example: Xilinx FPGA toolchain has a tool to generate an FDT source file from the FPGA design files. Since the hardware description is constrained to the FDT, 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.
+
* Example: Xilinx FPGA toolchain has a tool to generate an FDT source file from the FPGA design files.
 +
**Since the hardware description is constrained to the FDT, 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 ===
 
=== for embedded Linux ecosystem ===
Line 58: Line 67:
 
=== for firmware/bootloader developers ===
 
=== 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.
 
* 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 tool to describe related board variant without allocating new machine numbers or new ATAGs.
+
* 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.
+
* Note: The FDT isn't a replacement to ATAGS, but does supplement them.
  
 
=== Other advantages ===
 
=== Other advantages ===
Line 65: Line 74:
 
** Xilinx FPGA tools do FDT generation
 
** Xilinx FPGA tools do FDT generation
 
** U-Boot firmware can inspect and modify an FDT image before booting
 
** U-Boot firmware can inspect and modify an FDT image before booting
 
== The device tree is not.... ==
 
* a solution to all board port problems
 
** Nothing will eliminate board specific drivers for custom and complex boards.
 
* 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
 
* a method to build a generic ARM kernel.
 
** this does not try to build a single kernel which can boot on all ARM boards
 
* an invasive change
 
** No requirement to use FDT approach in a board port
 
** No requirement to convert existing board ports
 
** No requirement to modify firmware
 
  
 
== Competing Solutions ==
 
== Competing Solutions ==
Line 84: Line 79:
 
Some platforms use board-specific C data structures for passing data
 
Some platforms use board-specific C data structures for passing data
 
from the bootloader to the kernel.  Notable here is embedded PowerPC
 
from the bootloader to the kernel.  Notable here is embedded PowerPC
support before standardizing on the FDT data format and custom board
+
support before standardizing on the FDT data format.
specific ATAGs used by some ARM platforms.
+
  
 
Experience with PowerPC demonstrated that using a custom C data
 
Experience with PowerPC demonstrated that using a custom C data
Line 95: Line 89:
 
structure is passed to it.  PowerPCs board info structure ended up being
 
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
 
a mess of #ifdefs and ugly hacks, and it still only passed a handful of
datum like memory size and Ethernet MAC addresses.
+
data like memory size and Ethernet MAC addresses.
  
 
ATAGs have the elegance of providing an well defined namespace for
 
ATAGs have the elegance of providing an well defined namespace for
Line 130: Line 124:
 
== Resources ==
 
== Resources ==
 
=== Presentations and Papers ===
 
=== Presentations and Papers ===
 +
There is documentation describing device tree support (with information current as of 2006) in the
 +
Linux kernel source tree at:
 +
[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/powerpc/booting-without-of.txt;hb=HEAD Documentation/powerpc/booting-without-of.txt]
 +
 
"Using the Device Tree to Describe
 
"Using the Device Tree to Describe
 
Embedded Hardware" - Grant Likely, Embedded Linux Conference, 2008
 
Embedded Hardware" - Grant Likely, Embedded Linux Conference, 2008
Line 140: Line 138:
 
Note from Device Tree Birds of a Feature session at OLS 2008:
 
Note from Device Tree Birds of a Feature session at OLS 2008:
 
http://lists.ozlabs.org/pipermail/devicetree-discuss/2008-July/000004.html
 
http://lists.ozlabs.org/pipermail/devicetree-discuss/2008-July/000004.html
 +
 +
Links to the Open Firmware device tree bindings and recommended practices which also apply to the FDT: http://www.openfirmware.info/Bindings
 +
 +
A view from outside from the FreeBSD ARM community: http://wiki.freebsd.org/FreeBSDArmBoards
  
 
==== Coming Up Soon ====
 
==== Coming Up Soon ====
 
Grant's talk at Plumber's conference 2009 - http://linuxplumbersconf.org/ocw/proposals/47
 
Grant's talk at Plumber's conference 2009 - http://linuxplumbersconf.org/ocw/proposals/47
 +
 +
=== Tools ===
 +
* Device Tree Compiler (dtc) - converts between the human editable device tree source "dts" format and the compact device tree blob "dtb" representation usable by the kernel.  See <tt>scripts/dtc</tt> in the kernel source directory.
 +
* Xilinx EDK device-tree generator - Generates an FDT from Xilinx FPGA design files.  http://xilinx.wikidot.com/device-tree-generator
 +
"The device tree generator is a Xilinx EDK tool that plugs into the Automatic BSP Generation features of the tool, XPS"
  
 
=== Device-tree Mailing List ===
 
=== Device-tree Mailing List ===
Line 154: Line 161:
 
http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/01942.html
 
http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/01942.html
 
(see whole thread for interesting discussion)
 
(see whole thread for interesting discussion)
 +
 +
But maybe Russel can be convinced: http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/03618.html
  
 
David Gibson defends FDT:
 
David Gibson defends FDT:
 
http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/02304.html
 
http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/02304.html
 
+
[[Category:Bootloader]]
=== Xilink device tree generator documentation ===
+
[[Category:Kernel]]
Xilinx provides a device-tree generator:
+
http://xilinx.wikidot.com/device-tree-generator
+
"The device tree generator is a Xilinx EDK tool that plugs into the Automatic BSP Generation features of the tool, XPS"
+

Revision as of 14:23, 3 May 2012

Introduction

The Flattened Device Tree (FDT) is a data structure for describing the hardware in a system. It is a derived from the device tree format used by Open Firmware to encapsulate platform information and convey it to the- operating system. The operating system uses the FDT data to find and register the devices in the system.

Currently the Linux kernel can read device tree information in the 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, and
  • interrupt controllers and IRQ line connections.

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
    • No requirement to use FDT approach in a board port
    • No requirement to convert existing board ports
    • No requirement to modify existing firmware

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 FDT <vendor>,<boardname> namespace instead
  • Most board specific code changes constrained to FDT file and device drivers.
  • Example: Xilinx FPGA toolchain has a tool to generate an FDT source file from the FPGA design files.
    • Since the hardware description is constrained to the FDT, 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

  • FDTs can easily be machine generated and/or modified.
    • Xilinx FPGA tools do FDT 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 design.

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 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 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 member of the United EFI Forum. It is conceivable that there will be an ARM implementation of UEFI.

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 (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

Presentations and Papers

There is documentation describing device tree support (with information current as of 2006) in the Linux kernel source tree at: Documentation/powerpc/booting-without-of.txt

"Using the Device Tree to Describe Embedded Hardware" - Grant Likely, Embedded Linux Conference, 2008 http://www.celinux.org/elc08_presentations/glikely--device-tree.pdf

"A Symphony of Flavours: Using the device tree to describe embedded hardware" - Grant Likely and Josh Boyer - paper for OLS 2008 http://ols.fedoraproject.org/OLS/Reprints-2008/likely2-reprint.pdf

Note from Device Tree Birds of a Feature session at OLS 2008: http://lists.ozlabs.org/pipermail/devicetree-discuss/2008-July/000004.html

Links to the Open Firmware device tree bindings and recommended practices which also apply to the FDT: http://www.openfirmware.info/Bindings

A view from outside from the FreeBSD ARM community: http://wiki.freebsd.org/FreeBSDArmBoards

Coming Up Soon

Grant's talk at Plumber's conference 2009 - http://linuxplumbersconf.org/ocw/proposals/47

Tools

  • Device Tree Compiler (dtc) - converts between the human editable device tree source "dts" format and the compact device tree blob "dtb" representation usable by the kernel. See scripts/dtc in the kernel source directory.
  • Xilinx EDK device-tree generator - Generates an FDT from Xilinx FPGA design files. http://xilinx.wikidot.com/device-tree-generator

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

Device-tree Mailing List

https://lists.ozlabs.org/listinfo/devicetree-discuss

Mailing list discussion

Recent discussion of "Flattened Device Tree" work on linux-embedded mailing list: http://www.mail-archive.com/linux-embedded@vger.kernel.org/msg01721.html

Russel King is against adding support for FDT to the ARM platform: http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/01942.html (see whole thread for interesting discussion)

But maybe Russel can be convinced: http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/03618.html

David Gibson defends FDT: http://lkml.indiana.edu/hypermail/linux/kernel/0905.3/02304.html