os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only changes to fix indentation, remove trailing whitespace,

Browse source 
and wrap long lines.  Translators: none of these changes affect content,
and can be ignored for translation purposes.

Approved by:	gjb (mentor)
This commit is contained in:
Warren Block 2012-01-07 13:43:22 +00:00
parent f232f53d9b
commit 3cb17c52b0
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=38148
1 changed files with 283 additions and 244 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

357
en_US.ISO8859-1/books/arch-handbook/newbus/chapter.sgml
View file

@ -27,43 +27,53 @@
<author> <author>
<firstname>Jeroen</firstname> <firstname>Jeroen</firstname>
<surname>Ruigrok van der Werven (asmodai)</surname> <surname>Ruigrok van der Werven (asmodai)</surname>
<affiliation><address><email>asmodai@FreeBSD.org</email></address> <affiliation>
<address><email>asmodai@FreeBSD.org</email></address>
</affiliation> </affiliation>
<contrib>Written by </contrib> <contrib>Written by </contrib>
</author> </author>
<author> <author>
<firstname>Hiten</firstname> <firstname>Hiten</firstname>
<surname>Pandya</surname> <surname>Pandya</surname>
<affiliation><address><email>hiten@uk.FreeBSD.org</email></address> <affiliation>
<address><email>hiten@uk.FreeBSD.org</email></address>
</affiliation> </affiliation>
</author> </author>
</authorgroup> </authorgroup>
</chapterinfo> </chapterinfo>
<title>Newbus</title> <title>Newbus</title>
<para><emphasis>Special thanks to Matthew N. Dodd, Warner Losh, Bill Paul, <para><emphasis>Special thanks to Matthew N. Dodd, Warner Losh, Bill
Doug Rabson, Mike Smith, Peter Wemm and Scott Long</emphasis>.</para> 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"> <sect1 id="newbus-devdrivers">
<title>Device Drivers</title> <title>Device Drivers</title>
<sect2> <sect2>
<title>Purpose of a Device Driver</title> <title>Purpose of a Device Driver</title>
<indexterm><primary>device driver</primary></indexterm> <indexterm><primary>device driver</primary></indexterm>
<indexterm><primary>device driver</primary><secondary>introduction</secondary></indexterm>
<indexterm><primary>device
driver</primary><secondary>introduction</secondary></indexterm>
<para>A device driver is a software component which provides the <para>A device driver is a software component which provides the
interface between the kernel's generic view of a peripheral interface between the kernel's generic view of a peripheral
(e.g. disk, network adapter) and the actual implementation of the (e.g. disk, network adapter) and the actual implementation of
peripheral. The <emphasis>device driver interface (DDI)</emphasis> is the peripheral. The <emphasis>device driver interface
the defined interface between the kernel and the device driver component. (DDI)</emphasis> is the defined interface between the kernel
</para> and the device driver component.</para>
</sect2> </sect2>
<sect2> <sect2>
<title>Types of Device Drivers</title> <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> <itemizedlist>
<listitem><para>block device drivers</para></listitem> <listitem><para>block device drivers</para></listitem>
@ -74,13 +84,14 @@
<indexterm><primary>block devices</primary></indexterm> <indexterm><primary>block devices</primary></indexterm>
<para><emphasis>Block devices</emphasis> performed in way that used <para><emphasis>Block devices</emphasis> performed in way that
fixed size blocks [of data]. This type of driver depended on the used fixed size blocks [of data]. This type of driver
so called <emphasis>buffer cache</emphasis>, which had the purpose depended on the so called <emphasis>buffer cache</emphasis>,
to cache accessed blocks of data in a dedicated part of the memory. which had the purpose to cache accessed blocks of data in a
Often this buffer cache was based on write-behind, which meant that when dedicated part of the memory. Often this buffer cache was
data was modified in memory it got synced to disk whenever the system based on write-behind, which meant that when data was modified
did its periodical disk flushing, thus optimizing writes.</para> in memory it got synced to disk whenever the system did its
periodical disk flushing, thus optimizing writes.</para>
</sect2> </sect2>
<sect2> <sect2>
@ -89,8 +100,8 @@
<indexterm><primary>character devices</primary></indexterm> <indexterm><primary>character devices</primary></indexterm>
<para>However, in the versions of FreeBSD 4.0 and onward the <para>However, in the versions of FreeBSD 4.0 and onward the
distinction between block and character devices became non-existent. distinction between block and character devices became
</para> non-existent.</para>
</sect2> </sect2>
</sect1> </sect1>
@ -103,13 +114,14 @@
<indexterm><primary>Newbus</primary></indexterm> <indexterm><primary>Newbus</primary></indexterm>
<para><emphasis>Newbus</emphasis> is the implementation of a new bus <para><emphasis>Newbus</emphasis> is the implementation of a new
architecture based on abstraction layers which saw its introduction in bus architecture based on abstraction layers which saw its
FreeBSD 3.0 when the Alpha port was imported into the source tree. It was introduction in FreeBSD 3.0 when the Alpha port was imported
not until 4.0 before it became the default system to use for device into the source tree. It was not until 4.0 before it became the
drivers. Its goals are to provide a more object oriented means of default system to use for device drivers. Its goals are to
interconnecting the various busses and devices which a host system provide a more object oriented means of interconnecting the
provides to the <emphasis>Operating System</emphasis>.</para> various busses and devices which a host system provides to the
<emphasis>Operating System</emphasis>.</para>
<para>Its main features include amongst others:</para> <para>Its main features include amongst others:</para>
@ -119,100 +131,114 @@
<listitem><para>pseudo-busses</para></listitem> <listitem><para>pseudo-busses</para></listitem>
</itemizedlist> </itemizedlist>
<para>One of the most prominent changes is the migration from the flat and <para>One of the most prominent changes is the migration from the
ad-hoc system to a device tree lay-out.</para> flat and ad-hoc system to a device tree lay-out.</para>
<para>At the top level resides the <emphasis><quote>root</quote></emphasis> <para>At the top level resides the
device which is the parent to hang all other devices on. For each <emphasis><quote>root</quote></emphasis> device which is the
architecture, there is typically a single child of <quote>root</quote> parent to hang all other devices on. For each architecture,
which has such things as <emphasis>host-to-PCI bridges</emphasis>, etc. there is typically a single child of <quote>root</quote> which
attached to it. For x86, this <quote>root</quote> device is the has such things as <emphasis>host-to-PCI bridges</emphasis>,
<emphasis><quote>nexus</quote></emphasis> device and for Alpha, various etc. attached to it. For x86, this <quote>root</quote> device
different different models of Alpha have different top-level devices is the <emphasis><quote>nexus</quote></emphasis> device and for
corresponding to the different hardware chipsets, including Alpha, various different different models of Alpha have
<emphasis>lca</emphasis>, <emphasis>apecs</emphasis>, different top-level devices corresponding to the different
<emphasis>cia</emphasis> and <emphasis>tsunami</emphasis>.</para> 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 <para>A device in the Newbus context represents a single hardware
in the system. For instance each PCI device is represented by a Newbus entity in the system. For instance each PCI device is
device. Any device in the system can have children; a device which has represented by a Newbus device. Any device in the system can
children is often called a <emphasis><quote>bus</quote></emphasis>. have children; a device which has children is often called a
Examples of common busses in the system are ISA and PCI which manage lists <emphasis><quote>bus</quote></emphasis>. Examples of common
of devices attached to ISA and PCI busses respectively.</para> 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 <para>Often, a connection between different kinds of bus is
a <emphasis><quote>bridge</quote></emphasis> device which normally has one represented by a <emphasis><quote>bridge</quote></emphasis>
child for the attached bus. An example of this is a device which normally has one child for the attached bus. An
<emphasis>PCI-to-PCI bridge</emphasis> which is represented by a device example of this is a <emphasis>PCI-to-PCI bridge</emphasis>
<emphasis><devicename>pcibN</devicename></emphasis> on the parent PCI bus which is represented by a device
and has a child <emphasis><devicename>pciN</devicename></emphasis> for the <emphasis><devicename>pcibN</devicename></emphasis> on the
attached bus. This layout simplifies the implementation of the PCI bus parent PCI bus and has a child
tree, allowing common code to be used for both top-level and bridged <emphasis><devicename>pciN</devicename></emphasis> for the
busses.</para> 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 <para>Each device in the Newbus architecture asks its parent to
resources. The parent then asks its own parent until the nexus is map its resources. The parent then asks its own parent until
reached. So, basically the nexus is the only part of the Newbus system the nexus is reached. So, basically the nexus is the only part
which knows about all resources.</para> of the Newbus system which knows about all resources.</para>
<tip><para>An ISA device might want to map its IO port at <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 <literal>0x230</literal>, so it asks its parent, in this case
bus. The ISA bus hands it over to the PCI-to-ISA bridge which in its turn the ISA bus. The ISA bus hands it over to the PCI-to-ISA bridge
asks the PCI bus, which reaches the host-to-PCI bridge and finally the which in its turn asks the PCI bus, which reaches the
nexus. The beauty of this transition upwards is that there is room to host-to-PCI bridge and finally the nexus. The beauty of this
translate the requests. For example, the <literal>0x230</literal> IO port transition upwards is that there is room to translate the
request might become memory-mapped at <literal>0xb0000230</literal> on a requests. For example, the <literal>0x230</literal> IO port
<acronym>MIPS</acronym> box by the PCI bridge.</para></tip> 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 <para>Resource allocation can be controlled at any place in the
tree. For instance on many Alpha platforms, ISA interrupts are managed device tree. For instance on many Alpha platforms, ISA
separately from PCI interrupts and resource allocations for ISA interrupts interrupts are managed separately from PCI interrupts and
are managed by the Alpha's ISA bus device. On IA-32, ISA and PCI resource allocations for ISA interrupts are managed by the
interrupts are both managed by the top-level nexus device. For both Alpha's ISA bus device. On IA-32, ISA and PCI interrupts are
ports, memory and port address space is managed by a single entity - nexus both managed by the top-level nexus device. For both ports,
for IA-32 and the relevant chipset driver on Alpha (e.g. CIA or tsunami). memory and port address space is managed by a single entity -
</para> 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, <para>In order to normalize access to memory and port mapped
Newbus integrates the <literal>bus_space</literal> APIs from NetBSD. resources, Newbus integrates the <literal>bus_space</literal>
These provide a single API to replace inb/outb and direct memory APIs from NetBSD. These provide a single API to replace inb/outb
reads/writes. The advantage of this is that a single driver can easily and direct memory reads/writes. The advantage of this is that a
use either memory-mapped registers or port-mapped registers single driver can easily use either memory-mapped registers or
(some hardware supports both).</para> port-mapped registers (some hardware supports both).</para>
<para>This support is integrated into the resource allocation mechanism. <para>This support is integrated into the resource allocation
When a resource is allocated, a driver can retrieve the associated mechanism. When a resource is allocated, a driver can retrieve
<structfield>bus_space_tag_t</structfield> and the associated <structfield>bus_space_tag_t</structfield> and
<structfield>bus_space_handle_t</structfield> from the resource.</para> <structfield>bus_space_handle_t</structfield> from the
resource.</para>
<para>Newbus also allows for definitions of interface methods in files <para>Newbus also allows for definitions of interface methods in
dedicated to this purpose. These are the <filename>.m</filename> files files dedicated to this purpose. These are the
that are found under the <filename>src/sys</filename> hierarchy.</para> <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 <para>The core of the Newbus system is an extensible
<quote>object-based programming</quote> model. Each device in the system <quote>object-based programming</quote> model. Each device in
has a table of methods which it supports. The system and other devices the system has a table of methods which it supports. The system
uses those methods to control the device and request services. The and other devices uses those methods to control the device and
different methods supported by a device are defined by a number of request services. The different methods supported by a device
<quote>interfaces</quote>. An <quote>interface</quote> is simply a group are defined by a number of <quote>interfaces</quote>. An
of related methods which can be implemented by a device.</para> <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 <para>In the Newbus system, the methods for a device are provided
various device drivers in the system. When a device is attached to a by the various device drivers in the system. When a device is
driver during <emphasis>auto-configuration</emphasis>, it uses the method attached to a driver during
<emphasis>auto-configuration</emphasis>, it uses the method
table declared by the driver. A device can later table declared by the driver. A device can later
<emphasis>detach</emphasis> from its driver and <emphasis>detach</emphasis> from its driver and
<emphasis>re-attach</emphasis> to a new driver with a new method table. <emphasis>re-attach</emphasis> to a new driver with a new method
This allows dynamic replacement of drivers which can be useful for driver table. This allows dynamic replacement of drivers which can be
development.</para> useful for driver development.</para>
<para>The interfaces are described by an interface definition language <para>The interfaces are described by an interface definition
similar to the language used to define vnode operations for file systems. language similar to the language used to define vnode operations
The interface would be stored in a methods file (which would normally named for file systems. The interface would be stored in a methods
file (which would normally named
<filename>foo_if.m</filename>).</para> <filename>foo_if.m</filename>).</para>
<example> <example>
<title>Newbus Methods</title> <title>Newbus Methods</title>
<programlisting> <programlisting>
# Foo subsystem/driver (a comment...) # Foo subsystem/driver (a comment...)
@ -233,112 +259,123 @@
</example> </example>
<para>When this interface is compiled, it generates a header file <para>When this interface is compiled, it generates a header file
<quote><filename>foo_if.h</filename></quote> which contains function <quote><filename>foo_if.h</filename></quote> which contains
declarations:</para> function declarations:</para>
<programlisting> <programlisting>
int FOO_DOIT(device_t dev); int FOO_DOIT(device_t dev);
int FOO_DOIT_TO_CHILD(device_t dev, device_t child); int FOO_DOIT_TO_CHILD(device_t dev, device_t child);
</programlisting> </programlisting>
<para>A source file, <quote><filename>foo_if.c</filename></quote> is <para>A source file, <quote><filename>foo_if.c</filename></quote>
also created to accompany the automatically generated header file; it is also created to accompany the automatically generated header
contains implementations of those functions which look up the location file; it contains implementations of those functions which look
of the relevant functions in the object's method table and call that up the location of the relevant functions in the object's method
function.</para> table and call that function.</para>
<para>The system defines two main interfaces. The first fundamental <para>The system defines two main interfaces. The first
interface is called <emphasis><quote>device</quote></emphasis> and fundamental interface is called
includes methods which are relevant to all devices. Methods in the <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>device</quote></emphasis> interface include
<emphasis><quote>probe</quote></emphasis>, <emphasis><quote>probe</quote></emphasis>,
<emphasis><quote>attach</quote></emphasis> and <emphasis><quote>attach</quote></emphasis> and
<emphasis><quote>detach</quote></emphasis> to control detection of <emphasis><quote>detach</quote></emphasis> to control detection
hardware and <emphasis><quote>shutdown</quote></emphasis>, of hardware and <emphasis><quote>shutdown</quote></emphasis>,
<emphasis><quote>suspend</quote></emphasis> and <emphasis><quote>suspend</quote></emphasis> and
<emphasis><quote>resume</quote></emphasis> for critical event <emphasis><quote>resume</quote></emphasis> for critical event
notification.</para> notification.</para>
<para>The second, more complex interface is <para>The second, more complex interface is
<emphasis><quote>bus</quote></emphasis>. This interface contains <emphasis><quote>bus</quote></emphasis>. This interface
methods suitable for devices which have children, including methods to contains methods suitable for devices which have children,
access bus specific per-device information including methods to access bus specific per-device information
<footnote><para>&man.bus.generic.read.ivar.9; and <footnote><para>&man.bus.generic.read.ivar.9; and
&man.bus.generic.write.ivar.9;</para></footnote>, event notification &man.bus.generic.write.ivar.9;</para></footnote>, event
notification
(<emphasis><literal>child_detached</literal></emphasis>, (<emphasis><literal>child_detached</literal></emphasis>,
<emphasis><literal>driver_added</literal></emphasis>) and resource <emphasis><literal>driver_added</literal></emphasis>) and
management (<emphasis><literal>alloc_resource</literal></emphasis>, resource management
(<emphasis><literal>alloc_resource</literal></emphasis>,
<emphasis><literal>activate_resource</literal></emphasis>, <emphasis><literal>activate_resource</literal></emphasis>,
<emphasis><literal>deactivate_resource</literal></emphasis>, <emphasis><literal>deactivate_resource</literal></emphasis>,
<emphasis><literal>release_resource</literal></emphasis>).</para> <emphasis><literal>release_resource</literal></emphasis>).</para>
<para>Many methods in the <quote>bus</quote> interface are performing <para>Many methods in the <quote>bus</quote> interface are
services for some child of the bus device. These methods would normally performing services for some child of the bus device. These
use the first two arguments to specify the bus providing the service methods would normally use the first two arguments to specify
and the child device which is requesting the service. To simplify the bus providing the service and the child device which is
driver code, many of these methods have accessor functions which requesting the service. To simplify driver code, many of these
lookup the parent and call a method on the parent. For instance the methods have accessor functions which lookup the parent and call
method a method on the parent. For instance the method
<literal>BUS_TEARDOWN_INTR(device_t dev, device_t child, ...)</literal> <literal>BUS_TEARDOWN_INTR(device_t dev, device_t child,
can be called using the function ...)</literal> can be called using the function
<literal>bus_teardown_intr(device_t child, ...)</literal>.</para> <literal>bus_teardown_intr(device_t child,
...)</literal>.</para>
<para>Some bus types in the system define additional interfaces to <para>Some bus types in the system define additional interfaces to
provide access to bus-specific functionality. For instance, the PCI provide access to bus-specific functionality. For instance, the
bus driver defines the <quote>pci</quote> interface which has two PCI bus driver defines the <quote>pci</quote> interface which
methods <emphasis><literal>read_config</literal></emphasis> and has two methods
<emphasis><literal>write_config</literal></emphasis> for accessing the <emphasis><literal>read_config</literal></emphasis> and
configuration registers of a PCI device.</para> <emphasis><literal>write_config</literal></emphasis> for
accessing the configuration registers of a PCI device.</para>
</sect1> </sect1>
<sect1 id="newbus-api"> <sect1 id="newbus-api">
<title>Newbus API</title> <title>Newbus API</title>
<para>As the Newbus API is huge, this section makes some effort at <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 documenting it. More information to come in the next revision
document.</para> of this document.</para>
<sect2> <sect2>
<title>Important locations in the source hierarchy</title> <title>Important locations in the source hierarchy</title>
<para><filename>src/sys/[arch]/[arch]</filename> - Kernel code for a <para><filename>src/sys/[arch]/[arch]</filename> - Kernel code
specific machine architecture resides in this directory. For example, for a specific machine architecture resides in this directory.
the <literal>i386</literal> architecture, or the For example, the <literal>i386</literal> architecture, or the
<literal>SPARC64</literal> architecture.</para> <literal>SPARC64</literal> architecture.</para>
<para><filename>src/sys/dev/[bus]</filename> - device support for a <para><filename>src/sys/dev/[bus]</filename> - device support
specific <literal>[bus]</literal> resides in this directory.</para> for a specific <literal>[bus]</literal> resides in this
directory.</para>
<para><filename>src/sys/dev/pci</filename> - PCI bus support code <para><filename>src/sys/dev/pci</filename> - PCI bus support
resides in this directory.</para> code resides in this directory.</para>
<para><filename>src/sys/[isa|pci]</filename> - PCI/ISA device drivers <para><filename>src/sys/[isa|pci]</filename> - PCI/ISA device
reside in this directory. The PCI/ISA bus support code used to exist drivers reside in this directory. The PCI/ISA bus support
in this directory in FreeBSD version <literal>4.0</literal>.</para> code used to exist in this directory in FreeBSD version
<literal>4.0</literal>.</para>
</sect2> </sect2>
<sect2> <sect2>
<title>Important structures and type definitions</title> <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>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 <para><literal>device_method_t</literal> - This is same as
<literal>kobj_method_t</literal> (see <literal>kobj_method_t</literal> (see
<filename>src/sys/kobj.h</filename>).</para> <filename>src/sys/kobj.h</filename>).</para>
<para><literal>device_t</literal> - This is a type definition of a <para><literal>device_t</literal> - This is a type definition of
pointer to a <literal>struct device</literal>. a pointer to a <literal>struct device</literal>.
<literal>device_t</literal> represents a device in the system. It is <literal>device_t</literal> represents a device in the system.
a kernel object. See <filename>src/sys/sys/bus_private.h</filename> It is a kernel object. See
for implementation details.</para> <filename>src/sys/sys/bus_private.h</filename> for
implementation details.</para>
<para><literal>driver_t</literal> - This is a type definition which, <para><literal>driver_t</literal> - This is a type definition
references <literal>struct driver</literal>. The which, references <literal>struct driver</literal>. The
<literal>driver</literal> struct is a class of the <literal>driver</literal> struct is a class of the
<literal>device</literal> kernel object; it also holds data private <literal>device</literal> kernel object; it also holds data
to for the driver.</para> private to for the driver.</para>
<figure> <figure>
<title><emphasis>driver_t</emphasis> implementation</title> <title><emphasis>driver_t</emphasis> implementation</title>
<programlisting> <programlisting>
struct driver { struct driver {
KOBJ_CLASS_FIELDS; KOBJ_CLASS_FIELDS;
@ -353,7 +390,9 @@
autoconfiguration process.</para> autoconfiguration process.</para>
<figure> <figure>
<title>Device states<emphasis>device_state_t</emphasis></title> <title>Device
states<emphasis>device_state_t</emphasis></title>
<programlisting> <programlisting>
/* /*
* src/sys/sys/bus.h * src/sys/sys/bus.h