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