Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
FDT(4)                 FreeBSD Kernel Interfaces Manual                 FDT(4)

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:

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

     +o   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.

     +o   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.

     +o   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.

FreeBSD 11.0-PRERELEASE          July 12, 2010         FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | DEFINITIONS | BUILDING THE WORLD | BUILDING KERNEL | SEE ALSO | STANDARDS | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fdt&sektion=4&manpath=FreeBSD+10.3-RELEASE+and+Ports>

home | help