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.Op Fl P Ar predefined_properties 55.Ar input_file 56.Sh DESCRIPTION 57The 58.Nm 59utility converts flattened device tree (FDT) representations. 60 It 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 157useful if you are generating a device tree blob for bootloader or similar that 158needs to reserve some memory before passing control to the operating 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 EXAMPLES 248The command: 249.Pp 250.Dl "dtc -o blob.S -O asm device.dts" 251.Pp 252will generate a 253.Pa blob.S 254file from the device tree source 255.Pa device.dts 256and print errors if any occur during parsing or property checking. 257The 258resulting file can be assembled and linked into a binary. 259.Pp 260The command: 261.Pp 262.Dl "dtc -o - -O dts -I dtb device.dtb" 263.Pp 264will write the device tree source for the device tree blob 265.Pa device.dtb 266to the standard output. 267This is useful when debugging device trees. 268.Sh COMPATIBILITY 269This utility is intended to be compatible with the device tree compiler 270provided by elinux.org. 271Currently, it implements the subset of features 272required to build FreeBSD and others that have been requested by FreeBSD 273developers. 274.Pp 275The 276.Ar fs 277input format is not supported. 278This builds a tree from a Linux 279.Pa /proc/device-tree , 280a file system hierarchy not found in FreeBSD, which instead exposes the DTB 281directly via a sysctl. 282.Pp 283The warnings and errors supported by the elinux.org tool are not documented. 284This tool supports the warnings described in the 285.Sx CHECKERS 286section. 287.Sh SEE ALSO 288.Xr fdt 4 289.Sh STANDARDS 290The device tree formats understood by this tool conform to the Power.org 291Standard for Embedded Power Architecture Platform Requirements 292.Pq Vt ePAPR , 293except as noted in the 294.Sx BUGS 295section and with the following exceptions for compatibility with the elinux.org 296tool: 297.Pp 298.Bl -bullet -compact 299.It 300The target of cross references is defined to be a node name in the 301specification, but is in fact a label. 302.El 303.Pp 304The /include/ directive is not part of the standard, however it is implemented 305with the semantics compatible with the elinux.org tool. 306It must appear in the top level of a file, and imports a new root definition. 307If a file, plus all of its inclusions, contains multiple roots then they are 308merged. 309All nodes that are present in the second but not the first are imported. 310Any that appear in both are recursively merged, with properties from the second 311replacing those from the first and properties child nodes being recursively 312merged. 313.Sh HISTORY 314A dtc tool first appeared in 315.Fx 9.0 . 316This version of the tool first appeared in 317.Fx 10.0 . 318.Sh AUTHORS 319.An David T. Chisnall 320.Pp 321Note: The fact that the tool and the author share the same initials is entirely 322coincidental. 323.Sh BUGS 324The device tree compiler does not yet support the following features: 325.Pp 326.Bl -bullet -compact 327.It 328Labels in the middle of property values. 329This is only useful in the assembly output, and only vaguely useful there, so 330is unlikely to be added soon. 331.It 332Full paths, rather than labels, as the targets for phandles. 333This is not very hard to add, but will probably not be added until something 334actually needs it. 335.El 336.Pp 337The current version performs a very limited set of semantic checks on the tree. 338This will be improved in future versions. 339