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