2 .\" Copyright (c) 2010 The FreeBSD Foundation
3 .\" All rights reserved.
5 .\" This software was developed by Semihalf under sponsorship from
6 .\" the FreeBSD Foundation.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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
36 .Nd Flattened Device Tree support
39 .Cd "makeoptions FDT_DTS_FILE=<board name>.dts"
40 .Cd "options FDT_DTB_STATIC"
42 .Em Flattened Device Tree
43 is a mechanism for describing computer hardware resources, which cannot be
44 probed or self enumerated, in a uniform and portable way. The primary
45 consumers of this technology are
47 where a lot of designs are based on similar chips, but have different
48 assignment of pins, memory layout, addresses bindings, interrupts routing and
51 Configuration data, which cannot be self discovered in run-time, has to be
52 supplied from external source. The concept of a flattened device tree is a
53 platform and architecture independent approach for resolving such problems.
54 The idea is inherited from Open Firmware IEEE 1275 device-tree notion, and has
55 been successfully adopted by the embedded industry. The scheme works in the
59 Hardware platform resources are
61 described in a human readable text source format, where all non
62 self-enumerating information is gathered.
64 This source description is converted
66 into a binary object i.e. a flattened device tree
68 which is passed to the kernel at boot time.
70 The kernel (driver) learns about hardware resources details and dependencies
71 from this [externally supplied] blob, which eliminates the need for embedding
72 any information about the underlying platform hardware resources in the kernel.
74 The flattened device tree mechanism in principle does not depend on any
75 particular first-stage bootloader or firmware features. The only overall
76 requirement for the environment is to provide a complete device tree
77 description to the kernel.
82 layer allows any platform code in the kernel to retrieve information about
83 hardware resources from a unified origin, which brings advantages to the
84 embedded applications (eliminates hard-coded configuration approach, enforces
85 code to be data driven and extensible) leading to easier porting and
89 .It Va Device tree source (DTS)
90 The device tree source is a text file which describes hardware resources of a
91 computer system in a human-readable form, with certain hierarchical structure
92 (a tree). The default location for DTS files
98 .It Va Device tree blob (DTB)
99 The textual device tree description (DTS file) is first converted (compiled)
100 into a binary object (the device tree blob) i.e. the DTB, which is handed over
101 to the final consumer (typically kernel) for parsing and processing of its
103 .It Va Device tree compiler (DTC)
104 A utility program executed on the host, which transforms (compiles) a textual
105 description of a device tree (DTS) into a binary object (DTB).
106 .It Va Device tree bindings
107 While the device tree textual description and the binary object are media to
108 convey the hardware configuration information, an actual meaning and
109 interpretation of the contents are defined by the device tree
111 They are certain conventions describing definitions (encoding) of particular
112 nodes in a device tree and their properties, allowed values, ranges and so on.
113 Such reference conventions were provided by the legacy Open Firmware bindings,
114 further supplemented by the ePAPR specification.
116 .Sh "BUILDING THE WORLD"
117 In order for the system to support
121 world be built with the
123 build knob supplied either via
125 or command line defined with -D.
127 This creates the user space
133 .Sh "BUILDING KERNEL"
134 There is a couple of options for managing
141 The primary option for enabling
143 support in the kernel. It covers all low-level and infrastructure parts of
145 kernel support, which primarily are the
149 drivers, as well as helper routines and libraries.
150 .It Va makeoptions FDT_DTS_FILE=<board name>.dts
151 Specifies a preferred (default) device tree source (DTS) file for a given
152 kernel. The indicated DTS file will be converted (compiled) into a binary form
153 along with building the kernel itself. The DTS file name is relative
154 to the default location of DTS sources i.e.
155 .Pa sys/boot/fdt/dts .
156 This makeoption is not mandatory unless FDT_DTB_STATIC is also defined (see
158 .It Va options FDT_DTB_STATIC
159 Typically, the device tree blob (DTB) is a stand-alone file, physically
160 separate from the kernel, but this option lets statically embed a
161 DTB file into a kernel image. Note that when this is specified the
162 FDT_DTS_FILE makeoption becomes mandatory (as there needs to be a DTS file
163 specified in order to embed it into the kernel image).
170 IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware:
171 Core Requirements and Practices
172 .Pq Vt Open Firmware .
174 Power.org Standard for Embedded Power Architecture Platform Requirements
179 support first appeared in
184 support was developed by Semihalf under sponsorship from the FreeBSD
185 Foundation. This manual page was written by
186 .An Rafal Jaworowski .