Manpage of QI_SRVP

QI_SRVP

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

srv, service, qi_srvp, qi_srvp_t - STREAMS driver or module service procedure

SYNOPSIS

#include <sys/stream.h>
typedef int (*qi_srvp_t) (queue_t *q);

ARGUMENTS

q: pointer to the queue(9) to service.

INTERFACE

STREAMS.

DESCRIPTION

qi_srvp() is one of 5 principal synchronous entry points into a STREAMS driver or module that form part of its definition. The principal entry points are: qi_qopen(9), qi_qclose(9), qi_qadmin(9), qi_putp(9), and qi_srvp().

The qi_srvp() procedure is specified in both the read and write queue qinit(9) structure that is associated with each queue in an existing queue pair forming an instance of the driver or module from the definitions in the module- and driver-defining streamtab(9) structure.

The qi_srvp() procedure is called by STREAMS whenever the queue, q, has been scheduled for service and reaches the front of the STREAMS scheduler run queue. Queues are scheduled for service either explicitly, using STREAMS utility functions such as enableq(9) and qenable(9); or, implicitly by STREAMS message queue functions such as putq(9) and getq(9). The qi_srvp() procedure is the primary mechanism for deferring message processing and handling flow control within the STREAMS framework. Although qi_srvp() is declared to return a value, any returned value is ignored by STREAMS, and is not available to the caller of enableq(9), qenable(9), putq(9), or getq(9).

The argument passed to the qi_srvp() procedure is as follows:

q: is a pointer to the queue(9) structure representing the read or write queue which is to be serviced.

STREAMS maintains a list of queues that are scheduled for service. When a queue is scheduled that has not already been scheduled, it is placed on the tail of the list. When the STREAMS scheduler runs [see runqueues(9)], queues are taken off of the head of this run queues list and the qi_srvp() procedure of the queue is invoked with the queue pointer as the argument. Therefore, qi_srvp() procedures are always invoked within the context of the STREAMS scheduler, and are invoked single-threaded for a given queue, q.

Scheduling a queue's qi_srvp() procedure for execution is termed enabling the queue. Once a queue's qi_srvp() procedure has been scheduled (i.e., the queue has been enabled), the procedure cannot be scheduled again until it has been executed. In other words, a queue cannot be enabled when it is already enabled. If a queue does not have a qi_srvp() procedure defined (i.e., the qi_srvp member of the associated qinit(9) structure is NULL), then the queue cannot be enabled: there is no service procedure to schedule. When flow control blocking by a forward queue subsides and STREAMS causes a feeding message queue with a defined qi_srvp() procedure to be enabled, this is termed back-enabling .

The qi_srvp() procedure is scheduled for execution under the following circumstances:

(1): A queue is explicity enabled by calling enableq(9) and the queue has not previously had queue enabling suppressed with a call to noenable(9); that is, when a call to canenable(9) will return true.
(2): A queue is explicity enabled by calling qenable(9), regardless of the setting of the QNOENB flag [see noenable(9)].
(3): A queue is enabled under some circumstances when messages are placed on the message queue: When a high priority message is placed back on a message queue with putbq(9) the queue will be enabled (again); a high priority message is placed on a message queue with putq(9) the queue will be enabled (if it is not already enabled); or, a normal priority message is placed on a message queue with putq(9), insq(9), qppq(9), and the message becomes the first message on the queue, or the QWANTR bit is set in the q_flag member of the queue indicating that getq(9) emptied the queue, the queue will be enabled (if it is not already enabled, and if queue enabling has not been suspended with noenable(9)).
(4): A queue is enabled under some circumstances when messages are removed from a forward message queue that was previously flow controlled (termed back-enabling ). A queue is back-enabled after a canput(9), canputnext(9), bcanput(9), bcanputnext(9), call has previously failed from the queue's qi_putp() or qi_srvp(), because a forward message queue is full (i.e., its QFULL or QB_FULL flag is set for the specified message band), when the previously full queue's count falls beneath its low water mark, or the queue becomes empty. STREAMS utility functions that remove messages from a message queue can cause its queue count or queue band count to drop beneath its low water mark, or the queue to become empty. These utility functions are: getq(9), rmvq(9), flushband(9), and flushq(9). Any of these functions can cause the nearest feeding queue in the Stream that has a defined qi_srvp() to become back-enabled. See the corresponding manual pages for details.

When the qi_srvp() procedure is executed for a queue by the STREAMS scheduler, the following conditions prevail:

(1): The qi_srvp() procedure is run single-threaded with respect to a given queue, q. That is, for any given value of the argument q, only one thread can be executing the qi_srvp() procedure with that value passed as an argument.
(2): The Stream containing the queue must be in a thawed state, see unfreezestr(9), before any qi_putp(9) or qi_srvp() procedure will be entered within the stream. However, the Stream amy become frozen after (or immediately before) the qi_srvp() procedure is called. (Freezing a Stream with freezestr(9) is advisory to threads entering qi_putp(9) or qi_srvp() procedures, and is mandatory for threads attempting to alter the state of the target queue.)
(3): A Stream head plumbing read lock will be acquired and held across the call to the qi_srvp() procedure. The Stream head plumbing read lock held in this fashion guarantees that dereferencing of the q_next pointers for the queue, and any queue in the same Stream, will be valid through the qi_srvp() procedure (and any qi_putp(9) procedure invoked by it). This permits use of the putnext(9), canputnext(9), bcanputnext(9), putctlnext(9), putctl1next(9), putctl2next(9), getq(9), rmvq(9), flushq(9), flushband(9), STREAMS utilities that walk the Stream dereferencing q_next pointers.
(4): Queue qi_putp(9) and qi_srvp() procedures will have been enabled with qprocson(9) for the queue pair containing the qi_srvp() procedure before the call, and will not be disabled with qprocsoff(9) for the queue pair until after the call returns.
(5): If an mp-streams(9) synchronization specification has been made for the module or river, the calling thread will enter the inner synchronization barrier shared or exclusive (depending on the specification) before the call to qi_srvp() and will leave the barrier after its return.

In constrast to the qi_putp(9) procedure, that handles immediate processing of messages, the qi_srvp() procedure is responsible for delayed or deferred processing of messages that were placed on the message queue by the qi_putp(9) procedure. Another difference is that qi_srvp() procedures run under STREAMS scheduler context, whereas qi_putp(9) procedures run under whatever context prevailed when the put(9) or putnext(9) utility invoking them were called. The qi_srvp() procedure is responsible for taking messages from the message queue in turn, using getq(9), and processing them. There are four actions that a qi_srvp() procedure can take with regard to the disposition of message on the queue:

(1): leave the message on the message queue;
(2): free the message (or part of the message) with a STREAMS utility such as freeb(9) or freemsg(9);
(3): pass the message (or part of the message) to another queue using put(9) or putnext(9); or,
(4): place the message (or part of the message) back on the message queue using the STREAMS utility putbq(9).

If a message is left on the queue, a message is placed back on the queue with putbq(9), or, a call to getq(9) to get the next message for processing returns NULL, the qi_srvp() procedure must exit. Otherwise, the qi_srvp() procedure continues to take messages off of the queue with getq(9) and processes them in turn.

Just as the qi_putp(9) procedure, qi_srvp() procedure is allowed to modify messages that are removed from the message queue at its discretion before applying one of the above terminal dispositions to the message. However, the qi_srvp() procedure should not modify the contents of the data buffer associated with any data block, datab(9), that has a reference count, db_ref, greater thatn one (1) [see dupmsg(9)]. Message blocks with a data block reference greater than one should be copied and the copy altered instead.

Any other actions taken with regard to the message form part of the definition of the module or driver concerned.

The more specific steps taken by a qi_srvp() procedure are as follows:

(1): Remove a message from the queue with getq(9).
(2): If getq(9) returns NULL, return from the procedure.
(3): If getq(9) retreives a message, check if the message is a high priority mesage (db_type >= QPCTL). If it is, process the message and possibly pass it to the next queue with putnext(9).
(4): If the mssage is a normal priority message (db_type < QPCTL), test if the message can be passed along with bcanputnext(9), for the band b_band.
(5): if bcanputnext(9) returns true, process the message and pass the mesage along with putnext(9).
(6): If bcanputnext(9) returns false, place the message back on the queue with putbq(9) and return from the procedure.
(7): Repeat at step (1).

See below under EXAMPLES ® for examples of these steps.

USAGE

The driver or module qi_srvp() procedure is responsible for maintaining proper operations of the Stream by handling specific message types in specific fashions. The following sections provide some guidelines for the design of qi_srvp() procedures from a driver or module, and rules for handling of messages within the procedure:

Driver and Module qi_srvp() Design Rules

The following design rules apply to both drivers and modules:

*

Defining a qi_srvp() procedure for a queue is optional. Not all drivers or modules require deferral of message processing: some can perform all message processing directly from their qi_putp(9) procedures.

*

A queue with a defined qi_putp(9) procedure that never places message on its message queue must not define a qi_srvp() procedure.

*

A qi_srvp() procedure must not place messages directly on a neighbouring queue's message queue using putq(9) or putbq(9) STREAMS utilities. It must only call put(9) or putnext(9) for the neighbouring queue to pass messages.

*

qi_srvp() procedures must not sleep or preempt. Any qi_srvp() procedure must be congnisant of the fact that service procedures for other queues may be awaiting execution for the duration of the current call. Message processing performed by the qi_srvp() procedure must be finite and should be bounded. Any extensive unbound processing, or processing that would benefit from sleeping, should be delegated to independent kernel threads spawned to perform the processing.

Performing extended and unbound message processing directly from a qi_srvp() procedure, or causing a qi_srvp() to sleep, can have detrimental impact on STREAMS subsystem performance and latency of response to time-critical events.

*

qi_srvp() procedures are not allowed to access (directly or indirectly via kernel utilities) the current user task structure. The task that is current when a qi_srvp() procedure is invoked can be either the STREAMS scheduler kernel thread, or a user process executing on behalf of the STREAMS scheduler before exiting a system call. The STREAMS scheduler has no fixed relationship to the user that invoked a chain of events resulting in the procedure being called.

*

Every queue with a defined qi_srvp() procedure is responsible for flow control within the Stream. Message handling rules for flow control must be followed whenever messages are to be passed to a neighbouring queue. Flow control rules are as follows:

1): Messages that are of high priority [see datab(9)] can be passed to a neighbouring queue without regard to flow control or message ordering within the message queue.
2): Messages that are of normal priority (ordinary or priorty messages), must be maintained in sequence with regard to other messages of the same priority on the message queue. That is, if a message of the same priority already exists on the message queue, an arriving message must be queued in order behind it. (The STREAMS putbq(9) utility maintains such ordering.)
3): Messages that are of normal priority that are to be passed to a neighbouring queue, in accordance with the above, must have flow control checked for the neighbouring queue using the canput(9), canputnext(9), bcanput(9), bcanputnext(9), STREAMS utilities. When the called utility returns false, the message must not be passed, but may be placed back on the local message queue using putbq(9) (or discarded).

Module qi_srvp() Design Rules

The following design rules apply to modules:

*: If a module qi_srvp() procedure is processing a message containing a message type that it does not recognize, it should pass the message to the next module in the Stream (in accordance with queueing and flow control rules appropriate to the priority of the message).
*: Modules must follow the module rules for handling specific message types. These rules are detailed on the manual page describing the message type (e.g., M_FLUSH(9)). For a list of message types and their corresponding manual pages, see datab(9).

Driver qi_srvp() Design Rules

The following design rules apply to drivers:

*: If a driver qi_srvp() procedure is processing a message containing a message type that it does not recognize, it should discard (ignore and free) the message.
*: Drivers must follow the driver rules for handling specific message types. These rules are detailed on the manual page describing the message type (e.g., M_FLUSH(9)). For a list of message types and their corresponding manual pages, see datab(9).

RETURN

The qi_srvp() procedure returns an integer value. This value is ignored by STREAMS and should always be zero (0).

ERRORS

Although the qi_srvp() procedure is capable of returning an error code, the returned value is always ignored by STREAMS and cannot be passed back to the caller of any function.

CONTEXT

A driver or module qi_srvp() procedure, when invoked correctly, can be called by STREAMS either in STREAMS scheduler context (kernel thread), or in the context of a user process executing on behalf of the STREAMS scheduler before returning from a system call.

MP-STREAMS

Synchronized Modules and Drivers

If mp-streams(9) synchronization has been specified for the driver or module, the inner synchronization barrier, if any, is entered shared or exclusive in accordance with the synchronization specification for the driver or module, across the call to the qi_srvp() procedure. If synchronization has not been specified for the driver or module (that is, the module or driver is specified as MP-safe), the qi_srvp() procedure is invoked without synchronization.

MP-Safe Modules and Drivers

qi_srvp() is called by STREAMS either in STREAMS scheduler context (kernel thread), or in the context of a user process executing on behalf of the STREAMS scheduler before returning from a system call. Regardless of context, when properly invoked, STREAMS is aware of which queue is being processed on a per-processor basis.

STREAMS acquires and holds a Stream head plumbing read lock, for the Stream within which the queue resides, across the call to the qi_srvp() procedure. This permits the qi_srvp() procedure, and any STREAMS utility functions called by the qi_srvp() procedure, to dereference any q_next pointer in the Stream, and the dereference will remain valid for the duration of the qi_srvp() call. Note that this does not provide any assurances of the validity of a q_next pointer dereference in any other Stream, such as another Stream in an upper or lower multiplex: the qi_srvp() procedure is responsible for asserting its own assurances in that regard. (Note that freezing a Stream with freezestr(9) guarantees validity of all subsequent q_next pointer derefernces until the Stream is thawed with unfreezestr(9)).

If the Stream containing the queue, q, has been frozen with a call to freezestr(9), by a processor, STREAMS running on another processor will not enter any qi_srvp() procedure in the Stream, but will spin awaiting the thawing of the Stream by the processor that froze it, with a call to unfreezestr(9). If the Stream was frozen after the qi_srvp() procedure began execution, any attempt by the procedure to alter the state of the queue targetted in the freezestr(9) command that froze the Stream, will spin until the Stream is thawed by unfreezestr(9).

No qi_srvp() procedure for a queue pair that has not yet had qprocson(9) called for the queue pair, or that has not returned from its qi_qopen(9) routine, will be executed by STREAMS. Once a qi_srvp() is executing, any call to qprocsoff(9) for the queue pair will spin until the qi_srvp() procedure exits and releases the Stream head plumbing read lock. If a qi_srvp() procedure has been scheduled for execution, has procedures turned off for its queue pair with qprocsoff(9) before the procedure has a chance to execute, when it is the qi_srvp() procedure's turn to execute, STREAMS will cancel it and release its reference to the queue pair.

For MP-Safe drivers and modules, only one thread can be executing the qi_srvp() procedure for a given queue; however, other threads may be executing the qi_putp(9), qi_qopen(9), q_qclose(9), or q_qadmin(9), procedures and routines concurrently. It is the responsible of the writer of the qi_srvp() procedure to acquire and hold the necessary locks to provide exclusive access to data structures shared across these calls. freezestr(9) is inadequate in this case, and the procedures should use driver or module private locks.

NOTICES

A queue qi_srvp() procedure is an internal STREAMS entry point to the driver or module, that is not intended to be called directly by the module or driver writer. See enableq(9) and qenable(9) for accepted methods of invoking this procedure.

STYLE

It is common practise to name qi_srvp() procedures as follows, (where prefix is the configuration prefix chosen for the driver or module and typically derived from the name of the driver or module, and which may contain a trailing underscore):

prefixrsrv(): read side of a module or upper multiplex read side of a driver;
prefixwsrv(): write side of a module or upper multiplex write side of a driver;
prefixmuxrsrv(): lower multiplex read side of a driver; and,
prefixmuxwsrv(): lower multiplex write side of a driver.

EXAMPLES

Example #1 - Module qi_srvp()

The following example of a module qi_srvp() procedure comes directly from the read and write side of the bufmod(4) module located in src/modules/bufmod.c source file in the streams-0.9.2.4 distribution:

 1  static int
 2  bufmod_srv(queue_t *q)
 3  {
 4      mblk_t *mp;
 5  
 6      while ((mp = getq(q))) {
 7          if (likely
 8              (mp->b_datap->db_type >= QPCTL
 9               || bcanputnext(q, mp->b_band))) {
10              putnext(q, mp);
11              continue;
12          }
13          putbq(q, mp);
14          break;
15      }
16      return (0);
17  }

The operation of the bufmod(4) module is described in the bufmod(4) manual page. The write qi_srvp() procedure passes all messages downstream and performs flow control and buffering.

Line 6:: The module loops taking messages off of the message queue with getq(9) and processing them.
Line 7-12:: If the message is a high priority message or passes flow control restrictions for the message band, the message is passed to the next queue with putnext(9).
Line 13-14:: If the message is a normal priority message and the message band is flow controlled forward in the Stream, the message is placed back on the queue using putbq(9) and the procedure breaks out of the loop and returns. The service procedure will be back enabled when flow control subsides at the flow controlled queue forward in the Stream.
Line 6,15:: If there is no more messages on the message queue, getq(9) returns NULL and the loop terminates and the procedure exits. The service procedure will be enabled again when a message is placed onto the message queue.
Line 16:: The procedure always returns zero (0).

See the src/modules directory in the streams-0.9.2.4 distribution for more working examples of module service procedures.

Example #2 - Driver qi_srvp()

The following example of a driver qi_srvp() procedure comes directly from the lower read side of the mux(4) multiplexing driver located in src/modules/mux source file in the streams-0.9.2.4 distribution:

If the lower read put procedure encounters flow control on the queue beyond the accepting upper read queue, or if the lower read service procedure is invoked for a lower Stream that is not connected across the multiplexer, it places the message back on its queue and waits for the upper read queue service procedure to enable it when congestion has cleared, or when a connection is formed. If the upper read queue disconnects from the lower read queue (or has not connected yet), the procedure leaves these messages on the queue to (potentially) be processed by the Stream head after unlinking, or to be processed by an upper read queue after connection across the multiplexer.

 1  static int
 2  mux_lrsrv(queue_t *q)
 3  {
 4      struct mux *mux = q->q_ptr;
 5      queue_t *rq = NULL;
 6      mblk_t *mp;
 7  
 8      read_lock(&mux_lock);
 9      if (mux->other)
10          rq = mux->other->rq;
11      if (rq) {
12          while ((mp = getq(q))) {
13              if (mp->b_datap->db_type >= QPCTL
14                  || bcanputnext(rq, mp->b_band)) {
15                  putnext(rq, mp);
16                  continue;
17              }
18              putbq(q, mp);
19              break;
20          }
21      } else
22          noenable(q);
23      read_unlock(&mux_lock);
24      return (0);
25  }

The operation of the mux(4) multiplexing driver is described in the mux(4) manual page.

Line 8,23:: Because the private structure is altered by the upper write put procedure in response to an M_IOCTL(9) message, the procedure takes a read lock here.
Line 11,22:: If there is no connection across the multiplexer, the procedure disables automatic enabling of the queue using noenable(9), and returns. When a connection is formed, the procedure forming the connection will explicitly enable the queue using enableok(9) and qenable(9).
Line 12,20:: If there is a connection across the multiplexer, the procedure loops taking messages off of the message queue and processing them. When no messages are left of the message queue, the procedure terminates and returns zero (0).
Line 13-17:: If the message is a high priority message, or the message is a normal priority message and the message band across the multiplexer is not flow controlled for the message band, the message is passed to the queue across the multiplexer using putnext(9).
Line 18-19:: If the message is a normal priority message and the queue across the multiplexer is flow controlled for the message band, the message is placed back on the message queue using putbq(9) and the procedure breaks out of the loop and returns.
Line 24:: The procedure always returns zero (0).

See the src/drivers directory in the streams-0.9.2.4 distribution for more working examples of driver service procedures.

BUGS

Linux Fast-STREAMS invocation of the qi_srvp() entry point has no known bugs.

COMPATIBILITY

The qi_srvp() procedure is compatible with SVR 4.2[1] and implementations based on SVR 4[2], with the following portability considerations:

---: SVR 4.2[3] did not define a type for the prototype of a queue qi_srvp(9) procedure. This was an embellishment that first appeared in OSF/1® 1.1[4], and propagated to AIX®[5] and HP-UX®[6].
: Portable STREAMS drivers and modules will not directly reference the qi_qsrvp_t type.
---: Some implementations permit a wider range of STREAMS utilities to be called from outside of STREAMS. HP-UX®[6] limits the set in a similar manner to Linux Fast-STREAMS, however, Linux Fast-STREAMS permits the larger set to be used in some circumstances.
: Portable STREAMS drivers will restrict the use of STREAMS utilities called from outside the STREAMS environment to put(9), canput(9), and bcanput(9), and the later two will only be used if the target driver queue has a service procedure.
---: The same applies to placing messages on Stream ends across a multiplexing driver.
: Portable STREAMS drivers will restrict the STREAMS utilities used to operate on a different Stream to put(9), canput(9), and bcanput(9). Again, the later two will only be used if the target driver queue has a service procedure.
---: Because a number of the primary data structure and types have different definitions on the GNU/Linux system, binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility considerations.

CONFORMANCE

SVR 4.2 MP[3].

HISTORY

The qi_qsrvp_t type first appeared in OSF/1® 1.1[4].

The queue qi_srvp() service procedure first appeared in SVR 3[7].

REFERENCES

[1]: USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[4]: Digital® UNIX (OSF/1.2), Digital UNIX: Network Programmers Guide, 1996, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[5]: AIX® 5L Version 5.1, AIX STREAMS Programmers Guide, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[6]: HP-UX STREAMS, STREAMS Programmer's Guide -- HP 9000 and Integrity Server Computer Systems, October 2005, (Palo Alto, California), Hewlett-Packard Development Company L.P., HP. <http://docs.hp.com/>
[7]: SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.