fdt — Flattened Device Tree support

Authors

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

Debian                                           March 28, 2019                                           FDT(4)

Building Kernel

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

makeoptionsDTS+=<boardname>.dts
Specifies device tree source (DTS) files for a given kernel. The indicated DTS files will
be converted (compiled) into a binary form along with building the kernel itself. Any DTS
file names not written as an absolute path must be specified relative to the default
location of DTS sources i.e., sys/dts.

makeoptionsDTSO+=<overlayname>.dtso
Specifies device tree source overlay (DTSO) files for a given kernel. Overlay files will
be built with the kernel as with the makeoption DTS described above. Overlay files
specified as relative paths will be relative to the default location of DTS overlays for
the platform being built i.e., sys/dts/arm/overlays.

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

makeoptionsFDT_DTS_FILE=<boardname>.dts
Specifies a preferred (default) device tree source (DTS) file for a given kernel. It will
be built along with the kernel as if it were supplied via the makeoption DTS described
above. This makeoption is not mandatory unless FDT_DTB_STATIC is also defined (see below).

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

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

Definitions

Devicetreesource(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/dts directory.

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

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

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

Description

FlattenedDeviceTree 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 embeddedsystems, 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.

History

       The fdt support first appeared in FreeBSD 9.0.

Name

       fdt — Flattened Device Tree support

Standards

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

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

Synopsis

optionsFDTmakeoptionsFDT_DTS_FILE=<boardname>.dtsoptionsFDT_DTB_STATIC