Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DTC(1)			  BSD General Commands Manual			DTC(1)

     dtc -- device tree	compiler

     dtc [-fhsv] [-b boot_cpu_id] [-d dependency_file] [-E [no-]checker_name]
	 [-H phandle_format] [-I input_format] [-O output_format]
	 [-o output_file] [-R entries] [-S bytes] [-p bytes] [-V blob_version]
	 [-W [no-]checker_name]	[-P predefined_properties] input_file

     The dtc 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.

     The binary	can be written in two formats, binary and assembly.  The bi-
     nary is identical to the in-memory	representation and can be used di-
     rectly by firmware, loaders, and so on.  The assembly format, documented
     in	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 de-
     vice, with	the device tree	blob compiled in.

     The options are as	follows:

     -d	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.

     -E	[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 CHECKERS.

     -f	     Force the tool to attempt to generate the output, even if the in-
	     put had errors.

     -h	     Display the help text and exit.

     -H	phandle_format
	     Specifies the type	of phandle nodes to generate in	the output.
	     Valid values are:

	     linux   Generate the legacy linux,phandle nodes expected by older
	     epapr   Generate the phandle nodes, as described in the ePAPR
		     specification.  This is the most sensible option for de-
		     vice trees	being used with	FreeBSD.
	     both    Generate both, for	maximum	compatibility.

     -I	input_format
	     Specifies the input format.  Valid	values are:

	     dtb     Device tree blob.	The binary representation of the FDT.
	     dts     Device tree source.  The ASCII representation of the FDT.
		     This is the default if the	input format is	not explicitly

     -O	output_format
	     Specifies the output format.  Valid values	are:

	     asm     Assembler source for generating a device tree blob, as
		     described in ASM FORMAT.
	     dtb     Device tree blob.	The binary representation of the FDT.
		     This is the default if the	output format is not explic-
		     itly stated.
	     dts     Device tree source.  The ASCII representation of the FDT.

     -o	output_file
	     The file to which to write	the output.

     -P	predefined_macro
	     Defines a macro, in the form name=value or	name to	be used	for
	     device tree source	files that contain conditional components.
	     This tool supports	two extensions to the standard to support con-
	     ditional compilation of device trees.  The	first is an
	     /include/if [property]/ file.dts directive	that is	allowed	at the
	     start of a	file and which will only include the specified file if
	     it	the specified property is passed with this flag.  The second
	     is	the $NAME format for property values.  These allow property
	     value to be specified on the command line.

     -R	entries
	     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 be-
	     fore passing control to the operating system.

     -S	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.

     -p	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	cor-
	     rect size.	 This is useful	for environments where the device tree
	     blob must be modified in place.

     -W	[no-]checker_name
	     Enable or disable a specified checker.  This is an	alias for -E.

     -s	     Sorts the properties and nodes in the tree.  This is mainly use-
	     ful when using tools like diff(1) to compare two device tree

     -V	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.

     -v	     Display the tool version and exit.

	     The source	file.

     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:

	   dt_blob_start     start of the device tree blob.
	   dt_header	     start of the header, usually identical to the
			     start of the blob.
	   dt_reserve_map    start of the reservation map.
	   dt_struct_start   start of the structure table.
	   dt_struct_end     end of the	structure table.
	   dt_strings_start  start of the strings table.
	   dt_strings_end    end of the	strings	table.
	   dt_blob_end	     end of the	device tree blob.

     The utility provides a number of semantic checks on the correctness of
     the tree.	These can be disabled with the -W flag.	 For example, -W
     no-type-phandle will disable the phandle type check.  The supported
     checks are:

	   type-compatible  Checks the type of the compatible property.
	   type-model	    Checks the type of the model property.
	   type-compatible  Checks the type of the compatible property.
			    Checks that	all nodes with children	have both
			    #address-cells and #size-cells properties.

     The command:

	   dtc -o blob.S -O asm	device.dts

     will generate a blob.S file from the device tree source device.dts	and
     print errors if any occur during parsing or property checking.  The re-
     sulting file can be assembled and linked into a binary.

     The command:

	   dtc -o - -O dts -I dtb device.dtb

     will write	the device tree	source for the device tree blob	device.dtb to
     the standard output.  This	is useful when debugging device	trees.

     This utility is intended to be compatible with the	device tree compiler
     provided by  Currently, it implements the subset of features
     required to build FreeBSD and others that have been requested by FreeBSD

     The fs input format is not	supported.  This builds	a tree from a Linux
     /proc/device-tree,	a file system hierarchy	not found in FreeBSD, which
     instead exposes the DTB directly via a sysctl.

     The warnings and errors supported by the tool are not docu-
     mented.  This tool	supports the warnings described	in the CHECKERS	sec-


     The device	tree formats understood	by this	tool conform to	the
     Standard for Embedded Power Architecture Platform Requirements (ePAPR),
     except as noted in	the BUGS section and with the following	exceptions for
     compatibility with	the tool:

     +o	 The target of cross references	is defined to be a node	name in	the
	 specification,	but is in fact a label.

     The /include/ directive is	not part of the	standard, however it is	imple-
     mented with the semantics compatible with the 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 proper-
     ties from the second replacing those from the first and properties	child
     nodes being recursively merged.

     A dtc tool	first appeared in FreeBSD 9.0.	This version of	the tool first
     appeared in FreeBSD 10.0.

     David T. Chisnall

     Note: The fact that the tool and the author share the same	initials is
     entirely coincidental.

     The device	tree compiler does not yet support the following features:

     +o	 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.
     +o	 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.

     The current version performs a very limited set of	semantic checks	on the
     tree.  This will be improved in future versions.

BSD				January	1, 2013				   BSD


Want to link to this manual page? Use this URL:

home | help