supp device auto config.htm

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

In this example, this ID is contained in the
<tt><var>none_id_t</var></tt>
array.
<a href="#co_id_52_rtn_14">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_52_15"></a>
Increments the
<tt><var>num_none</var></tt>
variable to indicate that a
<tt>NONE</tt>
controller was probed.
<a href="#co_id_52_rtn_15">[Return to example]</a>
</li></ol><p>
<a name="RegSharedISIswithhandlerRtns"></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="#RegISIswithhandlerRtns"><img src="supp%20device%20auto%20config_files/PREV.GIF" alt="[Previous Section]" border="0"></a>
<a href="#probeAddrwithBADADDR"><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.7&nbsp;&nbsp;&nbsp;&nbsp;Using the handler Interfaces to Register Shared Interrupt Handlers
</h3>
<p>
<a name="nx_id_381"></a>
<a name="nx_id_382"></a>
<a name="nx_id_383"></a>
<a name="nx_id_384"></a>
Some Alpha CPU platforms require multiple hardware devices to
share an interrupt line.
A shared interrupt line is a hardware interrupt level (connection) shared
by more than one hardware device.
To work correctly on these types of systems, a driver must determine if
an interrupt was generated by the device it controls.
Digital UNIX provides a framework for supporting shared interrupt lines
and their associated shared interrupt handlers.
With this shared interrupt framework, all devices registered to use a
specific interrupt line are called, one at a time, until an interrupt
handler indicates that it has handled the interrupt.
Although device drivers are not required to support shared interrupts,
failure to do so might limit the hardware configuration on which the
device is supported.
</p><p>
A shared interrupt handler is a driver routine registered to take
advantage of the shared interrupt framework that Digital UNIX provides
for hardware devices that share an interrupt line.
Currently, the AlphaStation 200, AlphaStation 400, and
AlphaStation 600 series of computer systems support shared interrupts
on the PCI bus. 
Binary compatibility is maintained with device drivers that do not
implement the functionality to support shared interrupts.
To register a device driver's shared interrupt handlers, you perform the
same tasks you perform to register a nonshared interrupt handler, and
one more task specific to shared interrupts:
</p><ul>
<p></p><li>
Declare instances of the
<tt>ihandler_t</tt>
and
<tt>handler_intr_info</tt>
data structures
<p></p></li><li>
Get the controller number associated with the controller for this
device
<p></p></li><li>
Get the I/O handle passed in by the bus configuration code
<p></p></li><li>
Set the members of the
<tt>ihandler_t</tt>
and
<tt>handler_intr_info</tt>
structures to appropriate values
<p></p></li><li>
Set the shared interrupt bit in the
<tt>config_type</tt>
member of the
<tt>handler_intr_info</tt>
structure (specific to shared interrupts)
<p></p></li><li>
Call the
<tt>handler_add</tt>
and
<tt>handler_enable</tt>
interfaces
</li></ul><p>
Your
<tt>probe</tt>
interface will probably perform most of these tasks and, possibly, some
additional ones.
The following code shows how to perform these tasks, using the
<tt>/dev/xx</tt>
device driver as an example.
Assume that in this example the
<tt>/dev/xx</tt>
driver operates on one of the Alpha systems and the PCI bus that
require use of the shared interrupt framework.
</p><p>
The code also provides a typical implementation of a device driver's
interrupt handler that takes advantage of the shared interrupt functionality
supplied by Digital UNIX.
<a name="nx_id_385"></a>
<a name="nx_id_386"></a>
The numbered items that follow the example describe only the differences
for implementing shared interrupts.
<a href="http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/HTML/AA-PUBVD-TE_html/drivertut11.html#RegISIswithhandlerRtns">Section 7.1.6</a>
describes the other items in the example.
Note that the
<tt>/dev/xx</tt>
driver's
<tt>probe</tt>
interface is set up to handle multiple buses.
Assume that the
<tt>/dev/xx</tt>
driver has two other interfaces:
<tt>xx_readio</tt>
and
<tt>xx_writeio</tt>.
</p><p>
</p><p>
</p><pre><br>.<br>.<br>.<br>
ihandler_id_t *xx_id_t[NXX];
<br>.<br>.<br>.<br>
int xxprobe(bus_io_handle, ctlr)
 io_handle_t bus_io_handle;
 struct controller *ctlr;
{
<p>
     struct pci_config_hdr *pci_cfg_hdr = (void*)bus_io_handle; <a name="co_id_53_rtn_1"></a><a href="#co_id_53_1"><strong>[1]</strong></a>
     struct xx_softc *sc = &amp;xx_softc[ctlr-&gt;ctlr_num]; <a name="co_id_53_rtn_2"></a><a href="#co_id_53_2"><strong>[2]</strong></a>
     ihandler_t handler;
     struct handler_intr_info xx_intr_info;
     int unit = ctlr-&gt;ctlr_num;

     switch (ctlr-&gt;bus_hd-&gt;bus_type) {
        case BUS_PCI:
        sc-&gt;basereg = pci_cfg_hdr-&gt;bar0; <a name="co_id_53_rtn_3"></a><a href="#co_id_53_3"><strong>[3]</strong></a>
<br>.<br>.<br>.<br>
        case BUS_EISA:
        case BUS_ISA: <a name="co_id_53_rtn_4"></a><a href="#co_id_53_4"><strong>[4]</strong></a>
<br>.<br>.<br>.<br>
        case BUS_TC: <a name="co_id_53_rtn_5"></a><a href="#co_id_53_5"><strong>[5]</strong></a>
</p><p>
     handler.ih_bus = ctlr-&gt;bus_hd;
</p><p>
     xx_intr_info.configuration_st = (caddr_t)ctlr;
</p><p>
     xx_intr_info.config_type = (CONTROLLER_CONFIG_TYPE | SHARED_INTR_CAPABLE); <a name="co_id_53_rtn_6"></a><a href="#co_id_53_6"><strong>[6]</strong></a>
</p><p>
     xx_intr_info.intr = xxintr;
</p><p>
     xx_intr_info.param = (caddr_t)unit;
</p><p>
     handler.ih_bus_info = (char *)&amp;xx_intr_info;
</p><p>
     xx_id_t[unit] = handler_add(&amp;handler);
     if (xx_id_t[unit] == NULL) {
</p><p>
             return(0);
     }
</p><p>
             if (handler_enable(xx_id_t[unit]) != 0) {
                     handler_del(xx_id_t[unit]);
                     return(0);
     }
     xx_none++;
     return(0);

<br>.<br>.<br>.<br>
}/* End of xxprobe */
<br>.<br>.<br>.<br>
int xx_intr(parameter)
   int parameter; <a name="co_id_53_rtn_7"></a><a href="#co_id_53_7"><strong>[7]</strong></a>
{
<br>.<br>.<br>.<br>
   register struct xx_softc *sc = xx_softc[unit]; <a name="co_id_53_rtn_8"></a><a href="#co_id_53_8"><strong>[8]</strong></a>
   int intr_status; <a name="co_id_53_rtn_9"></a><a href="#co_id_53_9"><strong>[9]</strong></a>
<br>
<br>.<br>.<br>.<br>
   intr_status = xx_readio(PNV_INTR_CTRL, sc); <a name="co_id_53_rtn_10"></a><a href="#co_id_53_10"><strong>[10]</strong></a>

   if (!(intr_status &amp; PNV_INTR_OCCURRED))
        return(INTR_NOT_SERVICED); <a name="co_id_53_rtn_11"></a><a href="#co_id_53_11"><strong>[11]</strong></a>

   if ((intr_status &amp; PNV_DMA_INTR) { <a name="co_id_53_rtn_12"></a><a href="#co_id_53_12"><strong>[12]</strong></a>
        xx_writeio(PNV_INTR_CTRL,
                        (intr_status &amp; ~(PNV_CRD_INTR|PNV_ABRT_INTR)), sc);
<br>
<br>.<br>.<br>.<br>
   }
   return(INTR_SERVICED); <a name="co_id_53_rtn_13"></a><a href="#co_id_53_13"><strong>[13]</strong></a>
} /* End of xx_intr */
</p></pre>
<p>
</p><p>
<a name="nx_id_387"></a>
<a name="nx_id_388"></a>
</p><ol>
<p></p><li>
<a name="co_id_53_1"></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_53_rtn_1">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_2"></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_53_rtn_2">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_3"></a>
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_53_rtn_3">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_4"></a>
Performs tasks specific to the EISA or ISA bus.
<a href="#co_id_53_rtn_4">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_5"></a>
Performs tasks specific to the TURBOchannel bus.
<a href="#co_id_53_rtn_5">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_6"></a>
Sets the
<tt>config_type</tt>
member of the
<tt>xx_intr_info</tt>
structure to the bitwise inclusive OR of one of the interrupt handler
type bit
values and the shared interrupt bit value
<tt>SHARED_INTR_CAPABLE</tt>.
This example specifies the interrupt handler type bit value
<tt>CONTROLLER_CONFIG_TYPE</tt>
(the interrupt handler is for a controller driver).
<a href="#co_id_53_rtn_6">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_7"></a>
Specifies
any parameter that the driver needs to control operation of the
interrupt handler.
The value that gets passed to the
<tt><var>parameter</var></tt>
argument is the value you stored in the
<tt>param</tt>
member of the
<tt>handler_intr_info</tt>
data structure.
<p>
In this example, the device driver's interrupt handler does not make
use of this argument.
<a href="#co_id_53_rtn_7">[Return to example]</a>
</p><p></p></li><li>
<a name="co_id_53_8"></a>
Specifies a pointer to a
<tt>softc</tt>
data structure and initializes it to the
<tt>softc</tt>
structure associated with this
<tt>XX</tt>
device.
<a href="#co_id_53_rtn_8">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_9"></a>
Declares a variable called
<tt><var>intr_status</var></tt>
that stores the bit associated with the interrupt controller register
after the interrupt occurred.
<a href="#co_id_53_rtn_9">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_10"></a>
Calls the device driver's
<tt>xx_readio</tt>
interface, which reads the interrupt control register
<tt>PNV_INTR_CTRL</tt>
to determine if an interrupt occurred.
(Assume that the
<tt>/dev/xx</tt>
driver implements the
<tt>xx_readio</tt>
interface to read the control register.)
<a href="#co_id_53_rtn_10">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_11"></a>
If there is no interrupt status bit set in the interrupt control
register, returns the constant
<tt>INTR_NOT_SERVICED</tt>
to the kernel's interrupt dispatch code.
This constant indicates that the driver's interrupt handler
did not service the shared
interrupt.
<a href="#co_id_53_rtn_11">[Return to example]</a>
<p></p></li><li>
<a name="co_id_53_12"></a>
If the interrupt control register is set to the
<tt>PNV_DMA_INTR</tt>
bit, then an interrupt occurred.
Calls the device driver's
<tt>xx_writeio</tt>
interface to write the bit status to the interrupt control register.
(Assume that the
<tt>/dev/xx</tt>
driver implements the
<tt>xx_writeio</tt>
interface to write the bit status.)
<a href="#co_id_53_rtn_12">[Return to exa