Data Structures for Drivers queue(9S)
NAME
queue - STREAMS queue structure
SYNOPSIS
#include
INTERFACE LEVEL
Architecture independent level 1 (DI/DKI)
DESCRIPTION
A STREAMS driver or module consists of two queue structures:
read for upstream processing and write for downstream pro-
cessing. The queue structure is the major building block of
a stream.
queue Structure Members
The queue structure is defined as type queuet. The struc-
ture can be accessed at any time from inside a STREAMS entry
point associated with that queue.
struct qinit *qqinfo; /* queue processing procedure */
struct msgb *qfirst; /* first message in queue */
struct msgb *qlast; /* last message in queue */
struct queue *qnext; /* next queue in stream */
void *qptr; /* module-specific data */
sizet qcount; /* number of bytes on queue */
uintt qflag; /* queue state */
ssizet qminpsz; /* smallest packet OK on queue */
ssizet qmaxpsz; /* largest packet OK on queue */
sizet qhiwat; /* queue high water mark */
sizet qlowat; /* queue low water mark */
Contstraints and restrictions on the use of qflag and
queuet fields and the qnext values are detailed in the
following sections.
qflag Field
The qflag field must be used only to check the following
flag values.
QFUL Queue is full.
QREADR Queue is used for upstream (read-side) processing.
QUSE Queue has been allocated.
SunOS 5.11 Last change: 10 Jan 2006 1
Data Structures for Drivers queue(9S)
QENAB Queue has been enabled for service by qenable(9F).
QNOENB Queue will not be scheduled for service by
putq(9F).
QWANTR Upstream processing element wants to read from
queue.
QWANTW Downstream processing element wants to write to
queue.
queuet Fields
Aside from qptr and qqinfo, a module or driver must never
assume that a queuet field value will remain unchanged
across calls to STREAMS entry points. In addition, many
fields can change values inside a STREAMS entry point, espe-
cially if the STREAMS module or driver has perimeters that
allow parallelism. See mt-streams(9F). Fields that are not
documented below are private to the STREAMS framework and
must not be accessed.
o The values of the qhiwat, qlowat, qminpsz, and
qmaxpsz fields can be changed at the discretion of
the module or driver. As such, the stability of
their values depends on the perimeter configuration
associated with any routines that modify them.
o The values of the qfirst, qlast, and qcount
fields can change whenever putq(9F), putbq(9F),
getq(9F), insq(9F), or rmvq(9F) is used on the
queue. As such, the stability of their values
depends on the perimeter configuration associated
with any routines that call those STREAMS func-
tions.
o The qflag field can change at any time.
o The qnext field will not change while inside a
given STREAMS entry point. Additional restrictions
on the use of the qnext value are described in the
next section.
A STREAMS module or driver can assign any value to qptr.
Typically qptr is used to point to module-specific per-
queue state, allocated in open(9E) and freed in close(9E).
The value or contents of qptr is never inspected by the
STREAMS framework.
SunOS 5.11 Last change: 10 Jan 2006 2
Data Structures for Drivers queue(9S)
The initial values for qminpsz, qmaxpsz, qhiwat, and
qlowat are set using the moduleinfo(9S) structure when
modinstall(9F) is called. A STREAMS module or driver can
subsequently change the values of those fields as necessary.
The remaining visible fields, qqinfo, qfirst, qlast,
qnext, qcount, and qflag, must never be modified by a
module or driver.
The Solaris DI requires that STREAMS modules and drivers
obey the rules described on this page. Those that do not
follow the rules can cause data corruption or system insta-
bility, and might change in behavior across patches or
upgrades.
qnext Restrictions
There are additional restrictions associated with the use of
the qnext value. In particular, a STREAMS module or driver:
o Must not access the data structure pointed to by
qnext.
o Must not rely on the value of qnext before calling
qprocson(9F) or after calling qprocsoff(9F).
o Must not pass the value into any STREAMS framework
function other than put(9F), canput(9F),
bcanput(9F), putctl(9F), putctl1(9F). However, in
all cases the "next" version of these functions,
such as putnext(9F), should be preferred.
o Must not use the value to compare against queue
pointers from other streams. However, checking
qnext for NUL can be used to distinguish a module
from a driver in code shared by both.
SEE ALSO
close(9E), open(9E), bcanput(9F), canput(9F), getq(9F),
insq(9F), putbq(9F)modinstall(9F), put(9F), putbq(9F),
putctl(9F), putctl1(9F), putnext(9F), putq(9F),
qprocsoff(9F), qprocson(9F), rmvq(9F), strqget(9F),
strqset(9F), moduleinfo(9S), msgb(9S), qinit(9S),
streamtab(9S)
Writing Device Drivers
STREAMS Programming Guide
SunOS 5.11 Last change: 10 Jan 2006 3
|
