Fix style nit in dtc man page: sentences should start on new lines.
Reported By: joel
This commit is contained in:
David Chisnall
parent
c0c4446155
commit
03d37d34cc
@ -55,96 +55,113 @@
|
||||
.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.
|
||||
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
|
||||
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.
|
||||
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.
|
||||
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
|
||||
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:
|
||||
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
|
||||
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:
|
||||
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.
|
||||
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.
|
||||
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:
|
||||
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.
|
||||
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.
|
||||
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
|
||||
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.
|
||||
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.
|
||||
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
|
||||
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
|
||||
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.
|
||||
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
|
||||
@ -152,8 +169,8 @@ 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:
|
||||
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
|
||||
@ -175,11 +192,14 @@ 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
|
||||
tree.
|
||||
These can be disabled with the
|
||||
.Fl W
|
||||
flag. For example,
|
||||
flag.
|
||||
For example,
|
||||
.Fl W Ar no-type-phandle
|
||||
will disable the phandle type check. The supported checks are:
|
||||
will disable the phandle type check.
|
||||
The supported checks are:
|
||||
.Pp
|
||||
.Bl -tag -width "no-type-phandle" -compact -offset indent
|
||||
.It type-compatible
|
||||
@ -204,7 +224,8 @@ 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
|
||||
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:
|
||||
@ -213,16 +234,19 @@ The command:
|
||||
.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.
|
||||
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
|
||||
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
|
||||
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.
|
||||
@ -249,12 +273,14 @@ 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.
|
||||
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 .
|
||||
@ -270,11 +296,13 @@ 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.
|
||||
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.
|
||||
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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user