supp device auto config.htm

What is this ``device driver stuff anyway? Here s a very short introduction to the concept.

<tt>controller</tt>
structure for this controller.
This structure contains such information as the controller type, the
controller name, and the current status of the controller.
The bus configuration code passes this filled-in
<tt>controller</tt>
structure to the driver's
<tt>probe</tt>
interface.
A device driver typically uses the
<tt>ctlr_num</tt>
member of the
<tt>controller</tt>
structure as an index to identify which instance of the controller a
request is for.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut24.html#ControlStruct">Section 17.2</a>
describes the
<tt>controller</tt>
structure.
<a href="#co_id_50_rtn_2">[Return to example]</a>
</li></ol><p>
<a name="SetUpProbeRtnHandleMultBuses"></a>
</p><p></p><hr><p align="center">
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/Digital_UNIX_Bookshelf.html"><img src="supp%20device%20auto%20config_files/BOOKSHELF.GIF" alt="[Return to Library]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/TOC.html"><img src="supp%20device%20auto%20config_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#ImplProbeRtn"><img src="supp%20device%20auto%20config_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#SetUpProbeRoutine"><img src="supp%20device%20auto%20config_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#StructsUsedbyDrvstoRegIntrpts"><img src="supp%20device%20auto%20config_files/NEXT.GIF" alt="[Next Section]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut12.html"><img src="supp%20device%20auto%20config_files/FF.GIF" alt="[Next Chapter]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/INDEX.html"><img src="supp%20device%20auto%20config_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="supp%20device%20auto%20config_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h3>
7.1.4&nbsp;&nbsp;&nbsp;&nbsp;Setting Up the probe Interface to Handle Multiple Buses
</h3>
<p>
<a name="nx_id_361"></a>
If you want to write one device driver that operates on multiple buses,
the driver's
<tt>probe</tt>
interface must handle any differences related to the bus.
The following example shows you how to set up a
<tt>probe</tt>
interface to handle the EISA, ISA, PCI, and TURBOchannel buses, using
the
<tt>/dev/xx</tt>
driver as an example.
(Assume that the
<tt>/dev/xx</tt>
driver operates on these four buses.)
</p><p>
</p><p>
</p><pre>xxprobe(bus_io_handle, ctlr)
io_handle_t bus_io_handle; <a name="co_id_51_rtn_1"></a><a href="#co_id_51_1"><strong>[1]</strong></a> 
struct controller *ctlr;   <a name="co_id_51_rtn_2"></a><a href="#co_id_51_2"><strong>[2]</strong></a>
{
<br>.<br>.<br>.<br>
struct pci_config_hdr *pci_cfg_hdr = (void *)bus_io_handle; <a name="co_id_51_rtn_3"></a><a href="#co_id_51_3"><strong>[3]</strong></a>
struct xx_softc *sc = &amp;xx_softc[ctlr-&gt;ctlr_num]; <a name="co_id_51_rtn_4"></a><a href="#co_id_51_4"><strong>[4]</strong></a>
<br>.<br>.<br>.<br>
int unit = ctlr-&gt;ctlr_num; <a name="co_id_51_rtn_5"></a><a href="#co_id_51_5"><strong>[5]</strong></a>
<br>.<br>.<br>.<br>
    switch (ctlr-&gt;bus_hd-&gt;bus_type) { <a name="co_id_51_rtn_6"></a><a href="#co_id_51_6"><strong>[6]</strong></a>

        case BUS_TC: <a name="co_id_51_rtn_7"></a><a href="#co_id_51_7"><strong>[7]</strong></a>
<br>.<br>.<br>.<br>
               break;

        case BUS_ISA:
        case BUS_EISA: <a name="co_id_51_rtn_8"></a><a href="#co_id_51_8"><strong>[8]</strong></a>
<br>.<br>.<br>.<br>
                break;
<br>.<br>.<br>.<br>
        case BUS_PCI: <a name="co_id_51_rtn_9"></a><a href="#co_id_51_9"><strong>[9]</strong></a>
        sc-&gt;basereg = pci_cfg_hdr-&gt;bar0;
<br>.<br>.<br>.<br>
                break;

        default: <a name="co_id_51_rtn_10"></a><a href="#co_id_51_10"><strong>[10]</strong></a>
                printf("xx%d: xxprobe: unknown device\n",unit);
                return 0; <a name="co_id_51_rtn_11"></a><a href="#co_id_51_11"><strong>[11]</strong></a>
<br>.<br>.<br>.<br>
}
</pre>
<p>
</p><p>
</p><ol>
<p></p><li>
<a name="co_id_51_1"></a>
Declares an argument that specifies an I/O handle that you can use to
reference a device register or memory located in bus address space
(either I/O space or memory space).
This I/O handle references the device's I/O address space for the bus
where the read operation originates (in calls to the
<tt>read_io_port</tt>
interface) and where the write operation occurs (in calls to the
<tt>write_io_port</tt>
interface).
The bus configuration code passes this I/O handle to the driver's
<tt>probe</tt>
interface during device autoconfiguration.
<a href="#co_id_51_rtn_1">[Return to example]</a>
<p></p></li><li>
<a name="co_id_51_2"></a>
Declares a pointer to a
<tt>controller</tt>
structure for this controller.
This structure contains such information as the controller type, the
controller name, and the current status of the controller.
The bus configuration code passes this filled-in
<tt>controller</tt>
structure to the driver's
<tt>probe</tt>
interface.
A device driver typically uses the
<tt>ctlr_num</tt>
member of the
<tt>controller</tt>
structure as an index to identify which instance of the controller a
request is for.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut24.html#ControlStruct">Section 17.2</a>
describes the
<tt>controller</tt>
structure.
<a href="#co_id_51_rtn_2">[Return to example]</a>
<p></p></li><li>
<a name="co_id_51_3"></a>
Specifies a pointer to the
<tt>pci_config_hdr</tt>
data structure associated with this device.
This device is connected to a controller that operates on the PCI bus.
This is a PCI bus-specific structure that is described in
<cite>Writing PCI Bus Device Drivers</cite>.
<a href="#co_id_51_rtn_3">[Return to example]</a>
<p></p></li><li>
<a name="co_id_51_4"></a>
Declares a pointer to the driver's
<tt>softc</tt>
structure and  initializes it to the address of the
<tt>xx_softc</tt>
structure associated with this
<tt>XX</tt>
device.
The controller number (stored in the
<tt>ctlr_num</tt>
member of the
<tt>controller</tt>
structure pointer associated with this device)
is used as an index into the array of
<tt>xx_softc</tt>
structures to determine which
<tt>xx_softc</tt>
structure is associated with this
<tt>XX</tt>
device.
Assume that the
<tt>xx_softc</tt>
structure contains a
<tt>basereg</tt>
member that stores the I/O handle to the address space specified by the
base address zero (BAR0) device register.
This BAR0 device register is accessed through the
<tt>bar0</tt>
member of the
<tt>pci_config_hdr</tt>
structure.
<a href="#co_id_51_rtn_4">[Return to example]</a>
<p></p></li><li>
<a name="co_id_51_5"></a>
Stores the controller number for this controller in the
<tt><var>unit</var></tt>
variable.
<a href="#co_id_51_rtn_5">[Return to example]</a>
<p></p></li><li>
<a name="co_id_51_6"></a>
Evaluates the
<tt>bus_type</tt>
member to determine which bus this controller connects to.
Note that the
<tt>/dev/xx</tt>
driver references the bus type through the
<tt>bus_hd</tt>
member of the
<tt>controller</tt>
structure pointer.
<p>
The
<tt>bus_hd</tt>
member specifies a pointer to the
<tt>bus</tt>
structure to which this controller is connected.
<a href="#co_id_51_rtn_6">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_51_7"></a>
If the
<tt>switch</tt>
statement evaluates to the bus type
<tt>BUS_TC</tt>,
then this controller connects to a TURBOchannel bus.
The
<tt>xxprobe</tt>
interface performs tasks specific to the TURBOchannel bus.
The
<tt>/usr/sys/include/io/common/devdriver.h</tt>
file defines the bus type definitions.
<a href="#co_id_51_rtn_7">[Return to example]</a>
<p></p></li><li>
<a name="co_id_51_8"></a>
If the
<tt>switch</tt>
statement evaluates to the bus type
<tt>BUS_ISA</tt>
or
<tt>BUS_EISA</tt>,
then this controller connects to an ISA or EISA bus.
The
<tt>xxprobe</tt>
interface performs tasks specific to the ISA or EISA bus.
<a href="#co_id_51_rtn_8">[Return to example]</a>
<p></p></li><li>
<a name="co_id_51_9"></a>
If the
<tt>switch</tt>
statement evaluates to the bus type
<tt>BUS_PCI</tt>,
then this controller connects to a PCI bus.
Sets the
<tt>basereg</tt>
member of the
<tt>xx_softc</tt>
structure pointer associated with this
<tt>XX</tt>
device to the I/O handle.
<a href="#co_id_51_rtn_9">[Return to example]</a>
<p></p></li><li>
<a name="co_id_51_10"></a>
If the
<tt>switch</tt>
statement evaluates to something other than the bus type, then this
controller connects to some unknown device.
The
<tt>xxprobe</tt>
interface calls the
<tt>printf</tt>
interface to print an appropriate message on the console terminal.
Note that the
<tt>printf</tt>
interface prints the controller number for this
controller,
which was obtained from the
<tt>ctlr_num</tt>
member.
<a href="#co_id_51_rtn_10">[Return to example]</a>
<p></p></li><li>
<a name="co_id_51_11"></a>
Returns the value zero (0) to the bus configuration code to indicate
that the
driver did not complete the probe operation.
<a href="#co_id_51_rtn_11">[Return to example]</a>
</li></ol><p>
<a name="StructsUsedbyDrvstoRegIntrpts"></a>
</p><p></p><hr><p align="center">
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/Digital_UNIX_Bookshelf.html"><img src="supp%20device%20auto%20config_files/BOOKSHELF.GIF" alt="[Return to Library]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/TOC.html"><img src="supp%20device%20auto%20config_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#ImplProbeRtn"><img src="supp%20device%20auto%20config_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#SetUpProbeRtnHandleMultBuses"><img src="supp%20device%20auto%20config_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#Theihandler_tStruct"><img src="supp%20device%20auto%20config_files/NEXT.GIF" alt="[Next Section]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut12.html"><img src="supp%20device%20auto%20config_files/FF.GIF" alt="[Next Chapter]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/INDEX.html"><img src="supp%20device%20auto%20config_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="supp%20device%20auto%20config_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h3>
7.1.5&nbsp;&nbsp;&nbsp;&nbsp;Using Data Structures to Register Interrupt Handlers
</h3>
<p>
One task that a device driver's
<tt>probe</tt>
interface must perform is to register interrupt handlers.
An interrupt handler is a device driver
routine that services hardware interrupts.
Digital requires that all drivers call the
<tt>handler</tt>
interfaces to dynamically register interrupt handlers. 
The dynamic registration of interrupt handlers involves the use of the
following data structures:
</p><ul>
<p></p><li>
<tt>ihandler_t</tt>
<p></p></li><li>
<tt>handler_intr_info</tt>
</li></ul><p>
</p><p>
The following sections describe each of these data structures.
<a name="Theihandler_tStruct"></a>
</p><p></p><hr><p align="center">
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/Digital_UNIX_Bookshelf.html"><img src="supp%20device%20auto%20config_files/BOOKSHELF.GIF" alt="[Return to Library]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/TOC.html"><img src="supp%20device%20auto%20config_files/TOC.GIF" alt="[Contents]" border="0"></a>
<a href="#ImplProbeRtn"><img src="supp%20device%20auto%20config_files/REW.GIF" alt="[Previous Chapter]" border="0"></a>
<a href="#StructsUsedbyDrvstoRegIntrpts"><img src="supp%20device%20auto%20config_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#Thehandler_intr_infoStruct"><img src="supp%20device%20auto%20config_files/NEXT.GIF" alt="[Next Section]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut12.html"><img src="supp%20device%20auto%20config_files/FF.GIF" alt="[Next Chapter]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/INDEX.html"><img src="supp%20device%20auto%20config_files/INDEX.GIF" alt="[Index]" border="0"></a>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/HELP.html"><img src="supp%20device%20auto%20config_files/HELP.GIF" alt="[Help]" border="0"></a>
</p><p></p><hr><p>
</p><h3>
7.1.5.1&nbsp;&nbsp;&nbsp;&nbsp;The ihandler_t Data Structure
</h3>
<p>
<a name="nx_id_362"></a>
<a name="nx_id_363"></a>
<a name="nx_id_364"></a>
The
<tt>ihandler_t</tt>
structure contains information associated with device driver interrupt
handling.
This model of interrupt dispatching uses the bus as the means
of interrupt dispatching for all drivers.
For this reason, all of the information needed to register an
interrupt is considered to be bus specific.
As a result, no attempt is made to represent all the possible
permutations within the
<tt>ihandler_t</tt>
data structure.
</p><p>
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut11.html#Tblihandler_tStructMembers">Table 7-1</a>
lists the members of the
<tt>ihandler_t</tt>
structure along with their associated data types.
</p><p>
<a name="Tblihandler_tStructMembers"></a>
</p><h3>
Table 7-1: Members of the ihandler_t Structure
</h3>
<a name="nx_id_365"></a>
<table border="4" cellpadding="4">
<tbody><tr>
<td align="left" valign="top">
<strong>
Member Name
</strong>
</td>
<td align="left" valign="top">
<strong>
Data Type
</strong>
</td>
</tr>