e29c18df28
This checks that every node that has children specifies their register sizes. This is not enabled by default, as the default sizes are sometimes required (including by some DTS in the tree), but can help when writing new device trees so that you can check that you actually meant the defaults.
316 lines
9.8 KiB
Groff
316 lines
9.8 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2013 David Chisnall
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This software was developed by SRI International and the University of
|
|
.\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237)
|
|
.\" ("CTSRD"), as part of the DARPA CRASH research programme.
|
|
.\"
|
|
.\" This software was developed by SRI International and the University of
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"/
|
|
.Dd January 1, 2013
|
|
.Dt DTC 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm dtc
|
|
.Nd device tree compiler
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl fhsv
|
|
.Op Fl b Ar boot_cpu_id
|
|
.Op Fl d Ar dependency_file
|
|
.Op Fl E Ar [no-]checker_name
|
|
.Op Fl H Ar phandle_format
|
|
.Op Fl I Ar input_format
|
|
.Op Fl O Ar output_format
|
|
.Op Fl o Ar output_file
|
|
.Op Fl R Ar entries
|
|
.Op Fl S Ar bytes
|
|
.Op Fl p Ar bytes
|
|
.Op Fl V Ar blob_version
|
|
.Op Fl W Ar [no-]checker_name
|
|
.Ar input_file
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility converts flattened device tree (FDT) representations.
|
|
It is most commonly used to generate device tree blobs (DTB), the binary
|
|
representation of an FDT, from device tree sources (DTS), the ASCII text source
|
|
representation.
|
|
.Pp
|
|
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
|
|
.Sx "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.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width indent
|
|
.It Fl d Ar dependency_file
|
|
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.
|
|
.It Fl E Ar [no-]checker_name
|
|
Enable or disable a specified checker.
|
|
The argument is the name of the checker.
|
|
The full list of checkers is given in
|
|
.Sx CHECKERS .
|
|
.It Fl f
|
|
Force the tool to attempt to generate the output, even if the input had errors.
|
|
.It Fl h
|
|
Display the help text and exit.
|
|
.It Fl H Ar phandle_format
|
|
Specifies the type of phandle nodes to generate in the output.
|
|
Valid values are:
|
|
.Pp
|
|
.Bl -tag -width indent -compact
|
|
.It Ar linux
|
|
Generate the legacy linux,phandle nodes expected by older systems.
|
|
.It Ar epapr
|
|
Generate the phandle nodes, as described in the ePAPR specification.
|
|
This is the most sensible option for device trees being used with
|
|
.Fx .
|
|
.It Ar both
|
|
Generate both, for maximum compatibility.
|
|
.El
|
|
.It Fl I Ar input_format
|
|
Specifies the input format.
|
|
Valid values are:
|
|
.Pp
|
|
.Bl -tag -width indent -compact
|
|
.It Ar dtb
|
|
Device tree blob.
|
|
The binary representation of the FDT.
|
|
.It Ar dts
|
|
Device tree source.
|
|
The ASCII representation of the FDT.
|
|
This is the default if the input format is not explicitly stated.
|
|
.El
|
|
.It Fl O Ar output_format
|
|
Specifies the output format.
|
|
Valid values are:
|
|
.Pp
|
|
.Bl -tag -width indent -compact
|
|
.It Ar asm
|
|
Assembler source for generating a device tree blob, as described in
|
|
.Sx "ASM FORMAT" .
|
|
.It Ar dtb
|
|
Device tree blob.
|
|
The binary representation of the FDT.
|
|
This is the default if the output format is not explicitly stated.
|
|
.It Ar dts
|
|
Device tree source.
|
|
The ASCII representation of the FDT.
|
|
.El
|
|
.It Fl o Ar output_file
|
|
The file to which to write the output.
|
|
.It Fl R Ar entries
|
|
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.
|
|
.It Fl S Ar bytes
|
|
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.
|
|
.It Fl p Ar bytes
|
|
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.
|
|
.It Fl W Ar [no-]checker_name
|
|
Enable or disable a specified checker.
|
|
This is an alias for
|
|
.Fl E .
|
|
.It Fl s
|
|
Sorts the properties and nodes in the tree.
|
|
This is mainly useful when using tools like
|
|
.Xr diff 1
|
|
to compare two device tree sources.
|
|
.It Fl V Ar output_version
|
|
The version of the format to output.
|
|
This is only relevant for binary outputs, and only a value of 17 is currently
|
|
supported.
|
|
.It Fl v
|
|
Display the tool version and exit.
|
|
.It Ar input_file
|
|
The source file.
|
|
.El
|
|
.Sh "ASM FORMAT"
|
|
The assembly format defines several globals that can be referred to from other
|
|
compilation units, in addition to any labels specified in the source.
|
|
These are:
|
|
.Pp
|
|
.Bl -tag -width "dt_strings_start" -compact -offset indent
|
|
.It dt_blob_start
|
|
start of the device tree blob.
|
|
.It dt_header
|
|
start of the header, usually identical to the start of the blob.
|
|
.It dt_reserve_map
|
|
start of the reservation map.
|
|
.It dt_struct_start
|
|
start of the structure table.
|
|
.It dt_struct_end
|
|
end of the structure table.
|
|
.It dt_strings_start
|
|
start of the strings table.
|
|
.It dt_strings_end
|
|
end of the strings table.
|
|
.It dt_blob_end
|
|
end of the device tree blob.
|
|
.El
|
|
.Sh CHECKERS
|
|
The utility provides a number of semantic checks on the correctness of the
|
|
tree.
|
|
These can be disabled with the
|
|
.Fl W
|
|
flag.
|
|
For example,
|
|
.Fl W Ar no-type-phandle
|
|
will disable the phandle type check.
|
|
The supported checks are:
|
|
.Pp
|
|
.Bl -tag -width "no-type-phandle" -compact -offset indent
|
|
.It type-compatible
|
|
Checks the type of the
|
|
.Va compatible
|
|
property.
|
|
.It type-model
|
|
Checks the type of the
|
|
.Va model
|
|
property.
|
|
.It type-compatible
|
|
Checks the type of the
|
|
.Va compatible
|
|
property.
|
|
.It cells-attributes
|
|
Checks that all nodes with children have both
|
|
.Va #address-cells
|
|
and
|
|
.Va #size-cells
|
|
properties.
|
|
.El
|
|
.Sh EXAMPLES
|
|
The command:
|
|
.Pp
|
|
.Dl "dtc -o blob.S -O asm device.dts"
|
|
.Pp
|
|
will generate a
|
|
.Pa blob.S
|
|
file from the device tree source
|
|
.Pa device.dts
|
|
and print errors if any occur during parsing or property checking.
|
|
The
|
|
resulting file can be assembled and linked into a binary.
|
|
.Pp
|
|
The command:
|
|
.Pp
|
|
.Dl "dtc -o - -O dts -I dtb device.dtb"
|
|
.Pp
|
|
will write the device tree source for the device tree blob
|
|
.Pa device.dtb
|
|
to the standard output.
|
|
This is useful when debugging device trees.
|
|
.Sh COMPATIBILITY
|
|
This utility is intended to be compatible with the device tree compiler
|
|
provided by elinux.org.
|
|
Currently, it implements the subset of features
|
|
required to build FreeBSD and others that have been requested by FreeBSD
|
|
developers.
|
|
.Pp
|
|
The
|
|
.Ar fs
|
|
input format is not supported.
|
|
This builds a tree from a Linux
|
|
.Pa /proc/device-tree ,
|
|
a file system hierarchy not found in FreeBSD, which instead exposes the DTB
|
|
directly via a sysctl.
|
|
.Pp
|
|
The warnings and errors supported by the elinux.org tool are not documented.
|
|
This tool supports the warnings described in the
|
|
.Sx CHECKERS
|
|
section.
|
|
.Sh SEE ALSO
|
|
.Xr fdt 4
|
|
.Sh STANDARDS
|
|
The device tree formats understood by this tool conform to the Power.org
|
|
Standard for Embedded Power Architecture Platform Requirements
|
|
.Pq Vt ePAPR ,
|
|
except as noted in the
|
|
.Sx BUGS
|
|
section and with the following exceptions for compatibility with the elinux.org
|
|
tool:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
The target of cross references is defined to be a node name in the
|
|
specification, but is in fact a label.
|
|
.El
|
|
.Pp
|
|
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.
|
|
.Sh HISTORY
|
|
A dtc tool first appeared in
|
|
.Fx 9.0 .
|
|
This version of the tool first appeared in
|
|
.Fx 10.0 .
|
|
.Sh AUTHORS
|
|
.An David T. Chisnall
|
|
.Pp
|
|
Note: The fact that the tool and the author share the same initials is entirely
|
|
coincidental.
|
|
.Sh BUGS
|
|
The device tree compiler does not yet support the following features:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
Labels in the middle of property values.
|
|
This is only useful in the assembly output, and only vaguely useful there, so
|
|
is unlikely to be added soon.
|
|
.It
|
|
Full paths, rather than labels, as the targets for phandles.
|
|
This is not very hard to add, but will probably not be added until something
|
|
actually needs it.
|
|
.El
|
|
.Pp
|
|
The current version performs a very limited set of semantic checks on the tree.
|
|
This will be improved in future versions.
|