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 March 27, 2019
  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 .Op Fl P Ar predefined_properties
  55 .Ar input_file
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 utility converts between flattened device tree (FDT) representations.
  60 It is most commonly used to generate device tree blobs (DTB), the binary
  61 representation of an FDT, from device tree sources (DTS), the ASCII text source
  62 representation.
  63 .Pp
  64 The binary can be written in two formats, binary and assembly.
  65 The binary is identical to the in-memory representation and can be used
  66 directly by firmware, loaders, and so on.
  67 The assembly format, documented in
  68 .Sx "ASM FORMAT" ,
  69 will produce the same binary format when assembled, but also includes some
  70 global variables that refer to parts of the table.
  71 This format is most commonly used to produce a kernel specific to a device,
  72 with the device tree blob compiled in.
  73 .Pp
  74 The options are as follows:
  75 .Bl -tag -width indent
  76 .It Fl d Ar dependency_file
  77 Writes a dependency file understandable by make to the specified file.
  78 This file can be included in a Makefile and will ensure that the output file
  79 depends on the input file and any files that it includes.
  80 This argument is only useful when the input is DTS, as only the source format
  81 has a notion of inclusions.
  82 .It Fl E Ar [no-]checker_name
  83 Enable or disable a specified checker.
  84 The argument is the name of the checker.
  85 The full list of checkers is given in
  86 .Sx CHECKERS .
  87 .It Fl @
  88 Emit a __symbols__ node to allow plugins to be loaded.
  89 .It Fl f
  90 Force the tool to attempt to generate the output, even if the input had errors.
  91 .It Fl h
  92 Display the help text and exit.
  93 .It Fl H Ar phandle_format
  94 Specifies the type of phandle nodes to generate in the output.
  95 Valid values are:
  96 .Pp
  97 .Bl -tag -width indent -compact
  98 .It Ar linux
  99 Generate the legacy linux,phandle nodes expected by older systems.
 100 .It Ar epapr
 101 Generate the phandle nodes, as described in the ePAPR specification.
 102 This is the most sensible option for device trees being used with
 103 .Fx .
 104 .It Ar both
 105 Generate both, for maximum compatibility.
 106 .El
 107 .It Fl I Ar input_format
 108 Specifies the input format.
 109 Valid values are:
 110 .Pp
 111 .Bl -tag -width indent -compact
 112 .It Ar dtb
 113 Device tree blob.
 114 The binary representation of the FDT.
 115 .It Ar dts
 116 Device tree source.
 117 The ASCII representation of the FDT.
 118 This is the default if the input format is not explicitly stated.
 119 .El
 120 .It Fl O Ar output_format
 121 Specifies the output format.
 122 Valid values are:
 123 .Pp
 124 .Bl -tag -width indent -compact
 125 .It Ar asm
 126 Assembler source for generating a device tree blob, as described in
 127 .Sx "ASM FORMAT" .
 128 .It Ar dtb
 129 Device tree blob.
 130 The binary representation of the FDT.
 131 This is the default if the output format is not explicitly stated.
 132 .It Ar dts
 133 Device tree source.
 134 The ASCII representation of the FDT.
 135 .El
 136 .It Fl o Ar output_file
 137 The file to which to write the output.
 138 .It Fl P Ar predefined_macro
 139 Defines a macro, in the form
 140 .Ar name=value
 141 or
 142 .Ar name
 143 to be used for device tree source files that contain conditional components.
 144 This tool supports two extensions to the standard to support conditional
 145 compilation of device trees.
 146 The first is an
 147 .Ar /include/if [property]/ "file.dts"
 148 directive that is allowed at the start of a file and which will only include
 149 the specified file if it the specified property is passed with this flag.
 150 The second is the
 151 .Ar $NAME
 152 format for property values.
 153 These allow property value to be specified on the command line.
 154 .It Fl R Ar entries
 155 The number of empty reservation table entries to pad the table with.
 156 This is useful if you are generating a device tree blob for bootloader or
 157 similar that needs to reserve some memory before passing control to the
 158 operating system.
 159 .It Fl S Ar bytes
 160 The minimum size in bytes of the blob.
 161 The blob will be padded after the strings table to ensure that it is the
 162 correct size.
 163 This is useful for environments where the device tree blob must be modified in
 164 place.
 165 .It Fl p Ar bytes
 166 The number of bytes of padding to add to the blob.
 167 The blob will be padded after the strings table to ensure that it is the
 168 correct size.
 169 This is useful for environments where the device tree blob must be modified in
 170 place.
 171 .It Fl W Ar [no-]checker_name
 172 Enable or disable a specified checker.
 173 This is an alias for
 174 .Fl E .
 175 .It Fl s
 176 Sorts the properties and nodes in the tree.
 177 This is mainly useful when using tools like
 178 .Xr diff 1
 179 to compare two device tree sources.
 180 .It Fl V Ar output_version
 181 The version of the format to output.
 182 This is only relevant for binary outputs, and only a value of 17 is currently
 183 supported.
 184 .It Fl v
 185 Display the tool version and exit.
 186 .It Ar input_file
 187 The source file.
 188 .El
 189 .Sh "ASM FORMAT"
 190 The assembly format defines several globals that can be referred to from other
 191 compilation units, in addition to any labels specified in the source.
 192 These are:
 193 .Pp
 194 .Bl -tag -width "dt_strings_start" -compact -offset indent
 195 .It dt_blob_start
 196 start of the device tree blob.
 197 .It dt_header
 198 start of the header, usually identical to the start of the blob.
 199 .It dt_reserve_map
 200 start of the reservation map.
 201 .It dt_struct_start
 202 start of the structure table.
 203 .It dt_struct_end
 204 end of the structure table.
 205 .It dt_strings_start
 206 start of the strings table.
 207 .It dt_strings_end
 208 end of the strings table.
 209 .It dt_blob_end
 210 end of the device tree blob.
 211 .El
 212 .Sh CHECKERS
 213 The utility provides a number of semantic checks on the correctness of the
 214 tree.
 215 These can be disabled with the
 216 .Fl W
 217 flag.
 218 For example,
 219 .Fl W Ar no-type-phandle
 220 will disable the phandle type check.
 221 The supported checks are:
 222 .Pp
 223 .Bl -tag -width "no-type-phandle" -compact -offset indent
 224 .It type-compatible
 225 Checks the type of the
 226 .Va compatible
 227 property.
 228 .It type-model
 229 Checks the type of the
 230 .Va model
 231 property.
 232 .It type-compatible
 233 Checks the type of the
 234 .Va compatible
 235 property.
 236 .It cells-attributes
 237 Checks that all nodes with children have both
 238 .Va #address-cells
 239 and
 240 .Va #size-cells
 241 properties.
 242 .It deleted-nodes
 243 Checks that all
 244 .Va /delete-node/
 245 statements refer to nodes that are merged.
 246 .El
 247 .Sh OVERLAYS
 248 The utility provides support for generating overlays, also known as plugins.
 249 Overlays are a method of patching a base device tree that has been compiled with
 250 the
 251 .Fl @
 252 flag, with some limited support for patching device trees that were not compiled
 253 with the
 254 .Fl @
 255 flag.
 256 .Pp
 257 To denote that a DTS is intended to be used as an overlay,
 258 .Va /plugin/;
 259 should be included in the header, following any applicable
 260 .Va /dts-v1/;
 261 tag.
 262 .Pp
 263 Conventional overlays are crafted by creating
 264 .Va fragment
 265 nodes in a root.
 266 Each fragment node must have either a
 267 .Va target
 268 property set to a label reference, or a
 269 .Va target-path
 270 string property set to a path.
 271 It must then have an
 272 .Va __overlay__
 273 child node, whose properties and child nodes are merged into the base device
 274 tree when the overlay is applied.
 275 .Pp
 276 Much simpler syntactic sugar was later invented to simplify generating overlays.
 277 Instead of creating targetted fragments manually, one can instead create a root
 278 node that targets a label in the base FDT using the
 279 .Va &label
 280 syntax supported in conventional DTS.
 281 This will indicate that a fragment should be generated for the node, with the
 282 given
 283 .Va label
 284 being the target, and the properties and child nodes will be used as the
 285 __overlay__.
 286 .Pp
 287 Additionally, a path-based version of this syntactic sugar is supported.
 288 A root node may target a path in the base FDT using a name of the form
 289 .Va &{/path} .
 290 A fragment will be generated for the node as it is in the
 291 .Va &label
 292 case, except the
 293 .Va target-path
 294 property will be set to
 295 .Va /path
 296 and no
 297 .Va target
 298 will be set.
 299 .Pp
 300 Both conventional overlays and the later-added syntactic sugar are supported.
 301 .Pp
 302 Overlay blobs can be applied at boot time by setting
 303 .Va fdt_overlays
 304 in
 305 .Xr loader.conf 5 .
 306 Multiple overlays may be specified, and they will be applied in the order given.
 307 .Sh NODE OMISSION
 308 This utility supports the
 309 .Va /omit-if-no-ref/
 310 statement to mark nodes for omission if they are ultimately not referenced
 311 elsewhere in the device tree.
 312 This may be used in more space-constrained environments to remove nodes that may
 313 not be applicable to the specific device the tree is being compiled for.
 314 .Pp
 315 When the
 316 .Fl @
 317 flag is used to write symbols, nodes with labels will be considered referenced
 318 and will not be removed from the tree.
 319 .Sh EXAMPLES
 320 The command:
 321 .Pp
 322 .Dl "dtc -o blob.S -O asm device.dts"
 323 .Pp
 324 will generate a
 325 .Pa blob.S
 326 file from the device tree source
 327 .Pa device.dts
 328 and print errors if any occur during parsing or property checking.
 329 The resulting file can be assembled and linked into a binary.
 330 .Pp
 331 The command:
 332 .Pp
 333 .Dl "dtc -o - -O dts -I dtb device.dtb"
 334 .Pp
 335 will write the device tree source for the device tree blob
 336 .Pa device.dtb
 337 to the standard output.
 338 This is useful when debugging device trees.
 339 .Pp
 340 The command:
 341 .Pp
 342 .Dl "dtc -@ -O dtb -I dts -o device.dtb device.dts"
 343 .Pp
 344 will generate a
 345 .Pa device.dtb
 346 file from the device tree source
 347 .Pa device.dts
 348 with a __symbols__ node included so that overlays may be applied to it.
 349 .Pp
 350 The command:
 351 .Pp
 352 .Dl "dtc -@ -O dtb -I dts -o device_overlay.dtbo device_overlay.dts"
 353 .Pp
 354 will generate a
 355 .Pa device_overlay.dtbo
 356 file, using the standard extension for a device tree overlay, from the device
 357 tree source
 358 .Pa device_overlay.dts .
 359 A __symbols__ node will be included so that overlays may be applied to it.
 360 The presence of a
 361 .Va /plugin/;
 362 directive in
 363 .Pa device_overlay.dts
 364 will indicate to the utility that it should also generate the underlying
 365 metadata required in overlays.
 366 .Sh COMPATIBILITY
 367 This utility is intended to be compatible with the device tree compiler
 368 provided by elinux.org.
 369 Currently, it implements the subset of features
 370 required to build FreeBSD and others that have been requested by FreeBSD
 371 developers.
 372 .Pp
 373 The
 374 .Ar fs
 375 input format is not supported.
 376 This builds a tree from a Linux
 377 .Pa  /proc/device-tree ,
 378 a file system hierarchy not found in FreeBSD, which instead exposes the DTB
 379 directly via a sysctl.
 380 .Pp
 381 The warnings and errors supported by the elinux.org tool are not documented.
 382 This tool supports the warnings described in the
 383 .Sx CHECKERS
 384 section.
 385 .Sh SEE ALSO
 386 .Xr fdt 4
 387 .Sh STANDARDS
 388 The device tree formats understood by this tool conform to the Power.org
 389 Standard for Embedded Power Architecture Platform Requirements
 390 .Pq Vt ePAPR ,
 391 except as noted in the
 392 .Sx BUGS
 393 section and with the following exceptions for compatibility with the elinux.org
 394 tool:
 395 .Pp
 396 .Bl -bullet -compact
 397 .It
 398 The target of cross references is defined to be a node name in the
 399 specification, but is in fact a label.
 400 .El
 401 .Pp
 402 The /include/ directive is not part of the standard, however it is implemented
 403 with the semantics compatible with the elinux.org tool.
 404 It must appear in the top level of a file, and imports a new root definition.
 405 If a file, plus all of its inclusions, contains multiple roots then they are
 406 merged.
 407 All nodes that are present in the second but not the first are imported.
 408 Any that appear in both are recursively merged, with properties from the second
 409 replacing those from the first and properties child nodes being recursively
 410 merged.
 411 .Sh HISTORY
 412 A dtc tool first appeared in
 413 .Fx 9.0 .
 414 This version of the tool first appeared in
 415 .Fx 10.0 .
 416 .Sh AUTHORS
 417 .Nm
 418 was written by
 419 .An David T. Chisnall .
 420 Some features were added later by
 421 .An Kyle Evans .
 422 .Pp
 423 Note: The fact that the tool and the author share the same initials is entirely
 424 coincidental.
 425 .Sh BUGS
 426 The device tree compiler does not yet support the following features:
 427 .Pp
 428 .Bl -bullet -compact
 429 .It
 430 Labels in the middle of property values.
 431 This is only useful in the assembly output, and only vaguely useful there, so
 432 is unlikely to be added soon.
 433 .It
 434 Full paths, rather than labels, as the targets for phandles.
 435 This is not very hard to add, but will probably not be added until something
 436 actually needs it.
 437 .El
 438 .Pp
 439 The current version performs a very limited set of semantic checks on the tree.
 440 This will be improved in future versions.