xref: /freebsd/usr.bin/dtc/dtc.1 (revision cfd6422a5217410fbd66f7a7a8a64d9d85e61229)
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 March 27, 2019
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 between flattened device tree (FDT) representations.
60It 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 useful if you are generating a device tree blob for bootloader or
157similar that needs to reserve some memory before passing control to the
158operating 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 OVERLAYS
248The utility provides support for generating overlays, also known as plugins.
249Overlays are a method of patching a base device tree that has been compiled with
250the
251.Fl @
252flag, with some limited support for patching device trees that were not compiled
253with the
254.Fl @
255flag.
256.Pp
257To denote that a DTS is intended to be used as an overlay,
258.Va /plugin/;
259should be included in the header, following any applicable
260.Va /dts-v1/;
261tag.
262.Pp
263Conventional overlays are crafted by creating
264.Va fragment
265nodes in a root.
266Each fragment node must have either a
267.Va target
268property set to a label reference, or a
269.Va target-path
270string property set to a path.
271It must then have an
272.Va __overlay__
273child node, whose properties and child nodes are merged into the base device
274tree when the overlay is applied.
275.Pp
276Much simpler syntactic sugar was later invented to simplify generating overlays.
277Instead of creating targetted fragments manually, one can instead create a root
278node that targets a label in the base FDT using the
279.Va &label
280syntax supported in conventional DTS.
281This will indicate that a fragment should be generated for the node, with the
282given
283.Va label
284being the target, and the properties and child nodes will be used as the
285__overlay__.
286.Pp
287Additionally, a path-based version of this syntactic sugar is supported.
288A root node may target a path in the base FDT using a name of the form
289.Va &{/path} .
290A fragment will be generated for the node as it is in the
291.Va &label
292case, except the
293.Va target-path
294property will be set to
295.Va /path
296and no
297.Va target
298will be set.
299.Pp
300Both conventional overlays and the later-added syntactic sugar are supported.
301.Pp
302Overlay blobs can be applied at boot time by setting
303.Va fdt_overlays
304in
305.Xr loader.conf 5 .
306Multiple overlays may be specified, and they will be applied in the order given.
307.Sh NODE OMISSION
308This utility supports the
309.Va /omit-if-no-ref/
310statement to mark nodes for omission if they are ultimately not referenced
311elsewhere in the device tree.
312This may be used in more space-constrained environments to remove nodes that may
313not be applicable to the specific device the tree is being compiled for.
314.Pp
315When the
316.Fl @
317flag is used to write symbols, nodes with labels will be considered referenced
318and will not be removed from the tree.
319.Sh EXAMPLES
320The command:
321.Pp
322.Dl "dtc -o blob.S -O asm device.dts"
323.Pp
324will generate a
325.Pa blob.S
326file from the device tree source
327.Pa device.dts
328and print errors if any occur during parsing or property checking.
329The resulting file can be assembled and linked into a binary.
330.Pp
331The command:
332.Pp
333.Dl "dtc -o - -O dts -I dtb device.dtb"
334.Pp
335will write the device tree source for the device tree blob
336.Pa device.dtb
337to the standard output.
338This is useful when debugging device trees.
339.Pp
340The command:
341.Pp
342.Dl "dtc -@ -O dtb -I dts -o device.dtb device.dts"
343.Pp
344will generate a
345.Pa device.dtb
346file from the device tree source
347.Pa device.dts
348with a __symbols__ node included so that overlays may be applied to it.
349.Pp
350The command:
351.Pp
352.Dl "dtc -@ -O dtb -I dts -o device_overlay.dtbo device_overlay.dts"
353.Pp
354will generate a
355.Pa device_overlay.dtbo
356file, using the standard extension for a device tree overlay, from the device
357tree source
358.Pa device_overlay.dts .
359A __symbols__ node will be included so that overlays may be applied to it.
360The presence of a
361.Va /plugin/;
362directive in
363.Pa device_overlay.dts
364will indicate to the utility that it should also generate the underlying
365metadata required in overlays.
366.Sh COMPATIBILITY
367This utility is intended to be compatible with the device tree compiler
368provided by elinux.org.
369Currently, it implements the subset of features
370required to build FreeBSD and others that have been requested by FreeBSD
371developers.
372.Pp
373The
374.Ar fs
375input format is not supported.
376This builds a tree from a Linux
377.Pa  /proc/device-tree ,
378a file system hierarchy not found in FreeBSD, which instead exposes the DTB
379directly via a sysctl.
380.Pp
381The warnings and errors supported by the elinux.org tool are not documented.
382This tool supports the warnings described in the
383.Sx CHECKERS
384section.
385.Sh SEE ALSO
386.Xr fdt 4
387.Sh STANDARDS
388The device tree formats understood by this tool conform to the Power.org
389Standard for Embedded Power Architecture Platform Requirements
390.Pq Vt ePAPR ,
391except as noted in the
392.Sx BUGS
393section and with the following exceptions for compatibility with the elinux.org
394tool:
395.Pp
396.Bl -bullet -compact
397.It
398The target of cross references is defined to be a node name in the
399specification, but is in fact a label.
400.El
401.Pp
402The /include/ directive is not part of the standard, however it is implemented
403with the semantics compatible with the elinux.org tool.
404It must appear in the top level of a file, and imports a new root definition.
405If a file, plus all of its inclusions, contains multiple roots then they are
406merged.
407All nodes that are present in the second but not the first are imported.
408Any that appear in both are recursively merged, with properties from the second
409replacing those from the first and properties child nodes being recursively
410merged.
411.Sh HISTORY
412A dtc tool first appeared in
413.Fx 9.0 .
414This version of the tool first appeared in
415.Fx 10.0 .
416.Sh AUTHORS
417.Nm
418was written by
419.An David T. Chisnall .
420Some features were added later by
421.An Kyle Evans .
422.Pp
423Note: The fact that the tool and the author share the same initials is entirely
424coincidental.
425.Sh BUGS
426The device tree compiler does not yet support the following features:
427.Pp
428.Bl -bullet -compact
429.It
430Labels in the middle of property values.
431This is only useful in the assembly output, and only vaguely useful there, so
432is unlikely to be added soon.
433.It
434Full paths, rather than labels, as the targets for phandles.
435This is not very hard to add, but will probably not be added until something
436actually needs it.
437.El
438.Pp
439The current version performs a very limited set of semantic checks on the tree.
440This will be improved in future versions.
441