usr.bin/dtc/dtc.1

   1 .\"-
   2 .\" Copyright (c) 2013 David Chisnall
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed by SRI International and the University of
   6 .\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237)
   7 .\" ("CTSRD"), as part of the DARPA CRASH research programme.
   8 .\"
   9 .\" This software was developed by SRI International and the University of
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\" $FreeBSD$
  32 .\"/
  33 .Dd January 1, 2013
  34 .Dt DTC 1
  35 .Os
  36 .Sh NAME
  37 .Nm dtc
  38 .Nd device tree compiler
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl fhsv
  42 .Op Fl b Ar boot_cpu_id
  43 .Op Fl d Ar dependency_file
  44 .Op Fl E Ar [no-]checker_name
  45 .Op Fl H Ar phandle_format
  46 .Op Fl I Ar input_format
  47 .Op Fl O Ar output_format
  48 .Op Fl o Ar output_file
  49 .Op Fl R Ar entries
  50 .Op Fl S Ar bytes
  51 .Op Fl p Ar bytes
  52 .Op Fl V Ar blob_version
  53 .Op Fl W Ar [no-]checker_name
  54 .Ar input_file
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 utility converts flattened device tree (FDT) representations.
  59  It is most commonly used to generate device tree blobs (DTB), the binary
  60 representation of an FDT, from device tree sources (DTS), the ASCII text source
  61 representation.
  62 .Pp
  63 The binary can be written in two formats, binary and assembly.
  64 The binary is identical to the in-memory representation and can be used
  65 directly by firmware, loaders, and so on.
  66 The assembly format, documented in
  67 .Sx "ASM FORMAT" ,
  68 will produce the same binary format when assembled, but also includes some
  69 global variables that refer to parts of the table.
  70 This format is most commonly used to produce a kernel specific to a device,
  71 with the device tree blob compiled in.
  72 .Pp
  73 The options are as follows:
  74 .Bl -tag -width indent
  75 .It Fl d Ar dependency_file
  76 Writes a dependency file understandable by make to the specified file.
  77 This file can be included in a Makefile and will ensure that the output file
  78 depends on the input file and any files that it includes.
  79 This argument is only useful when the input is DTS, as only the source format
  80 has a notion of inclusions.
  81 .It Fl E Ar [no-]checker_name
  82 Enable or disable a specified checker.
  83 The argument is the name of the checker.
  84 The full list of checkers is given in
  85 .Sx CHECKERS .
  86 .It Fl f
  87 Force the tool to attempt to generate the output, even if the input had errors.
  88 .It Fl h
  89 Display the help text and exit.
  90 .It Fl H Ar phandle_format
  91 Specifies the type of phandle nodes to generate in the output.
  92 Valid values are:
  93 .Pp
  94 .Bl -tag -width indent -compact
  95 .It Ar linux
  96 Generate the legacy linux,phandle nodes expected by older systems.
  97 .It Ar epapr
  98 Generate the phandle nodes, as described in the ePAPR specification.
  99 This is the most sensible option for device trees being used with
 100 .Fx .
 101 .It Ar both
 102 Generate both, for maximum compatibility.
 103 .El
 104 .It Fl I Ar input_format
 105 Specifies the input format.
 106 Valid values are:
 107 .Pp
 108 .Bl -tag -width indent -compact
 109 .It Ar dtb
 110 Device tree blob.
 111 The binary representation of the FDT.
 112 .It Ar dts
 113 Device tree source.
 114 The ASCII representation of the FDT.
 115 This is the default if the input format is not explicitly stated.
 116 .El
 117 .It Fl O Ar output_format
 118 Specifies the output format.
 119 Valid values are:
 120 .Pp
 121 .Bl -tag -width indent -compact
 122 .It Ar asm
 123 Assembler source for generating a device tree blob, as described in
 124 .Sx "ASM FORMAT" .
 125 .It Ar dtb
 126 Device tree blob.
 127 The binary representation of the FDT.
 128 This is the default if the output format is not explicitly stated.
 129 .It Ar dts
 130 Device tree source.
 131 The ASCII representation of the FDT.
 132 .El
 133 .It Fl o Ar output_file
 134 The file to which to write the output.
 135 .It Fl R Ar entries
 136 The number of empty reservation table entries to pad the table with.
 137 This is
 138 useful if you are generating a device tree blob for bootloader or similar that
 139 needs to reserve some memory before passing control to the operating system.
 140 .It Fl S Ar bytes
 141 The minimum size in bytes of the blob.
 142 The blob will be padded after the strings table to ensure that it is the
 143 correct size.
 144 This is useful for environments where the device tree blob must be modified in
 145 place.
 146 .It Fl p Ar bytes
 147 The number of bytes of padding to add to the blob.
 148 The blob will be padded after the strings table to ensure that it is the
 149 correct size.
 150 This is useful for environments where the device tree blob must be modified in
 151 place.
 152 .It Fl W Ar [no-]checker_name
 153 Enable or disable a specified checker.
 154 This is an alias for
 155 .Fl E .
 156 .It Fl s
 157 Sorts the properties and nodes in the tree.
 158 This is mainly useful when using tools like
 159 .Xr diff 1
 160 to compare two device tree sources.
 161 .It Fl V Ar output_version
 162 The version of the format to output.
 163 This is only relevant for binary outputs, and only a value of 17 is currently
 164 supported.
 165 .It Fl v
 166 Display the tool version and exit.
 167 .It Ar input_file
 168 The source file.
 169 .El
 170 .Sh "ASM FORMAT"
 171 The assembly format defines several globals that can be referred to from other
 172 compilation units, in addition to any labels specified in the source.
 173 These are:
 174 .Pp
 175 .Bl -tag -width "dt_strings_start" -compact -offset indent
 176 .It dt_blob_start
 177 start of the device tree blob.
 178 .It dt_header
 179 start of the header, usually identical to the start of the blob.
 180 .It dt_reserve_map
 181 start of the reservation map.
 182 .It dt_struct_start
 183 start of the structure table.
 184 .It dt_struct_end
 185 end of the structure table.
 186 .It dt_strings_start
 187 start of the strings table.
 188 .It dt_strings_end
 189 end of the strings table.
 190 .It dt_blob_end
 191 end of the device tree blob.
 192 .El
 193 .Sh CHECKERS
 194 The utility provides a number of semantic checks on the correctness of the
 195 tree.
 196 These can be disabled with the
 197 .Fl W
 198 flag.
 199 For example,
 200 .Fl W Ar no-type-phandle
 201 will disable the phandle type check.
 202 The supported checks are:
 203 .Pp
 204 .Bl -tag -width "no-type-phandle" -compact -offset indent
 205 .It type-compatible
 206 Checks the type of the
 207 .Va compatible
 208 property.
 209 .It type-model
 210 Checks the type of the
 211 .Va model
 212 property.
 213 .It type-compatible
 214 Checks the type of the
 215 .Va compatible
 216 property.
 217 .It cells-attributes
 218 Checks that all nodes with children have both
 219 .Va #address-cells
 220 and
 221 .Va #size-cells
 222 properties.
 223 .El
 224 .Sh EXAMPLES
 225 The command:
 226 .Pp
 227 .Dl "dtc -o blob.S -O asm device.dts"
 228 .Pp
 229 will generate a
 230 .Pa blob.S
 231 file from the device tree source
 232 .Pa device.dts
 233 and print errors if any occur during parsing or property checking.
 234 The
 235 resulting file can be assembled and linked into a binary.
 236 .Pp
 237 The command:
 238 .Pp
 239 .Dl "dtc -o - -O dts -I dtb device.dtb"
 240 .Pp
 241 will write the device tree source for the device tree blob
 242 .Pa device.dtb
 243 to the standard output.
 244 This is useful when debugging device trees.
 245 .Sh COMPATIBILITY
 246 This utility is intended to be compatible with the device tree compiler
 247 provided by elinux.org.
 248 Currently, it implements the subset of features
 249 required to build FreeBSD and others that have been requested by FreeBSD
 250 developers.
 251 .Pp
 252 The
 253 .Ar fs
 254 input format is not supported.
 255 This builds a tree from a Linux
 256 .Pa  /proc/device-tree ,
 257 a file system hierarchy not found in FreeBSD, which instead exposes the DTB
 258 directly via a sysctl.
 259 .Pp
 260 The warnings and errors supported by the elinux.org tool are not documented.
 261 This tool supports the warnings described in the
 262 .Sx CHECKERS
 263 section.
 264 .Sh SEE ALSO
 265 .Xr fdt 4
 266 .Sh STANDARDS
 267 The device tree formats understood by this tool conform to the Power.org
 268 Standard for Embedded Power Architecture Platform Requirements
 269 .Pq Vt ePAPR ,
 270 except as noted in the
 271 .Sx BUGS
 272 section and with the following exceptions for compatibility with the elinux.org
 273 tool:
 274 .Pp
 275 .Bl -bullet -compact
 276 .It
 277 The target of cross references is defined to be a node name in the
 278 specification, but is in fact a label.
 279 .El
 280 .Pp
 281 The /include/ directive is not part of the standard, however it is implemented
 282 with the semantics compatible with the elinux.org tool.
 283 It must appear in the top level of a file, and imports a new root definition.
 284 If a file, plus all of its inclusions, contains multiple roots then they are
 285 merged.
 286 All nodes that are present in the second but not the first are imported.
 287 Any that appear in both are recursively merged, with properties from the second
 288 replacing those from the first and properties child nodes being recursively
 289 merged.
 290 .Sh HISTORY
 291 A dtc tool first appeared in
 292 .Fx 9.0 .
 293 This version of the tool first appeared in
 294 .Fx 10.0 .
 295 .Sh AUTHORS
 296 .An David T. Chisnall
 297 .Pp
 298 Note: The fact that the tool and the author share the same initials is entirely
 299 coincidental.
 300 .Sh BUGS
 301 The device tree compiler does not yet support the following features:
 302 .Pp
 303 .Bl -bullet -compact
 304 .It
 305 Labels in the middle of property values.
 306 This is only useful in the assembly output, and only vaguely useful there, so
 307 is unlikely to be added soon.
 308 .It
 309 Full paths, rather than labels, as the targets for phandles.
 310 This is not very hard to add, but will probably not be added until something
 311 actually needs it.
 312 .El
 313 .Pp
 314 The current version performs a very limited set of semantic checks on the tree.
 315 This will be improved in future versions.