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