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. The primary 45consumers 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. The 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. The scheme works in the 56following 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. The only overall 76requirement for the environment is to provide a complete device tree 77description to the kernel. 78.El 79.Pp 80The 81.Nm 82layer allows any platform code in the kernel to retrieve information about 83hardware resources from a unified origin, which brings advantages to the 84embedded applications (eliminates hard-coded configuration approach, enforces 85code to be data driven and extensible) leading to easier porting and 86maintenance. 87.Sh DEFINITIONS 88.Bl -tag -width Ar 89.It Va Device tree source (DTS) 90The device tree source is a text file which describes hardware resources of a 91computer system in a human-readable form, with certain hierarchical structure 92(a tree). The default location for DTS files 93in the 94.Fx 95source repository is 96.Pa sys/boot/fdt/dts 97directory. 98.It Va Device tree blob (DTB) 99The textual device tree description (DTS file) is first converted (compiled) 100into a binary object (the device tree blob) i.e. the DTB, which is handed over 101to the final consumer (typically kernel) for parsing and processing of its 102contents. 103.It Va Device tree compiler (DTC) 104A utility program executed on the host, which transforms (compiles) a textual 105description of a device tree (DTS) into a binary object (DTB). 106.It Va Device tree bindings 107While the device tree textual description and the binary object are media to 108convey the hardware configuration information, an actual meaning and 109interpretation of the contents are defined by the device tree 110.Pa bindings . 111They are certain conventions describing definitions (encoding) of particular 112nodes in a device tree and their properties, allowed values, ranges and so on. 113Such reference conventions were provided by the legacy Open Firmware bindings, 114further supplemented by the ePAPR specification. 115.El 116.Sh "BUILDING THE WORLD" 117In order for the system to support 118.Nm 119it is required that 120.Fx 121world be built with the 122.Pa WITH_FDT 123build knob supplied either via 124.Xr src.conf 5 125or command line defined with -D. 126.Pp 127This creates the user space 128.Pa dtc 129compiler and enables 130.Nm 131support in 132.Xr loader 8 . 133.Sh "BUILDING KERNEL" 134There is a couple of options for managing 135.Nm 136support at the 137.Fx 138kernel level. 139.Bl -tag -width Ar 140.It Va options FDT 141The primary option for enabling 142.Nm 143support in the kernel. It covers all low-level and infrastructure parts of 144.Nm 145kernel support, which primarily are the 146.Xr fdtbus 4 147and 148.Xr simplebus 4 149drivers, as well as helper routines and libraries. 150.It Va makeoptions FDT_DTS_FILE=<board name>.dts 151Specifies a preferred (default) device tree source (DTS) file for a given 152kernel. The indicated DTS file will be converted (compiled) into a binary form 153along with building the kernel itself. The DTS file name is relative 154to the default location of DTS sources i.e. 155.Pa sys/boot/fdt/dts . 156This makeoption is not mandatory unless FDT_DTB_STATIC is also defined (see 157below). 158.It Va options FDT_DTB_STATIC 159Typically, the device tree blob (DTB) is a stand-alone file, physically 160separate from the kernel, but this option lets statically embed a 161DTB file into a kernel image. Note that when this is specified the 162FDT_DTS_FILE makeoption becomes mandatory (as there needs to be a DTS file 163specified in order to embed it into the kernel image). 164.El 165.Sh SEE ALSO 166.Xr fdtbus 4 , 167.Xr openfirm 4 , 168.Xr simplebus 4 169.Sh STANDARDS 170IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware: 171Core Requirements and Practices 172.Pq Vt Open Firmware . 173.Pp 174Power.org Standard for Embedded Power Architecture Platform Requirements 175.Pq Vt ePAPR . 176.Sh HISTORY 177The 178.Nm 179support first appeared in 180.Fx 9.0 . 181.Sh AUTHORS 182The 183.Nm 184support was developed by Semihalf under sponsorship from the FreeBSD 185Foundation. This manual page was written by 186.An Rafal Jaworowski . 187