usr.bin/dtc/dtc.1

   1 .\"-
   2 .\" Copyright (c) 2013 David Chisnall
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed by SRI International and the University of
   6 .\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237)
   7 .\" ("CTSRD"), as part of the DARPA CRASH research programme.
   8 .\"
   9 .\" This software was developed by SRI International and the University of
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\" $FreeBSD$
  32 .\"/
  33 .Dd January 1, 2013
  34 .Dt DTC 1
  35 .Os
  36 .Sh NAME
  37 .Nm dtc
  38 .Nd device tree compiler
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl fhsv
  42 .Op Fl b Ar boot_cpu_id
  43 .Op Fl d Ar dependency_file
  44 .Op Fl E Ar [no-]checker_name
  45 .Op Fl H Ar phandle_format
  46 .Op Fl I Ar input_format
  47 .Op Fl O Ar output_format
  48 .Op Fl o Ar output_file
  49 .Op Fl R Ar entries
  50 .Op Fl S Ar bytes
  51 .Op Fl p Ar bytes
  52 .Op Fl V Ar blob_version
  53 .Op Fl W Ar [no-]checker_name
  54 .Op Fl P Ar predefined_properties
  55 .Ar input_file
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 utility converts flattened device tree (FDT) representations.
  60  It is most commonly used to generate device tree blobs (DTB), the binary
  61 representation of an FDT, from device tree sources (DTS), the ASCII text source
  62 representation.
  63 .Pp
  64 The binary can be written in two formats, binary and assembly.
  65 The binary is identical to the in-memory representation and can be used
  66 directly by firmware, loaders, and so on.
  67 The assembly format, documented in
  68 .Sx "ASM FORMAT" ,
  69 will produce the same binary format when assembled, but also includes some
  70 global variables that refer to parts of the table.
  71 This format is most commonly used to produce a kernel specific to a device,
  72 with the device tree blob compiled in.
  73 .Pp
  74 The options are as follows:
  75 .Bl -tag -width indent
  76 .It Fl d Ar dependency_file
  77 Writes a dependency file understandable by make to the specified file.
  78 This file can be included in a Makefile and will ensure that the output file
  79 depends on the input file and any files that it includes.
  80 This argument is only useful when the input is DTS, as only the source format
  81 has a notion of inclusions.
  82 .It Fl E Ar [no-]checker_name
  83 Enable or disable a specified checker.
  84 The argument is the name of the checker.
  85 The full list of checkers is given in
  86 .Sx CHECKERS .
  87 .It Fl f
  88 Force the tool to attempt to generate the output, even if the input had errors.
  89 .It Fl h
  90 Display the help text and exit.
  91 .It Fl H Ar phandle_format
  92 Specifies the type of phandle nodes to generate in the output.
  93 Valid values are:
  94 .Pp
  95 .Bl -tag -width indent -compact
  96 .It Ar linux
  97 Generate the legacy linux,phandle nodes expected by older systems.
  98 .It Ar epapr
  99 Generate the phandle nodes, as described in the ePAPR specification.
 100 This is the most sensible option for device trees being used with
 101 .Fx .
 102 .It Ar both
 103 Generate both, for maximum compatibility.
 104 .El
 105 .It Fl I Ar input_format
 106 Specifies the input format.
 107 Valid values are:
 108 .Pp
 109 .Bl -tag -width indent -compact
 110 .It Ar dtb
 111 Device tree blob.
 112 The binary representation of the FDT.
 113 .It Ar dts
 114 Device tree source.
 115 The ASCII representation of the FDT.
 116 This is the default if the input format is not explicitly stated.
 117 .El
 118 .It Fl O Ar output_format
 119 Specifies the output format.
 120 Valid values are:
 121 .Pp
 122 .Bl -tag -width indent -compact
 123 .It Ar asm
 124 Assembler source for generating a device tree blob, as described in
 125 .Sx "ASM FORMAT" .
 126 .It Ar dtb
 127 Device tree blob.
 128 The binary representation of the FDT.
 129 This is the default if the output format is not explicitly stated.
 130 .It Ar dts
 131 Device tree source.
 132 The ASCII representation of the FDT.
 133 .El
 134 .It Fl o Ar output_file
 135 The file to which to write the output.
 136 .It Fl P Ar predefined_macro
 137 Defines a macro, in the form
 138 .Ar name=value
 139 or
 140 .Ar name
 141 to be used for device tree source files that contain conditional components.
 142 This tool supports two extensions to the standard to support conditional
 143 compilation of device trees.
 144 The first is an
 145 .Ar /include/if [property]/ "file.dts"
 146 directive that is allowed at the start of a file and which will only include
 147 the specified file if it the specified property is passed with this flag.
 148 The second is the
 149 .Ar $NAME
 150 format for property values.
 151 These allow property value to be specified on the command line.
 152 .It Fl R Ar entries
 153 The number of empty reservation table entries to pad the table with.
 154 This is
 155 useful if you are generating a device tree blob for bootloader or similar that
 156 needs to reserve some memory before passing control to the operating system.
 157 .It Fl S Ar bytes
 158 The minimum size in bytes of the blob.
 159 The blob will be padded after the strings table to ensure that it is the
 160 correct size.
 161 This is useful for environments where the device tree blob must be modified in
 162 place.
 163 .It Fl p Ar bytes
 164 The number of bytes of padding to add to the blob.
 165 The blob will be padded after the strings table to ensure that it is the
 166 correct size.
 167 This is useful for environments where the device tree blob must be modified in
 168 place.
 169 .It Fl W Ar [no-]checker_name
 170 Enable or disable a specified checker.
 171 This is an alias for
 172 .Fl E .
 173 .It Fl s
 174 Sorts the properties and nodes in the tree.
 175 This is mainly useful when using tools like
 176 .Xr diff 1
 177 to compare two device tree sources.
 178 .It Fl V Ar output_version
 179 The version of the format to output.
 180 This is only relevant for binary outputs, and only a value of 17 is currently
 181 supported.
 182 .It Fl v
 183 Display the tool version and exit.
 184 .It Ar input_file
 185 The source file.
 186 .El
 187 .Sh "ASM FORMAT"
 188 The assembly format defines several globals that can be referred to from other
 189 compilation units, in addition to any labels specified in the source.
 190 These are:
 191 .Pp
 192 .Bl -tag -width "dt_strings_start" -compact -offset indent
 193 .It dt_blob_start
 194 start of the device tree blob.
 195 .It dt_header
 196 start of the header, usually identical to the start of the blob.
 197 .It dt_reserve_map
 198 start of the reservation map.
 199 .It dt_struct_start
 200 start of the structure table.
 201 .It dt_struct_end
 202 end of the structure table.
 203 .It dt_strings_start
 204 start of the strings table.
 205 .It dt_strings_end
 206 end of the strings table.
 207 .It dt_blob_end
 208 end of the device tree blob.
 209 .El
 210 .Sh CHECKERS
 211 The utility provides a number of semantic checks on the correctness of the
 212 tree.
 213 These can be disabled with the
 214 .Fl W
 215 flag.
 216 For example,
 217 .Fl W Ar no-type-phandle
 218 will disable the phandle type check.
 219 The supported checks are:
 220 .Pp
 221 .Bl -tag -width "no-type-phandle" -compact -offset indent
 222 .It type-compatible
 223 Checks the type of the
 224 .Va compatible
 225 property.
 226 .It type-model
 227 Checks the type of the
 228 .Va model
 229 property.
 230 .It type-compatible
 231 Checks the type of the
 232 .Va compatible
 233 property.
 234 .It cells-attributes
 235 Checks that all nodes with children have both
 236 .Va #address-cells
 237 and
 238 .Va #size-cells
 239 properties.
 240 .El
 241 .Sh EXAMPLES
 242 The command:
 243 .Pp
 244 .Dl "dtc -o blob.S -O asm device.dts"
 245 .Pp
 246 will generate a
 247 .Pa blob.S
 248 file from the device tree source
 249 .Pa device.dts
 250 and print errors if any occur during parsing or property checking.
 251 The
 252 resulting file can be assembled and linked into a binary.
 253 .Pp
 254 The command:
 255 .Pp
 256 .Dl "dtc -o - -O dts -I dtb device.dtb"
 257 .Pp
 258 will write the device tree source for the device tree blob
 259 .Pa device.dtb
 260 to the standard output.
 261 This is useful when debugging device trees.
 262 .Sh COMPATIBILITY
 263 This utility is intended to be compatible with the device tree compiler
 264 provided by elinux.org.
 265 Currently, it implements the subset of features
 266 required to build FreeBSD and others that have been requested by FreeBSD
 267 developers.
 268 .Pp
 269 The
 270 .Ar fs
 271 input format is not supported.
 272 This builds a tree from a Linux
 273 .Pa  /proc/device-tree ,
 274 a file system hierarchy not found in FreeBSD, which instead exposes the DTB
 275 directly via a sysctl.
 276 .Pp
 277 The warnings and errors supported by the elinux.org tool are not documented.
 278 This tool supports the warnings described in the
 279 .Sx CHECKERS
 280 section.
 281 .Sh SEE ALSO
 282 .Xr fdt 4
 283 .Sh STANDARDS
 284 The device tree formats understood by this tool conform to the Power.org
 285 Standard for Embedded Power Architecture Platform Requirements
 286 .Pq Vt ePAPR ,
 287 except as noted in the
 288 .Sx BUGS
 289 section and with the following exceptions for compatibility with the elinux.org
 290 tool:
 291 .Pp
 292 .Bl -bullet -compact
 293 .It
 294 The target of cross references is defined to be a node name in the
 295 specification, but is in fact a label.
 296 .El
 297 .Pp
 298 The /include/ directive is not part of the standard, however it is implemented
 299 with the semantics compatible with the elinux.org tool.
 300 It must appear in the top level of a file, and imports a new root definition.
 301 If a file, plus all of its inclusions, contains multiple roots then they are
 302 merged.
 303 All nodes that are present in the second but not the first are imported.
 304 Any that appear in both are recursively merged, with properties from the second
 305 replacing those from the first and properties child nodes being recursively
 306 merged.
 307 .Sh HISTORY
 308 A dtc tool first appeared in
 309 .Fx 9.0 .
 310 This version of the tool first appeared in
 311 .Fx 10.0 .
 312 .Sh AUTHORS
 313 .An David T. Chisnall
 314 .Pp
 315 Note: The fact that the tool and the author share the same initials is entirely
 316 coincidental.
 317 .Sh BUGS
 318 The device tree compiler does not yet support the following features:
 319 .Pp
 320 .Bl -bullet -compact
 321 .It
 322 Labels in the middle of property values.
 323 This is only useful in the assembly output, and only vaguely useful there, so
 324 is unlikely to be added soon.
 325 .It
 326 Full paths, rather than labels, as the targets for phandles.
 327 This is not very hard to add, but will probably not be added until something
 328 actually needs it.
 329 .El
 330 .Pp
 331 The current version performs a very limited set of semantic checks on the tree.
 332 This will be improved in future versions.