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 17, 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 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 node 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 287Both conventional overlays and the later-added syntactic sugar are supported. 288.Pp 289Overlay blobs can be applied at boot time by setting 290.Va fdt_overlays 291in 292.Xr loader.conf 5 . 293Multiple overlays may be specified, and they will be applied in the order given. 294.El 295.Sh EXAMPLES 296The command: 297.Pp 298.Dl "dtc -o blob.S -O asm device.dts" 299.Pp 300will generate a 301.Pa blob.S 302file from the device tree source 303.Pa device.dts 304and print errors if any occur during parsing or property checking. 305The resulting file can be assembled and linked into a binary. 306.Pp 307The command: 308.Pp 309.Dl "dtc -o - -O dts -I dtb device.dtb" 310.Pp 311will write the device tree source for the device tree blob 312.Pa device.dtb 313to the standard output. 314This is useful when debugging device trees. 315.Pp 316The command: 317.Pp 318.Dl "dtc -@ -O dtb -I dts -o device.dtb device.dts" 319.Pp 320will generate a 321.Pa device.dtb 322file from the device tree source 323.Pa device.dts 324with a __symbols__ node included so that overlays may be applied to it. 325.Pp 326The command: 327.Pp 328.Dl "dtc -@ -O dtb -I dts -o device_overlay.dtbo device_overlay.dts" 329.Pp 330will generate a 331.Pa device_overlay.dtbo 332file, using the standard extension for a device tree overlay, from the device 333tree source 334.Pa device_overlay.dts . 335A __symbols__ node will be included so that overlays may be applied to it. 336The presence of a 337.Va /plugin/; 338directive in 339.Pa device_overlay.dts 340will indicate to the utility that it should also generate the underlying 341metadata required in overlays. 342.Sh COMPATIBILITY 343This utility is intended to be compatible with the device tree compiler 344provided by elinux.org. 345Currently, it implements the subset of features 346required to build FreeBSD and others that have been requested by FreeBSD 347developers. 348.Pp 349The 350.Ar fs 351input format is not supported. 352This builds a tree from a Linux 353.Pa /proc/device-tree , 354a file system hierarchy not found in FreeBSD, which instead exposes the DTB 355directly via a sysctl. 356.Pp 357The warnings and errors supported by the elinux.org tool are not documented. 358This tool supports the warnings described in the 359.Sx CHECKERS 360section. 361.Sh SEE ALSO 362.Xr fdt 4 363.Sh STANDARDS 364The device tree formats understood by this tool conform to the Power.org 365Standard for Embedded Power Architecture Platform Requirements 366.Pq Vt ePAPR , 367except as noted in the 368.Sx BUGS 369section and with the following exceptions for compatibility with the elinux.org 370tool: 371.Pp 372.Bl -bullet -compact 373.It 374The target of cross references is defined to be a node name in the 375specification, but is in fact a label. 376.El 377.Pp 378The /include/ directive is not part of the standard, however it is implemented 379with the semantics compatible with the elinux.org tool. 380It must appear in the top level of a file, and imports a new root definition. 381If a file, plus all of its inclusions, contains multiple roots then they are 382merged. 383All nodes that are present in the second but not the first are imported. 384Any that appear in both are recursively merged, with properties from the second 385replacing those from the first and properties child nodes being recursively 386merged. 387.Sh HISTORY 388A dtc tool first appeared in 389.Fx 9.0 . 390This version of the tool first appeared in 391.Fx 10.0 . 392.Sh AUTHORS 393.An David T. Chisnall 394.Pp 395Note: The fact that the tool and the author share the same initials is entirely 396coincidental. 397.Sh BUGS 398The device tree compiler does not yet support the following features: 399.Pp 400.Bl -bullet -compact 401.It 402Labels in the middle of property values. 403This is only useful in the assembly output, and only vaguely useful there, so 404is unlikely to be added soon. 405.It 406Full paths, rather than labels, as the targets for phandles. 407This is not very hard to add, but will probably not be added until something 408actually needs it. 409.El 410.Pp 411The current version performs a very limited set of semantic checks on the tree. 412This will be improved in future versions. 413