SCO OpenServer

driver_info(D4oddi)

driver_info -- driver description structure for interrupt registration

Synopsis

   #include <sys/ci/ciintr.h>

Description

The driver_info structure is passed as a pointer to the idistributed(D3oddi) function used to register interupt handlers for non-SCSI drivers. The shareg_ex(D4osdi) structure is similar and is used when registering SCSI host adapters

Structure definition

   typedef struct driver_info_2 {
   	int version;
   	int irq;
   	int iosaddr;
   	int ioeaddr;
   	int weight;
   	int (*intr)();
   	int ipl;
   	int route;
   	int mode;
   	int processor_mask;
   	char *name;
   	int bus;
   	/* new things go here */
   } driver_info;

Structure members

The members are defined as follows:

version

Identifies the version number of the structure passed. Valid values are:

DRV_INFO_VERS_1: driver controls a non-PCI device
DRV_INFO_VERS_2: driver controls a PCI device

irq

If the device driver is controlling a non-PCI device, then this member specifies the interrupt line (IRQ) that the device uses. If the device driver is controlling a PCI device, then this member is set to the PCI device and function number. In the latter case, use the following macro to determine the IRQ value:

di.irq = IDIST_PCI_IRQ(device, function)

The device argument is the PCI device number (0-31), and function is the PCI function number (0-7). Note that for PCI devices, the interrupt line (IRQ) is read by the kernel from the Interrupt Line register (offset 3C hex) in the PCI Configuration Space of the device.

iosaddr

Reserved; drivers should set to zero.

ioeaddr

Reserved; drivers should set to zero.

weight

Gives an indication to the kernel of the kind of interrupt load to expect from the device. This member should be set to the interrupt priority level of the device driver.

intr

Interrupt handler that the driver uses.

ipl

Interrupt priority level of the device driver. See ``Usage'' for information about populating this member.

route

Routing of the interrupt. Must be set to IROUTE_GLOBAL.

mode

Specifies whether the device driver is capable of sharing interrupts or not. It corresponds to the ``Type'' field in the sdevice(F) file, and can take on the following values:

IMODE_SHARED_CDRIVERIPL (Recommended): The device requires an interrupt vector. If the driver supports more than one hardware controller, each controller may either share a vector with one of the other controllers or use a separate vector. Multiple device drivers having the same IPL can share this interrupt. Most drivers should be written to use this mode.
IMODE_NONE: The device does not require an interrupt vector.
IMODE_EXCLUSIVE: The device requires an interrupt vector. If the driver supports more than one hardware controller, each controller requires a separate vector.
IMODE_SHARED_DRIVER: The device requires an interrupt vector. If the driver supports more than one hardware controller, each controller will share the same vector.
IMODE_SHARED_DRIVERIPL: The device requires an interrupt vector. If the driver supports more than one hardware controller, each controller will share the same vector. Multiple device drivers with the same IPL can share this interrupt.
IMODE_SHARED_INTER: The device requires an interrupt vector. If the driver supports more than one hardware controller, each controller will share the same vector. This interrupt type is only used by hard disk drivers to prevent other devices from sharing the same vector.

processor_mask

Indicates whether the interrupt handler specified to the intr member is multithreaded. (See ``Multithreaded drivers'' in HDK Technical Reference.) If the device driver is non-multithreaded or only the base level entry point routines are multithreaded, this member should be set to 1. If the interrupt handler specified to the intr member is multithreaded, this member should be set using the remap_driver_cpu(D3oddi) function.

name

This provides a name that can be used by kernel routines should an error arise. The name is used when outputting error messages to identify the driver.

bus

If the device driver is controlling a PCI device, then this member is set to the PCI bus number on which the device resides. It is not used if the device driver is controlling a non-PCI device.

Usage

If the interrupt priority level (IPL) of the device is statically defined in the link kit, then it should be obtained from the sdevice(F) file. This can be achieved by placing the following variable definition into the driver's space.c file:

   #include "config.h"
   
   int     xx_ipl = XX_0_IPL;

where xx is device driver prefix, and '0' is the value of the ``Unit'' field of the sdevice entry, assumed to be zero.

If the interrupt vector of the device is statically defined in the link kit, then it can also be obtained from the sdevice(F) file using the XX_0_VECT definition.

NOTE: It is strongly recommended that interrupt vectors not be registered statically when using the DRV_INFO_VERS_1 method of registration. Drivers should use some form of dynamic interrupt configuration such as reading the interrupt vector from device registers at driver initialization time. Interrupt vectors should not be configured statically unless dynamic configuration is not possible.

If the version member of the driver_info structure is set to DRV_INFO_VERS_2 then the argument passed to the interrupt routine must be obtained by a call to the get_intr_arg(D3oddi) kernel function.

The driver_info structure can be declared locally and discarded after the call to idistributed( ). However, after the call to idistributed( ), the structure values must be treated as undefined. All elements of the structure must be re-initialized if the structure is to be used in a subsequent call to idistributed( ).

Hardware applicability

All

Version applicability

oddi: 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp

Differences between versions

Drivers written for ODDI versions prior to version 3 use the add_intr_handler(D3oddi) function to dynamically register their interrupt handlers and do not use this function.

SCO OpenServer ODDI compatibility

DDI drivers do not support this structure. See ``Interrupt handlers, attaching and registering'' in HDK Technical Reference for information about attaching and registering interrupt handlers in DDI drivers.

References

get_intr_arg(D3oddi), idistributed(D3oddi), remap_driver_cpu(D3oddi), shareg_ex(D4osdi)

``Interrupt handlers, attaching and registering'' in HDK Technical Reference