d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix style nit in dtc man page: sentences should start on new lines.

Browse Source 
Reported By:	joel
This commit is contained in:
David Chisnall 2013-01-25 08:34:38 +00:00
parent c0c4446155
commit 03d37d34cc
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=245901
1 changed files with 86 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
usr.bin/dtc/dtc.1
View File

@ -55,96 +55,113 @@
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
utility converts flattened device tree (FDT) representations. It is most utility converts flattened device tree (FDT) representations.
commonly used to generate device tree blobs (DTB), the binary representation of It is most commonly used to generate device tree blobs (DTB), the binary
an FDT, from device tree sources (DTS), the ASCII text source representation. representation of an FDT, from device tree sources (DTS), the ASCII text source
representation.
.Pp .Pp
The binary can be written in two formats, binary and assembly. The binary is The binary can be written in two formats, binary and assembly.
identical to the in-memory representation and can be used directly by firmware, The binary is identical to the in-memory representation and can be used
loaders, and so on. The assembly format, documented in directly by firmware, loaders, and so on.
The assembly format, documented in
.Sx "ASM FORMAT" , .Sx "ASM FORMAT" ,
will produce the same binary format when assembled, but also includes some 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 global variables that refer to parts of the table.
commonly used to produce a kernel specific to a device, with the device tree This format is most commonly used to produce a kernel specific to a device,
blob compiled in. with the device tree blob compiled in.
.Pp .Pp
The options are as follows: The options are as follows:
.Bl -tag -width indent .Bl -tag -width indent
.It Fl d Ar dependency_file .It Fl d Ar dependency_file
Writes a dependency file understandable by make to the specified file. This Writes a dependency file understandable by make to the specified file.
file can be included in a Makefile and will ensure that the output file depends This file can be included in a Makefile and will ensure that the output file
on the input file and any files that it includes. This argument is only useful depends on the input file and any files that it includes.
when the input is DTS, as only the source format has a notion of inclusions. 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 .It Fl E Ar [no-]checker_name
Enable or disable a specified checker. The argument is the name of the Enable or disable a specified checker.
checker. The full list of checkers is given in The argument is the name of the checker.
The full list of checkers is given in
.Sx CHECKERS . .Sx CHECKERS .
.It Fl f .It Fl f
Force the tool to attempt to generate the output, even if the input had errors. Force the tool to attempt to generate the output, even if the input had errors.
.It Fl h .It Fl h
Display the help text and exit. Display the help text and exit.
.It Fl H Ar phandle_format .It Fl H Ar phandle_format
Specifies the type of phandle nodes to generate in the output. Valid values Specifies the type of phandle nodes to generate in the output.
are: Valid values are:
.Pp .Pp
.Bl -tag -width indent -compact .Bl -tag -width indent -compact
.It Ar linux .It Ar linux
Generate the legacy linux,phandle nodes expected by older systems. Generate the legacy linux,phandle nodes expected by older systems.
.It Ar epapr .It Ar epapr
Generate the phandle nodes, as described in the ePAPR specification. This is Generate the phandle nodes, as described in the ePAPR specification.
the most sensible option for device trees being used with This is the most sensible option for device trees being used with
.Fx . .Fx .
.It Ar both .It Ar both
Generate both, for maximum compatibility. Generate both, for maximum compatibility.
.El .El
.It Fl I Ar input_format .It Fl I Ar input_format
Specifies the input format. Valid values are: Specifies the input format.
Valid values are:
.Pp .Pp
.Bl -tag -width indent -compact .Bl -tag -width indent -compact
.It Ar dtb .It Ar dtb
Device tree blob. The binary representation of the FDT. Device tree blob.
The binary representation of the FDT.
.It Ar dts .It Ar dts
Device tree source. The ASCII representation of the FDT. This is the default Device tree source.
if the input format is not explicitly stated. The ASCII representation of the FDT.
This is the default if the input format is not explicitly stated.
.El .El
.It Fl O Ar output_format .It Fl O Ar output_format
Specifies the output format. Valid values are: Specifies the output format.
Valid values are:
.Pp .Pp
.Bl -tag -width indent -compact .Bl -tag -width indent -compact
.It Ar asm .It Ar asm
Assembler source for generating a device tree blob, as described in Assembler source for generating a device tree blob, as described in
.Sx "ASM FORMAT" . .Sx "ASM FORMAT" .
.It Ar dtb .It Ar dtb
Device tree blob. The binary representation of the FDT. This is the default Device tree blob.
if the output format is not explicitly stated. The binary representation of the FDT.
This is the default if the output format is not explicitly stated.
.It Ar dts .It Ar dts
Device tree source. The ASCII representation of the FDT. Device tree source.
The ASCII representation of the FDT.
.El .El
.It Fl o Ar output_file .It Fl o Ar output_file
The file to which to write the output. The file to which to write the output.
.It Fl R Ar entries .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 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. needs to reserve some memory before passing control to the operating system.
.It Fl S Ar bytes .It Fl S Ar bytes
The minimum size in bytes of the blob. The blob will be padded after the The minimum size in bytes of the blob.
strings table to ensure that it is the correct size. This is useful for The blob will be padded after the strings table to ensure that it is the
environments where the device tree blob must be modified in place. correct size.
This is useful for environments where the device tree blob must be modified in
place.
.It Fl p Ar bytes .It Fl p Ar bytes
The number of bytes of padding to add to the blob. The blob will be padded The number of bytes of padding to add to the blob.
after the strings table to ensure that it is the correct size. This is useful The blob will be padded after the strings table to ensure that it is the
for environments where the device tree blob must be modified in place. correct size.
This is useful for environments where the device tree blob must be modified in
place.
.It Fl W Ar [no-]checker_name .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 . .Fl E .
.It Fl s .It Fl s
Sorts the properties and nodes in the tree. This is mainly useful when using Sorts the properties and nodes in the tree.
tools like This is mainly useful when using tools like
.Xr diff 1 .Xr diff 1
to compare two device tree sources. to compare two device tree sources.
.It Fl V Ar output_version .It Fl V Ar output_version
The version of the format to output. This is only relevant for binary outputs, The version of the format to output.
and only a value of 17 is currently supported. This is only relevant for binary outputs, and only a value of 17 is currently
supported.
.It Fl v .It Fl v
Display the tool version and exit. Display the tool version and exit.
.It Ar input_file .It Ar input_file
@ -152,8 +169,8 @@ The source file.
.El .El
.Sh "ASM FORMAT" .Sh "ASM FORMAT"
The assembly format defines several globals that can be referred to from other 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 compilation units, in addition to any labels specified in the source.
are: These are:
.Pp .Pp
.Bl -tag -width "dt_strings_start" -compact -offset indent .Bl -tag -width "dt_strings_start" -compact -offset indent
.It dt_blob_start .It dt_blob_start
@ -175,11 +192,14 @@ end of the device tree blob.
.El .El
.Sh CHECKERS .Sh CHECKERS
The utility provides a number of semantic checks on the correctness of the 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 .Fl W
flag. For example, flag.
For example,
.Fl W Ar no-type-phandle .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 .Pp
.Bl -tag -width "no-type-phandle" -compact -offset indent .Bl -tag -width "no-type-phandle" -compact -offset indent
.It type-compatible .It type-compatible
@ -204,7 +224,8 @@ will generate a
.Pa blob.S .Pa blob.S
file from the device tree source file from the device tree source
.Pa device.dts .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. resulting file can be assembled and linked into a binary.
.Pp .Pp
The command: The command:
@ -213,16 +234,19 @@ The command:
.Pp .Pp
will write the device tree source for the device tree blob will write the device tree source for the device tree blob
.Pa device.dtb .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 .Sh COMPATIBILITY
This utility is intended to be compatible with the device tree compiler 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 required to build FreeBSD and others that have been requested by FreeBSD
developers. developers.
.Pp .Pp
The The
.Ar fs .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 , .Pa /proc/device-tree ,
a file system hierarchy not found in FreeBSD, which instead exposes the DTB a file system hierarchy not found in FreeBSD, which instead exposes the DTB
directly via a sysctl. directly via a sysctl.
@ -249,12 +273,14 @@ specification, but is in fact a label.
.El .El
.Pp .Pp
The /include/ directive is not part of the standard, however it is implemented 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 with the semantics compatible with the elinux.org tool.
top level of a file, and imports a new root definition. If a file, plus all of It must appear in the top level of a file, and imports a new root definition.
its inclusions, contains multiple roots then they are merged. All nodes that If a file, plus all of its inclusions, contains multiple roots then they are
are present in the second but not the first are imported. Any that appear in merged.
both are recursively merged, with properties from the second replacing those All nodes that are present in the second but not the first are imported.
from the first and properties child nodes being recursively merged. 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 .Sh HISTORY
A dtc tool first appeared in A dtc tool first appeared in
.Fx 9.0 . .Fx 9.0 .
@ -270,11 +296,13 @@ The device tree compiler does not yet support the following features:
.Pp .Pp
.Bl -bullet -compact .Bl -bullet -compact
.It .It
Labels in the middle of property values. This is only useful in the assembly Labels in the middle of property values.
output, and only vaguely useful there, so is unlikely to be added soon. This is only useful in the assembly output, and only vaguely useful there, so
is unlikely to be added soon.
.It .It
Full paths, rather than labels, as the targets for phandles. This is not very Full paths, rather than labels, as the targets for phandles.
hard to add, but will probably not be added until something actually needs it. This is not very hard to add, but will probably not be added until something
actually needs it.
.El .El
.Pp .Pp
The current version performs a very limited set of semantic checks on the tree. The current version performs a very limited set of semantic checks on the tree.