share/man/man4/fdt.4

   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
  43 is a mechanism for describing computer hardware resources, which cannot be
  44 probed or self enumerated, in a uniform and portable way.
  45 The primary consumers of this technology are
  46 .Em embedded systems,
  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
  49 other resources.
  50 .Pp
  51 Configuration data, which cannot be self discovered in run-time, has to be
  52 supplied from external source.
  53 The concept of a flattened device tree is a
  54 platform and architecture independent approach for resolving such problems.
  55 The idea is inherited from Open Firmware IEEE 1275 device-tree notion, and has
  56 been successfully adopted by the embedded industry.
  57 The scheme works in the following way:
  58 .Bl -bullet
  59 .It
  60 Hardware platform resources are
  61 .Em manually
  62 described in a human readable text source format, where all non
  63 self-enumerating information is gathered.
  64 .It
  65 This source description is converted
  66 .Em (compiled)
  67 into a binary object i.e. a flattened device tree
  68 .Em blob
  69 which is passed to the kernel at boot time.
  70 .It
  71 The kernel (driver) learns about hardware resources details and dependencies
  72 from this [externally supplied] blob, which eliminates the need for embedding
  73 any information about the underlying platform hardware resources in the kernel.
  74 .It
  75 The flattened device tree mechanism in principle does not depend on any
  76 particular first-stage bootloader or firmware features.
  77 The only overall
  78 requirement for the environment is to provide a complete device tree
  79 description to the kernel.
  80 .El
  81 .Pp
  82 The
  83 .Nm
  84 layer allows any platform code in the kernel to retrieve information about
  85 hardware resources from a unified origin, which brings advantages to the
  86 embedded applications (eliminates hard-coded configuration approach, enforces
  87 code to be data driven and extensible) leading to easier porting and
  88 maintenance.
  89 .Sh DEFINITIONS
  90 .Bl -tag -width Ar
  91 .It Va Device tree source (DTS)
  92 The device tree source is a text file which describes hardware resources of a
  93 computer system in a human-readable form, with certain hierarchical structure
  94 (a tree).
  95 The default location for DTS files in the
  96 .Fx
  97 source repository is
  98 .Pa sys/dts
  99 directory.
 100 .It Va Device tree blob (DTB)
 101 The textual device tree description (DTS file) is first converted (compiled)
 102 into a binary object (the device tree blob) i.e. the DTB, which is handed over
 103 to the final consumer (typically kernel) for parsing and processing of its
 104 contents.
 105 .It Va Device tree compiler (DTC)
 106 A utility program executed on the host, which transforms (compiles) a textual
 107 description of a device tree (DTS) into a binary object (DTB).
 108 .It Va Device tree bindings
 109 While the device tree textual description and the binary object are media to
 110 convey the hardware configuration information, an actual meaning and
 111 interpretation of the contents are defined by the device tree
 112 .Pa bindings .
 113 They are certain conventions describing definitions (encoding) of particular
 114 nodes in a device tree and their properties, allowed values, ranges and so on.
 115 Such reference conventions were provided by the legacy Open Firmware bindings,
 116 further supplemented by the ePAPR specification.
 117 .El
 118 .Sh "BUILDING THE WORLD"
 119 In order for the system to support
 120 .Nm
 121 it is required that
 122 .Fx
 123 world be built with the
 124 .Pa WITH_FDT
 125 build knob supplied either via
 126 .Xr src.conf 5
 127 or command line defined with -D.
 128 .Pp
 129 This creates the user space
 130 .Pa dtc
 131 compiler and enables
 132 .Nm
 133 support in
 134 .Xr loader 8 .
 135 .Sh "BUILDING KERNEL"
 136 There is a couple of options for managing
 137 .Nm
 138 support at the
 139 .Fx
 140 kernel level.
 141 .Bl -tag -width Ar
 142 .It Va makeoptions DTS+=<board name>.dts
 143 Specifies device tree source (DTS) files for a given kernel.
 144 The indicated DTS files will be converted (compiled) into a binary form
 145 along with building the kernel itself.
 146 Any DTS file names not written as an absolute path must be specified relative
 147 to the default location of DTS sources i.e.,
 148 .Pa sys/dts .
 149 .It Va makeoptions DTSO+=<overlay name>.dtso
 150 Specifies device tree source overlay (DTSO) files for a given kernel.
 151 Overlay files will be built with the kernel as with the makeoption
 152 .Va DTS
 153 described above.
 154 Overlay files specified as relative paths will be relative to the default
 155 location of DTS overlays for the platform being built i.e.,
 156 .Pa sys/dts/arm/overlays .
 157 .It Va options FDT
 158 The primary option for enabling
 159 .Nm
 160 support in the kernel.
 161 It covers all low-level and infrastructure parts of
 162 .Nm
 163 kernel support, which primarily are the
 164 .Xr fdtbus 4
 165 and
 166 .Xr simplebus 4
 167 drivers, as well as helper routines and libraries.
 168 .It Va makeoptions FDT_DTS_FILE=<board name>.dts
 169 Specifies a preferred (default) device tree source (DTS) file for a given
 170 kernel.
 171 It will be built along with the kernel as if it were supplied via the makeoption
 172 .Va DTS
 173 described above.
 174 This makeoption is not mandatory unless FDT_DTB_STATIC is also defined (see
 175 below).
 176 .It Va options FDT_DTB_STATIC
 177 Typically, the device tree blob (DTB) is a stand-alone file, physically
 178 separate from the kernel, but this option lets statically embed a
 179 DTB file into a kernel image.
 180 Note that when this is specified the
 181 FDT_DTS_FILE makeoption becomes mandatory (as there needs to be a DTS file
 182 specified 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
 189 IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware:
 190 Core Requirements and Practices
 191 .Pq Vt Open Firmware .
 192 .Pp
 193 Power.org Standard for Embedded Power Architecture Platform Requirements
 194 .Pq Vt ePAPR .
 195 .Sh HISTORY
 196 The
 197 .Nm
 198 support first appeared in
 199 .Fx 9.0 .
 200 .Sh AUTHORS
 201 The
 202 .Nm
 203 support was developed by Semihalf under sponsorship from the FreeBSD
 204 Foundation.
 205 This manual page was written by
 206 .An Rafal Jaworowski .