diff options
Diffstat (limited to 'usr.bin')
| -rw-r--r-- | usr.bin/dtc/dtc.1 | 144 |
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. |