1 files changed, 86 insertions, 58 deletions

diff --git a/usr.bin/dtc/dtc.1 b/usr.bin/dtc/dtc.1
index 5d255e5e64b3..567aa03ef10d 100644
--- a/usr.bin/dtc/dtc.1
+++ b/usr.bin/dtc/dtc.1
@@ -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.