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