Example 9–1 is a sample print driver for an interrupt-per-character line printer. The driver is unidirectional—it has no read-side processing. It demonstrates some differences between module and driver programming, including the following:
Declarations for driver configuration
Open handling
A driver is passed a device number
Flush handling
A driver must loop M_FLUSH messages back upstream
Interrupt routine
A driver registers interrupt handler and processes interrupts
Most of the STREAMS processing in the driver is independent of the actual printer hardware; in this example, actual interaction with the printer is limited to the lpoutchar function, which prints one character at a time. For purposes of demonstration, the “printer hardware” is actually the system console, accessed through cmn_err(9F). Since there's no actual hardware to generate a genuine hardware interrupt, lpoutchar simulates interrupts using ddi_trigger_softintr(9F). For a real printer, the lpoutchar function is rewritten to send a character to the printer, which should generate a hardware interrupt.
The driver declarations follow. After specifying header files (include <sys/ddi.h> and <sys/sunddi.h> as the last two header files), the driver declares a per-printer structure, struct lp. This structure contains members that enable the driver to keep track of each instance of the driver, such as flags (what the driver is doing), msg (the current STREAMS print message), qptr (pointer to the stream's write queue), dip (the instance's device information handle), iblock_cookie (for registering an interrupt handler), siid (the handle of the soft interrupt), and lp_lock (a mutex to protect the data structure from multithreaded race conditions). The driver next defines the bits for the flags member of struct lp; the driver defines only one flag, BUSY.
Following function prototypes, the driver provides some standard STREAMS declarations: a module_info(9S) structure (minfo), a qinit(9S) structure for the read side (rinit) that is initialized by the driver's open and close entry points, a qinit(9S) structure for the write side (winit) that is initialized by the write put procedure, and a streamtab(9S) that points to rinit and winit. The values in the module name and ID fields in the module_info(9S) structure must be unique in the system. Because the driver is unidirectional, there is no read side put or service procedure. The flow control limits for use on the write side are 50 bytes for the low-watermark and 150 bytes for the high-watermark.
The driver next declares lp_state. This is an anchor on which the various “soft-state” functions provided by the DDK operate. The ddi_soft_state(9F) manual page describes how to maintain multiple instances of a driver.
The driver next declares acb_ops(9S) structure, which is required in all device drivers. In non-STREAMS device drivers, cb_ops(9S) contains vectors to the table-driven entry points. For STREAMS drivers, however, cb_ops(9S) contains mostly nodev entries. The cb_stream field, however, is initialized with a pointer to the driver's streamtab(9S) structure. This indicates to the kernel that this driver is a STREAMS driver.
Next, the driver declares a dev_ops(9S) structure, which points to the various initialization entry points as well as to the cb_ops(9S) structure. Finally, the driver declares a struct moldrv and a struct modlinkage for use by the kernel linker when the driver is dynamically loaded. struct moldrv contains a pointer to mod_driverops (a significant difference between a STREAMS driver and a STREAMS module—a STREAMS module would contain a pointer to mod_strops instead).
Example 9-1 Simple Line Printer Driver#include <sys/types.h>
#include <sys/param.h>
#include <sys/stream.h>
#include <sys/stropts.h>
#include <sys/signal.h>
#include <sys/errno.h>
#include <sys/cred.h>
#include <sys/stat.h>
#include <sys/modctl.h>
#include <sys/conf.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
/* This is a private data structure, one per minor device number */
struct lp {
short flags; /* flags -- see below */
mblk_t *msg; /* current message being output */
queue_t *qptr; /* back pointer to write queue */
dev_info_t *dip; /* devinfo handle */
ddi_iblock_cookie_t iblock_cookie;
ddi_softintr_t siid;
kmutex_t lp_lock; /* sync lock */
};
/* flags bits */
#define BUSY 1 /* dev is running, int is forthcoming */
/*
* Function prototypes.
*/
static int lpattach(dev_info_t *, ddi_attach_cmd_t);
static int lpdetach(dev_info_t *, ddi_detach_cmd_t);
static int lpgetinfo(dev_info_t *, ddi_info_cmd_t, void *, void **);
static int lpidentify(dev_info_t *);
static uint lpintr(caddr_t lp);
static void lpout(struct lp *lp);
static void lpoutchar(struct lp *lp, char c);
static int lpopen(queue_t*, dev_t*, int, int, cred_t*);
static int lpclose(queue_t*, int, cred_t*);
static int lpwput(queue_t*, mblk_t*);
/* Standard Streams declarations */
static struct module_info minfo = {
0xaabb,
"lp",
0,
INFPSZ,
150,
50
};
static struct qinit rinit = {
(int (*)()) NULL,
(int (*)()) NULL,
lpopen,
lpclose,
(int (*)()) NULL,
&minfo,
NULL
};
static struct qinit winit = {
lpwput,
(int (*)()) NULL,
(int (*)()) NULL,
(int (*)()) NULL,
(int (*)()) NULL,
&minfo,
NULL
};
static struct streamtab lpstrinfo = { &rinit, &winit, NULL, NULL };
/*
* An opaque handle where our lp lives
*/
static void *lp_state;
/* Module Loading/Unloading and Autoconfiguration declarations */
static struct cb_ops lp_cb_ops = {
nodev, /* cb_open */
nodev, /* cb_close */
nodev, /* cb_strategy */
nodev, /* cb_print */
nodev, /* cb_dump */
nodev, /* cb_read */
nodev, /* cb_write */
nodev, /* cb_ioctl */
nodev, /* cb_devmap */
nodev, /* cb_mmap */
nodev, /* cb_segmap */
nochpoll, /* cb_chpoll */
ddi_prop_op, /* cb_prop_op */
&lpstrinfo, /* cb_stream */
D_MP | D_NEW, /* cb_flag */
};
static struct dev_ops lp_ops = {
DEVO_REV, /* devo_rev */
0, /* devo_refcnt */
lpgetinfo, /* devo_getinfo */
lpidentify, /* devo_identify */
nulldev, /* devo_probe */
lpattach, /* devo_attach */
lpdetach, /* devo_detach */
nodev, /* devo_reset */
&lp_cb_ops, /* devo_cb_ops */
(struct bus_ops *)NULL /* devo_bus_ops */
};
/*
* Module linkage information for the kernel.
*/
static struct modldrv modldrv = {
&mod_driverops,
"Simple Sample Printer Streams Driver", /* Description */
&lp_ops, /* driver ops */
};
static struct modlinkage modlinkage = {
MODREV_1, &modldrv, NULL
};
Example 9–2 shows the required driver configuration entry points _init(9E), _fini(9E), and _info(9E). In addition to installing the driver using mod_install(9F), the _init entry point also initializes the per-instance driver structure using ddi_soft_state_init(9F). _fini(9E) performs the complementary calls to mod_remove(9F) and ddi_soft_state_fini(9F) to unload the driver and release the resources used by the soft-state routines.
Example 9-2 Configuration Entry Pointsint
_init(void)
{
int e;
if ((e = ddi_soft_state_init(&lp_state,
sizeof (struct lp), 1)) != 0) {
return (e);
}
if ((e = mod_install(&modlinkage)) != 0) {
ddi_soft_state_fini(&lp_state);
}
return (e);
}
int
_fini(void)
{
int e;
if ((e = mod_remove(&modlinkage)) != 0) {
return (e);
}
ddi_soft_state_fini(&lp_state);
return (e);
}
int
_info(struct modinfo *modinfop)
{
return (mod_info(&modlinkage, modinfop));
}
Example 9–3 shows the lp driver's implementation of the initialization entry points. In lpidentify, the driver ensures that the name of the device being attached is “lp”.
lpattach first uses ddi_soft_state_zalloc(9F) to allocate a per-instance structure for the printer being attached. Next it creates a node in the device tree for the printer using ddi_create_minor_node(9F); user programs use the node to access the device. lpattach then registers the driver interrupt handler because the sample is driver pseudo-hardware, the driver uses soft interrupts. A driver for a real printer would use ddi_add_intr(9F) instead of ddi_add_softintr(9F). A driver for a real printer would also need to perform any other required hardware initialization in lpattach. Finally, lpattach initializes the per-instance mutex.
In lpdetach, the driver undoes everything it did in lpattach.
lpgetinfo uses the soft-state structures to obtain the required information.
Example 9-3 Initialization Entry Pointsstatic int
lpidentify(dev_info_t *dip)
{
if (strcmp(ddi_get_name(dip), "lp") == 0) {
return (DDI_IDENTIFIED);
} else
return (DDI_NOT_IDENTIFIED);
}
static int
lpattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
int instance;
struct lp *lpp;
switch (cmd) {
case DDI_ATTACH:
instance = ddi_get_instance(dip);
if (ddi_soft_state_zalloc(lp_state, instance) != DDI_SUCCESS) {
cmn_err(CE_CONT, "%s%d: can't allocate state\n",
ddi_get_name(dip), instance);
return (DDI_FAILURE);
} else
lpp = ddi_get_soft_state(lp_state, instance);
if (ddi_create_minor_node(dip, "strlp", S_IFCHR,
instance, NULL, 0) == DDI_FAILURE) {
ddi_remove_minor_node(dip, NULL);
goto attach_failed;
}
lpp->dip = dip;
ddi_set_driver_private(dip, (caddr_t)lpp);
/* add (soft) interrupt */
if (ddi_add_softintr(dip, DDI_SOFTINT_LOW, &lpp->siid,
&lpp->iblock_cookie, 0, lpintr, (caddr_t)lpp)
!= DDI_SUCCESS) {
ddi_remove_minor_node(dip, NULL);
goto attach_failed;
}
mutex_init(&lpp->lp_lock, "lp lock", MUTEX_DRIVER,
(void *)lpp->iblock_cookie);
ddi_report_dev(dip);
return (DDI_SUCCESS);
default:
return (DDI_FAILURE);
}
attach_failed:
/*
* Use our own detach routine to toss
* away any stuff we allocated above.
*/
(void) lpdetach(dip, DDI_DETACH);
return (DDI_FAILURE);
}
static int
lpdetach(dev_info_t *dip, ddi_detach_cmd_t cmd)
{
int instance;
struct lp *lpp;
switch (cmd) {
case DDI_DETACH:
/*
* Undo what we did in lpattach, freeing resources
* and removing things we installed. The system
* framework guarantees we are not active with this devinfo
* node in any other entry points at this time.
*/
ddi_prop_remove_all(dip);
instance = ddi_get_instance(dip);
lpp = ddi_get_soft_state(lp_state, instance);
ddi_remove_minor_node(dip, NULL);
ddi_remove_softintr(lpp->siid);
ddi_soft_state_free(lp_state, instance);
return (DDI_SUCCESS);
default:
return (DDI_FAILURE);
}
}
/*ARGSUSED*/
static int
lpgetinfo(dev_info_t *dip, ddi_info_cmd_t infocmd, void *arg,
void **result)
{
struct lp *lpp;
int error = DDI_FAILURE;
switch (infocmd) {
case DDI_INFO_DEVT2DEVINFO:
if ((lpp = ddi_get_soft_state(lp_state,
getminor((dev_t)arg))) != NULL) {
*result = lpp->dip;
error = DDI_SUCCESS;
} else
*result = NULL;
break;
case DDI_INFO_DEVT2INSTANCE:
*result = (void *)getminor((dev_t)arg);
error = DDI_SUCCESS;
break;
default:
break;
}
return (error);
}
The STREAMS mechanism allows only one stream per minor device. The driver open routine is called whenever a STREAMS device is opened. open matches the correct private data structure with the stream using ddi_get_soft_state(9F). The driver open, lpopen in Example 9–4 , has the same interface as the module open.
The stream flag, sflag, must have the value 0, indicating a normal driver open. devp pointers to the major/minor device number for the port. After checking sflag, lpopen uses devp to find the correct soft-state structure.
The next check, if (q->q_ptr)..., determines if the printer is already open. q_ptr is a driver or module private data pointer. It can be used by the driver for any purpose and is initialized to zero by STREAMS before the first open. In this example, the driver sets the value of q_ptr, in both the read and write queue structures, to point to the device's per-instance data structure. If the pointer is non-NULL, it means the printer is already open, so lpopen returns EBUSY to avoid merging printouts from multiple users.
The driver close routine is called by the stream head. Any messages left in the queue are automatically removed by STREAMS. The stream is dismantled and data structures are released.
Example 9-4 Queue Processing Entry Points/*ARGSUSED*/
static int
lpopen(
queue_t *q, /* read queue */
dev_t *devp,
int flag,
int sflag,
cred_t *credp)
{
struct lp *lp;
if (sflag) /* driver refuses to do module or clone open */
return (ENXIO);
if ((lp = ddi_get_soft_state(lp_state, getminor(*devp))) == NULL)
return (ENXIO);
/* Check if open already. Can't have multiple opens */
if (q->q_ptr) {
return (EBUSY);
}
lp->qptr = WR(q);
q->q_ptr = (char *) lp;
WR(q)->q_ptr = (char *) lp;
qprocson(q);
return (0);
}
/*ARGSUSED*/
static int
lpclose(
queue_t *q, /* read queue */
int flag,
cred_t *credp)
{
struct lp *lp;
qprocsoff(q);
lp = (struct lp *) q->q_ptr;
/*
* Free message, queue is automatically
* flushed by STREAMS
*/
mutex_enter(&lp->lp_lock);
if (lp->msg) {
freemsg(lp->msg);
lp->msg = NULL;
}
lp->flags = 0;
mutex_exit(&lp->lp_lock);
return (0);
}
There are no physical pointers between the read and write queue of a pair. WR(9F) is a queue pointer function. WR(9F) generates the write pointer from the read pointer. RD(9F) and OTHERQ(9F) are additional queue pointer functions. RD(9F) generates the read pointer from the write pointer, and OTHERQ(9F) generates the mate pointer from either.
The write put procedure in Example 9–5 , lpwput, illustrates driver M_FLUSH handling. Note that all drivers are expected to incorporate flush handling.
If FLUSHW is set, the write message queue is flushed, and (in this example) the leading message (lp->msg) is also flushed. lp_lock protects the driver's per-instance data structure.
In most drivers, if FLUSHR is set, the read queue is flushed. However, in this example, no messages are ever placed on the read queue, so flushing it is not necessary. The FLUSHW bit is cleared and the message is sent upstream using qreply(9F). If FLUSHR is not set, the message is discarded.
The stream head always performs the following actions on flush requests received on the read side from downstream. If FLUSHR is set, messages waiting to be sent to user space are flushed. If FLUSHW is set, the stream head clears the FLUSHR bit and sends the M_FLUSH message downstream. In this manner, a single M_FLUSH message sent from the driver can reach all queues in a stream. A module must send two M_FLUSH messages to have the same effect.
lpwput queues M_DATA and M_IOCTL messages and if the device is not busy, starts output by calling lpout. Message types that are not recognized are discarded (in the default case of the switch).
Example 9-5 Driver Flush Handlingstatic int lpwput(
queue_t *q, /* write queue */
mblk_t *mp) /* message pointer */
{
struct lp *lp;
lp = (struct lp *)q->q_ptr;
switch (mp->b_datap->db_type) {
default:
freemsg(mp);
break;
case M_FLUSH: /* Canonical flush handling */
if (*mp->b_rptr & FLUSHW) {
flushq(q, FLUSHDATA);
mutex_enter(&lp->lp_lock); /* lock any access to lp */
if (lp->msg) {
freemsg(lp->msg);
lp->msg = NULL;
}
mutex_exit(&lp->lp_lock);
}
if (*mp->b_rptr & FLUSHR) {
*mp->b_rptr &= ~FLUSHW;
qreply(q, mp);
} else
freemsg(mp);
break;
case M_IOCTL:
case M_DATA:
(void) putq(q, mp);
mutex_enter(&lp->lp_lock);
if (!(lp->flags & BUSY))
lpout(lp);
mutex_exit(&lp->lp_lock);
}
return (0);
}
Example 9–6 shows the interrupt handling for the printer driver.
lpintr is the driver-interrupt handler registered by the attach routine.
lpout takes a single character from the queue and sends it to the printer. For convenience, the message currently being output is stored in lp->msg in the per-instance structure. This assumes that the message is called with the mutex held.
lpoutchar sends a single character to the printer (in this case the system console using cmn_err(9F)) and interrupts when complete. Of course, hardware would generate a hard interrupt, so the call to ddi_trigger_softintr(9F) would be unnecessary.
Example 9-6 Driver Interrupt Handling/* Device interrupt routine */static uint
lpintr(caddr_t lp) /* minor device number of lp */
{
struct lp *lpp = (struct lp *)lp;
mutex_enter(&lpp->lp_lock);
if (!(lpp->flags & BUSY)) {
mutex_exit(&lpp->lp_lock);
return (DDI_INTR_UNCLAIMED);
}
lpp->flags &= ~BUSY;
lpout(lpp);
mutex_exit(&lpp->lp_lock);
return (DDI_INTR_CLAIMED);
}
/* Start output to device - used by put procedure and driver */
static void
lpout(
struct lp *lp)
{
mblk_t *bp;
queue_t *q;
q = lp->qptr;
loop:
if ((bp = lp->msg) == NULL) { /*no current message*/
if ((bp = getq(q)) == NULL) {
lp->flags &= ~BUSY;
return;
}
if (bp->b_datap->db_type == M_IOCTL) {
/* lpdoioctl(lp, bp); */
goto loop;
}
lp->msg = bp; /* new message */
}
if (bp->b_rptr >= bp->b_wptr) { /* validate message */
bp = lp->msg->b_cont;
lp->msg->b_cont = NULL;
freeb(lp->msg);
lp->msg = bp;
goto loop;
}
lpoutchar(lp, *bp->b_rptr++); /*output one character*/
lp->flags |= BUSY;
}
static void
lpoutchar(
struct lp *lp,
char c)
{
cmn_err(CE_CONT, “%c”, c);
ddi_trigger_softintr(lp->siid);
}
The same utilities (described in Chapter 10, STREAMS Modules) and mechanisms used for module flow control are used by drivers.
When the message is queued, putq(9F) increments the value of q_count by the size of the message and compares the result to the driver's write high-watermark (q_hiwat) value. If the count reaches q_hiwat, putq(9F) sets the internal FULL indicator for the driver write queue. This causes messages from upstream to be halted (canputnext(9F) returns FALSE) until the write queue count drops below q_lowat. The driver messages waiting to be output through lpout are dequeued by the driver output interrupt routine with getq(9F), which decrements the count. If the resulting count is below q_lowat, getq(9F) back-enables any upstream queue that had been blocked.
For priority band data, qb_count, qb_hiwat, and qb_lowat are used.
STREAMS with flow control can be used on the driver read side to handle temporary upstream blocks.
To some extent, a driver or a module can control when its upstream transmission becomes blocked. Control is available through the M_SETOPTS message (see Appendix A, Message Types) to modify the stream head read-side flow control limits.