NAME

     fdt — Flattened Device Tree support

SYNOPSIS

     options FDT
     makeoptions FDT_DTS_FILE=<board name>.dts
     options FDT_DTB_STATIC

DESCRIPTION

     Flattened Device Tree is a mechanism for describing computer hardware resources, which
     cannot be probed or self enumerated, in a uniform and portable way. The primary consumers of
     this technology are embedded systems, where a lot of designs are based on similar chips, but
     have different assignment of pins, memory layout, addresses bindings, interrupts routing and
     other resources.

     Configuration data, which cannot be self discovered in run-time, has to be supplied from
     external source. The concept of a flattened device tree is a platform and architecture
     independent approach for resolving such problems.  The idea is inherited from Open Firmware
     IEEE 1275 device-tree notion, and has been successfully adopted by the embedded industry.
     The scheme works in the following way:

     •   Hardware platform resources are manually described in a human readable text source
         format, where all non self-enumerating information is gathered.

     •   This source description is converted (compiled) into a binary object i.e. a flattened
         device tree blob which is passed to the kernel at boot time.

     •   The kernel (driver) learns about hardware resources details and dependencies from this
         [externally supplied] blob, which eliminates the need for embedding any information
         about the underlying platform hardware resources in the kernel.

     •   The flattened device tree mechanism in principle does not depend on any particular
         first-stage bootloader or firmware features.  The only overall requirement for the
         environment is to provide a complete device tree description to the kernel.

     The fdt layer allows any platform code in the kernel to retrieve information about hardware
     resources from a unified origin, which brings advantages to the embedded applications
     (eliminates hard-coded configuration approach, enforces code to be data driven and
     extensible) leading to easier porting and maintenance.

DEFINITIONS

     Device tree source (DTS)
                   The device tree source is a text file which describes hardware resources of a
                   computer system in a human-readable form, with certain hierarchical structure
                   (a tree). The default location for DTS files in the FreeBSD source repository
                   is sys/boot/fdt/dts directory.

     Device tree blob (DTB)
                   The textual device tree description (DTS file) is first converted (compiled)
                   into a binary object (the device tree blob) i.e. the DTB, which is handed over
                   to the final consumer (typically kernel) for parsing and processing of its
                   contents.

     Device tree compiler (DTC)
                   A utility program executed on the host, which transforms (compiles) a textual
                   description of a device tree (DTS) into a binary object (DTB).

     Device tree bindings
                   While the device tree textual description and the binary object are media to
                   convey the hardware configuration information, an actual meaning and
                   interpretation of the contents are defined by the device tree bindings.  They
                   are certain conventions describing definitions (encoding) of particular nodes
                   in a device tree and their properties, allowed values, ranges and so on.  Such
                   reference conventions were provided by the legacy Open Firmware bindings,
                   further supplemented by the ePAPR specification.

BUILDING THE WORLD

     In order for the system to support fdt it is required that FreeBSD world be built with the
     WITH_FDT build knob supplied either via src.conf(5) or command line defined with -D.

     This creates the user space dtc compiler and enables fdt support in loader(8).

BUILDING KERNEL

     There is a couple of options for managing fdt support at the FreeBSD kernel level.

     options FDT   The primary option for enabling fdt support in the kernel. It covers all low-
                   level and infrastructure parts of fdt kernel support, which primarily are the
                   fdtbus(4) and simplebus(4) drivers, as well as helper routines and libraries.

     makeoptions FDT_DTS_FILE=<board name>.dts
                   Specifies a preferred (default) device tree source (DTS) file for a given
                   kernel. The indicated DTS file will be converted (compiled) into a binary form
                   along with building the kernel itself. The DTS file name is relative to the
                   default location of DTS sources i.e.  sys/boot/fdt/dts.  This makeoption is
                   not mandatory unless FDT_DTB_STATIC is also defined (see below).

     options FDT_DTB_STATIC
                   Typically, the device tree blob (DTB) is a stand-alone file, physically
                   separate from the kernel, but this option lets statically embed a DTB file
                   into a kernel image. Note that when this is specified the FDT_DTS_FILE
                   makeoption becomes mandatory (as there needs to be a DTS file specified in
                   order to embed it into the kernel image).

SEE ALSO

     fdtbus(4), openfirm(4), simplebus(4)

STANDARDS

     IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware: Core
     Requirements and Practices (Open Firmware).

     Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR).

HISTORY

     The fdt support first appeared in FreeBSD 9.0.

AUTHORS

     The fdt support was developed by Semihalf under sponsorship from the FreeBSD Foundation.
     This manual page was written by Rafal Jaworowski.