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 f 88Force the tool to attempt to generate the output, even if the input had errors. 89.It Fl h 90Display the help text and exit. 91.It Fl H Ar phandle_format 92Specifies the type of phandle nodes to generate in the output. 93Valid values are: 94.Pp 95.Bl -tag -width indent -compact 96.It Ar linux 97Generate the legacy linux,phandle nodes expected by older systems. 98.It Ar epapr 99Generate the phandle nodes, as described in the ePAPR specification. 100This is the most sensible option for device trees being used with 101.Fx . 102.It Ar both 103Generate both, for maximum compatibility. 104.El 105.It Fl I Ar input_format 106Specifies the input format. 107Valid values are: 108.Pp 109.Bl -tag -width indent -compact 110.It Ar dtb 111Device tree blob. 112The binary representation of the FDT. 113.It Ar dts 114Device tree source. 115The ASCII representation of the FDT. 116This is the default if the input format is not explicitly stated. 117.El 118.It Fl O Ar output_format 119Specifies the output format. 120Valid values are: 121.Pp 122.Bl -tag -width indent -compact 123.It Ar asm 124Assembler source for generating a device tree blob, as described in 125.Sx "ASM FORMAT" . 126.It Ar dtb 127Device tree blob. 128The binary representation of the FDT. 129This is the default if the output format is not explicitly stated. 130.It Ar dts 131Device tree source. 132The ASCII representation of the FDT. 133.El 134.It Fl o Ar output_file 135The file to which to write the output. 136.It Fl P Ar predefined_macro 137Defines a macro, in the form 138.Ar name=value 139or 140.Ar name 141to be used for device tree source files that contain conditional components. 142This tool supports two extensions to the standard to support conditional 143compilation of device trees. 144The first is an 145.Ar /include/if [property]/ "file.dts" 146directive that is allowed at the start of a file and which will only include 147the specified file if it the specified property is passed with this flag. 148The second is the 149.Ar $NAME 150format for property values. 151These allow property value to be specified on the command line. 152.It Fl R Ar entries 153The number of empty reservation table entries to pad the table with. 154This is 155useful if you are generating a device tree blob for bootloader or similar that 156needs to reserve some memory before passing control to the operating system. 157.It Fl S Ar bytes 158The minimum size in bytes of the blob. 159The blob will be padded after the strings table to ensure that it is the 160correct size. 161This is useful for environments where the device tree blob must be modified in 162place. 163.It Fl p Ar bytes 164The number of bytes of padding to add to the blob. 165The blob will be padded after the strings table to ensure that it is the 166correct size. 167This is useful for environments where the device tree blob must be modified in 168place. 169.It Fl W Ar [no-]checker_name 170Enable or disable a specified checker. 171This is an alias for 172.Fl E . 173.It Fl s 174Sorts the properties and nodes in the tree. 175This is mainly useful when using tools like 176.Xr diff 1 177to compare two device tree sources. 178.It Fl V Ar output_version 179The version of the format to output. 180This is only relevant for binary outputs, and only a value of 17 is currently 181supported. 182.It Fl v 183Display the tool version and exit. 184.It Ar input_file 185The source file. 186.El 187.Sh "ASM FORMAT" 188The assembly format defines several globals that can be referred to from other 189compilation units, in addition to any labels specified in the source. 190These are: 191.Pp 192.Bl -tag -width "dt_strings_start" -compact -offset indent 193.It dt_blob_start 194start of the device tree blob. 195.It dt_header 196start of the header, usually identical to the start of the blob. 197.It dt_reserve_map 198start of the reservation map. 199.It dt_struct_start 200start of the structure table. 201.It dt_struct_end 202end of the structure table. 203.It dt_strings_start 204start of the strings table. 205.It dt_strings_end 206end of the strings table. 207.It dt_blob_end 208end of the device tree blob. 209.El 210.Sh CHECKERS 211The utility provides a number of semantic checks on the correctness of the 212tree. 213These can be disabled with the 214.Fl W 215flag. 216For example, 217.Fl W Ar no-type-phandle 218will disable the phandle type check. 219The supported checks are: 220.Pp 221.Bl -tag -width "no-type-phandle" -compact -offset indent 222.It type-compatible 223Checks the type of the 224.Va compatible 225property. 226.It type-model 227Checks the type of the 228.Va model 229property. 230.It type-compatible 231Checks the type of the 232.Va compatible 233property. 234.It cells-attributes 235Checks that all nodes with children have both 236.Va #address-cells 237and 238.Va #size-cells 239properties. 240.El 241.Sh EXAMPLES 242The command: 243.Pp 244.Dl "dtc -o blob.S -O asm device.dts" 245.Pp 246will generate a 247.Pa blob.S 248file from the device tree source 249.Pa device.dts 250and print errors if any occur during parsing or property checking. 251The 252resulting file can be assembled and linked into a binary. 253.Pp 254The command: 255.Pp 256.Dl "dtc -o - -O dts -I dtb device.dtb" 257.Pp 258will write the device tree source for the device tree blob 259.Pa device.dtb 260to the standard output. 261This is useful when debugging device trees. 262.Sh COMPATIBILITY 263This utility is intended to be compatible with the device tree compiler 264provided by elinux.org. 265Currently, it implements the subset of features 266required to build FreeBSD and others that have been requested by FreeBSD 267developers. 268.Pp 269The 270.Ar fs 271input format is not supported. 272This builds a tree from a Linux 273.Pa /proc/device-tree , 274a file system hierarchy not found in FreeBSD, which instead exposes the DTB 275directly via a sysctl. 276.Pp 277The warnings and errors supported by the elinux.org tool are not documented. 278This tool supports the warnings described in the 279.Sx CHECKERS 280section. 281.Sh SEE ALSO 282.Xr fdt 4 283.Sh STANDARDS 284The device tree formats understood by this tool conform to the Power.org 285Standard for Embedded Power Architecture Platform Requirements 286.Pq Vt ePAPR , 287except as noted in the 288.Sx BUGS 289section and with the following exceptions for compatibility with the elinux.org 290tool: 291.Pp 292.Bl -bullet -compact 293.It 294The target of cross references is defined to be a node name in the 295specification, but is in fact a label. 296.El 297.Pp 298The /include/ directive is not part of the standard, however it is implemented 299with the semantics compatible with the elinux.org tool. 300It must appear in the top level of a file, and imports a new root definition. 301If a file, plus all of its inclusions, contains multiple roots then they are 302merged. 303All nodes that are present in the second but not the first are imported. 304Any that appear in both are recursively merged, with properties from the second 305replacing those from the first and properties child nodes being recursively 306merged. 307.Sh HISTORY 308A dtc tool first appeared in 309.Fx 9.0 . 310This version of the tool first appeared in 311.Fx 10.0 . 312.Sh AUTHORS 313.An David T. Chisnall 314.Pp 315Note: The fact that the tool and the author share the same initials is entirely 316coincidental. 317.Sh BUGS 318The device tree compiler does not yet support the following features: 319.Pp 320.Bl -bullet -compact 321.It 322Labels in the middle of property values. 323This is only useful in the assembly output, and only vaguely useful there, so 324is unlikely to be added soon. 325.It 326Full paths, rather than labels, as the targets for phandles. 327This is not very hard to add, but will probably not be added until something 328actually needs it. 329.El 330.Pp 331The current version performs a very limited set of semantic checks on the tree. 332This will be improved in future versions. 333