1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH QUEUE 9S "May 13, 2017"
.SH NAME
queue \- STREAMS queue structure
.SH SYNOPSIS
.nf
#include <sys/stream.h>
.fi
.SH INTERFACE LEVEL
Architecture independent level 1 (DDI/DKI)
.SH DESCRIPTION
A \fBSTREAMS\fR driver or module consists of two \fBqueue\fR structures:
\fIread\fR for upstream processing and \fIwrite\fR for downstream processing.
The queue structure is the major building block of a stream.
.SS "\fBqueue\fR Structure Members"
The \fBqueue\fR structure is defined as type \fBqueue_t\fR. The structure can
be accessed at any time from inside a \fBSTREAMS\fR entry point associated with
that queue.
.sp
.in +2
.nf
struct qinit *q_qinfo; /* queue processing procedure */
struct msgb *q_first; /* first message in queue */
struct msgb *q_last; /* last message in queue */
struct queue *q_next; /* next queue in stream */
void *q_ptr; /* module-specific data */
size_t q_count; /* number of bytes on queue */
uint_t q_flag; /* queue state */
ssize_t q_minpsz; /* smallest packet OK on queue */
ssize_t q_maxpsz; /* largest packet OK on queue */
size_t q_hiwat; /* queue high water mark */
size_t q_lowat; /* queue low water mark */
.fi
.in -2
.sp
.LP
Contstraints and restrictions on the use of \fBq_flag\fR and \fBqueue_t\fR
fields and the \fBq_next\fR values are detailed in the following sections.
.SS "\fBq_flag\fR Field"
The \fBq_flag\fR field must be used only to check the following flag values.
.sp
.ne 2
.na
\fB\fBQFULL\fR\fR
.ad
.RS 10n
Queue is full.
.RE
.sp
.ne 2
.na
\fB\fBQREADR\fR\fR
.ad
.RS 10n
Queue is used for upstream (read-side) processing.
.RE
.sp
.ne 2
.na
\fB\fBQUSE\fR\fR
.ad
.RS 10n
Queue has been allocated.
.RE
.sp
.ne 2
.na
\fB\fBQENAB\fR\fR
.ad
.RS 10n
Queue has been enabled for service by \fBqenable\fR(9F).
.RE
.sp
.ne 2
.na
\fB\fBQNOENB\fR\fR
.ad
.RS 10n
Queue will not be scheduled for service by \fBputq\fR(9F).
.RE
.sp
.ne 2
.na
\fB\fBQWANTR\fR\fR
.ad
.RS 10n
Upstream processing element wants to read from queue.
.RE
.sp
.ne 2
.na
\fB\fBQWANTW\fR\fR
.ad
.RS 10n
Downstream processing element wants to write to queue.
.RE
.SS "\fBqueue_t\fR Fields"
Aside from \fBq_ptr\fR and \fBq_qinfo\fR, a module or driver must never assume
that a \fBqueue_t\fR field value will remain unchanged across calls to
\fBSTREAMS\fR entry points. In addition, many fields can change values inside a
\fBSTREAMS\fR entry point, especially if the \fBSTREAMS\fR module or driver has
perimeters that allow parallelism. See \fBmt-streams\fR(9F). Fields that are
not documented below are private to the \fBSTREAMS\fR framework and must not be
accessed.
.RS +4
.TP
.ie t \(bu
.el o
The values of the \fBq_hiwat\fR, \fBq_lowat\fR, \fBq_minpsz\fR, and
\fBq_maxpsz\fR 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.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The values of the \fBq_first\fR, \fBq_last\fR, and \fBq_count\fR fields can
change whenever \fBputq\fR(9F), \fBputbq\fR(9F), \fBgetq\fR(9F),
\fBinsq\fR(9F), or \fBrmvq\fR(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 \fBSTREAMS\fR functions.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBq_flag\fR field can change at any time.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBq_next\fR field will not change while inside a given \fBSTREAMS\fR entry
point. Additional restrictions on the use of the \fBq_next\fR value are
described in the next section.
.RE
.sp
.LP
A \fBSTREAMS\fR module or driver can assign any value to \fBq_ptr\fR. Typically
\fBq_ptr\fR is used to point to module-specific per-queue state, allocated in
\fBopen\fR(9E) and freed in \fBclose\fR(9E). The value or contents of
\fBq_ptr\fR is never inspected by the \fBSTREAMS\fR framework.
.sp
.LP
The initial values for \fBq_minpsz\fR, \fBq_maxpsz\fR, \fBq_hiwat\fR, and
\fBq_lowat\fR are set using the \fBmodule_info\fR(9S) structure when
\fBmod_install\fR(9F) is called. A \fBSTREAMS\fR\ module or driver can
subsequently change the values of those fields as necessary. The remaining
visible fields, \fBq_qinfo\fR, \fBq_first\fR, \fBq_last\fR, \fBq_next\fR,
\fBq_count\fR, and \fBq_flag\fR, must never be modified by a module or driver.
.sp
.LP
The illumos DDI requires that \fBSTREAMS\fR modules and drivers obey the rules
described on this page. Those that do not follow the rules can cause data
corruption or system instability, and might change in behavior across updates
or upgrades.
.SS "\fBq_next\fR Restrictions"
There are additional restrictions associated with the use of the \fBq_next\fR
value. In particular, a \fBSTREAMS\fR module or driver:
.RS +4
.TP
.ie t \(bu
.el o
Must not access the data structure pointed to by \fBq_next\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Must not rely on the value of \fBq_next\fR before calling \fBqprocson\fR(9F) or
after calling \fBqprocsoff\fR(9F).
.RE
.RS +4
.TP
.ie t \(bu
.el o
Must not pass the value into any \fBSTREAMS\fR framework function other than
\fBput\fR(9F), \fBcanput\fR(9F), \fBbcanput\fR(9F), \fBputctl\fR(9F),
\fBputctl1\fR(9F). However, in all cases the "next" version of these functions,
such as \fBputnext\fR(9F), should be preferred.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Must not use the value to compare against queue pointers from other streams.
However, checking \fBq_next\fR for NULL can be used to distinguish a module
from a driver in code shared by both.
.RE
.SH SEE ALSO
\fBclose\fR(9E), \fBopen\fR(9E), \fBbcanput\fR(9F), \fBcanput\fR(9F),
\fBgetq\fR(9F), \fBinsq\fR(9F), \fBmod_install\fR(9F), \fBput\fR(9F),
\fBputbq\fR(9F), \fBputctl\fR(9F), \fBputctl1\fR(9F), \fBputnext\fR(9F),
\fBputq\fR(9F), \fBqprocsoff\fR(9F), \fBqprocson\fR(9F), \fBrmvq\fR(9F),
\fBstrqget\fR(9F), \fBstrqset\fR(9F), \fBmodule_info\fR(9S), \fBmsgb\fR(9S),
\fBqinit\fR(9S), \fBstreamtab\fR(9S)
.sp
.LP
\fIWriting Device Drivers\fR
.sp
.LP
\fISTREAMS Programming Guide\fR
|
