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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
FDT(4)		       FreeBSD Kernel Interfaces Manual			FDT(4)

NAME
     fdt -- Flattened Device Tree support

SYNOPSIS
     options FDT
     makeoptions FDT_DTS_FILE=<board name>.dts
     options FDT_DTB_STATIC

DESCRIPTION
     Flattened Device Tree is a	mechanism for describing computer hardware
     resources,	which cannot be	probed or self enumerated, in a	uniform	and
     portable way. The primary consumers of this technology are	embedded
     systems, where a lot of designs are based on similar chips, but have dif-
     ferent assignment of pins,	memory layout, addresses bindings, interrupts
     routing and other resources.

     Configuration data, which cannot be self discovered in run-time, has to
     be	supplied from external source. The concept of a	flattened device tree
     is	a platform and architecture independent	approach for resolving such
     problems.	The idea is inherited from Open	Firmware IEEE 1275 device-tree
     notion, and has been successfully adopted by the embedded industry. The
     scheme works in the following way:

     +o	 Hardware platform resources are manually described in a human read-
	 able text source format, where	all non	self-enumerating information
	 is gathered.

     +o	 This source description is converted (compiled) into a	binary object
	 i.e. a	flattened device tree blob which is passed to the kernel at
	 boot time.

     +o	 The kernel (driver) learns about hardware resources details and
	 dependencies from this	[externally supplied] blob, which eliminates
	 the need for embedding	any information	about the underlying platform
	 hardware resources in the kernel.

     +o	 The flattened device tree mechanism in	principle does not depend on
	 any particular	first-stage bootloader or firmware features.  The only
	 overall requirement for the environment is to provide a complete
	 device	tree description to the	kernel.

     The fdt layer allows any platform code in the kernel to retrieve informa-
     tion about	hardware resources from	a unified origin, which	brings advan-
     tages to the embedded applications	(eliminates hard-coded configuration
     approach, enforces	code to	be data	driven and extensible) leading to eas-
     ier porting and maintenance.

DEFINITIONS
     Device tree source	(DTS)
		   The device tree source is a text file which describes hard-
		   ware	resources of a computer	system in a human-readable
		   form, with certain hierarchical structure (a	tree). The
		   default location for	DTS files in the FreeBSD source	repos-
		   itory is sys/boot/fdt/dts directory.

     Device tree blob (DTB)
		   The textual device tree description (DTS file) is first
		   converted (compiled)	into a binary object (the device tree
		   blob) i.e. the DTB, which is	handed over to the final con-
		   sumer (typically kernel) for	parsing	and processing of its
		   contents.

     Device tree compiler (DTC)
		   A utility program executed on the host, which transforms
		   (compiles) a	textual	description of a device	tree (DTS)
		   into	a binary object	(DTB).

     Device tree bindings
		   While the device tree textual description and the binary
		   object are media to convey the hardware configuration
		   information,	an actual meaning and interpretation of	the
		   contents are	defined	by the device tree bindings.  They are
		   certain conventions describing definitions (encoding) of
		   particular nodes in a device	tree and their properties,
		   allowed values, ranges and so on.  Such reference conven-
		   tions were provided by the legacy Open Firmware bindings,
		   further supplemented	by the ePAPR specification.

BUILDING THE WORLD
     In	order for the system to	support	fdt it is required that	FreeBSD	world
     be	built with the WITH_FDT	build knob supplied either via src.conf(5) or
     command line defined with -D.

     This creates the user space dtc compiler and enables fdt support in
     loader(8).

BUILDING KERNEL
     There is a	couple of options for managing fdt support at the FreeBSD ker-
     nel level.

     options FDT   The primary option for enabling fdt support in the kernel.
		   It covers all low-level and infrastructure parts of fdt
		   kernel support, which primarily are the fdtbus(4) and
		   simplebus(4)	drivers, as well as helper routines and
		   libraries.

     makeoptions FDT_DTS_FILE=_board name_.dts
		   Specifies a preferred (default) device tree source (DTS)
		   file	for a given kernel. The	indicated DTS file will	be
		   converted (compiled)	into a binary form along with building
		   the kernel itself. The DTS file name	is relative to the
		   default location of DTS sources i.e.	 sys/boot/fdt/dts.
		   This	makeoption is not mandatory unless FDT_DTB_STATIC is
		   also	defined	(see below).

     options FDT_DTB_STATIC
		   Typically, the device tree blob (DTB) is a stand-alone
		   file, physically separate from the kernel, but this option
		   lets	statically embed a DTB file into a kernel image. Note
		   that	when this is specified the FDT_DTS_FILE	makeoption
		   becomes mandatory (as there needs to	be a DTS file speci-
		   fied	in order to embed it into the kernel image).

SEE ALSO
     fdtbus(4),	openfirm(4), simplebus(4)

STANDARDS
     IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration)
     Firmware: Core Requirements and Practices (Open Firmware).

     Power.org Standard	for Embedded Power Architecture	Platform Requirements
     (ePAPR).

HISTORY
     The fdt support first appeared in FreeBSD 9.0.

AUTHORS
     The fdt support was developed by Semihalf under sponsorship from the
     FreeBSD Foundation. This manual page was written by Rafal Jaworowski.

FreeBSD	9.2			 July 12, 2010			   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | DEFINITIONS | BUILDING THE WORLD | BUILDING KERNEL | SEE ALSO | STANDARDS | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=fdt&sektion=4&manpath=FreeBSD+10.0-RELEASE>

home | help