Device Driver Tutorial
|
|||
|
1. Introduction to Device Drivers 3. Reading and Writing Data in Kernel Memory Displaying Data Stored in Kernel Memory |
Modifying Data Stored in Kernel MemoryIn this third version of the Quote Of The Day driver, the user can write to the data that is stored in kernel memory. The pseudo device that is created in this section is a pseudo-disk device or ramdisk device. A ramdisk device simulates a disk device by allocating kernel memory that is subsequently used as data storage. See ramdisk(7D) for more information about ramdisk devices. As in Version 2 of the Quote Of The Day driver, this Version 3 driver stores its data and makes the data available through its read(9E) entry point. This Version 3 driver overwrites characters from the beginning of the data when the user writes to the device. This section first discusses the important code differences between this version and the previous version of the Quote Of The Day driver. This section then shows you how you can modify and display the quotation. In addition to changes in the driver, Quote Of The Day Version 3 introduces a header file and an auxiliary program. The header file is discussed in the following section. The utility program is discussed in Using Quote Of The Day Version 3. Writing Quote Of The Day Version 3This third version of the Quote Of The Day driver is more complex than the second version because this third version enables a user to change the text that is stored in the device. This section first explains some important features of this version of the driver. This section then shows all the source for this driver, including the header file and the configuration file. The following list summarizes the new features in Version 3 of the Quote Of The Day driver:
The following sections provide more detail about the additions and changes in Version 3 of the Quote Of The Day driver. The dev_ops(9S) structure and the modlinkage(9S) structure are the same as they were in Version 2 of the driver. The modldrv(9S) structure has not changed except for the version number of the driver. The _init(9E), _info(9E), _fini(9E), getinfo(9E), open(9E), and close(9E) functions are the same as in Version 2 of the driver. Attaching, Allocating Memory, and Initializing a Mutex and a Condition VariableThe qotd_attach() entry point first allocates and gets the device soft state. The qotd_attach() routine then creates a minor node. All of this code is the same as in Version 2 of the Quote Of The Day driver. If the call to ddi_create_minor_node(9F) is successful, the qotd_attach() routine sets the QOTD_DIDMINOR flag in the new flags member of the qotd_state state structure. Version 3 of the Quote Of The Day driver defines four new constants that keep track of four different events. A routine can test these flags to determine whether to deallocate, close, or remove resources. All four of these flags are set in the qotd_attach() entry point. All four of these conditions are checked in the qotd_detach() entry point, and the appropriate action is taken for each condition. Note that operations are undone in the qotd_detach() entry point in the opposite order in which they were done in the qotd_attach() entry point. The qotd_attach() routine creates a minor node, allocates memory for the quotation, initializes a mutex, and initializes a condition variable. The qotd_detach() routine destroys the condition variable, destroys the mutex, frees the memory, and removes the minor node. After the minor node is created, the qotd_attach() routine allocates memory for the quotation. For information on allocating and freeing memory in this driver, see Allocating and Freeing Kernel Memory. If memory is allocated, the qotd_attach() routine sets the QOTD_DIDALLOC flag in the flags member of the state structure. The qotd_attach() routine then calls the mutex_init(9F) function to initialize a mutex. If this operation is successful, the qotd_attach() routine sets the QOTD_DIDMUTEX flag. The qotd_attach() routine then calls the cv_init(9F) function to initialize a condition variable. If this operation is successful, the qotd_attach() routine sets the QOTD_DIDCV flag. The qotd_attach() routine then calls the strlcpy(9F) function to copy the initial quotation string to the new quotation member of the device state structure. Note that the strlcpy(9F) function is used instead of the strncpy(9F) function. The strncpy(9F) function can be wasteful because it always copies n characters, even if the destination is smaller than n characters. Try using strncpy(9F) instead of strlcpy(9F) and note the difference in the behavior of the driver. Finally, the initial quotation length is copied to the new quotation length member of the state structure. The remainder of the qotd_attach() routine is the same as in Version 2. Checking for Changes, Cleaning Up, and DetachingThe qotd_detach() routine is almost all new. The qotd_detach() routine must first get the soft state because the qotd_detach() routine needs to check the flags member of the state structure. The first flag the qotd_detach() routine checks is the QOTD_CHANGED flag. The QOTD_CHANGED flag indicates whether the device is in the initial state. The QOTD_CHANGED flag is set in the qotd_rw() routine and in the qotd_ioctl() entry point. The QOTD_CHANGED flag is set any time the user does anything to the device other than simply inspect the device. If the QOTD_CHANGED flag is set, the size or content of the storage buffer has been modified. See Writing New Data for more information on the QOTD_CHANGED flag. When the QOTD_CHANGED flag is set, the detach operation fails because the device might contain data that is valuable to the user and the device should not be removed. If the QOTD_CHANGED flag is set, the qotd_detach() routine returns an error that the device is busy. Once the quotation has been modified, the device cannot be detached until the user runs the qotdctl command with the -r option. The -r option reinitializes the quotation and indicates that the user is no longer interested in the contents of the device. See Exercising the Driver's I/O Controls for more information about the qotdctl command. The qotd_detach() routine then checks the four flags that were set in the qotd_attach() routine. If the QOTD_DIDCV flag is set, the qotd_detach() routine calls the cv_destroy(9F) function. If the QOTD_DIDMUTEX flag is set, the qotd_detach() routine calls the mutex_destroy(9F) function. If the QOTD_DIDALLOC flag is set, the qotd_detach() routine calls the ddi_umem_free(9F) function. Finally, if the QOTD_DIDMINOR flag is set, the qotd_detach() routine calls the ddi_remove_minor_node(9F) function. Allocating and Freeing Kernel MemoryOne of the new members of the device state structure supports memory allocation and deallocation. The qotd_cookie member receives a value from the ddi_umem_alloc(9F) function. The qotd_cookie value is then used by the ddi_umem_free(9F) function to free the memory. Version 3 of the Quote Of The Day driver allocates kernel memory in three places:
The qotd_attach() routine allocates memory after the minor node is created. Memory must be allocated to enable the user to modify the quotation. The qotd_attach() routine calls the ddi_umem_alloc(9F) function with the DDI_UMEM_NOSLEEP flag so that the ddi_umem_alloc(9F) function will return immediately. If the requested amount of memory is not available, ddi_umem_alloc(9F) returns NULL immediately and does not wait for memory to become available. If no memory is allocated, qotd_attach() calls qotd_detach() and returns an error. If memory is allocated, qotd_attach() sets the QOTD_DIDALLOC flag so that this memory will be freed by qotd_detach() later. The second place the driver allocates memory is in the QOTDIOCSSZ case of the qotd_ioctl() entry point. The QOTDIOCSSZ case sets a new size for the device. A new size is set when the user runs the qotdctl command with the -s option. See Exercising the Driver's I/O Controls for more information about the qotdctl command. This time, the ddi_umem_alloc(9F) function is called with the DDI_UMEM_SLEEP flag so that ddi_umem_alloc(9F) will wait for the requested amount of memory to be available. When the ddi_umem_alloc(9F) function returns, the requested memory has been allocated. Note that you cannot always use the DDI_UMEM_SLEEP flag. See the CONTEXT sections of the ddi_umem_alloc(9F), kmem_alloc(9F), and kmem_zalloc(9F) man pages. Also note the behavioral differences among these three functions. The kmem_zalloc(9F) function is more efficient for small amounts of memory. The ddi_umem_alloc(9F) function is faster and better for large allocations. The ddi_umem_alloc(9F) function is used in this qotd_3 driver because ddi_umem_alloc(9F) allocates whole pages of memory. The kmem_zalloc(9F) function might save memory because it might allocate smaller chunks of memory. This qotd_3 driver demonstrates a ramdisk device. In a production ramdisk device, you would use ddi_umem_alloc(9F) to allocate page-aligned memory. After the current quotation is copied to the new space, the qotd_ioctl() routine calls the ddi_umem_free(9F) function to free the memory that was previously allocated. The third place the driver allocates memory is in the QOTDIOCDISCARD case of the qotd_ioctl() entry point. The QOTDIOCDISCARD case is called from the qotdctl command. The qotdctl command with the -r option sets the quotation back to its initial value. If the number of bytes allocated for the current quotation is different from the initial number of bytes, then new memory is allocated to reinitialize the quotation. Again, the DDI_UMEM_SLEEP flag is used so that when the ddi_umem_alloc(9F) function returns, the requested memory has been allocated. The qotd_ioctl() routine then calls the ddi_umem_free(9F) function to free the memory that was previously allocated. Managing Thread SynchronizationThe Quote Of The Day Version 3 driver uses condition variables and mutual exclusion locks (mutexes) together to manage thread synchronization. See the Multithreaded Programming Guide for more information about mutexes, condition variables, and thread synchronization. In this driver, the mutex and condition variable both are initialized in the qotd_attach() entry point and destroyed in the qotd_detach() entry point. The condition variable is tested in the qotd_rw() routine and in the qotd_ioctl() entry point. The condition variable waits on the QOTD_BUSY condition. This condition is needed because the driver must do some operations that rely on exclusive access to internal structures without holding a lock. Accessing the storage buffer or its metadata requires mutual exclusion, but the driver cannot hold a lock if the operation might sleep. Instead of holding a lock in this case, the driver waits on the QOTD_BUSY condition. The driver acquires a mutex when the driver tests the condition variable and when the driver accesses the storage buffer. The mutex protects the storage buffer. Failure to use a mutual exclusion when accessing the storage buffer could allow one user process to resize the buffer while another user process tries to read the buffer, for example. The result of unprotected buffer access could be data corruption or a panic. The condition variable is used when functions are called that might need to sleep. The ddi_copyin(9F), ddi_copyout(9F), and uiomove(9F) functions can sleep. Memory allocation can sleep if you use the SLEEP flag. Functions must not hold a mutex while they are sleeping. Sleeping while holding a mutex can cause deadlock. When a function might sleep, set the QOTD_BUSY flag and take the condition variable, which drops the mutex. To avoid race conditions, the QOTD_BUSY flag can be set or cleared only when holding the mutex. For more information on deadlock, see Using Mutual Exclusion Locks in Multithreaded Programming Guide and Avoiding Deadlock in Multithreaded Programming Guide. Locking Rules for Quote Of The Day Version 3The locking rules for this qotd_3 driver are as follows:
These locking rules are very simple. These three rules ensure consistent access to the buffer and its metadata. Realistic drivers probably have more complex locking requirements. For example, drivers that use ring buffers or drivers that manage multiple register sets or multiple devices have more complex locking requirements. Lock and Condition Variable Members of the State StructureThe device state structure for Version 3 of the Quote Of The Day driver contains two new members to help manage thread synchronization:
Creating and Destroying Locks and Condition VariablesVersion 3 of the Quote Of The Day driver defines two constants to make sure the mutex and condition variable are destroyed when the driver is finished with them. The driver uses these constants to set and reset the new flags member of the device state structure.
Waiting on SignalsIn the qotd_rw() and qotd_ioctl() routines, the cv_wait_sig(9F) calls wait until the condition variable is signaled to proceed or until a signal(3C) is received. Either the cv_signal(9F) function or the cv_broadcast(9F) function signals the cv condition variable to proceed. A thread can wait on a condition variable until either the condition variable is signaled or a signal(3C) is received by the process. The cv_wait(9F) function waits until the condition variable is signaled but ignores signal(3C) signals. This driver uses the cv_wait_sig(9F) function instead of the cv_wait(9F) function because this driver responds if a signal is received by the process performing the operation. If a signal(3C) is taken by the process, this driver returns an interrupt error and does not complete the operation. The cv_wait_sig(9F) function usually is preferred to the cv_wait(9F) function because this implementation offers the user program more precise response. The signal(3C) causes an effect closer to the point at which the process was executing when the signal(3C) was received. In some cases, you cannot use the cv_wait_sig(9F) function because your driver cannot be interrupted by a signal(3C). For example, you cannot use the cv_wait_sig(9F) function during a DMA transfer that will result in an interrupt later. In this case, if you abandon the cv_wait_sig(9F) call, you have nowhere to put the data when the DMA transfer is finished, and your driver will panic. Writing New DataThe cb_ops(9S) structure for Version 3 of the Quote Of The Day driver declares two new entry points that support modifying the quotation. The two new entry points are write(9E) and ioctl(9E). The qotd_rw() routine is a third new routine in Version 3 of the driver. The qotd_rw() routine is called by both the read(9E) entry point and the write(9E) entry point. The device state structure for Version 3 of the Quote Of The Day driver contains two new members that are used to modify the quotation. The qotd string holds the quotation for the current instance of the device. The qotd_len member holds the length in bytes of the current quotation. Version 3 of the driver also defines two new constants that support modifying the quotation. In place of QOTD_MAXLEN, Version 3 of the driver defines QOTD_MAX_LEN. QOTD_MAX_LEN is used in the qotd_ioctl() entry point to test whether the user has entered a string that is too long. Version 3 of the driver also defines QOTD_CHANGED. The QOTD_CHANGED flag is set in the qotd_rw() routine and in the qotd_ioctl() entry point when a new quotation is copied from the user. When the qotd_3 device is opened for writing, the kernel calls the qotd_write() entry point. The qotd_write() entry point then calls the qotd_rw() routine and passes a UIO_WRITE flag. The new qotd_read() entry point is exactly the same as the qotd_write() entry point, except that the qotd_read() entry point passes a UIO_READ flag. The qotd_rw() routine supports both reading and writing the device and thereby eliminates much duplicate code. The qotd_rw() routine first gets the device soft state. Then the qotd_rw() routine checks the length of the I/O request in the uio(9S) I/O request structure. If this length is zero, the qotd_rw() routine returns zero. If this length is not zero, the qotd_rw() routine enters a mutex. While the device is busy, the qotd_rw() routine checks whether the condition variable has been signaled or a signal(3C) is pending. If either of these conditions is true, the qotd_rw() routine exits the mutex and returns an error. When the device is not busy, the qotd_rw() routine checks whether the data offset in the uio(9S) I/O request structure is valid. If the offset is not valid, the qotd_rw() routine exits the mutex and returns an error. If the offset is valid, the local length variable is set to the difference between the offset in the I/O request structure and the length in the device state structure. If this difference is zero, the qotd_rw() routine exits the mutex and returns. If the device was opened for writing, the qotd_rw() routine returns a space error. Otherwise, the qotd_rw() routine returns zero. The qotd_rw() routine then sets the QOTD_BUSY flag in the flags member of the device state structure and exits the mutex. The qotd_rw() routine then calls the uiomove(9F) function to copy the quotation. If the rw argument is UIO_READ, then the quotation is transferred from the state structure to the I/O request structure. If the rw argument is UIO_WRITE, then the quotation is transferred from the I/O request structure to the state structure. The qotd_rw() routine then enters a mutex again. If the device was opened for writing, the qotd_rw() routine sets the QOTD_CHANGED flag. The qotd_rw() routine then sets the device to not busy, calls cv_broadcast(9F) to unblock any threads that were blocked on this condition variable, and exits the mutex. Finally, the qotd_rw() routine returns the quotation. The quotation is written to the device node. Reporting and Setting Device Size and Re-initializing the DeviceThe behavior of the ioctl(9E) entry point depends on the command value passed in to the entry point. These constants are defined in the new qotd.h header file. The qotd_ioctl() routine reports the size of the space allocated for the quotation, sets a new amount of space to allocate for the quotation, or resets the quotation back to its initial value. If the request is to report the size of the space allocated for the quotation, then the qotd_ioctl() routine first sets a local size variable to the value of the quotation length in the state structure. If the device was not opened for reading, the qotd_ioctl() routine returns an error. Because the qotd_ioctl() routine transfers data between kernel space and user space, the qotd_ioctl() routine must check whether both spaces are using the same data model. If the return value of the ddi_model_convert_from(9F) function is DDI_MODEL_ILP32, then the driver must convert to 32-bit data before calling ddi_copyout(9F) to transfer the current size of the quotation space. If the return value of the ddi_model_convert_from(9F) function is DDI_MODEL_NONE, then no data type conversion is necessary. If the request is to set a new size for the space allocated for the quotation, then the qotd_ioctl() routine first sets local variables for the new size, the new quotation, and a new memory allocation cookie. If the device was not opened for writing, the qotd_ioctl() routine returns an error. The qotd_ioctl() routine then checks again for data model mismatch. If the return value of the ddi_model_convert_from(9F) function is DDI_MODEL_ILP32, then the driver declares a 32-bit size variable to receive the new size from ddi_copyin(9F). When the new size is received, the size is converted to the data type of the kernel space. If the new size is zero or is greater than QOTD_MAX_LEN, the qotd_ioctl() routine returns an error. If the new size is valid, then the qotd_ioctl() routine allocates new memory for the quotation and enters a mutex. While the device is busy, the qotd_ioctl() routine checks whether the condition variable has been signaled or a signal(3C) is pending. If either of these conditions is true, the qotd_ioctl() routine exits the mutex, frees the new memory it allocated, and returns an error. When the device is not busy, the qotd_ioctl() routine uses memcpy(9F) to copy the quotation from the driver's state structure to the new space. The qotd_ioctl() routine then frees the memory currently pointed to by the state structure, and updates the state structure members to the new values. The qotd_ioctl() routine then sets the QOTD_CHANGED flag, exits the mutex, and returns. If the request is to discard the current quotation and reset to the initial quotation, then the qotd_ioctl() routine first sets local variables for the new quotation and a new memory allocation cookie. If the device was not opened for writing, the qotd_ioctl() routine returns an error. If the space allocated for the current quotation is different from the space allocated for the initial quotation, then the qotd_ioctl() routine allocates new memory that is the size of the initial space and enters a mutex. While the device is busy, the qotd_ioctl() routine checks whether the condition variable has been signaled or a signal(3C) is pending. If either of these conditions is true, the qotd_ioctl() routine exits the mutex, frees the new memory it allocated, and returns an error. When the device is not busy, the qotd_ioctl() routine frees the memory currently pointed to by the state structure, updates the memory state structure members to the new values, and resets the length to its initial value. If the size of the current quotation space was the same as the initial size and no new memory was allocated, then qotd_ioctl() calls bzero(9F) to clear the current quotation. The qotd_ioctl() routine then calls the strlcpy(9F) function to copy the initial quotation string to the quotation member of the state structure. The qotd_ioctl() routine then unsets the QOTD_CHANGED flag, exits the mutex, and returns. Once the QOTD_CHANGED flag has been set, the only way to unset it is to run the qotdctl command with the -r option. See Exercising the Driver's I/O Controls for more information about the qotdctl command. Quote Of The Day Version 3 SourceEnter the source code shown in the following example into a text file named qotd_3.c. Example 3-5 Quote Of The Day Version 3 Source File#include <sys/types.h>
#include <sys/file.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/cred.h>
#include <sys/uio.h>
#include <sys/stat.h>
#include <sys/ksynch.h>
#include <sys/modctl.h>
#include <sys/conf.h>
#include <sys/devops.h>
#include <sys/debug.h>
#include <sys/cmn_err.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
#include "qotd.h"
#define QOTD_NAME "qotd_3"
static const char init_qotd[]
= "On the whole, I'd rather be in Philadelphia. - W. C. Fields\n";
static const size_t init_qotd_len = 128;
#define QOTD_MAX_LEN 65536 /* Maximum quote in bytes */
#define QOTD_CHANGED 0x1 /* User has made modifications */
#define QOTD_DIDMINOR 0x2 /* Created minors */
#define QOTD_DIDALLOC 0x4 /* Allocated storage space */
#define QOTD_DIDMUTEX 0x8 /* Created mutex */
#define QOTD_DIDCV 0x10 /* Created cv */
#define QOTD_BUSY 0x20 /* Device is busy */
static void *qotd_state_head;
struct qotd_state {
int instance;
dev_info_t *devi;
kmutex_t lock;
kcondvar_t cv;
char *qotd;
size_t qotd_len;
ddi_umem_cookie_t qotd_cookie;
int flags;
};
static int qotd_getinfo(dev_info_t *, ddi_info_cmd_t, void *, void **);
static int qotd_attach(dev_info_t *, ddi_attach_cmd_t);
static int qotd_detach(dev_info_t *, ddi_detach_cmd_t);
static int qotd_open(dev_t *, int, int, cred_t *);
static int qotd_close(dev_t, int, int, cred_t *);
static int qotd_read(dev_t, struct uio *, cred_t *);
static int qotd_write(dev_t, struct uio *, cred_t *);
static int qotd_rw(dev_t, struct uio *, enum uio_rw);
static int qotd_ioctl(dev_t, int, intptr_t, int, cred_t *, int *);
static struct cb_ops qotd_cb_ops = {
qotd_open, /* cb_open */
qotd_close, /* cb_close */
nodev, /* cb_strategy */
nodev, /* cb_print */
nodev, /* cb_dump */
qotd_read, /* cb_read */
qotd_write, /* cb_write */
qotd_ioctl, /* cb_ioctl */
nodev, /* cb_devmap */
nodev, /* cb_mmap */
nodev, /* cb_segmap */
nochpoll, /* cb_chpoll */
ddi_prop_op, /* cb_prop_op */
(struct streamtab *)NULL, /* cb_str */
D_MP | D_64BIT, /* cb_flag */
CB_REV, /* cb_rev */
nodev, /* cb_aread */
nodev /* cb_awrite */
};
static struct dev_ops qotd_dev_ops = {
DEVO_REV, /* devo_rev */
0, /* devo_refcnt */
qotd_getinfo, /* devo_getinfo */
nulldev, /* devo_identify */
nulldev, /* devo_probe */
qotd_attach, /* devo_attach */
qotd_detach, /* devo_detach */
nodev, /* devo_reset */
&qotd_cb_ops, /* devo_cb_ops */
(struct bus_ops *)NULL, /* devo_bus_ops */
nulldev, /* devo_power */
ddi_quiesce_not_needed, /* devo_quiesce */
};
static struct modldrv modldrv = {
&mod_driverops,
"Quote of the day 3.0",
&qotd_dev_ops};
static struct modlinkage modlinkage = {
MODREV_1,
(void *)&modldrv,
NULL
};
int
_init(void)
{
int retval;
if ((retval = ddi_soft_state_init(&qotd_state_head,
sizeof (struct qotd_state), 1)) != 0)
return retval;
if ((retval = mod_install(&modlinkage)) != 0) {
ddi_soft_state_fini(&qotd_state_head);
return (retval);
}
return (retval);
}
int
_info(struct modinfo *modinfop)
{
return (mod_info(&modlinkage, modinfop));
}
int
_fini(void)
{
int retval;
if ((retval = mod_remove(&modlinkage)) != 0)
return (retval);
ddi_soft_state_fini(&qotd_state_head);
return (retval);
}
/*ARGSUSED*/
static int
qotd_getinfo(dev_info_t *dip, ddi_info_cmd_t cmd, void *arg, void **resultp)
{
struct qotd_state *qsp;
int retval = DDI_FAILURE;
ASSERT(resultp != NULL);
switch (cmd) {
case DDI_INFO_DEVT2DEVINFO:
if ((qsp = ddi_get_soft_state(qotd_state_head,
getminor((dev_t)arg))) != NULL) {
*resultp = qsp->devi;
retval = DDI_SUCCESS;
} else
*resultp = NULL;
break;
case DDI_INFO_DEVT2INSTANCE:
*resultp = (void *)getminor((dev_t)arg);
retval = DDI_SUCCESS;
break;
}
return (retval);
}
static int
qotd_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
int instance = ddi_get_instance(dip);
struct qotd_state *qsp;
switch (cmd) {
case DDI_ATTACH:
if (ddi_soft_state_zalloc(qotd_state_head, instance)
!= DDI_SUCCESS) {
cmn_err(CE_WARN, "Unable to allocate state for %d",
instance);
return (DDI_FAILURE);
}
if ((qsp = ddi_get_soft_state(qotd_state_head, instance))
== NULL) {
cmn_err(CE_WARN, "Unable to obtain state for %d",
instance);
ddi_soft_state_free(dip, instance);
return (DDI_FAILURE);
}
if (ddi_create_minor_node(dip, QOTD_NAME, S_IFCHR, instance,
DDI_PSEUDO, 0) != DDI_SUCCESS) {
cmn_err(CE_WARN, "Unable to create minor node for %d",
instance);
(void)qotd_detach(dip, DDI_DETACH);
return (DDI_FAILURE);
}
qsp->flags |= QOTD_DIDMINOR;
qsp->qotd = ddi_umem_alloc(init_qotd_len, DDI_UMEM_NOSLEEP,
&qsp->qotd_cookie);
if (qsp->qotd == NULL) {
cmn_err(CE_WARN, "Unable to allocate storage for %d",
instance);
(void)qotd_detach(dip, DDI_DETACH);
return (DDI_FAILURE);
}
qsp->flags |= QOTD_DIDALLOC;
mutex_init(&qsp->lock, NULL, MUTEX_DRIVER, NULL);
qsp->flags |= QOTD_DIDMUTEX;
cv_init(&qsp->cv, NULL, CV_DRIVER, NULL);
qsp->flags |= QOTD_DIDCV;
(void)strlcpy(qsp->qotd, init_qotd, init_qotd_len);
qsp->qotd_len = init_qotd_len;
qsp->instance = instance;
qsp->devi = dip;
ddi_report_dev(dip);
return (DDI_SUCCESS);
case DDI_RESUME:
return (DDI_SUCCESS);
default:
return (DDI_FAILURE);
}
}
static int
qotd_detach(dev_info_t *dip, ddi_detach_cmd_t cmd)
{
int instance = ddi_get_instance(dip);
struct qotd_state *qsp;
switch (cmd) {
case DDI_DETACH:
qsp = ddi_get_soft_state(qotd_state_head, instance);
if (qsp != NULL) {
ASSERT(!(qsp->flags & QOTD_BUSY));
if (qsp->flags & QOTD_CHANGED)
return (EBUSY);
if (qsp->flags & QOTD_DIDCV)
cv_destroy(&qsp->cv);
if (qsp->flags & QOTD_DIDMUTEX)
mutex_destroy(&qsp->lock);
if (qsp->flags & QOTD_DIDALLOC) {
ASSERT(qsp->qotd != NULL);
ddi_umem_free(qsp->qotd_cookie);
}
if (qsp->flags & QOTD_DIDMINOR)
ddi_remove_minor_node(dip, NULL);
}
ddi_soft_state_free(qotd_state_head, instance);
return (DDI_SUCCESS);
case DDI_SUSPEND:
return (DDI_SUCCESS);
default:
return (DDI_FAILURE);
}
}
/*ARGSUSED*/
static int
qotd_open(dev_t *devp, int flag, int otyp, cred_t *credp)
{
int instance = getminor(*devp);
struct qotd_state *qsp;
if ((qsp = ddi_get_soft_state(qotd_state_head, instance)) == NULL)
return (ENXIO);
ASSERT(qsp->instance == instance);
if (otyp != OTYP_CHR)
return (EINVAL);
return (0);
}
/*ARGSUSED*/
static int
qotd_close(dev_t dev, int flag, int otyp, cred_t *credp)
{
struct qotd_state *qsp;
int instance = getminor(dev);
if ((qsp = ddi_get_soft_state(qotd_state_head, instance)) == NULL)
return (ENXIO);
ASSERT(qsp->instance == instance);
if (otyp != OTYP_CHR)
return (EINVAL);
return (0);
}
/*ARGSUSED*/
static int
qotd_read(dev_t dev, struct uio *uiop, cred_t *credp)
{
return qotd_rw(dev, uiop, UIO_READ);
}
/*ARGSUSED*/
static int
qotd_write(dev_t dev, struct uio *uiop, cred_t *credp)
{
return qotd_rw(dev, uiop, UIO_WRITE);
}
static int
qotd_rw(dev_t dev, struct uio *uiop, enum uio_rw rw)
{
struct qotd_state *qsp;
int instance = getminor(dev);
size_t len = uiop->uio_resid;
int retval;
if ((qsp = ddi_get_soft_state(qotd_state_head, instance)) == NULL)
return (ENXIO);
ASSERT(qsp->instance == instance);
if (len == 0)
return (0);
mutex_enter(&qsp->lock);
while (qsp->flags & QOTD_BUSY) {
if (cv_wait_sig(&qsp->cv, &qsp->lock) == 0) {
mutex_exit(&qsp->lock);
return (EINTR);
}
}
if (uiop->uio_offset < 0 || uiop->uio_offset > qsp->qotd_len) {
mutex_exit(&qsp->lock);
return (EINVAL);
}
if (len > qsp->qotd_len - uiop->uio_offset)
len = qsp->qotd_len - uiop->uio_offset;
if (len == 0) {
mutex_exit(&qsp->lock);
return (rw == UIO_WRITE ? ENOSPC : 0);
}
qsp->flags |= QOTD_BUSY;
mutex_exit(&qsp->lock);
retval = uiomove((void *)(qsp->qotd + uiop->uio_offset), len, rw, uiop);
mutex_enter(&qsp->lock);
if (rw == UIO_WRITE)
qsp->flags |= QOTD_CHANGED;
qsp->flags &= ~QOTD_BUSY;
cv_broadcast(&qsp->cv);
mutex_exit(&qsp->lock);
return (retval);
}
/*ARGSUSED*/
static int
qotd_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp,
int *rvalp)
{
struct qotd_state *qsp;
int instance = getminor(dev);
if ((qsp = ddi_get_soft_state(qotd_state_head, instance)) == NULL)
return (ENXIO);
ASSERT(qsp->instance == instance);
switch (cmd) {
case QOTDIOCGSZ: {
/* We are not guaranteed that ddi_copyout(9F) will read
* automatically anything larger than a byte. Therefore we
* must duplicate the size before copying it out to the user.
*/
size_t sz = qsp->qotd_len;
if (!(mode & FREAD))
return (EACCES);
#ifdef _MULTI_DATAMODEL
switch (ddi_model_convert_from(mode & FMODELS)) {
case DDI_MODEL_ILP32: {
size32_t sz32 = (size32_t)sz;
if (ddi_copyout(&sz32, (void *)arg, sizeof (size32_t),
mode) != 0)
return (EFAULT);
return (0);
}
case DDI_MODEL_NONE:
if (ddi_copyout(&sz, (void *)arg, sizeof (size_t),
mode) != 0)
return (EFAULT);
return (0);
default:
cmn_err(CE_WARN, "Invalid data model %d in ioctl\n",
ddi_model_convert_from(mode & FMODELS));
return (ENOTSUP);
}
#else /* ! _MULTI_DATAMODEL */
if (ddi_copyout(&sz, (void *)arg, sizeof (size_t), mode) != 0)
return (EFAULT);
return (0);
#endif /* _MULTI_DATAMODEL */
}
case QOTDIOCSSZ: {
size_t new_len;
char *new_qotd;
ddi_umem_cookie_t new_cookie;
uint_t model;
if (!(mode & FWRITE))
return (EACCES);
#ifdef _MULTI_DATAMODEL
model = ddi_model_convert_from(mode & FMODELS);
switch (model) {
case DDI_MODEL_ILP32: {
size32_t sz32;
if (ddi_copyin((void *)arg, &sz32, sizeof (size32_t),
mode) != 0)
return (EFAULT);
new_len = (size_t)sz32;
break;
}
case DDI_MODEL_NONE:
if (ddi_copyin((void *)arg, &new_len, sizeof (size_t),
mode) != 0)
return (EFAULT);
break;
default:
cmn_err(CE_WARN, "Invalid data model %d in ioctl\n",
model);
return (ENOTSUP);
}
#else /* ! _MULTI_DATAMODEL */
if (ddi_copyin((void *)arg, &new_len, sizeof (size_t),
mode) != 0)
return (EFAULT);
#endif /* _MULTI_DATAMODEL */
if (new_len == 0 || new_len > QOTD_MAX_LEN)
return (EINVAL);
new_qotd = ddi_umem_alloc(new_len, DDI_UMEM_SLEEP, &new_cookie);
mutex_enter(&qsp->lock);
while (qsp->flags & QOTD_BUSY) {
if (cv_wait_sig(&qsp->cv, &qsp->lock) == 0) {
mutex_exit(&qsp->lock);
ddi_umem_free(new_cookie);
return (EINTR);
}
}
memcpy(new_qotd, qsp->qotd, min(qsp->qotd_len, new_len));
ddi_umem_free(qsp->qotd_cookie);
qsp->qotd = new_qotd;
qsp->qotd_cookie = new_cookie;
qsp->qotd_len = new_len;
qsp->flags |= QOTD_CHANGED;
mutex_exit(&qsp->lock);
return (0);
}
case QOTDIOCDISCARD: {
char *new_qotd = NULL;
ddi_umem_cookie_t new_cookie;
if (!(mode & FWRITE))
return (EACCES);
if (qsp->qotd_len != init_qotd_len) {
new_qotd = ddi_umem_alloc(init_qotd_len,
DDI_UMEM_SLEEP, &new_cookie);
}
mutex_enter(&qsp->lock);
while (qsp->flags & QOTD_BUSY) {
if (cv_wait_sig(&qsp->cv, &qsp->lock) == 0) {
mutex_exit(&qsp->lock);
if (new_qotd != NULL)
ddi_umem_free(new_cookie);
return (EINTR);
}
}
if (new_qotd != NULL) {
ddi_umem_free(qsp->qotd_cookie);
qsp->qotd = new_qotd;
qsp->qotd_cookie = new_cookie;
qsp->qotd_len = init_qotd_len;
} else {
bzero(qsp->qotd, qsp->qotd_len);
}
(void)strlcpy(qsp->qotd, init_qotd, init_qotd_len);
qsp->flags &= ~QOTD_CHANGED;
mutex_exit(&qsp->lock);
return (0);
}
default:
return (ENOTTY);
}
}Enter the definitions shown in the following example into a text file named qotd.h. Example 3-6 Quote Of The Day Version 3 Header File#ifndef _SYS_QOTD_H
#define _SYS_QOTD_H
#define QOTDIOC ('q' << 24 | 't' << 16 | 'd' << 8)
#define QOTDIOCGSZ (QOTDIOC | 1) /* Get quote buffer size */
#define QOTDIOCSSZ (QOTDIOC | 2) /* Set new quote buffer size */
#define QOTDIOCDISCARD (QOTDIOC | 3) /* Discard quotes and reset */
#endif /* _SYS_QOTD_H */Enter the configuration information shown in the following example into a text file named qotd_3.conf. Example 3-7 Quote Of The Day Version 3 Configuration Filename="qotd_3" parent="pseudo" instance=0; Building and Installing Quote Of The Day Version 3Compile and link the driver. The following example shows compiling and linking for a 32-bit architecture: % cc -D_KERNEL -c qotd_3.c % ld -r -o qotd_3 qotd_3.o Make sure you are user root when you install the driver. Copy the driver binary to the /tmp directory as discussed in Building and Installing the Template Driver. # cp qotd_3 /tmp # ln -s /tmp/qotd_3 /usr/kernel/drv/qotd_3 Copy the configuration file to the kernel driver area of the system. # cp qotd_3.conf /usr/kernel/drv In a separate window, enter the following command: % tail -f /var/adm/messages Make sure you are user root when you load the driver. Use the add_drv(1M) command to load the driver: # add_drv qotd_3 You should see the following messages in the window where you are viewing /var/adm/messages: date time machine pseudo: [ID 129642 kern.info] pseudo-device: qotd_30 date time machine genunix: [ID 936769 kern.info] qotd_30 is /pseudo/qotd_3@0 Using Quote Of The Day Version 3This section describes how to read and write the qotd_3 device and how to test the driver's I/O controls. The I/O controls include retrieving the size of the storage buffer, setting a new size for the storage buffer, and reinitializing the storage buffer size and contents. Reading the DeviceWhen you access this qotd_3 device for reading, the command you use to access the device retrieves the data from the device node. The command then displays the data in the same way that the command displays any other input. To get the name of the device special file, look in the /devices directory: % ls -l /devices/pseudo/qotd* crw------- 1 root sys 122, 0 date time /devices/pseudo/qotd_3@0:qotd_3 To read the qotd_3 device, you can use the cat(1) command: # cat /devices/pseudo/qotd_3@0:qotd_3 On the whole, I'd rather be in Philadelphia. - W. C. Fields Writing the DeviceTo write to the qotd_3 device, you can redirect command-line input: # echo "A life is not important except in the impact it has on others. - Jackie Robinson" >> /devices/pseudo/qotd_3@0:qotd_3 # cat /devices/pseudo/qotd_3@0:qotd_3 A life is not important except in the impact it has on others. - Jackie Robinson Exercising the Driver's I/O ControlsIn addition to changes in the driver, Quote Of The Day Version 3 introduces a new utility program. The qotdctl command enables you to test the driver's I/O controls. The source for this command is shown in Example 3-8. Compile the qotdctl utility as follows: % cc -o qotdctl qotdctl.c The qotdctl command has the following options:
Use the qotdctl command to test the driver's I/O controls: # ./qotdctl -V
qotdctl 1.0
# ./qotdctl -h
Usage: ./qotdctl [-d device] {-g | -h | -r | -s size | -V}
# ./qotdctl -g
open: No such file or directoryBy default, the qotdctl command accesses the /dev/qotd0 device. The qotd_3 device in this example is /devices/pseudo/qotd_3@0:qotd_3. Either define a link from /dev/qotd0 to /devices/pseudo/qotd_3@0:qotd_3 or use the -d option to specify the correct device: # ./qotdctl -d /devices/pseudo/qotd_3@0:qotd_3 -g 128 # ./qotdctl -d /devices/pseudo/qotd_3@0:qotd_3 -s 512 # ./qotdctl -d /devices/pseudo/qotd_3@0:qotd_3 -g 512 # ./qotdctl -d /devices/pseudo/qotd_3@0:qotd_3 -r # cat /devices/pseudo/qotd_3@0:qotd_3 On the whole, I'd rather be in Philadelphia. - W. C. Fields If you try to remove the device now, you will receive an error message: # rem_drv qotd_3 Device busy Cannot unload module: qotd_3 Will be unloaded upon reboot. The device is still marked busy because you have not told the driver that you are no longer interested in this device. Run the qotdctl command with the -r option to unset the QOTD_CHANGED flag in the driver and mark the device not busy: # ./qotdctl -r Enter the source code shown in the following example into a text file named qotdctl.c. Example 3-8 Quote Of The Day I/O Control Command Source File#include <sys/ioctl.h>
#include <fcntl.h>
#include <stdio.h>
#include <unistd.h>
#include <errno.h>
#include <stdlib.h>
#include "qotd.h"
static const char *DEFAULT_DEVICE = "/dev/qotd0";
static const char *VERSION = "1.0";
static void show_usage(const char *);
static void get_size(const char *);
static void set_size(const char *, size_t);
static void reset_dev(const char *);
int
main(int argc, char *argv[])
{
int op = -1;
int opt;
int invalid_usage = 0;
size_t sz_arg;
const char *device = DEFAULT_DEVICE;
while ((opt = getopt(argc, argv,
"d:(device)g(get-size)h(help)r(reset)s:(set-size)V(version)"))
!= -1) {
switch (opt) {
case 'd':
device = optarg;
break;
case 'g':
if (op >= 0)
invalid_usage++;
op = QOTDIOCGSZ;
break;
case 'h':
show_usage(argv[0]);
exit(0);
/*NOTREACHED*/
case 'r':
if (op >= 0)
invalid_usage++;
op = QOTDIOCDISCARD;
break;
case 's':
if (op >= 0)
invalid_usage++;
op = QOTDIOCSSZ;
sz_arg = (size_t)atol(optarg);
break;
case 'V':
(void) printf("qotdctl %s\n", VERSION);
exit(0);
/*NOTREACHED*/
default:
invalid_usage++;
break;
}
}
if (invalid_usage > 0 || op < 0) {
show_usage(argv[0]);
exit(1);
}
switch (op) {
case QOTDIOCGSZ:
get_size(device);
break;
case QOTDIOCSSZ:
set_size(device, sz_arg);
break;
case QOTDIOCDISCARD:
reset_dev(device);
break;
default:
(void) fprintf(stderr,
"internal error - invalid operation %d\n", op);
exit(2);
}
return (0);
}
static void
show_usage(const char *execname)
{
(void) fprintf(stderr,
"Usage: %s [-d device] {-g | -h | -r | -s size | -V}\n", execname);
}
static void
get_size(const char *dev)
{
size_t sz;
int fd;
if ((fd = open(dev, O_RDONLY)) < 0) {
perror("open");
exit(3);
}
if (ioctl(fd, QOTDIOCGSZ, &sz) < 0) {
perror("QOTDIOCGSZ");
exit(4);
}
(void) close(fd);
(void) printf("%zu\n", sz);
}
static void
set_size(const char *dev, size_t sz)
{
int fd;
if ((fd = open(dev, O_RDWR)) < 0) {
perror("open");
exit(3);
}
if (ioctl(fd, QOTDIOCSSZ, &sz) < 0) {
perror("QOTDIOCSSZ");
exit(4);
}
(void) close(fd);
}
static void
reset_dev(const char *dev)
{
int fd;
if ((fd = open(dev, O_RDWR)) < 0) {
perror("open");
exit(3);
}
if (ioctl(fd, QOTDIOCDISCARD) < 0) {
perror("QOTDIOCDISCARD");
exit(4);
}
(void) close(fd);
}
|
||
|