The device driver makes known which entry points it supports by giving them public names in its object module. The lboot command links together the object modules of drivers and other kernel modules to make a bootable kernel. lboot recognizes the entry points by the form of their names. (See the lboot(1M) and autoconfig(1M) reference pages.)  

#define PREFIX_NAME(name) sample_ ## name
/* -----  driver prefix:  ^^^^^^^ defined there only */
#define PREFIX_ONLY PREFIX_NAME( )
#define STRINGIZER(x) # x
#define PREFIX_STRING STRINGIZER(PREFIX_ONLY)

PREFIX_NAME(init)()
{ ... }

#define PFX_INIT      PREFIX_NAME(init)
#define PFX_START     PREFIX_NAME(start)

PFX_INIT()
{ ... }

The names of all possible driver entry points and their purposes are summarized in Table 7-1. The entry point names are in alphabetic order, not logical order. Device driver entry points are discussed in this chapter. Entry points to STREAMS drivers are discussed in Chapter 22, “STREAMS Drivers”.

 To open the reference page, click on the reference page name. To jump to the discussion of an entry point, click on the “Discussion” cross-reference.

You specify D_MP in pfxdevflag to tell lboot that your driver is designed to operate in a multiprocessor system. The top half of the driver is designed to cope with multiple concurrent entries in multiple CPUs. The top and bottom halves synchronize through the use of semaphores or locks and do not rely on interrupt masking for critical sections. These issues are discussed further under “Designing for Multiprocessor Use”.

All drivers must be designed in this fashion and confirm it with D_MP, even drivers written for uniprocessor workstations.

Driver interrupt routines execute as independent, preemptable threads of control within the kernel address space (see “Interrupts as Threads”). D_MT indicates that this driver understands that it can be run as one or more cooperating threads, and uses kernel synchronization primitives to serialize access to driver common data structures.

In IRIX 6.4, D_MT does not commit a driver to anything beyond the meaning of D_MP.

This driver supports the PCI Hot Plug insertion of its devices by providing an attach() function that initializes the device hardware and software from a powered-down state while the system is running. A driver can support Hot Plug insertion, Hot Plug removal, or both. This flag has meaning only on an SGI Origin 3000 server series and is ignored on non-PCI drivers.

This driver supports the PCI Hot Plug removal of its devices by providing a detach() function that terminates operation of the device hardware and releases all software resources so the device can be powered down while the system is running. A driver can support Hot Plug insertion, Hot Plug removal, or both. This flag has meaning only on an SGI Origin 3000 server series and is ignored on non-PCI drivers.

You specify D_WBACK in pfxdevflag to tell lboot that a block driver performs any necessary cache write-back operations through explicit calls to dki_dcache_wb() and related functions (see the dki_dcache_wb(D3) reference page).

When D_WBACK is not present in pfxdevflag, the physiock() function ensures that all cached data related to buf_t structures is written back to main memory before it enters the driver's strategy routine. (See the physiock(D3) reference page and “Entry Point strategy()”.)

In IRIX versions before IRIX 6.4, a driver was allowed to have no pfxdevflag, or to have one containing only a flag named D_OLD. This flag, or the absence of a flag, requested compatibility handling for an obsolete driver interface. Support for this interface has been withdrawn effective with IRIX 6.4.

The initialization entry points of ordinary (nonloadable) drivers are called during system startup, after interrupts have been enabled and before the message “The system is coming up” is displayed on the console. In all cases, interrupts are enabled and basic kernel services are available at this time. However, other loadable or optional kernel modules might not have been initialized, depending on the sequence of statements in the files in /var/sysgen/system.

Whenever a driver is initialized, the entry points are called in the following sequence:

The pfxinit() entry point is called once during system startup or when a loadable driver is loaded. It receives no input arguments; its prototype is simply:

void pfxinit(void);

You can use this entry point for any of the following purposes:

A driver that is brought into the system by a USE or INCLUDE line in a system configuration file (see “Configuring a Kernel” in Chapter 9) typically initializes in the pfxinit() entry point.

The pfxedtinit() entry is designed to initialize devices that are configured using the VECTOR statement in the system configuration file (see “Kernel Configuration Files” in Chapter 2). This includes GIO, EISA, and VME devices. The entry point name is a contraction of “early device table initialization.”

The VECTOR statement specifies hardware details about a device on the VME, GIO, or EISA bus, including such items as iospace addresses, interrupt level, bus number, and a driver-defined integer value referred to as the controller number. The VECTOR statement also specifies the driver that is to manage the device; and it can specify probe operations that let the kernel test for the existence of the device.

When the kernel processes a VECTOR statement during bootstrap, it executes the probe, if one is specified. When the probe is successful (or no probe is given), the kernel makes sure that the specified driver is loaded. Then it stores the hardware parameters from the VECTOR statement in a structure of type edt_t. (This structure is declared in sys/edt.h.)

The kernel calls the specified driver's pfxedtinit() entry one time for each VECTOR statement that named that driver and had a successful probe (or had no probe). VECTOR statements are processed in reverse sequence to the order in which they are coded in /var/sysgen/system files.

The prototype of the pfxedtinit() entry is

void pfxedtinit(edt_t *e);

The edt_t contains at least the following fields (see the system(4) reference page for the corresponding VECTOR parameters):

The VME form of the VECTOR statement for IRIX 6.4 is discussed at length under “Defining VME Devices with the VECTOR Statement” in Chapter 12. The operation of the pfxedtinit() entry for VME is discussed under “Initializing a VME Device” in Chapter 13.

The pfxstart() entry point is called at system startup, and whenever a loadable driver is loaded. It is called after pfxedtinit() and pfxinit(), but before any other entry point such as pfxopen(). The pfxstart() entry point receives no arguments; its prototype is simply

void pfxstart(void);

The pfxstart() entry point is a suitable place to allocate a poll-head structure using phalloc(), as discussed in “Use and Operation of poll(2)”.

The pfxreg() entry point is specifically intended to allow a driver that supports the pfxattach() entry point (see “Entry Point attach()”) to register with the kernel. At present, the only buses that support device attachment and registration (accessible to OEMs) are the PCI and SCSI buses. The functions used to register as a PCI driver are discussed in “Configuration Register Initialization” in Chapter 20.

The pfxattach() entry point is called to notify the driver that the PCI bus adapter has located a device that has a vendor and device ID for which the driver has registered (see “Entry Point reg()”).

This entry point is typically called during bootstrap, while the kernel is probing the PCI bus. However, for a PCI Hot Plug insert operation it can occur at a later time, if the device is physically plugged in or activated after the system has initialized. In an Origin2000 system, the entry point is executed in the hardware node closest to the device being attached. (See “Allocating Memory in Specific Nodes of a Origin2000 System” in Chapter 8.)

The purpose of the entry point is to make the device usable, including making it visible in the hwgraph by creating vertexes and edges to represent it.

The pfxdetach() entry point is called when the kernel decides to detach a device. As of IRIX 6.4 this is only done for PCI devices. The need to detach can be created by a hardware failure or a PCI Hot Plug removal operation. If the entry point is not defined, the device cannot be detached.

In general, the detach entry point must undo as much as possible of the work done by the pfxattach() entry point (see “Entry Point attach()”). This includes such actions as:

The state of the device itself is not known. If the detach code attempts to reset the device or put it in a quiescent state, the code should be prepared for errors to occur.

The kernel calls a device driver's pfxopen() entry when a process executes the open() system call on any device special file (see the open(2) reference page). It is also called when a process executes the mount() system call on a block device (see the mount(2) reference page). (For the pfxopen() entry point of a STREAMS driver, see “Entry Point open()” in Chapter 22.)

The prototype of pfxopen() is as follows:

int pfxopen(dev_t *devp, int oflag, int otyp, cred_t *crp);

The argument values are

---

Note: In releases before IRIX 6.4, a driver's pfxdevflag constant could contain D_OLD. In that case, the first argument to pfxopen() was a dev_t value, not a pointer to a dev_t value. However, this compatibility mode is no longer supported. The first argument to pfxopen() is always a pointer to a dev_t.

---

The open(D2) reference page discusses the kind of work the pfxopen() entry point can do. In general, the driver is expected to verify that this user process is permitted access in the way specified in otyp (reading, writing, or both) for the device specified in *devp. If access is not allowable, the driver returns a nonzero error code from sys/errno.h, for example ENOMEM or EBUSY.

The kernel calls the pfxclose() entry when the last process calls close() or umount() for the device special file. It is important to know that when the device can be opened by multiple processes, pfxclose() is not called for every close() function, but only when the last remaining process closes the device and no other processes have it open. The function prototype and arguments of pfxclose() are

int pfxclose(dev_t dev, int flag, int otyp, cred_t *crp);

The arguments are the same as were passed to pfxopen(). However, the flag argument is not necessarily the same as at any particular call to open().

It is up to you to design the meaning of “close” for this type of device. The close(D2) reference page discusses some of the actions the driver can do. Some considerations are:

When a device can do DMA, the pfxclose() entry point is the appropriate place to make sure that all I/O has terminated. Since all processes have closed the device, there is no reason for it to continue transmitting data into memory; and if it does continue, it might corrupt memory.

The pfxclose() entry can detect an error and report it with a return code. However, the file is closed or unmounted regardless.

The command numbers supported by pfxioctl() are arbitrary; but the recommended practice is to make sure that they are different from those of any other driver. One method to achieve this is suggested in the ioctl(D2) reference page.

The ioctl() entry point may need to interpret a structure prepared in the user process. In a 64-bit system, the user process can be either a 32-bit or a 64-bit program. For discussion of this issue, see “Handling 32-Bit and 64-Bit Execution Models”.

The kernel returns 0 to the ioctl() system function unless the pfxioctl() function returns an error code. In the event of an error, the kernel may also return the code the driver places in *rvalp, if any, or -1. To ensure that the user process sees a specific error code, it is a good idea to set the code in *rvalp, and return that value. If your device driver does not define a pfxdevflag or sets it to D_OLD, see “Driver Flag Constant”.

The pfxread() and pfxwrite() entry points are similar to each other—only the direction of data transfer differs. The prototypes of the functions are

int pfxread (dev_t dev, uio_t *uiop, cred_t *crp);
int pfxwrite(dev_t dev, uio_t *uiop, cred_t *crp);

The arguments are

hypo_read (dev_t dev, uio_t *uiop, cred_t *crp)
{
   // ...validate the operation... //
   return physiock(hypo_strategy, /* our strategy entry */
                  0,   /* allocate temp buffer & buf_t */
                  dev, /* dev_t arg for strategy */
                  B_READ, /* direction flag for buf_t */
                  uiop);
}

A block device driver does not directly support system calls by user processes. Instead, it provides services to a filesystem such as XFS, or to the memory paging subsystem of IRIX. These subsystems call the pfxstrategy() entry point to read data in whole blocks.

Calls to pfxstrategy() are not directly related in time to system functions called by a user process. For example, a filesystem may buffer many blocks of data in memory, so that the user process may execute dozens or hundreds of write() calls without causing an entry to the device driver. When the user function closes the file or calls fsync()—or when for unrelated reasons the filesystem needs to free some buffers—the filesystem calls pfxstrategy() to write numerous blocks of data.

In a driver that supports the character interface as well, the pfxstrategy() entry can be called indirectly from the pfxread(), pfxwrite() and pfxioctl() entries, as described under “Calling Entry Point strategy() From Entry Point read() or write()”.

The prototype of the pfxstrategy() entry point is

int pfxstrategy(struct buf *bp);

The argument is the address of a buf_t structure, which gives the strategy routine the information it needs to perform the I/O:

For more on the contents of the buf_t structure, see “Structure buf_t” in Chapter 8 and the buf(D4) reference page.

The driver uses the information in the buf_t to validate the data transfer and programs the device to start the transfer. Then it stores the address of the buf_t where the interrupt handler can find it (see “Interrupt Entry Point and Handler”) and calls biowait() to wait for the operation to complete. For the next step, see “Completing Block I/O” (see also the biowait(D3) reference page). 

The IRIX version of poll() allows a process to wait for events of different types to occur on any combination of devices, files, and STREAMS (see the poll(2) and select(2) reference pages). It is possible for multiple processes to be waiting for events on the same device.

It is up to you as the designer of a driver to decide which of the events that are documented in poll(2) are meaningful for your device. Other requested events simply never happen to the device.

Much of the complexity of poll() is handled by the IRIX kernel, but the kernel requires the assistance of any device driver that supports poll(). The driver is expected to allocate and hold a pollhead structure (declared in sys/poll.h) for each minor device that it supports. Allocation is simple; the driver merely calls the phalloc() kernel function. (The pfxstart() entry point is a suitable place for this call; see “Entry Point start()”.)

There are two phases to the operation of poll(). When the system function is called, the kernel calls the pfxpoll() entry point to find out if any requested events are pending at this time. If the kernel finds any event s pending (on this or any other polled object), the poll() function returns to the user process. Nothing further is required.

However, when no requested event has happened, the user process expects the poll() function to block until an event has occurred. The kernel must implement this delay. It would be too inefficient for the kernel to repeatedly test for events. The kernel must rely on device drivers to notify it when an event has occurred.

The prototype for pfxpoll() is as follows:

int pfxpoll(dev_t dev, short events, int anyyet,
           short *reventsp, struct pollhead **phpp, 
           unsigned int *genp);

The argument values are

Example 7-4 shows the pfxpoll() code of a hypothetical device driver. Only three event tests are supported: POLLIN and POLLRDNORM (treated as equivalent) and POLLOUT. The device driver maintains an array of pollhead structures, one for each supported minor device. These are presumably allocated during initialization.

struct pollhead phds[MAXMINORS];
#define OUR_EVENTS (POLLIN|POLLOUT|POLLRDNORM)
hypo_poll(dev_t dev, short events, int anyyet,
          short *reventsp, struct pollhead **phpp, unsigned int *genp)
{
   minor_t dminor = geteminor(dev);
   short happened = 0;
   short wanted = events & OUR_EVENTS;
   *genp = POLLGEN(&phds[dminor])
   if (wanted & (POLLIN|POLLRDNORM))
   {
      if (device_has_data_ready(dminor))
         happened |= (POLLIN|POLLRDNORM);
   }
   if (wanted & POLLOUT)
   {
      if (device_ready_for_output(dminor))
         happened |= POLLOUT;
   }
   if (device_pending_error(dminor))
      happened |= POLLERR;
   if (0 == (*reventsp = happened))
   {
      if (anyyet) *phpp = &phds[dminor]
   }
   return 0;
}

The code in Example 7-4 begins by discarding any unsupported event flags that might have been requested, and passes back the driver's pollhead generation number before probing the device. Then it tests the remaining flags against the device status. If the device has an uncleared error, the code inserts the POLLERR event. If no events were detected, and if the kernel requested it, the address of the pollhead structure for this minor device is returned.

If no requested event has occurred, the process will queue awaiting the requested events, provided that no event has occurred in the interim—before it is able to queue. This is determined by comparing the pollhead generation number at the time of queueing with the pollhead generation number passed back at the initial request. Since a call to pollwakeup() increments the pollhead generation number, any difference in the current pollhead generation number to the one at the time of the initial request indicates a device event has occurred, and the device must be queried again to determine if it was a requested event. If the values of the previous and current pollhead generation numbers are equal, the process queues.

The purpose of the mmap() system function (see the mmap(2) reference page) is to make the contents of a file directly accessible as part of the virtual address space of the user process. The results depend on the kind of file that is mapped:

In all cases, access is gained through normal load and store instructions, without the overhead of calling system functions such as read(). Furthermore, the same mapping can be executed by other processes, in which case the same memory, or file, or device is shared by multiple, concurrent processes. This is how shared memory segments are achieved.

The pfxmap() entry point can be defined in either a character or a block driver (it is the only mapping entry point that a block driver can supply). The function prototype is

int pfxmap(dev_t dev, vhandl_t *vt,
          off_t off, int len, int prot);

The argument values are

The first task of the driver is to verify that the access specified in prot is allowed. The next task is to validate the off and len values: do they fall in the valid address space of the device?

When the device driver approves of a mapping, it uses a kernel function, v_mapphys(), to establish the mapping. This function (documented in the v_mapphys(D3) reference page) takes the vhandle_t, an address in kernel cached or uncached memory, and a length. It makes the specified region of kernel space a part of the address space of the user process.

For example, a pseudo-device driver that intends to share kernel virtual memory with user processes would first allocate the memory:

caddr_t *kaddr = kmem_alloc (len, KM_CACHEALIGN);

It would then use the address of the allocated memory with the vhandle_t value it had received to map the allocated memory into the user space:

v_mapphys (vt, kaddr, len)

---

Note: There are no special precautions to take when mapping cached memory into user space, or when mapping device registers or bus addresses. However, you should almost never map uncached memory into user space. The effects of uncached memory access are hardware dependent and differ between multiprocessors and uniprocessors. Among uniprocessors, the IP26 and IP28 CPU modules have highly restrictive rules for the use of uncached memory (see “Uncached Memory Access in the IP26 and IP28” in Chapter 1). In general, mapping uncached memory makes a driver nonportable and is likely to lead to subtle failures that are hard to resolve.

---

Example 7-5 contains an edited fragment of code from a Silicon Graphics device driver. This pseudo-device driver, whose prefix is flash_, provides access to “flash” PROM in certain computer models. It allows a user process to map the PROM into user space.

Example 7-5. Edited Fragment of flash_map()

int flash_map(dev_t dev, vhandl_t *vt, off_t off, long len) { long offset = (long) off; /*Actual offset in flash prom*/ /* Don't allow requests which exceed the flash prom size */ if ((offset + len) > FLASHPROM_SIZE) return ENOSPC; /* Don't allow non page-aligned offsets */ if ((offset % NBPC) != 0) return EIO; /* Only allow mapping of entire pages */ if ((len % NBPC) != 0) return EIO; return v_mapphys(vt, FLASHMAP_ADDR + offset, len); }

---

Note: Because there is no way for a driver to retract a successful call to v_mapphys(), your driver must return success to a pfxmap() call if v_mapphys() succeeds. In other words, you should make the call to v_mapphys() the last part of your pfxmap() routine, and only call it if you have determined that there have been no errors in any previous part of this routine. If there have been errors, the routine should return an error and not call v_mapphys(). If there have been no errors, then pfxmap() can return error or success based on the call to v_mapphys().

---

When the driver allocates some memory resource associated with the mapping, and when more than one mapping can be active at a time, the driver needs to tag each memory resource so it can be located when the pfxunmap() entry point is called. One answer is to use the v_gethandle() macro defined in ksys/ddmap.h. This macro takes a pointer to a vhandle_t and returns a unique pointer-sized integer that can be used to tag allocations. No other information in ksys/ddmap.h is supported for driver use.

The pfxmmap() (note: two letters “m”) entry can be used only in a character device driver. The prototype is

int pfxmmap(dev_t dev, off_t off, int prot);

The argument values are

The function is expected to return the page frame number (PFN) that corresponds to the offset off in the device address space. A PFN is an address divided by the page size. (See “Working With Page and Sector Units” in Chapter 8 for page unit conversion functions.)

This entry point is supported only for compatibility with SVR4. When the kernel needs to map a character device, it looks first for pfxmap(). It calls pfxmmap() only when pfxmap() is not available. The differences between the two entry points are as follows:

The kernel calls the pfxunmap() entry point after a mapping is created using the pfxmap() entry point. This entry should be supplied, even if it is an empty function, when the pfxmap() entry point is supplied. If it is not supplied, the munmap() system function returns the ENODEV error to the user process.

The pfxunmap() entry point is only called when the mapped region has been completely unmapped by all processes. For example, suppose a parent process calls mmap() to map a device. Then the parent creates one or more child processes using sproc(). Each child shares the address space, including the mapped segment. A process in the share group can terminate, or can explicitly unmap() the segment or part of the segment, but these actions do not result in a call to pfxunmap(). Only when the last process with access to the segment has fully unmapped the segment is pfxunmap() called.

On entry, the kernel has completed unmapping the object from the user process address space. This entry point does not need to do anything to affect the user address space; it only needs to release any resources that were allocated to support the mapping. The prototype is

int pfxunmap(dev_t dev, vhandl_t *vt);

The argument values are

If the driver allocated no resources to support a mapping, no action is needed here; the entry point can consist of a “return 0” statement.

When the driver does allocate memory or a PIO map to support a mapping, and supports multiple mappings, the driver needs to identify the resource associated with this particular mapping in order to release it. The vt_gethandle() function returns a unique number based on the vt argument; this can be used to identify resources.

The association between an interrupt and the driver is established in different ways depending on the hardware.

In all cases, the driver specifies the interrupt handler as the address of a function to be called, with an argument to be passed to the function when it is called. This argument value is typically the address of a data structure in which the driver has stored information about the device. Alternatively, it could be the dev_t that names the device—from which the interrupt handler can get device information, see “Allocating Storage for Device Information”.

In general, the interrupt handler implements the following tasks.

The details of each of these tasks depends on the hardware and on the design of the data structures used by the driver top half. In general, you should design an interrupt handler so that it does the least possible and exits as quickly as possible.

Calling pollwakeup()

When the interrupt represents an event that can be reported by the driver's pfxpoll() entry point (see “Entry Point poll()”), the interrupt handler must report the event to the kernel, in case some user process is waiting in a poll() call. Hypothetical code to do this is shown in Example 7-6.

Example 7-6. Hypothetical Call to pollwakeup()

hypo_intr(int ivec) { struct hypo_dev_info *pinfo; if (! pinfo = find_dev_info(ivec)) return; /* not our device */ ... if (pinfo->have_data_flag) pollwakeup (pinfo->phead, POLLIN, POLLRDNORM); if (pinfo->output_ok_flag) pollwakeup (pinfo->phead, POLLOUT); ...

---

Note: It's important that the call to pollwakeup() occurs after any state has been updated by the event interrupt routine.

---

In traditional UNIX design, and in versions of IRIX preceding IRIX 6.4, an interrupt is handled as an asynchronous trap. The hardware trap handler calls the driver's interrupt function as a subroutine. In these systems, when the interrupt handler code is entered the system is in an unknown state. As a result, the interrupt handler can use only a restricted set of kernel services, and no services that can sleep.

Starting with IRIX 6.4, the IRIX kernel does all its work under control of lightweight executable entities called “kernel threads.” When a device driver registers an interrupt handler, the kernel allocates a thread to execute that handler. The thread begins execution by waiting on an internal semaphore.

When a hardware interrupt occurs, the trap code merely posts the semaphore on which the handler's thread is waiting. Soon thereafter, the interrupt thread is scheduled to execute, and it calls the function registered by the driver.

The differences from previous releases are small. It is still true that the interrupt handler code is entered unpredictably, at a high priority; does little; and exits quickly. However, there are the following differences compared to earlier systems:

In IRIX 6.4, the driver writer has no control over the selection of interrupt thread priority. The kernel assigns a high relative priority to threads that execute interrupt handlers. However, higher priorities exist, and an interrupt thread can be preempted.

In historical UNIX systems, which were uniprocessor systems, when the only CPU is executing the interrupt handler, nothing else is executing. The hardware architecture ensured that top-half code could not preempt the interrupt handler; and the top half could use functions such as splhi() to block interrupts during critical sections (see “Priority Level Functions” in Chapter 8). An interrupt handler could only be preempted by an interrupt of higher priority—which would be an interrupt for a different driver, and so would have no conflicts with this driver over the use of data.

None of these comfortable assumptions are tenable any longer.

Another interrupt cannot be handled from the same device until the interrupt handler function returns. The interrupt thread runs at very nearly the highest priority, so all but the most essential work is suspended in the interrupted CPU until the handler returns.

The pfxunreg() entry point is called in a loadable driver, prior to the call to the pfxunload() entry point. This entry point is used by drivers that support the pfxattach() entry point (see “Attach and Detach Entry Points ”). Such drivers have to register with the kernel as supporting devices of certain types. Before unloading, a driver needs to retract this registration, so the kernel will not call the driver to attach another device.

If pfxunreg() returns a nonzero error code, the driver is not unloaded.

The pfxunload() entry point is called when the kernel is about to dynamically remove a loadable driver from the running system. A driver can be unloaded either because all its devices are closed and a timeout has elapsed, or because the operator has used the ml command (see the ml(1) reference page). The kernel calls pfxunload() only when no device special files managed by the driver are open. If any device had been opened, the pfxclose() entry has been called.

It is not easy to retain state information about the device over the time when the driver is not in memory. The entire text and data of a loadable driver, including static variables, are removed and reloaded. Global variables defined in the descriptive file (see “Describing the Driver in /var/sysgen/master.d” in Chapter 9) remain in memory after the driver is unloaded, as do any allocated memory addressed from a hwgraph vertex (see “Attaching Information to Vertexes” in Chapter 8). Be sure not to store any addresses of driver code or driver static variables in global variables or vertex structures, since the driver addresses will be different when the driver is reloaded.

Other than data addressed from the hwgraph, allocated dynamic memory should be released. The driver should also release any process handles (see “Sending a Process Signal” in Chapter 8).

The driver is not required to unload. If the driver should not be unloaded at this time, it returns a nonzero return code to the call, and the kernel does not unload it. There are several reasons why a driver should not be unloaded.

A driver should never permit unloading when there is any kind of pointer to the driver held in any kernel data structure. It is a frequent design error to unload when there is a live pointer to the driver. Unpredictable kernel panics often result.

One example of a live pointer to a driver is a pending callback function. Any pending itimeout() or bufcall() timers should be cancelled before returning 0 from pfxunload(). Another example is a registered interrupt handler. The driver must disconnect any interrupt handler before unloading; or else refuse to unload.

The kernel calls the pfxhalt() entry point, if one exists, while performing an orderly system shutdown (see the halt(1) reference page). No other driver entry points are called after this one. The prototype is simply

void pfxhalt(void);

Since the system is shutting down, there is no point in returning allocated memory. The only purpose this entry point can serve is to leave the device in a safe and stable condition. For example, this is the place at which a disk driver could command the heads of the drive to move to a safe zone for power off.

The driver cannot assume that interrupts are disabled or enabled. The driver cannot block waiting for device actions, so whatever commands it issues to the device must take effect immediately.

The pfxsize() entry point is required of block device drivers. It reports the size of the device in “sector” units, where a “sector” size is declared as NBPSCTR in sys/param.h (currently 512). The prototype is

int pfxsize(dev_t dev);

The device major and minor numbers can be extracted from the dev argument. The entry point is not called until pfxopen() has been called. Typically the driver will calculate the size of the medium during pfxopen().

Since the int return value is 32 bits in all systems, the largest possible block device is 1,024 gigabytes ((2³¹*512)/1,024³).

The pfxprint() entry point is called from the kernel to display a diagnostic message when an error is detected on a block device. The prototype and the complete logic of the entry point is shown in Example 7-7.

#include <sys/cmn_err.h>
#include <sys/ddi.h>
int hypo_print(dev_t dev, char *str)
{
   cmn_err(CE_NOTE,"Error on dev %d: %s\n",geteminor(dev),str);
   return 0;
}

A multiprocessor has two or more CPU modules, all of the same type. The CPUs execute independently, but all share the same main memory. Any CPU can execute the code of the IRIX kernel, and it is common for two or more CPUs to be executing kernel code, including driver code, simultaneously.

When designing an upper-half entry point, keep in mind that it could be executed concurrently with any other upper-half entry point, and that the one entry point could even be executed concurrently by multiple CPUs. Only a few entry points are immune:

Other upper-half entry points, and all STREAMS entry points, can be entered concurrently by multiple CPUs, when the driver is multiprocessor-aware. In earlier versions of IRIX, you could place a flag in the pfxdevflag of a character driver that made the kernel run the driver only on CPU 0. This effectively serialized all use of that driver. That feature is no longer supported. You must deal with concurrency.

Upper-half entry points prepare work for the device to do, and the interrupt handler reports the completion of the device action (see “Interrupt Handler Operation”). In a block device driver, this communication is relatively simple. In a character driver, you have more design options. The kernel functions mentioned in the following topics are covered under “Waiting and Mutual Exclusion” in Chapter 8.

#ifdef INTR_KTHREADS
#define INT_LOCK_TYPE mutex_t
#define INT_LOCK_INIT(p) MUTEX_INIT(p,MUTEX_DEFAULT,”DRIVER_NAME”)
#define INT_LOCK_LOCK(p) MUTEX_LOCK(p,-1)
#define INT_LOCK_FREE(p) MUTEX_UNLOCK(p)
#else /* not a threaded kernel */
#define INT_LOCK_TYPE struct{lock_t lk, int cookie}
#define INT_LOCK_INIT(p) LOCK_INIT(&p->lk,(uchar_t)-1,plhi,(lkinfo_t)-1)
#define INT_LOCK_LOCK(p) (p->cookie=LOCK(&p->lk,plhi))
#define INT_LOCK_FREE(p) UNLOCK(&p->lk,p->cookie)
#endif

As a general approach, you can convert a uniprocessor driver to make it multiprocessor-safe in the following steps:

In performing the conversion, you can look for calls to spl*() functions as marking points at which work is needed. These functions are used for mutual exclusion in a uniprocessor, but they are all ineffective or unnecessary in a multiprocessor-safe driver.

The code in Example 7-9 shows typical logic in a uniprocessor character driver.

s = splvme();
flag |= WAITING;
while (flag & WAITING) {
   sleep(&flag, PZERO);
}
splx(s);

The upper half calls the splvme() function with the intention of blocking interrupts, and thus preventing execution of this driver's interrupt handler while the flag variable is updated. In a multiprocessor this is ineffective because at best it sets the interrupt level on the current CPU. The interrupt handler can execute on another CPU and change the variable. The corresponding interrupt handler is shown in the following example.

if (flag & WAITING) {
   wakeup(&flag);
   flag &= ~WAITING;
}

The interrupt handler could execute on another CPU, and test the flag after the upper half has called splvme() and before it has set WAITING in flag. The interrupt is effectively lost. This would happen rarely and would be hard to repeat, but it would happen and would be hard to trace. A more reliable, and simpler, technique is to use a semaphore. The driver defines a global semaphore:

static sema_t sleeper;

A driver with multiple devices would have a semaphore per device, perhaps as an array of sema_t items indexed by device minor number. The semaphore (or array) would be initialized to a starting value of 1 in the pfxinit() or pfxstart() entry:

void hypo_start()
{
...
   initnsema(&sleeper,1,"sleeper");
}

After the upper half started a device operation, it would await the interrupt using psema():

psema(sleeper,PZERO);

The PZERO argument makes the wait immune to signals. If the driver should wake up when a signal is sent to the calling process (such as SIGINT or SIGTERM), the second argument can be PCATCH. A return value of -1 indicates the semaphore was posted by a signal, not by a vsema() call. The interrupt handler would use vsema() to post the semaphore.