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