From owner-svn-src-all@FreeBSD.ORG Wed Jul 14 13:03:00 2010 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id A77091065670; Wed, 14 Jul 2010 13:03:00 +0000 (UTC) (envelope-from raj@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 955468FC14; Wed, 14 Jul 2010 13:03:00 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id o6ED30Bn072421; Wed, 14 Jul 2010 13:03:00 GMT (envelope-from raj@svn.freebsd.org) Received: (from raj@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id o6ED30ur072416; Wed, 14 Jul 2010 13:03:00 GMT (envelope-from raj@svn.freebsd.org) Message-Id: <201007141303.o6ED30ur072416@svn.freebsd.org> From: Rafal Jaworowski Date: Wed, 14 Jul 2010 13:03:00 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r210053 - head/share/man/man4 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 14 Jul 2010 13:03:00 -0000 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=.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=.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 .