4    Data Structures for EISA/ISA Bus Device Drivers

Data structures are the mechanism used to pass information between the Digital UNIX kernel and device driver interfaces. EISA/ISA bus device driver writers must understand the data structures described in Writing Device Drivers: Tutorial. To write EISA/ISA bus device drivers, driver writers must also understand the following categories of data structures:

• controller structure members as specified on EISA/ISA buses

• EISA/ISA bus structures

The following sections describe the structures associated with each category. For reference page descriptions of these data structures, see Section A.3.

4.1    The controller Structure Members as Specified on EISA/ISA Buses

The controller structure represents an instance of a controller entity, one that connects logically to a bus. A controller can control devices that are directly connected or can perform some other controlling operation, such as a network interface or terminal controller operation.

Table 4-1 lists those members of the controller structure that have specific meanings on EISA/ISA buses along with their associated data types. Following the table are descriptions of these members as they apply to EISA/ISA buses.

Table 4-1: The controller Structure

4.1.1    The slot Member

The slot member specifies the bus slot or node number. As it applies to the EISA bus, the slot member specifies the slot number that the EISA/ISA bus board is plugged into. The slot number ranges from 1- n, where n represents the maximum number of slots. This value corresponds to the one that you (the device driver writer) specify in the system configuration file or the stanza.static file fragment. In the system configuration file, you precede the slot number for the slot that the EISA/ISA bus board is plugged into with the slot keyword, as follows:

slot 1

The autoconfiguration software uses the syntax following the slot keyword in the system configuration file or the stanza.static file fragment to obtain this value. The bus configuration code obtains this value from the autoconfiguration software and uses it to initialize the slot member of the controller structure associated with this EISA/ISA bus device.

The following code fragment shows that the /dev/envram device driver saves the slot number in a softc structure pointer:

.
.
.

struct  envram_softc {

 u_int slot; /* Slot this board is located in */

envram_probe(bus_io_handle, ctlr)
 io_handle_t bus_io_handle; /* I/O handle */
 struct controller *ctlr; /* Pointer to controller structure */

{
 register struct envram_softc *sc; /* Pointer to softc structure */

 sc->slot = ctlr->slot; /* Save the slot number that this */
                        /* board is located in */

4.1.2    The physaddr Member

The physaddr member specifies the physical address that corresponds to the virtual address set in the addr member. As it applies to the EISA/ISA bus, the physaddr member specifies an I/O handle that you can use to reference a device register located in the EISA/ISA bus address space. This I/O handle is for the base of the device's slot-specific I/O address space.

The /dev/envram device driver saves the I/O handle in the driver's softc structure pointer. The following code fragment shows how /dev/envram uses this address in the construction of a read and write device register interface:

.
.
.

/******************************************************
 * The ENVRAM_READIO- and ENVRAM_WRITE_IO-related     *
 * macros are defined in envram_data.c.  They use     *
 * the read_io_port and write_io_port interfaces and  *
 * OR the offset with the sc->regbase value.  The     *
 * sc->regbase value is the per option physical base  *
 * address of the EISA NVRAM I/O registers            *
 ***************************************************/

 

#define ENVRAM_READIO_D8(a)  read_io_port(sc->regbase + a, 1, 0)

#define ENVRAM_WRITEIO_D8(a,d) write_io_port(sc->regbase + a, 1, 0, d)

struct  envram_softc {

 io_handle_t regbase; /* Base address for device registers */

};

envram_probe(bus_io_handle, ctlr)
 io_handle_t bus_io_handle; /* I/O handle */
 struct controller *ctlr; /* Pointer to controller structure */

{
 register struct envram_softc *sc; /* Pointer to softc structure */

 sc->regbase = (io_handle_t)ctlr->physaddr; /* Save the controller's base */
                                            /* address. */

4.2    EISA/ISA Bus Structures

In addition to the structures described in Writing Device Drivers: Tutorial, device driver writers must understand the eisa_option data structure. The eisa_option structure contains EISA/ISA bus option information such as the name of the controlling device driver. An array of eisa_option structures is declared in the file /usr/sys/data/eisa_option_data.c for EISA device drivers and /usr/sys/data/isa_option_data.c for ISA device drivers. You must be familiar with:

• The members of the eisa_option structure

• The contents of the eisa_option_data.c file

• The contents of the isa_option_data.c file

4.2.1    Members of the eisa_option Structure

Table 4-2 lists the members of the eisa_option structure along with their associated data types. The meanings of the members is identical for the EISA bus and ISA bus except for board_id and function.

Table 4-2: The eisa_option Structure Members and Associated Data Types

The board_id member specifies the EISA bus option expansion board's product ID name. The EISA bus support code compares the value stored in this member with an EISA ID register to identify an option module and to connect it to its associated device driver. You set board_id to the character string that represents the option board's product ID name. The ID name consists of a 3-character manufacturer code, a 3-character product identifier, and a 1-character revision number. For example, the string ADP0002 identifies this as a second revision of an Adaptec ADP1742A SCSI option board.

ISA bus device drivers do not use this member. The ISA bus does not require such an ID register. Typically, ISA device driver writers set this member to the null string () in the eisa_option structure defined in /usr/sys/data/isa_option_data.c.

The function member specifies the text that identifies the product up to a maximum of 79 characters. This text can include part numbers. The default is the null string (). You set function to the character string that represents the product. For example, the string AHA1740 identifies this as the product name for a Digital ADP1742A SCSI option board.

For the ISA bus, this member specifies a string that matches the ISA configuration (ISACFG) handle.

The driver_name member specifies the name of the controlling device driver. You set driver_name to the character string that represents the name of the controlling device driver up to a maximum of 8 characters. This same character string also specifies the name of the controlling device driver in the system configuration file. For example, the string aha identifies this as the controlling device driver for the device connected to an ADP1742A SCSI option board.

The intr_b4_probe member specifies whether the device needs interrupts enabled before the bus configuration code calls the driver's xxprobe interface. You can set intr_b4_probe to the value zero (0) or the value 1. A zero (0) value indicates that the device does not need interrupts enabled; this is the default value. A value of 1 indicates that the device needs interrupts enabled.

The intr_aft_attach member specifies whether the device needs interrupts enabled after the driver's xxprobe and xxcattach or xxdattach interfaces complete execution. You can set intr_aft_attach to the value zero (0) or the value 1. A zero (0) value indicates that the device does not need interrupts enabled; this is the default value. A value of 1 indicates that the device needs interrupts enabled.

The type member specifies the type of device. You can set type to the string C (the device is a controller) or A (the device is a bus or an adapter). The default value is C.

The adpt_config member specifies the name of the bus (or adapter) configuration interface to call. You set adpt_config to the string that identifies the bus configuration interface, if type was set to A (the device is a bus or an adapter). Otherwise, do not set adpt_config to any value.

4.2.2    Contents of the eisa_option_data.c File

Digital initilizes the array of eisa_option structures with its own EISA bus option product information. Third-party device driver writers can directly edit the eisa_option array with their EISA bus option product information; or, they can use the mkdata utility to automatically add product entries to a copy of the eisa_option array. Chapter 8 discusses the mkdata utility.

The following shows the Digital-provided eisa_option_data.c file:

struct  eisa_option     eisa_option[] =
{
/* board      function    driver  intr_b4 itr_aft        adpt */
/* id           name       name    probe   attach type  config */
/* ------    ------------ ------  ------- ------- ----  ------ */

 

{ "CPQ3011", ,           "vga",    0,      1,   'C',    0}, /* QVISION */
{ "DEC4220", "NET,ETH",    "ln",     0,      1,   'C',    0}, /* DEC_LANCE */
{ "ADP0002", "AHA1740",    "aha",    0,      1,   'C',    0}, /* ADP1742A */
                                                              /* SCSI */
{ "ADP0002", "MSD,FPYCTL", "fdi",    0,      1,   'C',    0}, /* ADP1742A */
                                                              /* FLPY */
{ "DEC3001", ,           "fta",    0,      1,   'C',    0}, /* DEC_FDDI */
{ "DEC3002", ,           "fta",    0,      1,   'C',    0}, /* DEC_FDDI */
{ "DEC2500", ,           "envram", 0,      0,   'C',    0}, /* EISA NVRAM */
{ "ISA1010", "COM,1",      "ace",    0,      1,   'C',    0}, /* COMM POR TS */
{ "ISA1010", "COM,2",      "ace",    0,      1,   'C',    0}, /* COMM POR TS */
{ "ISA1010", "PAR",        "ace",    0,      1,   'C',    0}, /* COMM PORTS */

 


 

/*
* Do not delete any table entries above this line or your system
* will not configure properly.
*
* Add any new controllers or devices here.
* Remember, the module name must be blank padded to 7 bytes.
*/

 

    /*
%%%Used by mkdata as placemarker for automatic installation
   */

 

/*
* Do not delete this null entry, which terminates the table, or your
* system will not configure properly.
*/
{   ,                   }       /* Null terminator in the table */
};

4.2.3    Contents of the isa_option_data.c File

Digital initilizes the array of isa_option structures with its own ISA bus option product information. Third-party device driver writers can directly edit the isa_option array with their ISA bus option product information; or, they can use the mkdata utility to automatically add product entries to a copy of the isa_option array. Chapter 8 discusses the mkdata utility.

The following shows the Digital-provided isa_option_data.c file:

struct  eisa_option     isa_option[] =
{
/* board   function    driver  intr_b4 itr_aft       adpt */
/* id        name       name    probe   attach type config */
/* ------ ------------ ------  ------- ------- ---- ------ */

 

{ ,     "KBD,MOUSE",  "gpc",    0,      1,   'C',   0}, /* Keyboard /Mouse */
{ ,     "COM",        "ace",    0,      1,   'C',   0}, /* Serial FAX MODEM */
{ ,     "LPT",        "lp",     0,      0,   'C',   0}, /* parallel port */
{ ,     "FLOPPY",     "fdi",    0,      1,   'C',   0}, /* Floppy disk */
{ ,     "DE200-LN",   "ln",     0,      1,   'C',   0}, /* DEC_LANCE */
{ ,     "DE200-LE",   "le",     0,      1,   'C',   0}, /* DEC_LeMAC */
{ ,     "DT204",      "tra",    0,      1,   'C',   0}, /* DT204 */

 


 

/*
* Do not delete any table entries above this line or your system
* will not configure properly.
*
* Add any new controllers or devices here.
*/
{ ,        "PCXBJ",       "msb",     0,    1,   'C',    0}, /* Audio */

 

    /*
%%%Used by mkdata as placemarker for automatic installation
   */

 

/*
* Do not delete this null entry, which terminates the table, or your
* system will not configure properly.
*/
{   ,             , , 0, 0, '', 0     } /* Null terminator in the table */
};