xref: /freebsd/share/man/man4/fdt.4 (revision cfd6422a5217410fbd66f7a7a8a64d9d85e61229)
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 March 28, 2019
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 makeoptions DTS+=<board name>.dts
143Specifies device tree source (DTS) files for a given kernel.
144The indicated DTS files will be converted (compiled) into a binary form
145along with building the kernel itself.
146Any DTS file names not written as an absolute path must be specified relative
147to the default location of DTS sources i.e.,
148.Pa sys/dts .
149.It Va makeoptions DTSO+=<overlay name>.dtso
150Specifies device tree source overlay (DTSO) files for a given kernel.
151Overlay files will be built with the kernel as with the makeoption
152.Va DTS
153described above.
154Overlay files specified as relative paths will be relative to the default
155location of DTS overlays for the platform being built i.e.,
156.Pa sys/dts/arm/overlays .
157.It Va options FDT
158The primary option for enabling
159.Nm
160support in the kernel.
161It covers all low-level and infrastructure parts of
162.Nm
163kernel support, which primarily are the
164.Xr fdtbus 4
165and
166.Xr simplebus 4
167drivers, as well as helper routines and libraries.
168.It Va makeoptions FDT_DTS_FILE=<board name>.dts
169Specifies a preferred (default) device tree source (DTS) file for a given
170kernel.
171It will be built along with the kernel as if it were supplied via the makeoption
172.Va DTS
173described above.
174This makeoption is not mandatory unless FDT_DTB_STATIC is also defined (see
175below).
176.It Va options FDT_DTB_STATIC
177Typically, the device tree blob (DTB) is a stand-alone file, physically
178separate from the kernel, but this option lets statically embed a
179DTB file into a kernel image.
180Note that when this is specified the
181FDT_DTS_FILE makeoption becomes mandatory (as there needs to be a DTS file
182specified in order to embed it into the kernel image).
183.El
184.Sh SEE ALSO
185.Xr fdtbus 4 ,
186.Xr openfirm 4 ,
187.Xr simplebus 4
188.Sh STANDARDS
189IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware:
190Core Requirements and Practices
191.Pq Vt Open Firmware .
192.Pp
193Power.org Standard for Embedded Power Architecture Platform Requirements
194.Pq Vt ePAPR .
195.Sh HISTORY
196The
197.Nm
198support first appeared in
199.Fx 9.0 .
200.Sh AUTHORS
201The
202.Nm
203support was developed by Semihalf under sponsorship from the FreeBSD
204Foundation.
205This manual page was written by
206.An Rafal Jaworowski .
207