share/man/man4/fdt.4

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