BCANPUTNEXT

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

NAME

bcanputnext - test flow control on a STREAMS message queue

SYNOPSIS

#include <sys/stream.h>

int bcanputnext(queue_t *q, int band);

ARGUMENTS

q: the queue after which to begin testing for flow control.
band: the priority band within which to test for flow control.

INTERFACE

STREAMS.

DESCRIPTION

It is the responsibility of a STREAMS module passing a normal priority, message to the next queue, to check for flow control using bcanputnext() before passing the mssage with putnext(9).

bcanputnext() checks whether the Stream is flow controlled starting at q->q_next, and for the specified band. bcanputnext() looks for the first queue with a qi_srvp(9) service procedure, or no next queue (i.e. the q_next pointer is NULL).

If the first queue has the QFULL (band == 0) or QB_FULL (band >= 1) flag clear indicating that it is not full for the specified band, or a qband(9) structure does not yet exist for the specified band (band >= 1), then bcanputnext() will return true (1).

If the first queue has the QFULL (band == 0) or QB_FULL (band >= 1) flag set indicating that it is full for the specified band, and a qband(9) structure exists for the specified band (band >= 1), then bcanputnext() will return false (0).

When bcanputnext() returns false (0), it also sets the QWANTW (band == 0) or QB_WANTW (band >= 1) flag for the specified band, indicating that the STREAMS scheduler should back-enable qi_srvp(9) procedures backward up the queues when the flow controlled band is no longer flow controlled (falls to its low water mark).

USAGE

It is the responsibility of a STREAMS driver or module passing a banded (normal priority) data message (M_PROTO(9), M_DATA(9)) to a subsequent queue to check for flow control using bcanputnext() for the band associated with the message before passing the message to the queue with putnext(9). A STREAMS module is only required to check for flow control if it has a qi_srvp(9) procedure for the specified queue: otherwise, it was the responsibility of a previous STREAMS module, Stream head or Stream end to check flow control.

RETURN

bcanputnext() will return false (0) when the specified STREAMS message queue is flow controlled for the specified band, and returns true (1) when the specified STREAMS message queue is not flow controlled for the specified band, or the specified band has not yet been written to.

ERRORS

bcanputnext() always succeeds for a valid q. If q is invalid, the result is undefined. It is invalid to pass bcanputnext() a q where q->q_next is NULL.

CONTEXT

bcanputnext() can be called from any context, including user context, module procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines.

MP-STREAMS

bcanputnext() is MP-safe when called from any context. However, the caller is responsible for the validity of the passed in queue pointer, q, across the call.

The validity of either queue in the pair, and either q_next pointer for a queue in the pair, for the queue pointer passed to a module procedure, callout or synchronous callback functions, is guaranteed by Linux Fast-STREAMS. Any queue pointer in the pair passed as an argument to an asynchronous callback function is also valid, providing the driver or module observes the rules for cancellation of asynchronous callbacks on close.

When wishing to test flow control on the queue beyond a driver's upper multiplex read queue from an interrupt service routine, where there is no qi_srvp(9) service procedure defined for the read queue, a more portable approach is to call put(9) instead and test flow control from within the read queue's qi_putp(9) put procedure.

It is possible, due to race conditions in a multiprocessor (MP) system, that bcanputnext() can be called for a queue and return true (1) and yet the Stream becomes flow controlled before a call to putnext(9). The caller to putnext(9) is then in violation of flow-control rules; however, the extent of this violation is bounded.

It is also possible, that bcanputnext() can be called for a queue and return false (0), and a queue utility retrieving a message from the full queue causes flow control to subside and the service procedure of the caller to become back-enabled before the call to putq(9) (in the case bcanputnext() is called from a qi_putp(9) put procedure), or putbq(9) (in the case bcanputnext() is called from a qi_srvp(9) service procedure). In the case that the service procedure runs before putq(9), placing the message on the queue will invoke the service procedure again, when necessary. In the case that the queue was enabled before putbq(9), execution of the service procedure will occur after the current service procedure exits.

Although bcanput(q->q_next, band) is functionally equivalent to bcanputnext(q, band), for the bcanput(9) form, the dereference of the q->q_next pointer is not protected on some implementations of STREAMS for MP architectures: on which q_next may change as a result of a concurrent reconfiguration of the Stream (e.g. an I_PUSH or I_POP streamio(7) operation). For MP operation, portable STREAMS drivers and modules will always call bcanputnext() instead of bcanput(q->q_next, band).

For maximum portability and compatibility, bcanputnext(q, band) under Linux Fast-STREAMS is always MP-safe from any context and for any q whose validity the caller can guarantee across the call.

NOTICES

It is the responsibility of a STREAMS driver or module passing a normal priority, message to an adjacent queue to check for flow control using bcanputnext() before passing a message to the queue with putnext(9).

canputnext(9) and bcanputnext() should always be used instead of canput(q->q_next) and bcanput(q->q_next) on multiprocessor (MP) implementations.

canputnext(9) and bcanputnext() will always be used instead of canput(q->q_next) or bcanput(q->q_next) by portable STREAMS drivers and modules on multiprocessor (MP) systems.

canput(9) and canputnext(9) are the equivalent of bcanput() and bcanputnext(9) with a zero band: and are implemented as such.

Note that there is some conflict in the documentation as to what happens when bcanputnext() hits the queue at end of the Stream (q->q_next is NULL) and the queue has no service procedure. Some implementations, notably UnixWare®[1], say bcanputnext() always returns true (1) in this situation. The SVR 4 SPG[2] stays that bcanputnext() searches for the a queue with a service procedure or which has no forward queue and then peforms the actions. This also consistent with Solaris®[3] behaviour. The SVR 4 SPG[2], however, also says that if a qi_putp(9) put procedure places a message onto its own queue with putq(9), that it requires a qi_srvp(9) service procedure. One would not then expect a queue without a service procedure to have anything but an empty message queue, and in that case, bcanputnext() can be expected to always return true (1) for it.

Linux Fast-STREAMS performs the actions on the queue at the end of the Stream when it is reached regardless of whether it has a qi_srvp(9) service procedure or not. This is consistent with the description in the SVR 4 SPG[2] as well as Solaris® behaviour. If such a queue's qi_putp(9) put procedure never places message on the queue with putq(9), there will be no difference in the values returned to bcanputnext(); if the put procedure does place messages with putq(9), without a service procedure, bcanputnext() will act as expected by the description in the SVR 4 SPG[2]. See also USAGE , above.

IMPLEMENTATION

Linux Fast-STREAMS[4] provides the additional feature that band can be specified as ANYBAND. When band is ANYBAND, bcanputnext() checks whether any band (other than band zero), is not flow controlled. If a band exists that is not flow controlled, bcanputnext() with ANYBAND returns one (1). If all existing bands are flow controlled, bacnputnext() returns zero (0).

bcanputnext() uses atomic bit operations and does not require locking of the queue structure. Therefore, bcanput() can be called for a q that is frozen with freezestr(9).

EXAMPLES

Example #4

The following is an example of a transmit ISR that takes messages directly off of the write queue using rmvq(9):

Following is the write queue put procedure for the driver:

 1  int
 2  example_wput(queue_t *q, mblk_t *mp)
 3  {
 4      switch (mp->b_datap->db_type) {
 5      case M_FLUSH:
 6          /* ... */
 7          break;
 8      case M_IOCTL:
 9          /* ... */
10          break;
11      case M_DATA:
12          putq(q, mp);
13          break;
14      default:
15          freemsg(mp);
16          break;
17      }
18      return (0);
19  }

Data messages are simply placed onto the message queue at Line 12.

Following is the transmit ISR:

 1  void
 2  example_xmit_isr_handler(queue_t *q)
 3  {
 4      pl_t pl;
 5  
 6      /* q is a write queue of the driver */
 7      pl = freezestr(q);
 8      {
 9          mblk_t *mp, *bp;
10          int count = 0;
11  
12          while ((bp = mp = q->q_first)) {
13              rmvq(q, mp);
14              do {
15                  while ((mp->b_rptr < mp->b_wptr)) {
16                      outb(mp->b_rptr[0], OUTPUT_PORT);
17                      mp->b_rptr++;
18                      count++;
19                      if (count == XMIT_BUF_DEPTH) {
20                          insq(q, q->q_first, mp);
21                          goto done;
22                      }
23                  }
24              } while ((bp = bp->b_cont));
25              freemsg(mp);
26          }
27          if (count < XMIT_BUF_DEPTH) {
28              /* xmit buffer underrun */
29          }
30        done:
31      }
32      unfreezestr(q, pl);
33  }

The transmit ISR operates much like a service procedure, it removes messages from the write queue at Line 13, writes data out to the device transmit FIFO at Line 16, and either places messages with more data back on the queue at Line 20, or frees empty messages at Line 25,

For rmvq(9) at Line 13 to properly back-enable the queue, canputnext(9) or bcanputnext(9) must set the QWANTW flag on this queue when QFULL is set, regardless of whether it has a service procedure or not. Of course, it is possible to provide a dummy service procedure as follows:

 1  int
 2  example_wsrv(queue_t *q)
 3  {
 4      return (0);
 5  }

But, that is rather pointless. (Nevertheless, see situations under which this is advised under COMPATIBILITY , below.)

BUGS

bcanputnext() has no known bugs.

COMPATIBILITY

bcanputnext() is compatible with SVR 4.2 MP DDI/DKI[5], and implementations based on SVR 4.2 MP[6], with the following portability considerations:

---: HP-UX®[7] lists bcanputnext() as a function that can only be passed a queue in the queue pair currently being synchronized within a module procedure. HP-UX®[7] also lists bcanputnext() as a utility that cannot be called from user functions or non-STREAMS code; that is, contexts asynchronous to the Stream containing q. HP-UX® compatible drivers and modules will not call bcanputnext() from outside of a qinit(9) routine for the queue pair of q.
: Solaris[8], does the reverse: canputnext(9) and bcanputnext() can be called from outside of STREAMS, but canput(9) and bcanput(9) cannot. Solaris® compatible drivers and modules will not call canput(9) from outside of a qinit(9) routine for the queue pair of q.
: bcanputnext() under Linux Fast-STREAMS can be passed any valid q pointer from any context, and the q_next pointer from any q synchronous context, and remain MP-safe. Therefore, there are no compatibility issues for Linux Fast-STREAMS.
---: bcanputnext() is MP-safe. Under LiS, bcanputnext() does not protect dereferencing of queue pointers during the search for a queue or band limited queue.
---: bcanputnext() always succeeds. Under LiS, bcanput() will return zero (0 - flow controlled) if an internal error occurs, without setting the QWANTW or QB_WANTW flag for the queue or band. This means that, although flow controlled, no back-enable procedure will be run. This can lead to indefinite postponement of a queue qi_srvp(9) procedure under LiS. Linux Fast-STREAMS[4] bcanputnext() does not have this problem.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[4] instead of LiS.
---: The declaration for bcanputnext() provides that band is of type int. Under SVR 4.2 DDI/DKI[5], and other systems based on SVR 4, band is unsigned char.
---: bcanputnext() protects dereferences of the q->q_next pointer with a Stream head lock. Under LiS, bcanputnext() is simply a macro that calls bcanput(9) without protection for the q->q_next pointer dereference.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: bcanputnext() explicitly protects dereferencing of the q->q_next pointer with the Stream head read lock that prevents reconfiguration of the Stream during the call. LiS does not explicitly protect this dereference.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: bcanputnext() called with an invalid q pointer or a q pointer that has an invalid q->q_next pointer, will have undefined results and may crash or destabilize the kernel. LiS will return false (0) under the same conditions. STREAMS drivers and modules that always obtain q from a pointer passed by the STREAMS scheduler via qi_qopen(9), qi_qclose(9), qi_putp(9), qi_srvp(9), (as is normal) will not encounter this problem.
---: HP-UX®[7] allows bcanput(9) (but not bcanputnext()) to be called from outside the STREAMS framework, but it cannot be passed a q->q_next pointer, even from within the framework. This is the reverse of Solaris®, below. HP-UX®, documented rules[7] are more restrictive than Linux Fast-STREAMS, so there are no portability issues.
: Solaris®[3], on the other hand, allows bcanputnext() (but not bcanput(9)) to be called from outside the STREAMS framework, but it cannot be passed a q->q_next pointer, even from within the framework. This is the reverse of HP-UX®, above. Solaris®, documented rules[3] are more restrictive than Linux Fast-STREAMS, so there are no portability issues.
---: bcanputnext() may be called on a Stream frozen with freezestr(9). SVR 4.2 MP DDI/DKI[5], Solaris®[3], SUPER-UX®[9] and UnixWare®[10] do not permit bcanputnext() to be called on a Stream frozen with freezestr(9).
: Portable STREAMS drivers and modules will not call bcanputnext() on a Stream frozen with freezestr(9).
---: bcanputnext() is an SVR 4.2 function, not a macro. LiS implements canput(q), canputnext(q), bcanput(q, band), and bcanputnext(q, band), with a macros that call bcanput(q, band)
or bcanput(q->q_next, 0). This makes canputnext(9) and bcanputnext() unsafe under LiS across a multiplexing driver.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: All versions of LiS contain the bug that they keep track of message queue counts, q_count, qb_count, in terms of the sum of the absolute sizes of the data buffers referenced by message blocks, (db_lim - db_base), and not the sizes of the message blocks themselves, (b_wptr - b_rptr), which does not conform to SVR 4.2 STREAMS[6]. See msgsize(9). No other implementation has this bug.
: Portable STREAMS applications programs, drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[5,6].

HISTORY

bcanputnext() first appeared in SVR 4.0 STREAMS[2].

Earlier versions of STREAMS (e.g. SVR 3)[11] did not have priority bands.

REFERENCES

[1]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[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]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[4]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[5]: 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.
[6]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[7]: 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/>
[8]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[9]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[10]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[11]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.