STREAMS/UX Uniprocessor Synchronization

A put, service, open, or close routine can pass its own queue or the other queue in its queue pair to a STREAMS/UX kernel utility. Many STREAMS/UX utilities operate on a queue. For example, getq takes a queue as an input parameter and returns a message from the queue. A service routine can only pass its queue or the other queue in its queue pair to getq. The restricted utilities are backq, bcanputnext, canputnext, flushband, flushq, freezestr, getq, insq, putbq, putnext, putnextctl, putnextctl1, putnextctl2, putq, qreply, qsize, rmvq, SAMESTR, strqget, strqset, and unfreezestr. The putq utility is not restricted when it is passed a driver's read queue or a lower mux's write queue. Any put or service routine can call putq if it passes it a driver's read queue or a lower mux's write queue. However, putq's caller must guarantee that the queue passed is still allocated. Some STREAMS/UX utilities, such as canput, are commonly passed a parameter of the form q->q_next. These routines are restricted in a slightly different way than those listed above. A put or service routine can only pass its own queue's q_next field or the q_next field of the other queue in its queue pair. These requirements apply to bcanput, canput, put, putctl, putctl1, putctl2, and streams_put. These utilities are not restricted when they are passed a parameter of the form q, except that the queue must still be allocated.

Some STREAMS/UX utilities cannot be called from user functions passed to timeout and bufcall or from non-STREAMS/UX code in the kernel. Also, this software cannot share data structures with STREAMS/UX modules and drivers, unless it raises the spl level to protect against interrupts. The utilities which cannot be called are backq, bcanputnext, canputnext, flushband, flushq, freezestr, getq, insq, putbq, putnext, putnextctl, putnextctl1, putnextctl2, qreply, qsize, rmvq, SAMESTR, strqget, strqset, and unfreezestr. The user functions and non-STREAMS/UX code cannot call bcanput, canput, put, putctl1, putctl2, or streams_put if they pass the utility a parameter of the form q->q_next. They can call these utilities if they pass a parameter of the form q (q must be a valid, allocated queue). User functions and non-STREAMS/UX code can only call putq if they pass it a driver's read queue or a lower mux's write queue. User functions and non-STREAMS/UX code can use the new streams_put utility documented in this chapter to get around these restrictions.

Some STREAMS/UX utilities cannot be called from free routines passed to esballoc. A free routine can call the same utilities as the module or driver entry point that called freeb.

If a multiplexor can execute on the ICS, take care when using putnext to pass messages across the multiplexor. If the upper mux passes messages downward by passing the lower mux's write queue to putnext, the upper mux must ensure that the driver stays linked under the mux until after the putnext completes. Likewise, if the lower mux passes messages upward by passing the upper mux's read queue to putnext, the lower mux must guarantee that the driver stays linked under the mux, the mux stays open, and modules are not pushed or popped until after the putnext finishes.

A protect_q parameter can be passed to the weldq utility. The protect_q parameter specifies which queue the func parameter can access safely. The func function can use the same STREAMS/UX utilities as the protect_q put and service routines.

The put and service routines cannot be called directly. They must be executed by calling STREAMS/UX utilities such as putnext, putq or qenable. They cannot be called using the function pointer stored in the q_qinfo structure.

Drivers and modules should not call STREAMS/UX utilities from software running on the interrupt control stack processing an spl6 or higher interrupt. STREAMS/UX protects its internal data structures using spl5.