Main index | Section 1 | Options |
The binary can be written in two formats, binary and assembly. The binary is identical to the in-memory representation and can be used directly by firmware, loaders, and so on. The assembly format, documented in ASM FORMAT, will produce the same binary format when assembled, but also includes some global variables that refer to parts of the table. This format is most commonly used to produce a kernel specific to a device, with the device tree blob compiled in.
The options are as follows:
| |
Writes a dependency file understandable by make to the specified file. This file can be included in a Makefile and will ensure that the output file depends on the input file and any files that it includes. This argument is only useful when the input is DTS, as only the source format has a notion of inclusions. | |
| |
Adds a path to search for include files. | |
| |
Enable or disable a specified checker. The argument is the name of the checker. The full list of checkers is given in CHECKERS. | |
| |
Emit a __symbols__ node to allow plugins to be loaded. | |
| |
Force the tool to attempt to generate the output, even if the input had errors. | |
| |
Display the help text and exit. | |
| |
Specifies the type of phandle nodes to generate in the output.
Valid values are:
| |
linux | Generate the legacy linux,phandle nodes expected by older systems. |
epapr | Generate the phandle nodes, as described in the ePAPR specification. This is the most sensible option for device trees being used with FreeBSD . |
both | Generate both, for maximum compatibility. |
| |
Specifies the input format.
Valid values are:
| |
dtb | Device tree blob. The binary representation of the FDT. |
dts | Device tree source. The ASCII representation of the FDT. This is the default if the input format is not explicitly stated. |
| |
Specifies the output format.
Valid values are:
| |
asm | Assembler source for generating a device tree blob, as described in ASM FORMAT. |
dtb | Device tree blob. The binary representation of the FDT. This is the default if the output format is not explicitly stated. |
dts | Device tree source. The ASCII representation of the FDT. |
| |
The file to which to write the output. | |
| |
Defines a macro, in the form name=value or name to be used for device tree source files that contain conditional components. This tool supports two extensions to the standard to support conditional compilation of device trees. The first is an /include/if [property]/ file.dts directive that is allowed at the start of a file and which will only include the specified file if it the specified property is passed with this flag. The second is the $NAME format for property values. These allow property value to be specified on the command line. | |
| |
The number of empty reservation table entries to pad the table with. This is useful if you are generating a device tree blob for bootloader or similar that needs to reserve some memory before passing control to the operating system. | |
| |
The minimum size in bytes of the blob. The blob will be padded after the strings table to ensure that it is the correct size. This is useful for environments where the device tree blob must be modified in place. | |
| |
The number of bytes of padding to add to the blob. The blob will be padded after the strings table to ensure that it is the correct size. This is useful for environments where the device tree blob must be modified in place. | |
| |
Enable or disable a specified checker.
This is an alias for
| |
| |
Sorts the properties and nodes in the tree. This is mainly useful when using tools like diff(1) to compare two device tree sources. | |
| |
The version of the format to output. This is only relevant for binary outputs, and only a value of 17 is currently supported. | |
| |
Display the tool version and exit. | |
input_file | |
The source file. | |
dt_blob_start | start of the device tree blob. |
dt_header | start of the header, usually identical to the start of the blob. |
dt_reserve_map | start of the reservation map. |
dt_struct_start | start of the structure table. |
dt_struct_end | end of the structure table. |
dt_strings_start | |
start of the strings table. | |
dt_strings_end | end of the strings table. |
dt_blob_end | end of the device tree blob. |
type-compatible | |
Checks the type of the compatible property. | |
type-model | Checks the type of the model property. |
type-compatible | |
Checks the type of the compatible property. | |
cells-attributes | |
Checks that all nodes with children have both #address-cells and #size-cells properties. | |
deleted-nodes | Checks that all /delete-node/ statements refer to nodes that are merged. |
To denote that a DTS is intended to be used as an overlay, /plugin/; should be included in the header, following any applicable /dts-v1/; tag.
Conventional overlays are crafted by creating fragment nodes in a root. Each fragment node must have either a target property set to a label reference, or a target-path string property set to a path. It must then have an __overlay__ child node, whose properties and child nodes are merged into the base device tree when the overlay is applied.
Much simpler syntactic sugar was later invented to simplify generating overlays. Instead of creating targetted fragments manually, one can instead create a root node that targets a label in the base FDT using the &label syntax supported in conventional DTS. This will indicate that a fragment should be generated for the node, with the given label being the target, and the properties and child nodes will be used as the __overlay__.
Additionally, a path-based version of this syntactic sugar is supported. A root node may target a path in the base FDT using a name of the form &{/path}. A fragment will be generated for the node as it is in the &label case, except the target-path property will be set to /path and no target will be set.
Both conventional overlays and the later-added syntactic sugar are supported.
Overlay blobs can be applied at boot time by setting fdt_overlays in loader.conf(5). Multiple overlays may be specified, and they will be applied in the order given.
When the
dtc -o blob.S -O asm device.dts
will generate a blob.S file from the device tree source device.dts and print errors if any occur during parsing or property checking. The resulting file can be assembled and linked into a binary.
The command:
dtc -o - -O dts -I dtb device.dtb
will write the device tree source for the device tree blob device.dtb to the standard output. This is useful when debugging device trees.
The command:
dtc -@ -O dtb -I dts -o device.dtb device.dts
will generate a device.dtb file from the device tree source device.dts with a __symbols__ node included so that overlays may be applied to it.
The command:
dtc -@ -O dtb -I dts -o device_overlay.dtbo device_overlay.dts
will generate a device_overlay.dtbo file, using the standard extension for a device tree overlay, from the device tree source device_overlay.dts. A __symbols__ node will be included so that overlays may be applied to it. The presence of a /plugin/; directive in device_overlay.dts will indicate to the utility that it should also generate the underlying metadata required in overlays.
The fs input format is not supported. This builds a tree from a Linux /proc/device-tree, a file system hierarchy not found in FreeBSD , which instead exposes the DTB directly via a sysctl.
The warnings and errors supported by the elinux.org tool are not documented. This tool supports the warnings described in the CHECKERS section.
The /include/ directive is not part of the standard, however it is implemented with the semantics compatible with the elinux.org tool. It must appear in the top level of a file, and imports a new root definition. If a file, plus all of its inclusions, contains multiple roots then they are merged. All nodes that are present in the second but not the first are imported. Any that appear in both are recursively merged, with properties from the second replacing those from the first and properties child nodes being recursively merged.
Note: The fact that the tool and the author share the same initials is entirely coincidental.
The current version performs a very limited set of semantic checks on the tree. This will be improved in future versions.
DTC (1) | March 27, 2019 |
Main index | Section 1 | Options |
Please direct any comments about this manual page service to Ben Bullock. Privacy policy.