A central component of the DOS-EISA world is a configuration program that allocates and sets up the resources that the EISA card uses. Once this program runs, the configuration results are downloaded into non-volatile memory for future driver use. Storing the configuration results serves two purposes:

In the DOS environment, the EISA configuration program allocates memory spaces, DMA channels, and interrupt request lines. In IRIX release 5.x, lboot handles the allocation of memory and I/O spaces. lboot passes the allocation results to the driver via the edt_t structure. Memory and I/O spaces are passed via edt, but dynamic resources are not. The driver requests DMA channels and interrupt request lines or queues (IRQs) as dynamic resources as required.

The EISA bus provides a locked cycle that allows users to read/write the contents of a device register or memory location as an atomic operation. This facility is normally implemented for semaphores' bit test-and-set operations.

On the Indigo2, the hardware implementation of a locked cycle is limited. Indigo2 allows an EISA card to issue a locked cycle, but only for the duration of two contiguous read/write operations. Access to this class of cycles is provided on the CPU side, much like the read/modify/write cycle on a VME bus, through the pio_rmw* kernel functions. See “Writing a Kernel-level EISA Device Driver.”

In general, LOCK* is not considered to be a supported feature of the Silicon Graphics EISA implementation.

EISA provides server DMA channels arranged into two channel groups (channels 0-3 and channels 5-7) for priority resolution. Silicon Graphics uses the rotating scheme described in the EISA-bus specification. Although the channels rotate in this scheme, channels 5-7 receive more cycles, in general, than channels 0-3.

The EISA bus supports 11 edge-triggerable or level-triggerable interrupts. IRQ0–IRQ2, IRQ8, and IRQ13 are used for internal functions only and are not available externally. The remaining 11 interrupt lines (IRQ3–IRQ7, IRQ9–IRQ12, IRQ14, IRQ15) are available for external system interrupts.

On Indigo2, all EISA interrupts are received at the same CPU level. When the CPU receives an EISA-bus interrupt, it responds to each device in IRQ priority order (lower number first). The operating system then determines which interrupt routine to use, based on the value specified by the device driver. Devices may share the same IRQ level.

The EISA bus supports 8-bit, 16-bit, and 32-bit data transfers through direct CPU access as well as DMA initiated by a bus-master card or the on-board DMA hardware.

The EISA-bus address space is divided into I/O address space and memory address space.

I/O address space provides access to the 4 KB page that references the registers on an EISA card on a slot-specific basis and the registers on an ISA card on an address-range basis.

The EISA memory space supports memory that is configured to respond to the address range starting at 0xa0000. On Indigo2 systems, the EISA memory address range extends 112 MB up to address 0x06ffffff (see Figure 4-1). Once properly mapped by the operating system, this memory space can be directly accessed by the CPU through loads and stores.

Figure 4-1. Indigo2 Memory Space

IRIX release 5.2 and later releases provide a set of procedural interfaces that a device driver must use to allocate and map the EISA I/O address space and memory address space.

The Indigo2 has four peripheral card slots that accept EISA, GIO, or graphics cards. A server can support up to four EISA cards, but then a graphics card cannot be used. CHALLENGE M platforms have four EISA slots available. Graphics cards are available that use one, two, or three slots:

An important implementation detail of the EISA bus you need to be aware of is that the EISA bus uses little-endian byte ordering; the CPU running IRIX uses big-endian byte ordering. Hence, a byte reference by the CPU to the low-order byte within a word results in a reference to the high-order byte on the EISA bus. This can sometimes become complex when referencing data structures across the bus.

There are several reasons why you might want to write a user-level device driver instead of a kernel-level device driver:

The main reasons for writing a kernel-level device driver are:

The main reasons for writing a kernel-level memory-mapping device driver are:

See Chapter 7, “Writing Kernel-level General Memory-mapping Device Drivers,” for a description of the memory-mapping facilities.

IRIX Release 5.x contains special files in the /dev/eisa directory that allow a user-level program to map arbitrary EISA or ISA devices into its address space. These files can be used to write a user-level memory-mapped device driver. The driver uses the mmap() system call to map the card's address space into user-level program address space. Then the driver can access the card through simple loads and stores of program variables.

The special device files found in the /dev/eisa directory are:

Where A is the specific EISA-bus adapter.

An Indigo2 system has a single EISA-bus slot, so its special device files are limited to eisa0io and eisa0mem.

A user-level driver may access a generic EISA device by opening the appropriate /dev/eisa special file, followed by an mmap() call to map in the device. For example:

int fd, len, off;
char *addr;
fd=open("/dev/eisa/eisa0io", O_RDWR);
len=4096;
off=0x1000;
addr=mmap(0, len, PROT_READ|PROT_WRITE, MAP_PRIVATE, fd, off);
 .
 .
 .
/* addr can be used to access any card register by adding the 
 * appropriate offset and then dereferencing the pointer
 */
 .
 .
 .

Note that in the example above, the offset starts at 0X1000, which is the base address of the first EISA slot. On Indigo2 systems, the slots are numbered in ascending order from top to bottom (that is, slot one is the top and slot four is on the bottom.). See the mmap(D2) man page for a complete description of this system call.

The mmap() routine maps len bytes starting at EISA address off to the user virtual address addr. Any loads or stores to the address range addr to addr+len will result in read or writes to the EISA I/O space.

---

Note: You are responsible for identifying the offset to reference each device on a slot-specific basis. The offset must be incremented by 4096 to reference the next EISA card's I/O space; the offset to an ISA card is its ISA address.

---

To configure a kernel-level EISA device driver, you must add certain system files to the kernel, create various data structures, and write the driver.

The I/O address space on an EISA card plugged into a card slot responds to the range of bus addresses for that slot. All EISA cards are identified by a manufacturer-specific device ID that the operating system uses to register the existence of each card. ISA cards, in contrast, are jumpered to respond to a specific address range that corresponds to the device's I/O registers.

Your driver can map these I/O addresses into the host processor address space; it can then access these registers with simple reads and writes. For a card's memory space to be accessible, the card must be configured or jumpered to respond to the appropriate address range. The memory space can then be mapped to the host address space with the kernel mapping routines. The specified address range must be selected to avoid conflicts with other EISA/ISA devices.

This section describes the configuration information needed to add an EISA driver to the kernel.

To add a new kernel-level device driver, you must create your own system file. This file should contain the appropriate directive that tells lboot how to include your driver, and it should specify which memory space will be allocated by your device. The filename must include the .sm suffix and reside in the directory /var/sysgen/system. Because lboot can probe for EISA devices, it can conditionally include an EISA device driver into the kernel.

VECTOR:   bustype=EISA   module=driver_name   [options]

(space_name, address_offset, size)

EISA Product Identifier (ID)

EISA expansion boards, embedded devices, and system boards have a four-byte product identifier (ID) that can be read from I/O port addresses 0xzC80 through 0xzC83. For example, the slot 1 product ID can be read from I/O port addresses 0x1C80-0x1C83.

The first two bytes (0xzC80 and 0xzC81) contain a compressed representation of the manufacturer code. The manufacturer code is a three-character code (uppercase, ASCII characters in the range of A to Z) chosen by the manufacturer and registered with the firm that distributes the EISA specification.

The manufacturer code “ISA” is used to indicate a generic ISA adapter. The three-character manufacturer code is compressed into three 5-bit values so that it can be incorporated into the two I/O bytes at 0xzC80 and 0xzC81, where z represents the slot number probed.

The compression procedure is:

1. Find the hexadecimal ASCII value for each letter:

   ASCII for “A”-“Z” : “A” = 0x41, “Z” = 0x5a

2. Subtract 0x40 from each ASCII value:

   Compressed “A” = 0x41-0x40 = 0x01 = 0000 0001
   Compressed “Z” = 0x5a-0x40 = 0x1A = 0001 1010

3. Retain five least significant bits for each letter:

   Discard three most significant bits (they are always zero)
   Compressed “A” = 0001. Compressed “Z” = 1010

4. Compressed code = concatenate “0” and the three 5-bit values:

   “AZA” = 0 00001 11010 00001 (16-bit value)
   0xzC80 = 00000111, 0xzC81h = 01000001

Figure 4-2 shows the format of the product ID (addresses 0xzC80-0xzC83).

Figure 4-2. Product ID Format

The manufacturer ID is located at bytes offset 0xzC80-0xzC83, where z represents the slot number probed. exprobe_space usage when searching for an EISA card is:

exprobe_space = (r, EISAIO, 0xzC80, 4, mfg_id, 0xffffffff)

The first argument (r) specifies that this probe consists of doing a single read. The second argument (EISAIO) declares that the address space is in the EISA register range. 0xzC80 is the offset of the manufacturer's unique ID. The size of this read is four bytes. mfg_id is the compressed 4-byte value that is returned by the particular card being searched for. The last argument is a mask which the mfg_id is ANDed against.

In addition to the system file described above, you must create a master file under /var/sysgen/master.d. (The name of the master file is the same as the name of the object file for the driver, but the master file must not have the “.o” suffix.) The FLAG field of the master file must at least include the character device flag c. (You do not need the s flag for EISA device drivers because lboot can probe for EISA devices.)

A more detailed description of the master file can be found in Chapter 2, “Writing a Device Driver,” and in the master(1M) man page.

The following example explores adding an ISA card device driver to the kernel. Assuming that the driver is called isacard.o, the following steps are necessary:

1. Copy the driver object file isacard.o to /var/sysgen/boot.

2. Create an isacard.sm system file in /var/sysgen/system.

   The file might contain the following lines:

   VECTOR: bustype=EISA module=isacard ctlr=0 adapter=0 iospace=(EISAIO,0x300,48) probe_space=(wr,EISAIO,0x300,1, 0x11,0xff) VECTOR: bustype=EISA module=isacard ctlr=1 adapter=0 iospace=(EISAIO,0x330,48) probe_space=(wr,EISAIO,0x330,1, 0x11,0xff)

   This would allow a kernel to support two of the same ISA cards located at different addresses. A one-byte test for card existence will be made at ISA I/O addresses 0x300 and 0x330. If either card returns the value written at one of those locations, the driver will be included in the kernel. Also a 48-byte ISA register address space will be allocated to the card without a memory address space being allocated in the example above.

3. Create a master file for the driver in the /var/sysgen/master.d directory. Check /usr/include/sys/major.h for available major device numbers or lboot can assign one. See Chapter 11, “Kernel-level Dynamically Loadable Modules (DLMs),” for more information on loadable drivers and master.d configuration:

   *Flag	Prefix	Soft	#Dev	Dependencies
   c	isa	60	–

   Note that even though the module name is referred to as isacard, the prefix for each of the driver routines can be independently declared, in this case as simply “isa.”

VECTOR: bustype=EISA module=eisacard ctlr=0 adapter=0
        iospace=(EISAIO,0x1000,0x1000)
        iospace2=(EISAMEM,0xC8000,0x10000)
        exprobe_space=(r,EISAIO,0x1C80,4, 
        0x00008107, 0xffffffff)
VECTOR: bustype=EISA module=eisacard ctlr=1 adapter=0
        iospace=(EISAIO,0x2000,0x1000)
        iospace2=(EISAMEM,0xD8000,0x10000)
        exprobe_space=(r,EISAIO,0x2C80,4, 
        0x00008107, 0xffffffff)
VECTOR: bustype=EISA module=eisacard ctlr=2 adapter=0
        iospace=(EISAIO,0x3000,0x1000)
        iospace2=(EISMEM,0xE8000,0x10000)
        exprobe_space=(r,EISAIO,0x3C80,4,
        0x00008107,0xffffffff)
VECTOR: bustype=EISA module=eisacard ctlr=3 adapter=0
        iospace=(EISAIO,0x3000,0x1000)
        iospace2=(EISMEM,0xF8000,0x10000)
        exprobe_space=(r,EISAIO,0x3C80,4,
        0x00008107,0xffffffff)

If you use the VECTOR: directive to configure a driver into the kernel, your driver can use a routine of the form drvedtinit(), where drv is the driver prefix. If your device driver object module includes a drvedtinit() routine, the system executes the drvedtinit() routine when the system boots. In general, you can use your drvedtinit() routine to perform any device driver initialization you want. Typically, the edtinit() routine is used to allocate and map in the resources that are needed for the driver to initialize the hardware and execute. The resources that might need to be initialized are:

When the system calls your driver's edtinit() routine, it hands the routine a pointer to a structure of type edt.

Synopsis

void drvedtinit(struct edt *e)
{
   your code here
}

The edt_t structure is filled in with the information taken from the system file when the operating system probes for the existence of the card. The edt_t structure is defined below.

#define NBASE 3
typedef unsigned long iopaddr_t;
typedef struct iospace {
    unchar       ios_type;       /* io space type on the adapter */
    iopaddr_t    ios_iopaddr;    /* io space base address */
    ulong        ios_size;
    caddr_t      ios_vaddr;      /* kernel virtual address */
} iospace_t;
typedef struct edt {
    uint_t       e_bus_type;    /* vme, scsi, eisa... */
    unchar       v_cpuintr;     /* cpu to send intr to */
    unchar       v_setcpuintr;  /* cpu field is valid */
    uint_t       e_adap;        /* adapter */
    uint_t       e_ctlr;        /* controller identifier */
    void*        e_bus_info;    /* bus dependent info */
    int          (*e_init)(struct edt *); /* device init/run-time probe */
    iospace_t    e_space[NBASE];
} edt_t;

In the example below, e_space array contains the iospace structures that are used to map in the card's address space. There are two steps in this process: allocating a PIO map and then mapping the requested bus space address into a kernel address.

On the Indigo2 the mapping is a fixed mapping, which permanently maps the entire EISA I/O and memory address space into kernel space, but using the piomap() call will allow your driver to remain fully compatible with potential future hardware that uses programmable I/O space map registers like those used for VME on the CHALLENGE and Onyx architectures. (Simplifies porting of the driver to future hardware.)

---

Note: The device will only respond to the requested memory address range if it has been programmed through software (in the case of an EISA card) or jumpered on the card (in the case of an ISA card).

---

Before actually beginning to program the card after mapping in the I/O space, it is wise to probe for the card's existence by writing and rereading a register located on the card. This allows the driver to recover if the device has been removed from the system since the kernel was built or if the kernel is copied to another system with a different hardware configuration.

---

Caution: The probe during edtinit() has a bus error handler in place. After this, a bus error ordinarily causes an operating system panic.

---

In the edtinit() for your driver, you must allocate the necessary mapping resources before you actually map the memory address. The mapping resource allocation and mapping calls apply across all of Silicon Graphics bus adapters (i.e., VME). Their structures are defined in <sys/pio.h.>.

piomap_t *pio_mapalloc(uint_t bus, uint_t adap, iospace_t
                       iospace, int flag, char *name)

This routine allocates a handle that specifies a mapping from kernel virtual space to I/O and memory address space. The returned piomap_t handle is used to provide the mapping to the address space through additional PIO access functions.

Currently, the bus and adap arguments must be ADAP_EISA and 0 respectively, because there is only one EISA bus on Indigo2 platforms. The name argument is a string used to identify which device has a particular space mapped.

The actual mapping is returned by:

caddr_t pio_mapaddr(piomap_t *piomap, iopaddr_t io)

This function returns the kernel virtual address that maps to the PIO-mapped I/O space address.

Silicon Graphics also supports a set of routines that allow a driver to operate on an I/O address space that has an allocated piomap, but does not have a kernel virtual address mapped to the I/O space. For example:

void pio_bcopyin(piomap_t *pmap, iopaddr_t io, caddr_t a, 
    int len)
void pio_bcopyout(piomap_t *pmap, iopaddr_t io, caddr_t a, 
    int len)

For a complete specification of the piomap* functions, see <sys/pio.h>.

---

Note: There is not currently any advantage to using the routines listed above, although they may be useful on future Silicon Graphics platforms.

---

Rather than bind the interrupt IRQ input and a specific channel for DMA to a specific VECTOR: entry at lboot time, the driver allocates these resources dynamically. In the case of interrupts, there are three parts to the process:

Once eisa_ivec_set() has been used to bind the selected IRQ to an interrupt handling routine, all interrupts generated to that IRQ cause the related handling routine to be called. Since multiple cards may be responsible for the interrupt, the driver is required to check its own hardware registers to test for the cause of the pending interrupt. The call is specified as:

eisa_ivec_set (vint_t adapter, int irq, void (func*)(), 
     int arg);

func passes arg as an argument when called. Typically, arg corresponds to the ctlr number of the device.

The process for allocating a DMA channel is similar to that for obtaining an interrupt number. The call to the eisa_dmachan_alloc() routine uses an 8-bit mask to represent DMA channels zero through seven. Note that bit four must always be masked because that channel is unavailable for a card's case. The value returned by the channel allocation routine is then saved to program the device to transfer data on that particular channel, as specified in the section describing the EISA DMA utility functions.

The following example is a possible outline initialization routine for the EISA device module declared in the previous section about the system files:

#include <sys/types.h>
#include <sys/edt.h>
#include <sys/pio.h>
#include <sys/eisa.h>
#include <sys/cmn_err.h>

struct edrv_info {
   caddr_t e_addr[NBASE];
   int     e_dmachan;
} einfo[4];

#define CARD_ID        0x0163b30a
#define IRQ_MASK       0x0018
#define DMACHAN_MASK   0x7a

edrv_edtinit(edt_t *e)
{
   int iospace, eirq, edma_chan;
   struct edrv_info *einf;
   piomap_t *pmap;
   einf = &einfo[e->e_ctlr];

   /* map address spaces */
   for (iospace = 0; iospace < NBASE; iospace++) {
      if (!e->e_space[iospace].ios_iopaddr)
         break;

      pmap = pio_mapalloc(e->e_bus_type, e->e_adap,
         &e->e_space[iospace], PIOMAP_FIXED, “edrv”);

      einf->e_addr[iospace] = pio_mapaddr(pmap,
         e->e_space[iospace].ios_iopaddr);
   }

      /* should mark not-present somewhere */
      return;
   }

   /* Initialize Interrupt Vector */
   eirq = eisa_ivec_alloc(e->e_adap, IRQ_MASK,
          EISA_EDGE_IRQ);
   if (eirq < 0) {
      cmn_err(CE_WARN,
      ”edrv: ctlr %d could not allocate IRQ\n”,
         e->e_ctlr);

      /* should mark unavailable */
      return;
   }

   eisa_ivec_set(e->e_adap, eirq, edrv_intr, e->e_ctlr);

   /* Allocate DMA Channel */
   edma_chan = eisa_dmachan_alloc(e->e_adap, DMACHAN_MASK);
   if (edma_chan < 0) {
      cmn_err(CE_WARN,
      ”edrv: ctlr %d could not allocate DMA Chan\n”,
         e->e_ctlr);

      /* should mark unavailable */
      return;
   }
   einf->e_dmachan = edma_chan;
   
}

The EISA specification provides that you can lock the bus and hold it for exclusive access if you assert LOCK*. This allows atomic operations such as a test-and-set, and thus sets the basis for implementing semaphores between the CPU and bus masters. Because the actual system bus (a GIO bus) does not support a LOCK* operation, Silicon Graphics provides an interface that the CPU can use for read-modify-write style instructions.

On Silicon Graphics systems that support EISA, if a bus master asserts LOCK*, some additional constraints apply to how long the bus master can hold the lock. Your locks should work correctly as long as your usage conforms to the read-modify-write paradigm used by the CPU programmatic interface. The following routines, which are also supported for VME device drivers, provide atomic and/or operations: they find the appropriate-sized mask by reading the PIO address, then they rewrite, modified by the mask value m.

void pio_orb_rmw(piomap_t* pio, iopaddr_t io, uchar m)
void pio_orh_rmw(piomap_t* pio, iopaddr_t io, ushort m)
void pio_orw_rmw(piomap_t* pio, iopaddr_t io, uint m)
void pio_andb_rmw(piomap_t* pio, iopaddr_t io, uchar m)
void pio_andh_rmw(piomap_t* pio, iopaddr_t io, ushort m)
void pio_andw_rmw(piomap_t* pio, iopaddr_t io, uint m)

DMA devices use a logical address. If your driver passes addresses to bus masters, it must use a special set of DMA mapping routines to map the DMA target into physical addresses. The system uses these special mapping routines to support physical address spaces larger than 32 bits. On Silicon Graphics systems that support EISA, the physical address is used. The map structure returned, dmamap_t, is defined in sys/dmamap.h.

dmamap_t  *dma_mapalloc(int bus, int adap, int npages, int flag)
void       dma_mapfree(dmmap_t *dmamap)
int        dma_map(dmamap_t *dmamap, caddr_t addr, int len)
uint       dma_mapaddr(dmamap_t *dmamap, caddr_t addr)

Indigo2 systems do not support bus address mapping, so calls to dma_map on an Indigo2, as opposed to a CHALLENGE, system are limited to a single page. Multiple virtual pages cannot be mapped into physically contiguous pages with dma_map unless the virtual pages have been allocated to be contiguous.

For a complete description of these routines, refer to “Using DMA Maps” in Chapter 3, “Writing a VME Device Driver.”

The mapped address returned by dma_mapaddr() must be used when specifying the bus address used by bus master cards or the following DMA routines. The map type used must be DMA_EISA.

Table 4-1 lists the DMA utility routines.