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