Driver Structure Overview

Figure 8-1 on page 162 shows data structures and routines that define the structure of a character device driver. Device drivers typically include the following:

• Device loadable driver section
• Device configuration section
• Device access section

Character Driver Device Access

The shaded device access section in Figure 8-1 illustrates character driver entry points.

---

Note - For a description of block drivers and block driver device access, see Chapter 9, "Drivers for Block Devices".

---

Figure 8-1

Entry Points

Associated with each device driver is a dev_ops(9S) structure, which in turn refers to a cb_ops(9S) structure. These structures contain pointers to the driver entry points and must be set by the driver. Table 8-1 lists the character device driver autoconfiguration routines and entry points.

Table 8-1

Entry Point	Description
_init(9E)	Initializes the loadable driver module.
_info(9E)	Returns the loadable driver module information.
_fini(9E)	Prepares a loadable driver module for unloading.
identify(9E)	Identifies whether the device driver supports a physical device.
probe(9E)	Determines if a device is present.
attach(9E)	Performs device-specific initialization.
detach(9E)	Removes device-specific state.
getinfo(9E)	Gets device driver information.
open(9E)	Gains access to a device.
close(9E)	Relinquishes access to a device.
read(9E)	Reads data from device.
aread(9E)	Reads data asynchronously from device.
write(9E)	Writes data to device.
awrite(9E)	Writes data asynchronously to device.
ioctl(9E)	Performs arbitrary operations.
prop_op(9E)	Manages arbitrary driver properties.
mmap(9E)	Checks virtual mapping for a memory mapped device.
segmap(9E)	Maps device memory into user space.
chpoll(9E)	Polls device for events.

---

Note - Some of these entry points may be replaced by nodev(9F) or nulldev(9F) as appropriate.

---

Autoconfiguration

The attach(9E) routine should perform the common initialization tasks that all devices require. Typically, these tasks include:

• Allocating per-instance state structures
• Registering device interrupts
• Mapping the device's registers
• Initializing mutex and condition variables
• Creating minor nodes

See "attach( )" on page 105 for code examples of these tasks.

Character device drivers create minor nodes of type S_IFCHR. This causes a character special file representing the node to eventually appear in the /devices hierarchy.

Code Example 8-1 Character driver attach(9E) routine

static int
xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
    switch (cmd) {
    case DDI_ATTACH:
        allocate a state structure and initialize it.
        map the device's registers.
        add the device driver's interrupt handler(s).
        initialize any mutexes and condition variables.
        /*
         * Create the device's minor node. Note that the node_type
         * argument is set to DDI_NT_TAPE.
         */
        if (ddi_create_minor_node(dip, "minor_name", S_IFCHR,
             minor_number, DDI_NT_TAPE, 0) == DDI_FAILURE) {
             free resources allocated so far.
             /* Remove any previously allocated minor nodes */
             ddi_remove_minor_node(dip, NULL);
             return (DDI_FAILURE);
        }
        ...
        return (DDI_SUCCESS);

    default:
        return (DDI_FAILURE);
    }
}

Controlling Device Access

Access to a device by one or more application programs is controlled through the open(9E) and close(9E) entry points. The open(9E) routine of a character driver is always called whenever an open(2) system call is issued on a special file representing the device. For a particular minor device, open(9E) may be called many times, but the close(9E) routine is called only when the final reference to a device is removed. If the device is accessed through file descriptors, this is by a call to close(2) or exit(2). If the device is accessed through memory mapping, this could also be by a call to munmap(2).

open( )

int xxopen(dev_t *devp, int flag, int otyp, cred_t *credp);

The primary function of open(9E) is to verify that the open request is allowed.

Code Example 8-2 Character driver open(9E) routine.

static int
xxopen(dev_t *devp, int flag, int otyp, cred_t *credp)
{
    int     instance;

    if (getminor(*devp) is invalid)
        return (EINVAL);
    instance = getminor(*devp); /* one-to-one example mapping */
    /* Is the instance attached? */
    if (ddi_get_soft_state(statep, instance) == NULL)
        return (ENXIO);
    /* verify that otyp is appropriate */
    if (otyp != OTYP_CHR)
        return (EINVAL);
    if ((flag & FWRITE) && drv_priv(credp) == EPERM)
        return (EPERM);

    return (0);
}

devp is a pointer to a device number. The open(9E) routine is passed a pointer so that the driver can change the minor number. This allows drivers to dynamically create minor instances of the device. An example of this might be a pseudo-terminal driver that creates a new pseudo-terminal whenever the driver is opened. A driver that chooses the minor number dynamically, normally creates only one minor device node in attach(9E) with ddi_create_minor_node(9F), then changes the minor number component of *devp using makedevice(9F) and getmajor(9F):

*devp = makedevice(getmajor(*devp), new_minor);

The driver must keep track of available minor numbers internally.

otyp indicates how open(9E) was called. The driver must check that the value of otyp is appropriate for the device. For character drivers, otyp should be OTYP_CHR (see the open(9E) manual page).

flag contains bits indicating whether the device is being opened for reading (FREAD), writing (FWRITE), or both. User threads issuing the open(2) system call can also request exclusive access to the device (FEXCL) or specify that the open should not block for any reason (FNDELAY), but it is up to the driver to enforce both cases. A driver for a write-only device such as a printer might consider an open for reading invalid.

credp is a pointer to a credential structure containing information about the caller, such as the user ID and group IDs. Drivers should not examine the structure directly, but should instead use drv_priv(9F) to check for the common case of root privileges. In this example, only root is allowed to open the device for writing.

close( )

int xxclose(dev_t dev, int flag, int otyp, cred_t *credp);

close(9E) should perform any cleanup necessary to finish using the minor device, and prepare the device (and driver) to be opened again. For example, the open routine might have been invoked with the exclusive access (FEXCL) flag. A call to close(9E) would allow further opens to continue. Other functions that close(9E) might perform are:

• Wait for I/O to drain from output buffers before returning.

• Rewind a tape (tape device).
• Hang up the phone line (modem device).

I/O Request Handling

This section gives the details of I/O request processing: from the application to the kernel, the driver, the device, the interrupt handler, and back to the user.

User Addresses

When a user thread issues a write(2) system call, it passes the address of a buffer in user space:

char buffer[] = "python";
count = write(fd, buffer, strlen(buffer) + 1);

The system builds a uio(9S) structure to describe this transfer by allocating an iovec(9S) structure and setting the iov_base field to the address passed to write(2); in this case, buffer. The uio(9S) structure is what is passed to the driver write(9E) routine (see "Vectored I/O" below for more information about the uio(9S) structure).

A problem is that this address is in user space, not kernel space, and so is not guaranteed to be currently in memory. It is not even guaranteed to be a valid address. In either case, accessing a user address directly from the device driver or from the kernel could crash the system, so device drivers should never access user addresses directly. Instead, they should always use one of the data transfer routines in the Solaris 2.x DDI/DKI that transfer data into or out of the kernel; see "Copying Data" on page 391 and "uio(9S) Handling" on page 447 for a summary of the available routines. These routines are able to handle page faults, either by bringing the proper user page in and continuing the copy transparently, or by returning an error on an invalid access.

Two routines commonly used are copyout(9F) to copy data from kernel space to user space and copyin(9F) to copy data from user space to kernel space. ddi_copyout(9F) and ddi_copyin(9F) operate similarly but are to be used in the ioctl(9E) routine. copyin(9F) and copyout(9F) can be used on the buffer described by each iovec(9S) structure, or uiomove(9F) can perform the entire transfer to or from a contiguous area of driver (or device) memory.

Vectored I/O

In character drivers, transfers are described by a uio(9S) structure. The uio(9S) structure contains information about the direction and size of the transfer, plus an array of buffers for one end of the transfer (the other end is the device). Below is a list of uio(9S) structure members that are important to character drivers.

uio( )

The uio structure contains the following members:

iovec_t      *uio_iov;    /* base address of the iovec buffer */
                          /* description array */
int          uio_iovcnt;/* the number of iovec structures */
off_t        uio_offset;/* offset into device where data is */
                          /* transferred from or to */
offset_t     uio_loffset/* 64-bit offset into file where data */
                          /* is transferred from or to. */
int          uio_resid; /* amount (in bytes) not transferred on */
                          /* completion */

A uio(9S) structure is passed to the driver read(9E) and write(9E) entry points. This structure is generalized to support what is called gather-write and scatter-read. When writing to a device, the data buffers to be written do not have to be contiguous in application memory. Similarly, when reading from a device into memory, the data comes off the device in a contiguous stream but can go into noncontiguous areas of application memory. See readv(2), writev(2), pread(2) and pwrite(2) for more information on scatter/gather I/O.

Each buffer is described by an iovec(9S) structure. This structure contains a pointer to the data area and the number of bytes to be transferred.

caddr_t      iov_base;    /* address of buffer */
int          iov_len;     /* amount to transfer */

The uio structure contains a pointer to an array of iovec(9S) structures. The base address of this array is held in uio_iov, and the number of elements is stored in uio_iovcnt.

The uio_offset field contains the 32-bit offset into the device at which the application wants to begin the transfer. uio_loffset is used for 64-bit file offsets. If the device does not support the notion of an offset these fields can be

safely ignored. The driver should interpret either uio_offset or uio_loffset (but not both). If the driver has set the D_64BIT flag in the cb_ops(9S) structure, it should use uio_loffset.

The uio_resid field starts out as the number of bytes to be transferred (the sum of all the iov_len fields in uio_iov) and must be set by the driver to the number of bytes not transferred before returning. The read(2) and write(2) system calls use the return value from the read(9E) and write(9E) entry points to determine if the transfer failed (and then return -1). If the return value indicates success, the system calls return the number of bytes requested minus uio_resid. If uio_resid is not changed by the driver, the read(2) and write(2) calls will return 0 (indicating end-of-file), even though all the data was transferred.

The support routines uiomove(9F), physio(9F) and aphysio(9F) update the uio(9S) structure directly. If they are used, no driver adjustments are necessary.

Synchronous vs. Asynchronous I/O

Data transfers can be synchronous or asynchronous depending on whether the entry point scheduling the transfer returns immediately or waits until the I/O is complete.

The read(9E) and write(9E) entry points are synchronous entry points; they must not return until the I/O is complete. Upon return from the routines, the process knows whether the transfer has succeeded or not.

The aread(9E) and awrite(9E) entry points are asynchronous entry points. They schedule the I/O and return immediately. Upon return, the process issuing the request knows that the I/O has been scheduled and that the status of the I/O must be determined later. In the meantime, the process may perform other operations.

When an asynchronous I/O request is made to the kernel by a user process, the process is not required to wait while the I/O is in process. A process can perform multiple I/O requests and let the kernel handle the data transfer details. This is useful in applications such as transaction processing where concurrent programming methods may take advantage of asynchronous kernel I/O operations to increase performance or response time. Any boost in performance for applications using asynchronous I/O, however, comes at the expense of greater programming complexity.

Data Transfer Methods

Data can be transferred using either programmed I/O or DMA. These data transfer methods may be used by either synchronous or asynchronous entry points, depending on the capabilities of the device.

Programmed I/O Transfers Programmed I/O devices rely on the CPU to perform the data transfer. Programmed I/O data transfers are identical to other device register read and write operations. Various data access routines are used to read or store values to device memory. See "Data Access Functions" on page 55 for more information.

uiomove( )

uiomove(9F) may be used to transfer data to some programmed I/O devices. uiomove(9F) transfers data between the user space (defined by the uio(9S) structure) and the kernel. uiomove(9F) can handle page faults so the memory to which data is transferred need not be locked down. It also updates the uio_resid field in the uio(9S) structure. The following example is one way to write a ramdisk read(9E) routine. It uses synchronous I/O and relies on the presence of the following fields in the ramdisk state structure:

    caddr_t      ram;         /* base address of ramdisk */
    int          ramsize;     /* size of the ramdisk */

Code Example 8-3 Ramdisk read(9E) routine using uiomove(9F)

static int
rd_read(dev_t dev, struct uio *uiop, cred_t *credp)
{
    int instance;
    rd_devstate_t *rsp;
    instance = getminor(dev);
    rsp = ddi_get_soft_state(rd_statep, instance);
    if (rsp == NULL)
        return (ENXIO);
    if (uiop->uio_offset >= rsp->ramsize)
        return (EINVAL);
    /*
     * uiomove takes the offset into the kernel buffer,
     * the data transfer count (minimum of the requested and

     * the remaining data), the UIO_READ flag, and a pointer
     * to the uio structure.
     */
    return (uiomove(rsp->ram + uiop->uio_offset,
        min(uiop->uio_resid, rsp->ramsize - uiop->uio_offset),
        UIO_READ, uiop));
}

uwritec( )and ureadc( ) Another example of programmed I/O might be a driver writing data one byte at a time directly to the device's memory. Each byte is retrieved from the uio(9S) structure using uwritec(9F), then sent to the device. read(9E) can use ureadc(9F) to transfer a byte from the device to the area described by the uio(9S) structure.

Code Example 8-4 Programmed I/O write(9E) routine using uwritec(9F)

static int
xxwrite(dev_t dev, struct uio *uiop, cred_t *credp)
{
    int     instance;
    int     value;
    struct xxstate *xsp;

    instance = getminor(dev);
    xsp = ddi_get_soft_state(statep, instance);
    if (xsp == NULL)
        return (ENXIO);

    while (uiop->uio_resid > 0) {
        /*
         * do the programmed I/O access
         */
        value = uwritec(uiop);
        if (value == -1)
             return (EFAULT);
        ddi_putb(xsp->data_access_handle, xsp->regp->data,
             (u_char)value);
        ddi_putb(xsp->data_access_handle, xsp->regp->csr,
             START_TRANSFER);

regp->data = (u_char)value;
        regp->csr = START_TRANSFER;
        /* this device requires a ten microsecond delay */

        /* between writes */
        drv_usecwait(10);
    }
    return (0);
}

DMA Transfers (Synchronous) Most character drivers use physio(9F) to do most of the setup work for DMA transfers in read(9E) and write(9E).

int physio(int (*strat)(struct buf *), struct buf *bp,
    dev_t dev, int rw, void (*mincnt)(struct buf *),
    struct uio *uio);

physio(9F) requires the driver to provide the address of a strategy(9E) routine. physio(9F) ensures that memory space is locked down (cannot be paged out) for the duration of the data transfer. This is necessary for DMA transfers because they cannot handle page faults. physio(9F) also provides an automated way of breaking a larger transfer into a series of smaller, more manageable ones. See "minphys( )" on page 175 for more information.

Code Example 8-5 read(9E) and write(9E) routines using physio(9F)

static int
xxread(dev_t dev, struct uio *uiop, cred_t *credp)
{
    int instance;
    struct xxstate *xsp;

    instance = getminor(dev);
    xsp = ddi_get_soft_state(statep, instance);

    if (xsp == NULL)
        return (ENXIO);
    return (physio(xxstrategy, NULL, dev, B_READ, xxminphys, uiop));
}

static int
xxwrite(dev_t dev, struct uio *uiop, cred_t *credp)
{
    int instance;
    struct xxstate *xsp;

    instance = getminor(dev);
    xsp = ddi_get_soft_state(statep, instance);

    if (xsp == NULL)
        return (ENXIO);
    return (physio(xxstrategy, NULL, dev, B_WRITE,
        xxminphys,*uiop));
}

In the call to physio(9F), xxstrategy is a pointer to the driver strategy routine. Passing NULL as the buf(9S) structure pointer tells physio(9F) to allocate a buf(9S) structure. If it is necessary for the driver to provide physio(9F) with a buf(9S) structure, getrbuf(9F) should be used to allocate one. physio(9F) returns zero if the transfer completes successfully, or an error number on failure. After calling strategy(9E), physio(9F) calls biowait(9F) to block until the transfer completes or fails. The return value of physio(9E) is determined by the error field in the buf(9S) structure set by bioerror(9F).

DMA Transfers (Asynchronous) Character drivers supporting aread(9E) and awrite(9E) use aphysio(9F) instead of physio(9F)..

int aphysio(int (*strat)(struct buf *), int (*cancel)(struct buf *),
    dev_t dev, int rw, void (*mincnt)(struct buf *),
    struct aio_req *aio_reqp);

---

Note - The address of anocancel(9F) is the only value that can currently be passed as the second argument to aphysio(9F).

---

aphysio(9F) requires that the driver pass the address of a strategy(9E) routine. aphysio(9F) ensures that memory space is locked down (cannot be paged out) for the duration of the data transfer. This is necessary for DMA transfers because they cannot handle page faults. aphysio(9F) also provides an automated way of breaking a larger transfer into a series of smaller, more manageable ones. See "minphys( )" on page 175 for more information. Code examples 8-6 and 8-7 demonstrate that the aread(9E) and awrite(9E) entry points differ only slightly from the read(9E) and write(9E) entry points; the difference lies mainly in their use of aphysio(9F) instead of physio(9F).

Code Example 8-6 aread(9E) and awrite(9E) routines using aphysio(9F)

static int
xxaread(dev_t dev, struct aio_req *aio, cred_t *cred_p)
{
    int instance;
    struct xxstate *xsp;

    instance = getminor(dev);
    xsp = ddi_get_soft_state(statep, instance);

    if (xsp == NULL)
        return (ENXIO);

    return (aphysio(xxstrategy, anocancel, dev, B_READ, xxminphys,
        aio));
}

static int
xxawrite(dev_t dev, struct aio_req *aio, cred_t *cred_p)
{
    int instance;
    struct xxstate *xsp;

    instance = getminor(dev);
    xsp = ddi_get_soft_state(statep, instance);

    if (xsp == NULL)
        return (ENXIO);

    return (aphysio(xxstrategy, anocancel, dev, B_WRITE, xxminphys,
        aio));
}

In the call to aphysio(9F), xxstrategy is a pointer to the driver strategy routine. Passing NULL as the buf(9S) structure pointer tells aphysio(9F) to allocate a buf(9S) structure. If it is necessary for the driver to provide aphysio(9F) with a buf(9S) structure, getrbuf(9F) should be used to allocate one. aio_reqp is passed as a parameter to aphysio. It is a pointer to the aio_req(9S) structure and is also passed to aread(9E) and awrite(9F). aio_reqp(9S) describes where data is to be stored in user space. aphysio(9F)

returns zero if the I/O request is scheduled successfully or an error number on failure. After calling strategy, aphysio(9F) returns without waiting for the I/O to complete or fail.

minphys( )

xxminphys is a pointer to a function to be called by physio(9F) or aphysio(9F) to ensure that the size of the requested transfer does not exceed a driver-imposed limit. If the user requests a larger transfer, strategy(9E) will be called repeatedly, requesting no more than the imposed limit at a time. This is important because DMA resources are limited. Drivers for slow devices, such as printers, should be careful not to tie up resources for a long time.

Usually, a driver passes the address of the kernel function minphys(9F), but the driver can define its own xxminphys() routine instead. The job of xxminphys() is to keep the b_bcount field of the buf(9S) structure below a driver limit. There may be additional system limits that the driver should not circumvent, so the driver xxminphys() routine should call the system minphys(9F) routine after setting the b_bcount field and before returning.

Code Example 8-7 minphys(9F) routine

#define XXMINVAL (124 << 10)
static void
xxminphys(struct buf *bp)
{
    if (bp->b_bcount > XXMINVAL);
        bp->b_bcount = XXMINVAL
    minphys(bp);
}

strategy( )

The strategy(9E) routine originated in block drivers and is so called because it can implement a strategy for efficient queuing of I/O requests to a block device. A driver for a character-oriented device can also use a strategy(9E) routine. In the character I/O model presented here, strategy(9E) does not maintain a queue of requests, but rather services one request at a time.

In this example, the strategy(9E) routine for a character-oriented DMA device allocates DMA resources for synchronous data transfer and starts the command by programming the device register (see Chapter 7, "DMA," for a detailed description).

---

Note - strategy(9E) does not receive a device number (dev_t) as a parameter; instead, this is retrieved from the b_edev field of the buf(9S) structure passed to strategy(9E).

---

Code Example 8-8 strategy(9E) routine

static int
xxstrategy(struct buf *bp)
{
    int     instance;
    struct xxstate *xsp;
    ddi_dma_cookie_t      cookie;
    instance = getminor(bp->b_edev);
    xsp = ddi_get_soft_state(statep, instance);
    ...
    set up DMA resources with ddi_dma_alloc_handle(9F) and
        ddi_dma_buf_bind_handle(9F)
    xsp->bp = bp; /* remember bp */

program DMA engine and start command

    return (0);
}

---

Note - Although strategy(9E) is declared to return an int, it must always return zero.

---

On completion of the DMA transfer, the device generates an interrupt, causing the interrupt routine to be called. In this example, xxintr() receives a pointer to the state structure for the device that might have generated the interrupt.

Code Example 8-9 Interrupt routine

static u_int
xxintr(caddr_t arg)
{
    struct xxstate *xsp = (struct xxstate *)arg;

if (device did not interrupt) {

    return (DDI_INTR_UNCLAIMED);
}
if (error) {

error handling

}

release any resources used in the transfer, such as DMA resources (ddi_dma_alloc_handle(9F) and ddi_dma_buf_bind_handle(9F))

))

    /* notify threads that the transfer is complete */
    biodone(xsp->bp);
    return (DDI_INTR_CLAIMED);
}

The driver indicates an error by calling bioerror(9F). The driver must call biodone(9F) when the transfer is complete or after indicating an error with bioerror(9F).

Mapping Device Memory

Some devices, such as frame buffers, have memory that is directly accessible to user threads by way of memory mapping. Drivers for these devices typically do not support the read(9E) and write(9E) interfaces. Instead, these drivers support memory mapping with the mmap(9E) entry point. A typical example is a frame buffer driver that implements the mmap(9E) entry point to allow the frame buffer to be mapped in a user thread.

segmap( )

int xxsegmap(dev_t dev, off_t off, struct as *asp, caddr_t *addrp,
    off_t len, unsigned int prot, unsigned int maxprot,
    unsigned int flags, cred_t *credp);

segmap(9E) is the entry point responsible for actually setting up a memory mapping requested by the system on behalf of an mmap(2) system call. Drivers for many memory-mapped devices may use ddi_segmap(9F) as the entry

point rather than define their own segmap(9E) routine. Drivers that need to manage multiple user contexts for a device can provide their own sepmap(9E) routine. See Chapter 10, "Device Context Management" for more information.

mmap( )

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

This routine is called as a result of an mmap(2) system call, and also as the result of a page fault. mmap(9E) is called to translate the device offset off to the corresponding page frame number. Code Example 8-10 allows a user thread to memory map the device registers.

Code Example 8-10 mmap(9E) routine

static int
xxmmap(dev_t dev, off_t off, int prot)
{
    int     instance;
    struct xxstate *xsp;
    if (prot & PROT_WRITE)
        return (-1);
    instance = getminor(dev);
    xsp = ddi_get_soft_state(statep, instance);
    if (xsp == NULL)
        return (-1);

if (off is invalid)

        return (-1);
    return (hat_getkpfnum(xsp->regp->csr + off));
}

dev is the device number and off is the offset into the device's memory. prot specifies the kind of access requested, such as PROT_READ and PROT_WRITE. A value of PROT_WRITE for prot would be invalid on a read-only device. See mmap(9E) and mmap(2).

hat_getkpfnum(9F) returns the page frame number for the memory that should be mapped. xsp->regp->csr is the memory address base of the device memory determined in attach(9E) by calling ddi_regs_map_setup(9F) and stored in the state structure.

In Code Example 8-10 the whole address range up to off must be mapped using ddi_regs_map_setup(9F). This can use a lot of system resources for devices that have a large mappable memory area and is a waste of resources if the driver only needs the mapping so it can call hat_getkpfnum(9F). A better way to get the page frame number for a given offset is to just map that individual page, retrieve the page frame number, then unmap the page before returning. Since the page frame number refers to a page on the device, it will not change when the page is unmapped.

Code Example 8-11 mmap(9E) routine using fewer resources

static int
xxmmap(dev_t dev, off_t off, int prot)
{
    int     kpfn = -1;
    caddr_t kva;

    ddi_device_acc_attr_t = {
        DDI_DEVICE_ATTR_V0,
        DDI_STRUCTURE_BE_ACC,
        DDI_STRICTORDER_ACC
    };
    ddi_acc_handle_t handle;
    ...
    if (ddi_regs_map_setup(xsp->dip, rnumber, &kva, (offset_t) off,
        (offset_t) ptob(1), &attr, &handle) ==
        DDI_SUCCESS) {
        kpfn = hat_getkpfnum(kva);
        ddi_regs_map_free(&handle);
    }
    return (kpfn);
}

If the mappable memory of the device is physically contiguous, converting off to the number of pages and adding it to the base page frame number will give the same result as getting the page frame number of a mapped page. In this case, only the first page of the device's memory needs to be mapped:

return (hat_getkpfnum(xsp->regp->csr + btop(off));

Multiplexing I/O on File Descriptors

A thread sometimes wants to handle I/O on more than one file descriptor. One example is an application program that wants to read the temperature from a temperature sensing device and then report the temperature to an interactive display. If the program makes a read request and there is no data available, it should not block waiting for the temperature before interacting with the user again.

The poll(2) system call provides users with a mechanism for multiplexing I/O over a set of file descriptors that reference open files. poll(2) identifies those file descriptors on which a program can send or receive data without blocking, or on which certain events have occurred.

To allow a program to poll a character driver, the driver must implement the chpoll(9E) entry point.

State Structure

This section adds the following field to the state structure. See "State Structure" on page 67 for more information.

struct pollhead pollhead; /* for chpoll(9E)/pollwakeup(9F) */

chpoll( )

int xxchpoll(dev_t dev, short events, int anyyet, short *reventsp,
    struct pollhead **phpp);

The system calls chpoll(9E) when a user process issues a poll(2) system call on a file descriptor associated with the device. The chpoll(9E) entry point routine is used by non-STREAMS character device drivers that wish to support polling.

In chpoll(9E), the driver must follow the following rules:

• Implement the following algorithm when the chpoll(9E) entry point is called:

  if (events are satisfied now) {

  *reventsp = mask of satisfied events;

} else {
    *reventsp = 0;
    if (!anyyet)

*phpp = & local pollhead structure;

}
return (0);

xxchpoll( ) should check to see if certain events have occurred; see chpoll(9E). It should then return the mask of satisfied events by setting the return events in *reventsp.

If no events have occurred, the return field for the events is cleared. If the anyyet field is not set, the driver must return an instance of the pollhead structure. It is usually allocated in a state structure and should be treated as opaque by the driver. None of its fields should be referenced.

• Call pollwakeup(9F) whenever a device condition of type events, listed in Code Example 8-12, occurs. This function should be called only with one event at a time. pollwakeup(9F) might be called in the interrupt routine when the condition has occurred.

  The following two examples show how to implement the polling discipline and how to use pollwakeup(9F).

Code Example 8-12 chpoll(9E) routine

static int
xxchpoll(dev_t dev, short events, int anyyet,
    short *reventsp,struct pollhead **phpp)
{
    int     instance;
    u_char status;
    short   revent;
    struct xxstate *xsp;
    instance = getminor(dev);
    xsp = ddi_get_soft_state(statep, instance);
    if (xsp == NULL)
        return (ENXIO);
    revent = 0;
    /*
     * Valid events are:
     * POLLIN | POLLOUT | POLLPRI | POLLHUP | POLLERR
     * This example checks only for POLLIN and POLLERR.
     */
    status = ddi_getb(xsp->data_access_handle, xsp->regp->csr);

    if ((events & POLLIN) && data available to read) {
        revent |= POLLIN;
    }
    if ((events & POLLERR) && (status & DEVICE_ERROR)) {
        revent |= POLLERR;
    }
    /* if nothing has occurred */
    if (revent == 0) {
        if (!anyyet) {
             *phpp = &xsp->pollhead;
        }
    }
    *reventsp = revent;
    return (0);
}

In this example, the driver can handle the POLLIN and POLLERR events (see chpoll(9E) for a detailed discussion of the available events). The driver first reads the status register to determine the current state of the device. The parameter events specifies which conditions the driver should check. If the appropriate conditions have occurred, the driver sets that bit in *reventsp. If none of the conditions have occurred and anyyet is not set, the address of the pollhead structure is returned in *phpp.

Code Example 8-13 Interrupt routine supporting chpoll(9E)

static u_int
xxintr(caddr_t arg)
{
    struct xxstate *xsp = (struct xxstate *) arg;
    u_char status;

normal interrupt processing

    ...
    status = ddi_getb(xsp->data_access_handle, xsp->regp->csr);
    if (status & DEVICE_ERROR) {
        pollwakeup(&xsp->pollhead, POLLERR);
    }
    if (just completed a read) {
        pollwakeup(&xsp->pollhead, POLLIN);
    }
    ...
    return (DDI_INTR_CLAIMED);
}

pollwakeup(9F) is usually called in the interrupt routine when a supported condition has occurred. The interrupt routine reads the status from the status register and checks for the conditions. It then calls pollwakeup(9F) for each event to possibly notify polling threads that they should check again. Note that pollwakeup(9F) should not be called with any locks held, since it could cause the chpoll(9E) routine to be entered, causing deadlock if that routine tries to grab the same lock.

Miscellaneous I/O Control

The ioctl(9E) routine is called when a user thread issues an ioctl(2) system call on a file descriptor associated with the device. The I/O control mechanism is a catchall for getting and setting device-specific parameters. It is frequently used to set a device-specific mode, either by setting internal driver software flags or by writing commands to the device. It can also be used to return information to the user about the current device state. In short, it can do whatever the application and driver need it to do.

ioctl(9E)

int xxioctl(dev_t dev, int cmd, int arg, int mode,
    cred_t *credp, int *rvalp);

The cmd parameter indicates which command ioctl(9E) should perform. By convention, I/O control commands indicate the driver they belong to in bits 8- 15 of the command (usually given by the ASCII code of a character representing the driver), and the driver-specific command in bits 0-7. They are usually created in the following way:

#define XXIOC    ('x' << 8) /* 'x' is a character representing /*
                               /* device xx */
#define XX_GET_STATUS (XXIOC | 1) /* get status register */
#define XX_SET_CMD
                          (XXIOC | 2) /* send command */

The interpretation of arg depends on the command. I/O control commands should be documented (in the driver documentation, or a manual page) and defined in a public header file, so that applications know the names, what they do, and what they accept or return as arg. Any data transfer of arg (into or out of the driver) must be performed by the driver.

ioctl(9E) is usually a switch statement with a case for each supported ioctl(9E) request.

Code Example 8-14 ioctl(9E) routine

static int
xxioctl(dev_t dev, int cmd, int arg, int mode,
    cred_t *credp,int *rvalp)
{
    int     instance;
    u_char       csr;
    struct xxstate *xsp;
    instance = getminor(dev);
    xsp = ddi_get_soft_state(statep, instance);
    if (xsp == NULL) {
        return (ENXIO);
    }
    switch (cmd) {
    case XX_GET_STATUS:
        csr = ddi_getb(xsp->data_access_handle, xsp->regp->csr);
        if (ddi_copyout(&csr, (caddr_t) arg, sizeof(u_char),
             mode) != 0) {
             return (EFAULT);
        }
        break;
    case XX_SET_CMD:
        if (ddi_copyin((caddr_t) arg, &csr, sizeof(u_char),
             mode) != 0) {
             return (EFAULT);
        }
        ddi_putb(xsp->data_access_handle, xsp->regp->csr, csr);
        break;
    default:
        /* generic "ioctl unknown" error */
        return (ENOTTY);
    }
    return (0);
}

The cmd variable identifies a specific device control operation. If arg contains a user virtual address, ioctl(9E) must call ddi_copyin(9F) or ddi_copyout(9F) to transfer data between the data structure in the application program pointed to by arg and the driver. In Code Example 8-14, for the case of an XX_GET_STATUS request the contents of xsp->regp->csr is copied to the address in arg. When a request succeeds, ioctl(9E) can store in *rvalp any integer value to be the return value of the ioctl(2) system call

that made the request. Negative return values, such as -1, should be avoided, as they usually indicate the system call failed, and many application programs assume negative values indicate failure.

An application that uses the I/O controls above could look like the following:

Code Example 8-15 Using ioctl(2)

#include <sys/types.h>
#include "xxio.h"/* contains device's ioctl cmds and arguments */
int main(void)
{
    u_char status;
    /*
     * read the device status
     */
    if (ioctl(fd, XX_GET_STATUS, &status) == -1) {
        error handling
    }
    printf("device status %x\n", status);
    exit(0);
}