STREAMS Modules

This chapter provides specific examples of how modules work, including code samples.

• Module Overview

• Data Flow Control

• Design Guidelines

Module Overview

STREAMS modules process messages as they flow through the stream between an application and a character device driver. A STREAMS module is a pair of initialized queue structures and the specified kernel-level procedures that process data, status, and control information for the two queues. A stream can contain zero or more modules. Application processes push (stack) modules on a stream using the I_PUSH ioctl(2) and pop (unstack) them using the I_POP ioctl(2).

STREAMS Module Configuration

Like device drivers, STREAMS modules are dynamically linked and can be loaded into and unloaded from the running kernel.

Note - The word module is used differently when talking about drivers. A device driver is a kernel-loadable module that provides the interface between a device and the Device Driver Interface, and is linked to the kernel when it is first invoked.

A loadable module must provide linkage information to the kernel in an initialized modlstrmod(9S) and three entry points: _init(9E), _info(9E), and _fini(9E).

STREAMS modules can be unloaded from the kernel when not pushed onto a stream. A STREAMS module can prevent itself from being unloaded by returning an error (selected from errno.h) from its _fini(9E) routine (EBUSY is a good choice).

Module Procedures

STREAMS module procedures (open, close, put, service) have already been described in the previous chapters. This section shows some examples and further describes attributes common to module put and service procedures.

A module's put procedure is called by the preceding module, driver, or stream head, and always before that queue's service procedure. The put procedure does any immediate processing (for example, high-priority messages), while the corresponding service procedure performs deferred processing.

The service procedure is used primarily for performing deferred processing, with a secondary task to implement flow control. Once the service procedure is enabled, it can start but not finish before running user-level code. The put and service procedures must not block because there is no thread synchronization being done.

Example 10-1 shows a STREAMS module read-side put procedure.

Example 10-1 Read-side put Procedure

static int
modrput (queue_t *q, mblk_t *mp)
{
		struct mod_prv *modptr;

		modptr = (struct mod_prv *) q->q_ptr;  /*state info*/

		if (mp->b_datap->db_type >= QPCTL){	/*proc pri msg*/
			putnext(q, mp); 						/* and pass it on */
			return (0);
		}

		switch(mp->b_datap->db_type) {
			case M_DATA:				/* can process message data */
				putq(q, mp);	/* queue msg for service procedure */
			return (0);

			case M_PROTO:			/* handle protocol control message */
					.
					.
					.

			default:
					putnext(q, mp);		
					return (0);
		}
}

The preceding code does the following:

• A pointer to a queue defining an instance of the module and a pointer to a message are passed to the put procedure.

• The put procedure performs a switch on the type of the message. For each message type, the put procedure either enqueues the message for further processing by the module service procedure, or passes the message to the next module in the stream.

• High-priority messages are typically processed immediately. Immediate processing is not required by the put procedure and the message is passed to the next module.

• Ordinary (or normal) messages are either queued or passed along the stream.

Example 10-2 shows a module write-side put procedure.

Example 10-2 Write-side put Procedure

static int
modwput (queue_t *q, mblk_t *mp)
{
 	struct mod_prv *modptr;

 modptr = (struct mod_prv *) q->q_ptr;		/*state info*/

 if (mp->b_datap->db_type >= QPCTL){	/* proc pri msg and pass it on */
			putnext(q, mp);
			return (0);
		}

 switch(mp->b_datap->db_type) {
		case M_DATA:			/* can process message data queue msg */
			putq(q, mp);		/* for service procedure or pass message */
								/* along with putnext(q,mp) */
			return (0);

		case M_PROTO:
				.
				.
				.

		case M_IOCTL:		/* if cmd in msg is recognized */
							/* process message and send reply back */
							/* else pass message downstream */

		default:
			putnext(q, mp);
			return (0);
	 }
}

The write-side put procedure, unlike the read side, can be passed M_IOCTL messages. The module must recognize and process the ioctl(2) command, or pass the message downstream if it does not recognize the command.

Example 10-3 shows a general scenario employed by the module's service procedure.

Example 10-3 STREAMS Module Service Procedure

static int
modrsrv (queue_t *q)
{
		mblk_t *mp;

		while ((mp = getq(q)) != NULL) {
			/* flow control check */
			if (!(mp->b_datap->db_type >= QPCTL) && !canputnext(q)) {	
				putbq(q, mp);						/* return message */
				return (0);
			}
			/* process the message */
				.
				.
				.
			putnext(q, mp); /* pass the result */
		}
		return (0);
}