1.\" 2.\" Copyright (c) 2010 The FreeBSD Foundation 3.\" 4.\" This software was developed by Semihalf under sponsorship from 5.\" the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd March 28, 2019 31.Dt FDT 4 32.Os 33.Sh NAME 34.Nm fdt 35.Nd Flattened Device Tree support 36.Sh SYNOPSIS 37.Cd "options FDT" 38.Cd "makeoptions FDT_DTS_FILE=<board name>.dts" 39.Cd "options FDT_DTB_STATIC" 40.Sh DESCRIPTION 41.Em Flattened Device Tree 42is a mechanism for describing computer hardware resources, which cannot be 43probed or self enumerated, in a uniform and portable way. 44The primary consumers of this technology are 45.Em embedded systems, 46where a lot of designs are based on similar chips, but have different 47assignment of pins, memory layout, addresses bindings, interrupts routing and 48other resources. 49.Pp 50Configuration data, which cannot be self discovered in run-time, has to be 51supplied from external source. 52The concept of a flattened device tree is a 53platform and architecture independent approach for resolving such problems. 54The idea is inherited from Open Firmware IEEE 1275 device-tree notion, and has 55been successfully adopted by the embedded industry. 56The scheme works in the following way: 57.Bl -bullet 58.It 59Hardware platform resources are 60.Em manually 61described in a human readable text source format, where all non 62self-enumerating information is gathered. 63.It 64This source description is converted 65.Em (compiled) 66into a binary object i.e. a flattened device tree 67.Em blob 68which is passed to the kernel at boot time. 69.It 70The kernel (driver) learns about hardware resources details and dependencies 71from this [externally supplied] blob, which eliminates the need for embedding 72any information about the underlying platform hardware resources in the kernel. 73.It 74The flattened device tree mechanism in principle does not depend on any 75particular first-stage bootloader or firmware features. 76The only overall 77requirement for the environment is to provide a complete device tree 78description to the kernel. 79.El 80.Pp 81The 82.Nm 83layer allows any platform code in the kernel to retrieve information about 84hardware resources from a unified origin, which brings advantages to the 85embedded applications (eliminates hard-coded configuration approach, enforces 86code to be data driven and extensible) leading to easier porting and 87maintenance. 88.Sh DEFINITIONS 89.Bl -tag -width Ar 90.It Va Device tree source (DTS) 91The device tree source is a text file which describes hardware resources of a 92computer system in a human-readable form, with certain hierarchical structure 93(a tree). 94The default location for DTS files in the 95.Fx 96source repository is 97.Pa sys/dts 98directory. 99.It Va Device tree blob (DTB) 100The textual device tree description (DTS file) is first converted (compiled) 101into a binary object (the device tree blob) i.e. the DTB, which is handed over 102to the final consumer (typically kernel) for parsing and processing of its 103contents. 104.It Va Device tree compiler (DTC) 105A utility program executed on the host, which transforms (compiles) a textual 106description of a device tree (DTS) into a binary object (DTB). 107.It Va Device tree bindings 108While the device tree textual description and the binary object are media to 109convey the hardware configuration information, an actual meaning and 110interpretation of the contents are defined by the device tree 111.Pa bindings . 112They are certain conventions describing definitions (encoding) of particular 113nodes in a device tree and their properties, allowed values, ranges and so on. 114Such reference conventions were provided by the legacy Open Firmware bindings, 115further supplemented by the ePAPR specification. 116.El 117.Sh "BUILDING THE WORLD" 118In order for the system to support 119.Nm 120it is required that 121.Fx 122world be built with the 123.Pa WITH_FDT 124build knob supplied either via 125.Xr src.conf 5 126or command line defined with -D. 127.Pp 128This creates the user space 129.Pa dtc 130compiler and enables 131.Nm 132support in 133.Xr loader 8 . 134.Sh "BUILDING KERNEL" 135There is a couple of options for managing 136.Nm 137support at the 138.Fx 139kernel level. 140.Bl -tag -width Ar 141.It Va makeoptions DTS+=<board name>.dts 142Specifies device tree source (DTS) files for a given kernel. 143The indicated DTS files will be converted (compiled) into a binary form 144along with building the kernel itself. 145Any DTS file names not written as an absolute path must be specified relative 146to the default location of DTS sources i.e., 147.Pa sys/dts . 148.It Va makeoptions DTSO+=<overlay name>.dtso 149Specifies device tree source overlay (DTSO) files for a given kernel. 150Overlay files will be built with the kernel as with the makeoption 151.Va DTS 152described above. 153Overlay files specified as relative paths will be relative to the default 154location of DTS overlays for the platform being built i.e., 155.Pa sys/dts/arm/overlays . 156.It Va options FDT 157The primary option for enabling 158.Nm 159support in the kernel. 160It covers all low-level and infrastructure parts of 161.Nm 162kernel support, which primarily are the 163.Xr fdtbus 4 164and 165.Xr simplebus 4 166drivers, as well as helper routines and libraries. 167.It Va makeoptions FDT_DTS_FILE=<board name>.dts 168Specifies a preferred (default) device tree source (DTS) file for a given 169kernel. 170It will be built along with the kernel as if it were supplied via the makeoption 171.Va DTS 172described above. 173This makeoption is not mandatory unless FDT_DTB_STATIC is also defined (see 174below). 175.It Va options FDT_DTB_STATIC 176Typically, the device tree blob (DTB) is a stand-alone file, physically 177separate from the kernel, but this option lets statically embed a 178DTB file into a kernel image. 179Note that when this is specified the 180FDT_DTS_FILE makeoption becomes mandatory (as there needs to be a DTS file 181specified in order to embed it into the kernel image). 182.El 183.Sh SEE ALSO 184.Xr fdtbus 4 , 185.Xr openfirm 4 , 186.Xr simplebus 4 187.Sh STANDARDS 188IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware: 189Core Requirements and Practices 190.Pq Vt Open Firmware . 191.Pp 192Power.org Standard for Embedded Power Architecture Platform Requirements 193.Pq Vt ePAPR . 194.Sh HISTORY 195The 196.Nm 197support first appeared in 198.Fx 9.0 . 199.Sh AUTHORS 200The 201.Nm 202support was developed by Semihalf under sponsorship from the FreeBSD 203Foundation. 204This manual page was written by 205.An Rafal Jaworowski . 206