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 July 12, 2010
  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. The primary
  45 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. 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
  56 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.  The only overall
  76 requirement for the environment is to provide a complete device tree
  77 description to the kernel.
  78 .El
  79 .Pp
  80 The
  81 .Nm
  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
  86 maintenance.
  87 .Sh DEFINITIONS
  88 .Bl -tag -width Ar
  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
  93 in the
  94 .Fx
  95 source repository is
  96 .Pa sys/boot/fdt/dts
  97 directory.
  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
 102 contents.
 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
 110 .Pa bindings .
 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.
 115 .El
 116 .Sh "BUILDING THE WORLD"
 117 In order for the system to support
 118 .Nm
 119 it is required that
 120 .Fx
 121 world be built with the
 122 .Pa WITH_FDT
 123 build knob supplied either via
 124 .Xr src.conf 5
 125 or command line defined with -D.
 126 .Pp
 127 This creates the user space
 128 .Pa dtc
 129 compiler and enables
 130 .Nm
 131 support in
 132 .Xr loader 8 .
 133 .Sh "BUILDING KERNEL"
 134 There is a couple of options for managing
 135 .Nm
 136 support at the
 137 .Fx
 138 kernel level.
 139 .Bl -tag -width Ar
 140 .It Va options FDT
 141 The primary option for enabling
 142 .Nm
 143 support in the kernel. It covers all low-level and infrastructure parts of
 144 .Nm
 145 kernel support, which primarily are the
 146 .Xr fdtbus 4
 147 and
 148 .Xr simplebus 4
 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
 157 below).
 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).
 164 .El
 165 .Sh SEE ALSO
 166 .Xr fdtbus 4 ,
 167 .Xr openfirm 4 ,
 168 .Xr simplebus 4
 169 .Sh STANDARDS
 170 IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware:
 171 Core Requirements and Practices
 172 .Pq Vt Open Firmware .
 173 .Pp
 174 Power.org Standard for Embedded Power Architecture Platform Requirements
 175 .Pq Vt ePAPR .
 176 .Sh HISTORY
 177 The
 178 .Nm
 179 support first appeared in
 180 .Fx 9.0 .
 181 .Sh AUTHORS
 182 The
 183 .Nm
 184 support was developed by Semihalf under sponsorship from the FreeBSD
 185 Foundation. This manual page was written by
 186 .An Rafal Jaworowski .