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