Device Access (Character Drivers)
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) can 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, the final call to close(9E) may occur as a result of a close(2) or exit(2) system call. If the device is accessed through memory mapping, the final call to close(9E) may occur as a result of a munmap(2) system call.
open() Entry Point (Character Drivers)
The syntax for open(9E) is as follows:
int xxopen(dev_t *devp, int flag, int otyp, cred_t *credp); |
The primary function of open() is to verify that the open request is allowed. 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 enables 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 dynamically chooses the minor number, 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); |
It is not necessary to call ddi_create_minor_node(9F) for the new minor. A driver may not change the major number of *devp. 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 the driver must enforce both cases. A driver for a write-only device such as a printer might consider an open(9E) 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.
Example 10-2 shows a character driver open(9E) routine.
Example 10-2 Character Driver open(9E) Routine
close() Entry Point (Character Drivers)
The syntax for close(9E) is as follows:
int xxclose(dev_t dev, int flag, int otyp, cred_t *credp); |
close() 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 open routines to continue. Other functions that close(9E) might perform are:
Waiting for I/O to drain from output buffers before returning
Rewinding a tape (tape device)
Hanging 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 passed to the driver write(9E) routine (see "Vectored I/O" for more information about the uio(9S) structure).
The address in the iovec(9S) 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 9 DDI/DKI that transfer data into or out of the kernel. 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).
The uio(9S) 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; /* 32-bit offset into file where */
/* data is transferred from or to */
offset_t uio_loffset; /* 64-bit offset into file where */
/* data is transferred from or to */
uio_seg_t uio_segflg; /* identifies the type of I/O */
/* transfer: */
/* UIO_SYSSPACE: kernel <-> kernel */
/* UIO_USERSPACE: kernel <-> user */
short uio_fmode; /* file mode flags (not driver setable) */
daddr_t uio_limit; /* 32-bit ulimit for file (maximum */
/* block offset). not driver setable. */
diskaddr_t uio_llimit; /* 64-bit ulimit for file (maximum block */
/* block offset). not driver setable. */
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 the readv(2), writev(2), pread(2), and pwrite(2) man pages 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 needs 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, updating the device offset to account for the data transfer. When used with a seekable device, for which the concept of position is relevant, the driver does not need to adjust either the uio_offset or uio_loffset fields. I/O performed to a device in this manner is constrained by the maximum possible value of uio_offset or uio_loffset. An example of such a usage is raw I/O on a disk.
When performing I/O on a device on which the concept of position has no relevance, the driver can save uio_offset or uio_loffset, perform the I/O operation, then restore uio_offset or uio_loffset to the field's initial value. I/O performed to a device in this manner is not constrained by the maximum possible value of uio_offset or uio_loffset. An example of such a usage is I/O on a serial line.
The following example shows one way to preserve uio_loffset in the read(9E) function.
static int
xxread(dev_t dev, struct uio *uio_p, cred_t *cred_p)
{
offset_t off;
...
off = uio_p->uio_loffset; /* save the offset */
/* do the transfer */
uio_p->uio_loffset = off; /* restore it */
}
|