svn commit: r210053 - head/share/man/man4

Rafal Jaworowski raj at FreeBSD.org
Wed Jul 14 13:03:00 UTC 2010 

Author: raj
Date: Wed Jul 14 13:03:00 2010
New Revision: 210053
URL: http://svn.freebsd.org/changeset/base/210053

Log:
  Provide initial man pages for Flattened Device Tree support and the common
  drivers.
  
  Sponsored by:	The FreeBSD Foundation

Added:
  head/share/man/man4/fdt.4   (contents, props changed)
  head/share/man/man4/fdtbus.4   (contents, props changed)
  head/share/man/man4/simplebus.4   (contents, props changed)
Modified:
  head/share/man/man4/Makefile

Modified: head/share/man/man4/Makefile
==============================================================================
--- head/share/man/man4/Makefile	Wed Jul 14 10:49:14 2010	(r210052)
+++ head/share/man/man4/Makefile	Wed Jul 14 13:03:00 2010	(r210053)
@@ -110,6 +110,8 @@ MAN=	aac.4 \
 	fatm.4 \
 	fd.4 \
 	fdc.4 \
+	fdt.4 \
+	fdtbus.4 \
 	firewire.4 \
 	fpa.4 \
 	fwe.4 \
@@ -358,6 +360,7 @@ MAN=	aac.4 \
 	siba.4 \
 	siftr.4 \
 	siis.4 \
+	simplebus.4 \
 	sio.4 \
 	sis.4 \
 	sk.4 \
@@ -527,6 +530,7 @@ MLINKS+=fatm.4 if_fatm.4
 MLINKS+=fd.4 stderr.4 \
 	fd.4 stdin.4 \
 	fd.4 stdout.4
+MLINKS+=fdt.4 FDT.4
 MLINKS+=firewire.4 ieee1394.4
 MLINKS+=fpa.4 fea.4
 MLINKS+=fwe.4 if_fwe.4

Added: head/share/man/man4/fdt.4
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man4/fdt.4	Wed Jul 14 13:03:00 2010	(r210053)
@@ -0,0 +1,184 @@
+.\"
+.\" Copyright (c) 2010 The FreeBSD Foundation
+.\" All rights reserved.
+.\"
+.\" This software was developed by Semihalf under sponsorship from
+.\" the FreeBSD Foundation.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 12, 2010
+.Dt FDT 4
+.Os
+.Sh NAME
+.Nm fdt
+.Nd Flattened Device Tree support
+.Sh SYNOPSIS
+.Cd "options FDT"
+.Cd "makeoptions FDT_DTS_FILE=<board name>.dts"
+.Cd "options FDT_DTB_STATIC"
+.Sh DESCRIPTION
+.Em 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
+.Em embedded systems,
+where a lot of designs are based on similar chips, but have different
+assignment of pins, memory layout, addresses bindings, interrupts routing and
+other resources.
+.Pp
+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:
+.Bl -bullet
+.It
+Hardware platform resources are
+.Em manually
+described in a human readable text source format, where all non
+self-enumerating information is gathered.
+.It
+This source description is converted
+.Em (compiled)
+into a binary object i.e. a flattened device tree
+.Em blob
+which is passed to the kernel at boot time.
+.It
+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.
+.It
+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.
+.El
+.Pp
+The
+.Nm
+layer allows any platform code in the kernel to retrieve information about
+hardware resources from a unified origin, which brings advantages to the
+embedded applications (eliminates hard-coded configuration approach, enforces
+code to be data driven and extensible) leading to easier porting and
+maintenance.
+.Sh DEFINITIONS
+.Bl -tag -width Ar
+.It Va Device tree source (DTS)
+The device tree source is a text file which describes hardware resources of a
+computer system in a human-readable form, with certain hierarchical structure
+(a tree). The default location for DTS files
+in the
+.Fx
+source repository is
+.Pa sys/boot/fdt/dts
+directory.
+.It Va 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 consumer (typically kernel) for parsing and processing of its
+contents.
+.It Va 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).
+.It Va 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
+.Pa 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 conventions were provided by the legacy Open Firmware bindings,
+further supplemented by the ePAPR specification.
+.El
+.Sh "BUILDING THE WORLD"
+In order for the system to support
+.Nm
+it is required that
+.Fx
+world be built with the
+.Pa WITH_FDT
+build knob supplied either via
+.Xr src.conf 5
+or command line defined with -D.
+.Pp
+This creates the user space
+.Pa dtc
+compiler and enables
+.Nm
+support in
+.Xr loader 8 .
+.Sh "BUILDING KERNEL"
+There is a couple of options for managing
+.Nm
+support at the
+.Fx
+kernel level.
+.Bl -tag -width Ar
+.It Va options FDT
+The primary option for enabling
+.Nm
+support in the kernel. It covers all low-level and infrastructure parts of
+.Nm
+kernel support, which primarily are the
+.Xr fdtbus 4 and
+.Xr simplebus 4 drivers, as well as helper routines and libraries.
+.It Va 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.
+.Pa sys/boot/fdt/dts .
+This makeoption is not mandatory unless FDT_DTB_STATIC is also defined (see
+below).
+.It Va 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
+specified in order to embed it into the kernel image).
+.El
+.Sh SEE ALSO
+.Xr fdtbus 4 ,
+.Xr openfirm 4 ,
+.Xr simplebus 4 ,
+.Sh STANDARDS
+IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware:
+Core Requirements and Practices
+.Pq Vt Open Firmware .
+.Pp
+Power.org Standard for Embedded Power Architecture Platform Requirements
+.Pq Vt ePAPR .
+.Sh HISTORY
+The
+.Nm
+support first appeared in
+.Fx 9.0 .
+.Sh AUTHORS
+The
+.Nm
+support was developed by Semihalf under sponsorship from the FreeBSD
+Foundation. This manual page was written by
+.An Rafal Jaworowski .

Added: head/share/man/man4/fdtbus.4
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man4/fdtbus.4	Wed Jul 14 13:03:00 2010	(r210053)
@@ -0,0 +1,87 @@
+.\"
+.\" Copyright (c) 2010 The FreeBSD Foundation
+.\" All rights reserved.
+.\"
+.\" This software was developed by Semihalf under sponsorship from
+.\" the FreeBSD Foundation.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 12, 2010
+.Dt FDTBUS 4
+.Os
+.Sh NAME
+.Nm fdtbus
+.Nd Flattened Device Tree bus driver
+.Sh SYNOPSIS
+.Cd "options FDT"
+.Sh DESCRIPTION
+The
+.Nm
+abstract bus driver is the primary connection and translation layer between
+.Xr fdt 4
+hardware resources description and
+.Fx
+native newbus device drivers framework. For an embedded system
+.Nm
+represents peripherals typically found on a highly integrated chip
+(system-on-chip).
+.Pp
+The
+.Nm
+driver provides generic, common infrastructure for all
+.Xr fdt 4 oriented device drivers, and its main responsibilities are the
+following:
+.Bl -bullet
+.It
+Creating newbus children that reflect
+.Xr fdt 4
+nodes in the flattened device tree.
+.It
+Managing SYS_RES_IRQ resources.
+.It
+Managing SYS_RES_MEMORY, SYS_RES_IOPORT resources.
+.El
+.Sh SEE ALSO
+.Xr fdt 4 ,
+.Xr openfirm 4 ,
+.Xr simplebus 4 ,
+.Sh STANDARDS
+IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware:
+Core Requirements and Practices
+.Pq Vt Open Firmware .
+.Pp
+Power.org Standard for Embedded Power Architecture Platform Requirements
+.Pq Vt ePAPR .
+.Sh HISTORY
+The
+.Nm
+support first appeared in
+.Fx 9.0 .
+.Sh AUTHORS
+The
+.Nm
+support was developed by Semihalf under sponsorship from the FreeBSD
+Foundation. This manual page was written by
+.An Rafal Jaworowski .

Added: head/share/man/man4/simplebus.4
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man4/simplebus.4	Wed Jul 14 13:03:00 2010	(r210053)
@@ -0,0 +1,81 @@
+.\"
+.\" Copyright (c) 2010 The FreeBSD Foundation
+.\" All rights reserved.
+.\"
+.\" This software was developed by Semihalf under sponsorship from
+.\" the FreeBSD Foundation.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 12, 2010
+.Dt SIMPLEBUS 4
+.Os
+.Sh NAME
+.Nm simplebus
+.Nd ePAPR simple-bus driver
+.Sh SYNOPSIS
+.Cd "options FDT"
+.Sh DESCRIPTION
+This bus driver is dedicated for the
+.Pa simple-bus
+node of a flattened device tree compliant with the
+.Pa ePAPR
+specification.
+.Pp
+The
+.Nm
+entity does not represent any physical element by itself, it is rather an
+umbrella node grouping integrated on-chip peripherals like interrupt
+controller, connectivity controllers, accelerating engines and so on.
+.Pp
+The driver is generic and common for all flattened device tree nodes claiming
+.Pa simple-bus
+compatibility. It iterates over direct descendants of the
+.Pa simple-bus
+node, instantiates newbus children and assigns resources to them, based on the
+configuration data retrieved from the nodes properties in
+.Xr fdt 4 .
+.Pp
+Note the
+.Nm
+does not manage device resources and passes through any requests to the
+.Xr fdtbus 4 layer.
+.Sh SEE ALSO
+.Xr fdt 4 ,
+.Xr fdtbus 4 ,
+.Xr openfirm 4 ,
+.Sh STANDARDS
+Power.org Standard for Embedded Power Architecture Platform Requirements
+.Pq Vt ePAPR .
+.Sh HISTORY
+The
+.Nm
+support first appeared in
+.Fx 9.0 .
+.Sh AUTHORS
+The
+.Nm
+support was developed by Semihalf under sponsorship from the FreeBSD
+Foundation. This manual page was written by
+.An Rafal Jaworowski .

More information about the svn-src-all mailing list