QBAND

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

NAME

qband, qband_t - queue band structure

SYNOPSIS


typedef struct qband {
        struct qband *qb_next;  /* next (lower) priority band */
        size_t qb_count;        /* number of bytes queued */
        struct msgb *qb_first;  /* first queue message in this band */
        struct msgb *qb_last;   /* last queued message in this band */
        size_t qb_hiwat;        /* hi water mark for flow control */
        size_t qb_lowat;        /* lo water mark for flow control */
        unsigned long qb_flag;  /* flags */
        long qb_pad1;           /* reserved */
} qband_t;
#define qb_msgs qb_pad1
enum {
        QB_FULL_BIT,            /* band full flow control */
        QB_WANTW_BIT,           /* back enable required */
        QB_BACK_BIT,            /* UnixWare/Solaris/UXP/V */
};
#define QB_FULL  (1<<QB_FULL_BIT )
#define QB_WANTW (1<<QB_WANTW_BIT)
#define QB_BACK  (1<<QB_BACK_BIT)  /* UnixWare/Solaris/UXP/V */
#define NBAND    256               /* UnixWare/Solaris */

MEMBERS

The following members correspond to SVR 4.2 EFT members:

qb_next

A pointer to the qband structure corresponding to the the next lower priority band (or NULL if there is no lower priority band).

qb_count

The number of bytes queued to the band.

qb_first

A pointer to a msgb(9) structure representing the first message block queued to the band.

qb_last

A pointer to a msgb(9) structure representing the last message block queued to the band.

qb_hiwat

The high water mark in bytes that represents the number of bytes queued to the band beyond which band flow controls will be initiated.

qb_lowat

The low water mark in bytes that represents the number of bytes queue to the band beneath which band flow controls will be ceased.

qb_flag

Flags for the queue band. These are a bitwise OR of any of the following flags:

QB_FULL: This bit is set when the queue band was full (qb_count > qb_hiwat) but has not yet dropped to the low water mark (qb_count==0||qb_count<qb_lowat) and is subject to flow control.
QB_WANTW: This bit is set when the queue band requires a back enable. This occurs when bcanput(9) or bcanputnext(9) has previously failed for the queue band.
QB_BACK: For UnixWare®, Solaris® and UXP/V® compatibility. This bit is set when the queue band is back enabled.

qb_pad1

Padding to pad the structure to the size of the SVR 4.2 Extended fundamental Type.

The following members are Linux Fast-STREAMS[1] specific members:

qb_msgs: The count of the number of messages queued to the band. This member is a renaming of qb_pad1 above.

FUNCTIONS

The following queue band utility functions are provided:

appq(9) -: append messages to a queue
bcanput(9) -: test band for flow control for a queue
bcanputnext(9) -: test band for flow control for a queue
flushband(9) -: flush messages from a band of a queue
flushq(9) -: flush messages from a queue
insq(9) -: insert messages into a queue
putbq(9) -: put a message back on a queue
putq(9) -: put a message on a queue
qcountstrm(9) -: count the data bytes on all queues in a stream
rmvq(9) -: remove a message from a queue
strqget(9) -: get a parameter for a queue
strqset(9) -: set a parameter for a queue

INTERFACE

STREAMS.

DESCRIPTION

The qband structure contains pointers into the linked list of messages on the queue(9). These pointers, qb_first and qb_last, denote the beginning and end of messages for the particular band. When there are no messages in the band, both qb_first and qb_last are NULL; with any messages in the band, both are non-NULL.

The qb_count member is analogous to the queue(9)'s q_count member. However, qb_count only applies to the messages on the queue(9) in the band of data flow represented by the corresponding qband structure. In contrast, q_count contains information regarding normal (priority band zero) and high priority messages.

Each band has a separate high and low water mark, qb_hiwat and qb_lowat. These are initially set to the queue(9)'s q_hiwat and q_lowat respectively. Modules and drivers may change these values if desired using the strqset(9) utility.

Three flags, QB_FULL, QB_WANTW, and QB_BACK, are defined for qb_flag. QB_FULL denotes that the particular band is full. QB_WANTW indicates that the neighbouring feeding queue (with a service procedure) wanted to write to the band when it was full. QB_BACK is set when the qi_srvp(9) procedure is scheduled as a result of back-enabling from a queue being fed by this one for which flow control has subsided for this queue band.

The qband structures are not preallocated per queue(9). Rather, they are allocated when a normal priority message with a non-zero b_band is placed on the queue from appq(9), insq(9), putq(9), or putbq(9). When a qband structure does not exist for the band corresponding to b_band, STREAMS tries to allocate qband structures for all non-existent bands up to and including the band of the message and places the resulting qband structures into a reverse sorted q_bandp list on the queue(9). Since band allocation can fail, these routines return false (0) on failure and true (1) on success. strqset(9) and strqget(9) will also cause qband allocation to occur.

Once a qband structure is allocated, it remains associated with the queue until the queue is freed. Therefore, it is possible to ensure that no band allocation failures will result by preallocating any necessary band from a module's qi_qopen(9) procedure using strqset(9) or strqget(9).

See, appq(9), insq(9), putq(9), putbq(9), strqset(9), and strqget(9), for more information.

CONTEXT

Functions that operate on a queue band can be called from any context, including user context, module procedures, call-outs, callbacks, soft interrupts (tasklets and bottom halves) and interrupt service routines.

MP-STREAMS

The queue band pointers and members, with the exception of the qb_flag member, are protected by the queue reader-writer lock, (q_rwlock) in the parent queue(9) structure. The qb_flag member is protected using atomic bit operations. Whenever a queue reader-write lock is acquired, local interrupts are suppressed, allowing utilities that manipulate the queue(9) and qband structures to be called from any context.

Some queue and queue band utilities have a back-enable side-effect. These are utilities that remove messages from the queue or queue band: rmvq(9), getq(9), flushq(9), flushband(9). Because the back-enable side-effect, qbackenable(9), can only be invoked from specific contexts, these utilities are more restrictive. See rmvq(9), getq(9), flushq(9), flushband(9), for more information.

NOTICES

Members of the qband structure should not be accessed directly by STREAMS drivers or modules. Portable STREAMS drivers and modules should use the facilities provided by strqget(9) and strqset(9) for implementation and architecture independence, as well as MP-safety.

The qband structure is only a subset of the qbinfo structure used by the STREAMS scheduler. Additional hidden members are present in the qbinfo structure.

COMPATIBILITY

The qband structure is compatible with SVR 4.2 MP DDI/DKI[2], and implementations based on SVR 4.2 with the following portability considerations:

---

When a normal priority message, with zero band, is placed on a queue with appq(9), insq(9), putq(9), putbq(9), and a qband structure does not yet exist for the band corresponding to b_band, STREAMS tries to allocate qband structures for all non-existent bands up to and including the band of the message, and places the resulting qband structures into a reverse sorted q_bandp list on the queue(9). q_nband is adjusted, and always reflects the highest allocated band.

This is consistent with the description in the System V Release 4: Programmer's Guide: STREAMS[3], which states:

: "If a message is passed to putq(9) with a b_band value that is greater than the number of qband structures associated with the queue [member q_nband in the queue(9) structure], putq(9) tries to allocate a new qband structure for each band up to and including the band of the message."[3]

Solaris®[4] allocates qband structures up to and including b_band, and maintains the q_nband member of the queue(9) structure, as does other SVR 4.2-based implementations.

LiS allocates qband structures on demand, links them in a sparse array, and will also reuse qband structures that were previously allocated for bands that are currently empty. This is not a good approach because user established band high and low water marks will be reset to those of the queue(9) structure when a subsequent message is placed on the reused band. Also, this makes it difficult to predict when appq(9), insq(9), putq(9), putbq(9), strqget(9), strqset(9), will fail as a result of failure to allocate a qband structure. This LiS bug is not perpetuated in Linux Fast-STREAMS.

Portable STREAMS drivers and modules can rely on intermediate band structure being allocated when a normal priority message is placed on a queue and may examine the q_nband member of the queue(9) structure to determine whether a qband exists.

Portable STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.

---

qband structures, in the list pointed to by the q_bandp member of the queue(9) structure, are ordered from highest band number to lowest band number. This ensures that higher priority qband structures can be accessed faster than lower priority structures. Solaris®[5] orders qband from lowest to highest priority, and without gaps (see consideration of allocation above). LiS orders qband structures from most recently allocated/reused to least recently allocated/reused. Neither the Solaris® nor the LiS approach is very efficient.

Portable STREAMS drivers and modules will not depend on the ordering of qband structures within the q_bandp list on the queue(9) structure, and, will not access qband or queue(9) members directly, but will use the portable and MP-safe strqget(9) and strqset(9) utilities instead.

---

Versions of LiS previous to OpenSS7 Release LiS-2.16.18-17 automatically freed the message on failure. Versions of LiS subsequent to OpenSS7 Release LiS-2.16.18-16 do not free th message on failure in accordance with SVR 4[3] and other implementation documentation.

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.

---

Mac OT® has type short for qb_flag and qb_pad1 members of the qband structure. OSF/1® has types long and ulong for all members of the qband structure. Only SVR 4.2 MP[2] Extended Fundamental Types are supported. The qband structure is provided for source compatibility with SVR 4.2 EFT.

Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 EFT[2].

HISTORY

The qband structure was introduced in SVR 4[3].

REFERENCES

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

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

Index

NAME
SYNOPSIS
MEMBERS
FUNCTIONS
INTERFACE
DESCRIPTION
CONTEXT
MP-STREAMS
NOTICES
SEE ALSO
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 22:21:12 GMT, May 21, 2013

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci

QBAND

NAME

SYNOPSIS

MEMBERS

FUNCTIONS

INTERFACE

DESCRIPTION

CONTEXT

MP-STREAMS

NOTICES

SEE ALSO

COMPATIBILITY

CONFORMANCE

HISTORY

REFERENCES

TRADEMARKS

IDENTIFICATION

Index