PERFORCE change 204189 for review
Rene Ladan
rene at FreeBSD.org
Sat Jan 7 15:25:44 UTC 2012
http://p4web.freebsd.org/@@204189?ac=10
Change 204189 by rene at rene_acer on 2012/01/07 15:25:18
IFC
Affected files ...
.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/committers-guide/article.sgml#46 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml#119 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/portbuild/article.sgml#44 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.sgml#2 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.sgml#8 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/porters-handbook/book.sgml#121 integrate
.. //depot/projects/docproj_nl/share/misc/docbook.css#7 integrate
.. //depot/projects/docproj_nl/www/en/releases/9.0R/Makefile#2 integrate
.. //depot/projects/docproj_nl/www/en/releases/9.0R/hardware.html#1 branch
.. //depot/projects/docproj_nl/www/en/releases/9.0R/readme.html#1 branch
.. //depot/projects/docproj_nl/www/nl/share/sgml/header.l10n.ent#24 integrate
.. //depot/projects/docproj_nl/www/share/sgml/notices.xml#7 integrate
Differences ...
==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/committers-guide/article.sgml#46 (text+ko) ====
@@ -9,7 +9,7 @@
<corpauthor>The &os; Documentation Project</corpauthor>
- <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v 1.306 2011/11/12 17:57:14 crees Exp $</pubdate>
+ <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v 1.308 2012/01/05 06:35:47 manolis Exp $</pubdate>
<copyright>
<year>1999</year>
@@ -25,6 +25,7 @@
<year>2009</year>
<year>2010</year>
<year>2011</year>
+ <year>2012</year>
<holder>The FreeBSD Documentation Project</holder>
</copyright>
@@ -2638,31 +2639,31 @@
</step>
<step>
- <para>Make whatever changes needed to make the port
- work again. (If it was deleted due to no more distfiles
- being available, you will need to volunteer to become the
- "upstream" maintainer yourself and host the distfiles, or
- find someone else to do so.)</para>
+ <para>Perform whatever changes are necessary to make the port
+ work again. If it was deleted because the distfiles are
+ no longer available you will need to volunteer to host them
+ yourself, or find someone else to do so.</para>
</step>
<step>
- <para>Re-add the port via <command>cvs commit</command>.</para>
+ <para><command>cvs add</command> the updated files.</para>
</step>
<step>
- <para>Re-add the <makevar>SUBDIR</makevar> listing of the port
- in the parent directory <filename>Makefile</filename>.</para>
+ <para>Restore the <makevar>SUBDIR</makevar> listing of the port
+ in the parent directory <filename>Makefile</filename>, and
+ delete the entry from <filename>ports/MOVED</filename>.</para>
</step>
<step>
- <para>Delete the entry from
- <filename>ports/MOVED</filename>.</para>
+ <para>If the port had an entry in
+ <filename>ports/LEGAL</filename>, restore it.</para>
</step>
<step>
- <para>If the port had an entry in
- <filename>ports/LEGAL</filename>, re-add that.</para>
- </step>
+ <para><command>cvs commit</command> these changes, preferably in
+ one step.</para>
+ </step>
</procedure>
</answer>
</qandaentry>
==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml#119 (text+ko) ====
@@ -1,4 +1,4 @@
-<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml,v 1.1047 2011/12/28 07:20:11 bf Exp $ -->
+<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml,v 1.1051 2012/01/07 11:28:15 avl Exp $ -->
<!--
NOTE TO COMMITTERS: Contributors lists are sorted in alphabetical
order by first name.
@@ -3289,6 +3289,11 @@
</listitem>
<listitem>
+ <para>Gasol Wu
+ <email>gasol.wu at gmail.com</email></para>
+ </listitem>
+
+ <listitem>
<para>Gareth McCaughan
<email>gjm11 at dpmms.cam.ac.uk</email></para>
</listitem>
@@ -4147,6 +4152,11 @@
</listitem>
<listitem>
+ <para>Jake Smith
+ <email>jake at xz.cx</email></para>
+ </listitem>
+
+ <listitem>
<para>Jakub Klausa
<email>jacke at bofh.pl</email></para>
</listitem>
@@ -5217,7 +5227,7 @@
<listitem>
<para>Jyun-Yan You
- <email>pcTA at cs.nctu.edu.tw</email></para>
+ <email>jyyou at cs.nctu.edu.tw</email></para>
</listitem>
<listitem>
@@ -6957,6 +6967,11 @@
</listitem>
<listitem>
+ <para>Miks Mikelsons
+ <email>miks at cubesystems.lv</email></para>
+ </listitem>
+
+ <listitem>
<para>Milan Obuch
<email>bsd at dino.sk</email></para>
</listitem>
==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/portbuild/article.sgml#44 (text+ko) ====
@@ -11,7 +11,7 @@
<corpauthor>The &os; Ports Management Team</corpauthor>
</authorgroup>
- <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/portbuild/article.sgml,v 1.84 2011/12/24 21:22:29 linimon Exp $</pubdate>
+ <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/portbuild/article.sgml,v 1.87 2012/01/07 00:15:52 linimon Exp $</pubdate>
<copyright>
<year>2003</year>
@@ -23,6 +23,7 @@
<year>2009</year>
<year>2010</year>
<year>2011</year>
+ <year>2012</year>
<holder role="mailto:portmgr at FreeBSD.org">The &os; Ports
Management Team</holder>
</copyright>
@@ -48,7 +49,7 @@
cluster.</para>
<note>
- <para>Many of the details will be of interest only to
+ <para>Many of the details in this article will be of interest only to
those on the <ulink url="&url.base/portmgr">Ports Management</ulink>
team.</para>
</note>
@@ -74,7 +75,9 @@
<para>The scripts that control all of this live in
<filename class="directory">/var/portbuild/scripts/</filename>.
These are the checked-out copies from the Subversion repository
- <filename class="directory">base/projects/portbuild/scripts/</filename>.</para>
+ <ulink url="http://svnweb.freebsd.org/base/projects/portbuild/scripts/">
+ <filename class="directory">base/projects/portbuild/scripts/</filename>
+ </ulink>.</para>
<para>Typically, incremental builds are done that use previous
packages as dependencies; this takes less time, and puts less
@@ -134,6 +137,15 @@
rock-solid.</para>
</note>
+ <note>
+ <para>Also during this process, the codebase was migrated to the
+ <ulink url="http://svnweb.freebsd.org/base/projects/portbuild/scripts/">
+ Subversion repository</ulink>. For reference, the previous version
+ may still be
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Tools/portbuild/scripts/Attic/">
+ found in CVS</ulink>.</para>
+ </note>
+
</sect2>
</sect1>
@@ -2221,7 +2233,7 @@
with the following changes:</para>
<itemizedlist>
<listitem>
- <para>Delete <replaceable>new-branch</replaceable> from
+ <para>Delete <replaceable>old-branch</replaceable> from
<makevar>SRC_BRANCHES</makevar>.</para>
</listitem>
@@ -2240,6 +2252,40 @@
zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></command></para>
</listitem>
</itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>(both) You will probably find that the following files and
+ symlinks in <filename>/var/portbuild/errorlogs/</filename>
+ can be removed:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Files named
+ <filename>*-<replaceable>old_branch</replaceable>-failure.html</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Files named
+ <filename>buildlogs_*-<replaceable>old_branch</replaceable>-*-logs.txt</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Symlinks named
+ <filename>*-<replaceable>old_branch</replaceable>-previous*</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Symlinks named
+ <filename>*-<replaceable>old_branch</replaceable>-latest*</filename>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
</sect1>
<sect1 id="rebase-branch">
@@ -2477,15 +2523,105 @@
<para>This section is in progress.</para>
+ <para>Please talk to Mark Linimon before making any changes.</para>
+
+ <sect2 id="pointyhat-basics">
+ <title>Basic installation</title>
+
+ <procedure>
+
+ <step>
+ <para>Install FreeBSD.</para>
+ </step>
+
+ <step>
+ <para>For each supported arch, add a
+ <literal>ports-<replaceable>${arch}</replaceable></literal>
+ user and group. Add them to the <literal>wheel</literal>
+ group. They should have the <literal>'*'</literal> password.
+ Also, similarly, create the <literal>ports</literal> and
+ <literal>portmgr</literal> users.</para>
+ </step>
+
+ <step>
+ <para>For each supported arch, create
+ <filename>/home/ports-<replaceable>${arch}/.ssh/</replaceable></filename>
+ and populate <filename>authorized_keys</filename>. </para>
+ </step>
+
+<!-- NOTYET
+ <step>
+ <para>Also add the following users:<screen>
+squid:*:100:100::0:0:User &:/usr/local/squid:/bin/sh
+ganglia:*:102:102::0:0:User &:/usr/local/ganglia:/bin/sh</screen>
+ </para>
+ <para>Add them to <filename>/etc/group</filename> as well.</para>
+ </step>
+-->
+
+ <step>
+ <para>Create the appropriate files in
+ <filename>/etc/.ssh/</filename>.</para>
+ </step>
+
+ <step>
+ <para>Add the following to <filename>/etc/sysctl.conf</filename>:<screen>
+kern.maxfiles=40000</screen>
+ </para>
+ </step>
+
+ <step>
+ <para>TBA</para>
+ </step>
+ </procedure>
+
+ </sect2>
+
+ <sect2 id="pointyhat-disk">
+ <title>Configuring the disk</title>
+
+ <procedure>
+
+ <step>
+ <para>Create a <application>zfs</application> volume named
+ <filename>a</filename> and mount it on
+ <filename>/a</filename>.
+ </para>
+ </step>
+
+ <step>
+ <para>Create a <application>zfs</application> volume named
+ <filename>a/portbuild</filename> and mount it on
+ <filename>/a/portbuild</filename>.
+ </para>
+ </step>
+
+ <step>
+ <para><screen>
+# mkdir -p /a/portbuild
+# cd /a/portbuild
+#
+# chmod 775 .
+
+ln -s ../<replaceable>arch</replaceable>/archive/errorlogs <replaceable>arch</replaceable>-errorlogs</screen>
+ </para>
+ </step>
+
+ <step>
+ <para>TBA</para>
+ </step>
+
+ </procedure>
+
+ </sect2>
+
<sect2 id="pointyhat-src">
<title>Configuring <literal>src</literal></title>
<procedure>
<step>
- <para>Add the following to <filename>etc/sysctl.conf</filename>:<screen>
-kern.maxfiles=40000</screen>
- </para>
+ <para>TBA</para>
</step>
</procedure>
@@ -2534,6 +2670,19 @@
</sect2>
+ <sect2 id="pointyhat-other">
+ <title>Other</title>
+
+ <procedure>
+
+ <step>
+ <para>TBA</para>
+ </step>
+
+ </procedure>
+
+ </sect2>
+
</sect1>
<sect1 id="disk-failure">
==== //depot/projects/docproj_nl/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.sgml#2 (text+ko) ====
@@ -1,99 +1,110 @@
<!--
The FreeBSD Documentation Project
- $FreeBSD: doc/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.sgml,v 1.10 2006/08/28 18:59:15 blackend Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.sgml,v 1.11 2012/01/07 13:43:22 wblock Exp $
Originally by: Jeroen Ruigrok van der Warven
Date: newbus-draft.txt,v 1.8 2001/01/25 08:01:08
Copyright (c) 2000 Jeroen Ruigrok van der Warven (asmodai at wxs.nl)
Copyright (c) 2002 Hiten Mahesh Pandya (hiten at uk.FreeBSD.org)
-
+
Future Additions:
-
+
o Expand the information about device_t
o Add information about the bus_* functions.
o Add information about bus specific (e.g. PCI) functions.
o Add a reference section for additional information.
o Add more newbus related structures and typedefs.
o Add a 'Terminology' section.
- o Add information on resource manager functions, busspace
+ o Add information on resource manager functions, busspace
manager functions, newbus events related functions.
o More cleanup ... !
-
+
Provided under the FreeBSD Documentation License.
-->
<chapter id="newbus">
<chapterinfo>
<authorgroup>
<author>
- <firstname>Jeroen</firstname>
- <surname>Ruigrok van der Werven (asmodai)</surname>
- <affiliation><address><email>asmodai at FreeBSD.org</email></address>
- </affiliation>
- <contrib>Written by </contrib>
+ <firstname>Jeroen</firstname>
+ <surname>Ruigrok van der Werven (asmodai)</surname>
+ <affiliation>
+ <address><email>asmodai at FreeBSD.org</email></address>
+ </affiliation>
+ <contrib>Written by </contrib>
</author>
<author>
- <firstname>Hiten</firstname>
+ <firstname>Hiten</firstname>
<surname>Pandya</surname>
- <affiliation><address><email>hiten at uk.FreeBSD.org</email></address>
+ <affiliation>
+ <address><email>hiten at uk.FreeBSD.org</email></address>
</affiliation>
</author>
</authorgroup>
</chapterinfo>
<title>Newbus</title>
- <para><emphasis>Special thanks to Matthew N. Dodd, Warner Losh, Bill Paul,
- Doug Rabson, Mike Smith, Peter Wemm and Scott Long</emphasis>.</para>
+ <para><emphasis>Special thanks to Matthew N. Dodd, Warner Losh, Bill
+ Paul, Doug Rabson, Mike Smith, Peter Wemm and Scott
+ Long</emphasis>.</para>
+
+ <para>This chapter explains the Newbus device framework in
+ detail.</para>
- <para>This chapter explains the Newbus device framework in detail.</para>
<sect1 id="newbus-devdrivers">
<title>Device Drivers</title>
+
<sect2>
<title>Purpose of a Device Driver</title>
<indexterm><primary>device driver</primary></indexterm>
- <indexterm><primary>device driver</primary><secondary>introduction</secondary></indexterm>
- <para>A device driver is a software component which provides the
- interface between the kernel's generic view of a peripheral
- (e.g. disk, network adapter) and the actual implementation of the
- peripheral. The <emphasis>device driver interface (DDI)</emphasis> is
- the defined interface between the kernel and the device driver component.
- </para>
+
+ <indexterm><primary>device
+ driver</primary><secondary>introduction</secondary></indexterm>
+
+ <para>A device driver is a software component which provides the
+ interface between the kernel's generic view of a peripheral
+ (e.g. disk, network adapter) and the actual implementation of
+ the peripheral. The <emphasis>device driver interface
+ (DDI)</emphasis> is the defined interface between the kernel
+ and the device driver component.</para>
</sect2>
-
+
<sect2>
<title>Types of Device Drivers</title>
- <para>There used to be days in &unix;, and thus FreeBSD, in which there
- were four types of devices defined:</para>
-
+
+ <para>There used to be days in &unix;, and thus FreeBSD, in
+ which there were four types of devices defined:</para>
+
<itemizedlist>
- <listitem><para>block device drivers</para></listitem>
- <listitem><para>character device drivers</para></listitem>
- <listitem><para>network device drivers</para></listitem>
- <listitem><para>pseudo-device drivers</para></listitem>
+ <listitem><para>block device drivers</para></listitem>
+ <listitem><para>character device drivers</para></listitem>
+ <listitem><para>network device drivers</para></listitem>
+ <listitem><para>pseudo-device drivers</para></listitem>
</itemizedlist>
-
+
<indexterm><primary>block devices</primary></indexterm>
- <para><emphasis>Block devices</emphasis> performed in way that used
- fixed size blocks [of data]. This type of driver depended on the
- so called <emphasis>buffer cache</emphasis>, which had the purpose
- to cache accessed blocks of data in a dedicated part of the memory.
- Often this buffer cache was based on write-behind, which meant that when
- data was modified in memory it got synced to disk whenever the system
- did its periodical disk flushing, thus optimizing writes.</para>
+ <para><emphasis>Block devices</emphasis> performed in way that
+ used fixed size blocks [of data]. This type of driver
+ depended on the so called <emphasis>buffer cache</emphasis>,
+ which had the purpose to cache accessed blocks of data in a
+ dedicated part of the memory. Often this buffer cache was
+ based on write-behind, which meant that when data was modified
+ in memory it got synced to disk whenever the system did its
+ periodical disk flushing, thus optimizing writes.</para>
</sect2>
-
+
<sect2>
<title>Character devices</title>
<indexterm><primary>character devices</primary></indexterm>
<para>However, in the versions of FreeBSD 4.0 and onward the
- distinction between block and character devices became non-existent.
- </para>
+ distinction between block and character devices became
+ non-existent.</para>
</sect2>
</sect1>
-
+
<sect1 id="newbus-overview">
<!--
Real title:
@@ -101,118 +112,133 @@
-->
<title>Overview of Newbus</title>
- <indexterm><primary>Newbus</primary></indexterm>
+ <indexterm><primary>Newbus</primary></indexterm>
+
+ <para><emphasis>Newbus</emphasis> is the implementation of a new
+ bus architecture based on abstraction layers which saw its
+ introduction in FreeBSD 3.0 when the Alpha port was imported
+ into the source tree. It was not until 4.0 before it became the
+ default system to use for device drivers. Its goals are to
+ provide a more object oriented means of interconnecting the
+ various busses and devices which a host system provides to the
+ <emphasis>Operating System</emphasis>.</para>
- <para><emphasis>Newbus</emphasis> is the implementation of a new bus
- architecture based on abstraction layers which saw its introduction in
- FreeBSD 3.0 when the Alpha port was imported into the source tree. It was
- not until 4.0 before it became the default system to use for device
- drivers. Its goals are to provide a more object oriented means of
- interconnecting the various busses and devices which a host system
- provides to the <emphasis>Operating System</emphasis>.</para>
-
<para>Its main features include amongst others:</para>
-
+
<itemizedlist>
<listitem><para>dynamic attaching</para></listitem>
<listitem><para>easy modularization of drivers</para></listitem>
<listitem><para>pseudo-busses</para></listitem>
</itemizedlist>
-
- <para>One of the most prominent changes is the migration from the flat and
- ad-hoc system to a device tree lay-out.</para>
-
- <para>At the top level resides the <emphasis><quote>root</quote></emphasis>
- device which is the parent to hang all other devices on. For each
- architecture, there is typically a single child of <quote>root</quote>
- which has such things as <emphasis>host-to-PCI bridges</emphasis>, etc.
- attached to it. For x86, this <quote>root</quote> device is the
- <emphasis><quote>nexus</quote></emphasis> device and for Alpha, various
- different different models of Alpha have different top-level devices
- corresponding to the different hardware chipsets, including
- <emphasis>lca</emphasis>, <emphasis>apecs</emphasis>,
- <emphasis>cia</emphasis> and <emphasis>tsunami</emphasis>.</para>
-
- <para>A device in the Newbus context represents a single hardware entity
- in the system. For instance each PCI device is represented by a Newbus
- device. Any device in the system can have children; a device which has
- children is often called a <emphasis><quote>bus</quote></emphasis>.
- Examples of common busses in the system are ISA and PCI which manage lists
- of devices attached to ISA and PCI busses respectively.</para>
-
- <para>Often, a connection between different kinds of bus is represented by
- a <emphasis><quote>bridge</quote></emphasis> device which normally has one
- child for the attached bus. An example of this is a
- <emphasis>PCI-to-PCI bridge</emphasis> which is represented by a device
- <emphasis><devicename>pcibN</devicename></emphasis> on the parent PCI bus
- and has a child <emphasis><devicename>pciN</devicename></emphasis> for the
- attached bus. This layout simplifies the implementation of the PCI bus
- tree, allowing common code to be used for both top-level and bridged
- busses.</para>
-
- <para>Each device in the Newbus architecture asks its parent to map its
- resources. The parent then asks its own parent until the nexus is
- reached. So, basically the nexus is the only part of the Newbus system
- which knows about all resources.</para>
-
- <tip><para>An ISA device might want to map its IO port at
- <literal>0x230</literal>, so it asks its parent, in this case the ISA
- bus. The ISA bus hands it over to the PCI-to-ISA bridge which in its turn
- asks the PCI bus, which reaches the host-to-PCI bridge and finally the
- nexus. The beauty of this transition upwards is that there is room to
- translate the requests. For example, the <literal>0x230</literal> IO port
- request might become memory-mapped at <literal>0xb0000230</literal> on a
- <acronym>MIPS</acronym> box by the PCI bridge.</para></tip>
-
- <para>Resource allocation can be controlled at any place in the device
- tree. For instance on many Alpha platforms, ISA interrupts are managed
- separately from PCI interrupts and resource allocations for ISA interrupts
- are managed by the Alpha's ISA bus device. On IA-32, ISA and PCI
- interrupts are both managed by the top-level nexus device. For both
- ports, memory and port address space is managed by a single entity - nexus
- for IA-32 and the relevant chipset driver on Alpha (e.g. CIA or tsunami).
- </para>
-
- <para>In order to normalize access to memory and port mapped resources,
- Newbus integrates the <literal>bus_space</literal> APIs from NetBSD.
- These provide a single API to replace inb/outb and direct memory
- reads/writes. The advantage of this is that a single driver can easily
- use either memory-mapped registers or port-mapped registers
- (some hardware supports both).</para>
-
- <para>This support is integrated into the resource allocation mechanism.
- When a resource is allocated, a driver can retrieve the associated
- <structfield>bus_space_tag_t</structfield> and
- <structfield>bus_space_handle_t</structfield> from the resource.</para>
-
- <para>Newbus also allows for definitions of interface methods in files
- dedicated to this purpose. These are the <filename>.m</filename> files
- that are found under the <filename>src/sys</filename> hierarchy.</para>
-
- <para>The core of the Newbus system is an extensible
- <quote>object-based programming</quote> model. Each device in the system
- has a table of methods which it supports. The system and other devices
- uses those methods to control the device and request services. The
- different methods supported by a device are defined by a number of
- <quote>interfaces</quote>. An <quote>interface</quote> is simply a group
- of related methods which can be implemented by a device.</para>
-
- <para>In the Newbus system, the methods for a device are provided by the
- various device drivers in the system. When a device is attached to a
- driver during <emphasis>auto-configuration</emphasis>, it uses the method
- table declared by the driver. A device can later
- <emphasis>detach</emphasis> from its driver and
- <emphasis>re-attach</emphasis> to a new driver with a new method table.
- This allows dynamic replacement of drivers which can be useful for driver
- development.</para>
-
- <para>The interfaces are described by an interface definition language
- similar to the language used to define vnode operations for file systems.
- The interface would be stored in a methods file (which would normally named
- <filename>foo_if.m</filename>).</para>
-
+
+ <para>One of the most prominent changes is the migration from the
+ flat and ad-hoc system to a device tree lay-out.</para>
+
+ <para>At the top level resides the
+ <emphasis><quote>root</quote></emphasis> device which is the
+ parent to hang all other devices on. For each architecture,
+ there is typically a single child of <quote>root</quote> which
+ has such things as <emphasis>host-to-PCI bridges</emphasis>,
+ etc. attached to it. For x86, this <quote>root</quote> device
+ is the <emphasis><quote>nexus</quote></emphasis> device and for
+ Alpha, various different different models of Alpha have
+ different top-level devices corresponding to the different
+ hardware chipsets, including <emphasis>lca</emphasis>,
+ <emphasis>apecs</emphasis>, <emphasis>cia</emphasis> and
+ <emphasis>tsunami</emphasis>.</para>
+
+ <para>A device in the Newbus context represents a single hardware
+ entity in the system. For instance each PCI device is
+ represented by a Newbus device. Any device in the system can
+ have children; a device which has children is often called a
+ <emphasis><quote>bus</quote></emphasis>. Examples of common
+ busses in the system are ISA and PCI which manage lists of
+ devices attached to ISA and PCI busses respectively.</para>
+
+ <para>Often, a connection between different kinds of bus is
+ represented by a <emphasis><quote>bridge</quote></emphasis>
+ device which normally has one child for the attached bus. An
+ example of this is a <emphasis>PCI-to-PCI bridge</emphasis>
+ which is represented by a device
+ <emphasis><devicename>pcibN</devicename></emphasis> on the
+ parent PCI bus and has a child
+ <emphasis><devicename>pciN</devicename></emphasis> for the
+ attached bus. This layout simplifies the implementation of the
+ PCI bus tree, allowing common code to be used for both top-level
+ and bridged busses.</para>
+
+ <para>Each device in the Newbus architecture asks its parent to
+ map its resources. The parent then asks its own parent until
+ the nexus is reached. So, basically the nexus is the only part
+ of the Newbus system which knows about all resources.</para>
+
+ <tip><para>An ISA device might want to map its IO port at
+ <literal>0x230</literal>, so it asks its parent, in this case
+ the ISA bus. The ISA bus hands it over to the PCI-to-ISA bridge
+ which in its turn asks the PCI bus, which reaches the
+ host-to-PCI bridge and finally the nexus. The beauty of this
+ transition upwards is that there is room to translate the
+ requests. For example, the <literal>0x230</literal> IO port
+ request might become memory-mapped at
+ <literal>0xb0000230</literal> on a <acronym>MIPS</acronym> box
+ by the PCI bridge.</para></tip>
+
+ <para>Resource allocation can be controlled at any place in the
+ device tree. For instance on many Alpha platforms, ISA
+ interrupts are managed separately from PCI interrupts and
+ resource allocations for ISA interrupts are managed by the
+ Alpha's ISA bus device. On IA-32, ISA and PCI interrupts are
+ both managed by the top-level nexus device. For both ports,
+ memory and port address space is managed by a single entity -
+ nexus for IA-32 and the relevant chipset driver on Alpha (e.g.
+ CIA or tsunami).</para>
+
+ <para>In order to normalize access to memory and port mapped
+ resources, Newbus integrates the <literal>bus_space</literal>
+ APIs from NetBSD. These provide a single API to replace inb/outb
+ and direct memory reads/writes. The advantage of this is that a
+ single driver can easily use either memory-mapped registers or
+ port-mapped registers (some hardware supports both).</para>
+
+ <para>This support is integrated into the resource allocation
+ mechanism. When a resource is allocated, a driver can retrieve
+ the associated <structfield>bus_space_tag_t</structfield> and
+ <structfield>bus_space_handle_t</structfield> from the
+ resource.</para>
+
+ <para>Newbus also allows for definitions of interface methods in
+ files dedicated to this purpose. These are the
+ <filename>.m</filename> files that are found under the
+ <filename>src/sys</filename> hierarchy.</para>
+
+ <para>The core of the Newbus system is an extensible
+ <quote>object-based programming</quote> model. Each device in
+ the system has a table of methods which it supports. The system
+ and other devices uses those methods to control the device and
+ request services. The different methods supported by a device
+ are defined by a number of <quote>interfaces</quote>. An
+ <quote>interface</quote> is simply a group of related methods
+ which can be implemented by a device.</para>
+
+ <para>In the Newbus system, the methods for a device are provided
+ by the various device drivers in the system. When a device is
+ attached to a driver during
+ <emphasis>auto-configuration</emphasis>, it uses the method
+ table declared by the driver. A device can later
+ <emphasis>detach</emphasis> from its driver and
+ <emphasis>re-attach</emphasis> to a new driver with a new method
+ table. This allows dynamic replacement of drivers which can be
+ useful for driver development.</para>
+
+ <para>The interfaces are described by an interface definition
+ language similar to the language used to define vnode operations
+ for file systems. The interface would be stored in a methods
+ file (which would normally named
+ <filename>foo_if.m</filename>).</para>
+
<example>
<title>Newbus Methods</title>
+
<programlisting>
# Foo subsystem/driver (a comment...)
@@ -231,114 +257,125 @@
} DEFAULT doit_generic_to_child;
</programlisting>
</example>
-
- <para>When this interface is compiled, it generates a header file
- <quote><filename>foo_if.h</filename></quote> which contains function
- declarations:</para>
-
+
+ <para>When this interface is compiled, it generates a header file
+ <quote><filename>foo_if.h</filename></quote> which contains
+ function declarations:</para>
+
<programlisting>
int FOO_DOIT(device_t dev);
int FOO_DOIT_TO_CHILD(device_t dev, device_t child);
</programlisting>
-
- <para>A source file, <quote><filename>foo_if.c</filename></quote> is
- also created to accompany the automatically generated header file; it
- contains implementations of those functions which look up the location
- of the relevant functions in the object's method table and call that
- function.</para>
-
- <para>The system defines two main interfaces. The first fundamental
- interface is called <emphasis><quote>device</quote></emphasis> and
- includes methods which are relevant to all devices. Methods in the
- <emphasis><quote>device</quote></emphasis> interface include
- <emphasis><quote>probe</quote></emphasis>,
- <emphasis><quote>attach</quote></emphasis> and
- <emphasis><quote>detach</quote></emphasis> to control detection of
- hardware and <emphasis><quote>shutdown</quote></emphasis>,
- <emphasis><quote>suspend</quote></emphasis> and
- <emphasis><quote>resume</quote></emphasis> for critical event
- notification.</para>
-
- <para>The second, more complex interface is
- <emphasis><quote>bus</quote></emphasis>. This interface contains
- methods suitable for devices which have children, including methods to
- access bus specific per-device information
- <footnote><para>&man.bus.generic.read.ivar.9; and
- &man.bus.generic.write.ivar.9;</para></footnote>, event notification
- (<emphasis><literal>child_detached</literal></emphasis>,
- <emphasis><literal>driver_added</literal></emphasis>) and resource
- management (<emphasis><literal>alloc_resource</literal></emphasis>,
- <emphasis><literal>activate_resource</literal></emphasis>,
- <emphasis><literal>deactivate_resource</literal></emphasis>,
- <emphasis><literal>release_resource</literal></emphasis>).</para>
-
- <para>Many methods in the <quote>bus</quote> interface are performing
- services for some child of the bus device. These methods would normally
- use the first two arguments to specify the bus providing the service
- and the child device which is requesting the service. To simplify
- driver code, many of these methods have accessor functions which
- lookup the parent and call a method on the parent. For instance the
- method
- <literal>BUS_TEARDOWN_INTR(device_t dev, device_t child, ...)</literal>
- can be called using the function
- <literal>bus_teardown_intr(device_t child, ...)</literal>.</para>
-
- <para>Some bus types in the system define additional interfaces to
- provide access to bus-specific functionality. For instance, the PCI
- bus driver defines the <quote>pci</quote> interface which has two
- methods <emphasis><literal>read_config</literal></emphasis> and
- <emphasis><literal>write_config</literal></emphasis> for accessing the
- configuration registers of a PCI device.</para>
+
+ <para>A source file, <quote><filename>foo_if.c</filename></quote>
+ is also created to accompany the automatically generated header
+ file; it contains implementations of those functions which look
+ up the location of the relevant functions in the object's method
+ table and call that function.</para>
+
+ <para>The system defines two main interfaces. The first
+ fundamental interface is called
+ <emphasis><quote>device</quote></emphasis> and includes methods
+ which are relevant to all devices. Methods in the
+ <emphasis><quote>device</quote></emphasis> interface include
+ <emphasis><quote>probe</quote></emphasis>,
+ <emphasis><quote>attach</quote></emphasis> and
+ <emphasis><quote>detach</quote></emphasis> to control detection
+ of hardware and <emphasis><quote>shutdown</quote></emphasis>,
+ <emphasis><quote>suspend</quote></emphasis> and
+ <emphasis><quote>resume</quote></emphasis> for critical event
+ notification.</para>
+
+ <para>The second, more complex interface is
+ <emphasis><quote>bus</quote></emphasis>. This interface
+ contains methods suitable for devices which have children,
+ including methods to access bus specific per-device information
+ <footnote><para>&man.bus.generic.read.ivar.9; and
+ &man.bus.generic.write.ivar.9;</para></footnote>, event
+ notification
+ (<emphasis><literal>child_detached</literal></emphasis>,
+ <emphasis><literal>driver_added</literal></emphasis>) and
+ resource management
+ (<emphasis><literal>alloc_resource</literal></emphasis>,
+ <emphasis><literal>activate_resource</literal></emphasis>,
+ <emphasis><literal>deactivate_resource</literal></emphasis>,
+ <emphasis><literal>release_resource</literal></emphasis>).</para>
+
+ <para>Many methods in the <quote>bus</quote> interface are
+ performing services for some child of the bus device. These
+ methods would normally use the first two arguments to specify
+ the bus providing the service and the child device which is
+ requesting the service. To simplify driver code, many of these
+ methods have accessor functions which lookup the parent and call
+ a method on the parent. For instance the method
+ <literal>BUS_TEARDOWN_INTR(device_t dev, device_t child,
+ ...)</literal> can be called using the function
+ <literal>bus_teardown_intr(device_t child,
+ ...)</literal>.</para>
+
+ <para>Some bus types in the system define additional interfaces to
+ provide access to bus-specific functionality. For instance, the
+ PCI bus driver defines the <quote>pci</quote> interface which
+ has two methods
+ <emphasis><literal>read_config</literal></emphasis> and
+ <emphasis><literal>write_config</literal></emphasis> for
+ accessing the configuration registers of a PCI device.</para>
</sect1>
-
+
<sect1 id="newbus-api">
<title>Newbus API</title>
+
<para>As the Newbus API is huge, this section makes some effort at
- documenting it. More information to come in the next revision of this
- document.</para>
-
+ documenting it. More information to come in the next revision
+ of this document.</para>
+
<sect2>
<title>Important locations in the source hierarchy</title>
-
- <para><filename>src/sys/[arch]/[arch]</filename> - Kernel code for a
- specific machine architecture resides in this directory. For example,
- the <literal>i386</literal> architecture, or the
- <literal>SPARC64</literal> architecture.</para>
-
- <para><filename>src/sys/dev/[bus]</filename> - device support for a
- specific <literal>[bus]</literal> resides in this directory.</para>
-
- <para><filename>src/sys/dev/pci</filename> - PCI bus support code
- resides in this directory.</para>
-
- <para><filename>src/sys/[isa|pci]</filename> - PCI/ISA device drivers
- reside in this directory. The PCI/ISA bus support code used to exist
- in this directory in FreeBSD version <literal>4.0</literal>.</para>
+
+ <para><filename>src/sys/[arch]/[arch]</filename> - Kernel code
+ for a specific machine architecture resides in this directory.
+ For example, the <literal>i386</literal> architecture, or the
+ <literal>SPARC64</literal> architecture.</para>
+
+ <para><filename>src/sys/dev/[bus]</filename> - device support
+ for a specific <literal>[bus]</literal> resides in this
+ directory.</para>
+
+ <para><filename>src/sys/dev/pci</filename> - PCI bus support
+ code resides in this directory.</para>
+
+ <para><filename>src/sys/[isa|pci]</filename> - PCI/ISA device
+ drivers reside in this directory. The PCI/ISA bus support
+ code used to exist in this directory in FreeBSD version
+ <literal>4.0</literal>.</para>
</sect2>
-
+
<sect2>
<title>Important structures and type definitions</title>
- <para><literal>devclass_t</literal> - This is a type definition of a
- pointer to a <literal>struct devclass</literal>.</para>
-
- <para><literal>device_method_t</literal> - This is same as
- <literal>kobj_method_t</literal> (see
- <filename>src/sys/kobj.h</filename>).</para>
-
- <para><literal>device_t</literal> - This is a type definition of a
- pointer to a <literal>struct device</literal>.
- <literal>device_t</literal> represents a device in the system. It is
- a kernel object. See <filename>src/sys/sys/bus_private.h</filename>
- for implementation details.</para>
-
- <para><literal>driver_t</literal> - This is a type definition which,
- references <literal>struct driver</literal>. The
- <literal>driver</literal> struct is a class of the
- <literal>device</literal> kernel object; it also holds data private
- to for the driver.</para>
-
+
+ <para><literal>devclass_t</literal> - This is a type definition
+ of a pointer to a <literal>struct devclass</literal>.</para>
+
+ <para><literal>device_method_t</literal> - This is same as
+ <literal>kobj_method_t</literal> (see
+ <filename>src/sys/kobj.h</filename>).</para>
+
+ <para><literal>device_t</literal> - This is a type definition of
+ a pointer to a <literal>struct device</literal>.
+ <literal>device_t</literal> represents a device in the system.
+ It is a kernel object. See
+ <filename>src/sys/sys/bus_private.h</filename> for
+ implementation details.</para>
+
+ <para><literal>driver_t</literal> - This is a type definition
+ which, references <literal>struct driver</literal>. The
+ <literal>driver</literal> struct is a class of the
+ <literal>device</literal> kernel object; it also holds data
+ private to for the driver.</para>
+
<figure>
- <title><emphasis>driver_t</emphasis> implementation</title>
+ <title><emphasis>driver_t</emphasis> implementation</title>
+
<programlisting>
struct driver {
KOBJ_CLASS_FIELDS;
@@ -346,14 +383,16 @@
};
</programlisting>
</figure>
-
+
<para>A <literal>device_state_t</literal> type, which is
- an enumeration, <literal>device_state</literal>. It contains
- the possible states of a Newbus device before and after the
- autoconfiguration process.</para>
-
+ an enumeration, <literal>device_state</literal>. It contains
+ the possible states of a Newbus device before and after the
>>> TRUNCATED FOR MAIL (1000 lines) <<<
More information about the p4-projects
mailing list