FreeBSD Manual Pages
FDT(4) 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, inter- rupts 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 de- vice-tree notion, and has been successfully adopted by the embedded in- dustry. The scheme works in the following way: • Hardware platform resources are manually described in a human read- able text source format, where all non self-enumerating information is gathered. • This source description is converted (compiled) into a binary ob- ject i.e. a flattened device tree blob which is passed to the ker- nel at boot time. • The kernel (driver) learns about hardware resources details and de- pendencies from this [externally supplied] blob, which eliminates the need for embedding any information about the underlying plat- form 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 com- plete device tree description to the kernel. The fdt layer allows any platform code in the kernel to retrieve infor- mation about hardware resources from a unified origin, which brings ad- vantages to the embedded applications (eliminates hard-coded configura- tion 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-read- able form, with certain hierarchical structure (a tree). The default location for DTS files in the FreeBSD source repository is sys/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 fi- nal consumer (typically kernel) for parsing and process- ing 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 in- formation, 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 proper- ties, allowed values, ranges and so on. Such reference conventions were provided by the legacy Open Firmware bindings, further supplemented by the ePAPR specifica- tion. 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. makeoptions DTS+=<board name>.dts Specifies device tree source (DTS) files for a given ker- nel. The indicated DTS files will be converted (com- piled) 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. makeoptions DTSO+=<overlay name>.dtso Specifies device tree source overlay (DTSO) files for a given kernel. Overlay files will be built with the ker- nel 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. options FDT The primary option for enabling fdt support in the ker- nel. 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 li- braries. makeoptions FDT_DTS_FILE=<board name>.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 de- scribed above. 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 op- tion lets statically embed a DTB file into a kernel im- age. 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 im- age). 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 Require- ments (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 14.3 March 28, 2019 FDT(4)
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://man.freebsd.org/cgi/man.cgi?query=FDT&manpath=FreeBSD+14.3-RELEASE+and+Ports>