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