| blob | fdf5b972dd2e84c733a2195be1caacca9a6ba192 |
1 '\" te
2 .\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH BUFMOD 7M "Nov 11, 1997"
7 .SH NAME
8 bufmod \- STREAMS Buffer Module
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB#include <sys/bufmod.h>\fR
13 .fi
15 .LP
16 .nf
17 \fBioctl(fd, I_PUSH, "bufmod");\fR
18 .fi
20 .SH DESCRIPTION
21 .sp
22 .LP
23 \fBbufmod\fR is a \fBSTREAMS\fR module that buffers incoming messages, reducing
24 the number of system calls and the associated overhead required to read and
25 process them. Although \fBbufmod\fR was originally designed to be used in
26 conjunction with \fBSTREAMS-based\fR networking device drivers, the version
27 described here is general purpose so that it can be used anywhere \fBSTREAMS\fR
28 input buffering is required.
29 .SS "Read-side Behavior"
30 .sp
31 .LP
32 The behavior of \fBbufmod\fR depends on various parameters and flags that can
33 be set and queried as described below under \fBIOCTLS\fR. \fBbufmod\fR collects
34 incoming \fBM_DATA\fR messages into chunks, passing each chunk upstream when
35 the chunk becomes full or the current read timeout expires. It optionally
36 converts \fBM_PROTO\fR messages to \fBM_DATA\fR and adds them to chunks as
37 well. It also optionally adds to each message a header containing a timestamp,
38 and a cumulative count of messages dropped on the stream read side due to
39 resource exhaustion or flow control. Thedefault settings of \fBbufmod\fR allow
40 it to drop messages when flow control sets in or resources are exhausted;
41 disabling headers and explicitly requesting no drops makes \fBbufmod\fR pass
42 all messages through. Finally, \fBbufmod\fR is capable of truncating upstream
43 messages to a fixed, programmable length.
44 .sp
45 .LP
46 When a message arrives, \fBbufmod\fR processes it in several steps. The
47 following paragraphs discuss each step in turn.
48 .sp
49 .LP
50 Upon receiving a message from below, if the \fBSB_NO_HEADER\fR flag is not set,
51 \fBbufmod\fR immediately timestamps it and saves the current time value for
52 later insertion in the header described below.
53 .sp
54 .LP
55 Next, if \fBSB_NO_PROTO_CVT\fR is not set, \fBbufmod\fR converts all leading
56 \fBM_PROTO\fR blocks in the message to \fBM_DATA\fR blocks, altering only the
57 message type field and leaving the contents alone.
58 .sp
59 .LP
60 It then truncates the message to the current \fIsnapshot length\fR, which is
61 set with the \fBSBIOCSSNAP\fR \fBioctl\fR described below.
62 .sp
63 .LP
64 Afterwards, if \fBSB_NO_HEADER\fR is not set, \fBbufmod\fR prepends a header to
65 the converted message. This header is defined as follows.
66 .sp
67 .in +2
68 .nf
69 struct sb_hdr {
70 uint_t sbh_origlen;
71 uint_t sbh_msglen;
72 uint_t sbh_totlen;
73 uint_t sbh_drops;
74 #if defined(_LP64) || defined(_I32LPx)
75 struct timeval32 sbh_timestamp;
76 #else
77 struct timeval sbh_timestamp;
78 #endif /* !_LP64 */
79 };
80 .fi
81 .in -2
83 .sp
84 .LP
85 The \fBsbh_origlen\fR field gives the message's original length before
86 truncation in bytes. The \fBsbh_msglen\fR field gives the length in bytes of
87 the message after the truncation has been done. \fBsbh_totlen\fR gives the
88 distance in bytes from the start of the truncated message in the current chunk
89 (described below) to the start of the next message in the chunk; the value
90 reflects any padding necessary to insure correct data alignment for the host
91 machine and includes the length of the header itself. \fBsbh_drops\fR reports
92 the cumulative number of input messages that this instance of \fBbufmod\fR has
93 dropped due to flow control or resource exhaustion. In the current
94 implementation message dropping due to flow control can occur only if the
95 \fBSB_NO_DROPS\fR flag is not set. (Note: this accounts only for events
96 occurring within \fBbufmod\fR, and does not count messages dropped by
97 downstream or by upstream modules.) The \fBsbh_timestamp\fR field contains the
98 message arrival time expressed as a \fBstruct timeval\fR.
99 .sp
100 .LP
101 After preparing a message, \fBbufmod\fR attempts to add it to the end of the
102 current chunk, using the chunk size and timeout values to govern the addition.
103 The chunk size and timeout values are set and inspected using the \fBioctl()\fR
104 calls described below. If adding the new message would make the current chunk
105 grow larger than the chunk size, \fBbufmod\fR closes off the current chunk,
106 passing it up to the next module in line, and starts a new chunk. If adding the
107 message would still make the new chunk overflow, the module passes it upward in
108 an over-size chunk of its own. Otherwise, the module concatenates the message
109 to the end of the current chunk.
110 .sp
111 .LP
112 To ensure that messages do not languish forever in an accumulating chunk,
113 \fBbufmod\fR maintains a read timeout. Whenever this timeout expires, the
114 module closes off the current chunk and passes it upward. The module restarts
115 the timeout period when it receives a read side data message and a timeout is
116 not currently active. These two rules insure that \fBbufmod\fR minimizes the
117 number of chunks it produces during periods of intense message activity and
118 that it periodically disposes of all messages during slack intervals, but
119 avoids any timeout overhead when there is no activity.
120 .sp
121 .LP
122 \fBbufmod\fR handles other message types as follows. Upon receiving an
123 \fBM_FLUSH\fR message specifying that the read queue be flushed, the module
124 clears the currently accumulating chunk and passes the message on to the module
125 or driver above. (Note: \fBbufmod\fR uses zero length \fBM_CTL\fR messages for
126 internal synchronization and does not pass them through.) \fBbufmod\fR passes
127 all other messages through unaltered to its upper neighbor, maintaining message
128 order for non high priority messages by passing up any accumulated chunk first.
129 .sp
130 .LP
131 If the \fBSB_DEFER_CHUNK\fR flag is set, buffering does not begin until the
132 second message is received within the timeout window.
133 .sp
134 .LP
135 If the \fBSB_SEND_ON_WRITE\fR flag is set, \fBbufmod\fR passes up the read side
136 any buffered data when a message is received on the write side.
137 \fBSB_SEND_ON_WRITE\fR and \fBSB_DEFER_CHUNK\fR are often used together.
138 .SS "Write-side Behavior"
139 .sp
140 .LP
141 \fBbufmod\fR intercepts \fBM_IOCTL\fR messages for the \fBioctl\fRs described
142 below. The module passes all other messages through unaltered to its lower
143 neighbor. If \fBSB_SEND_ON_WRITE\fR is set, message arrival on the writer side
144 suffices to close and transmit the current read side chunk.
145 .SH IOCTLS
146 .sp
147 .LP
148 \fBbufmod\fR responds to the following \fBioctl\fRs.
149 .sp
150 .ne 2
151 .na
152 \fB\fBSBIOCSTIME\fR \fR
153 .ad
154 .RS 16n
155 Set the read timeout value to the value referred to by the \fBstruct timeval\fR
156 pointer given as argument. Setting the timeout value to zero has the
157 side-effect of forcing the chunk size to zero as well, so that the module will
158 pass all incoming messages upward immediately upon arrival. Negative values are
159 rejected with an \fBEINVAL\fR error.
160 .RE
162 .sp
163 .ne 2
164 .na
165 \fB\fBSBIOCGTIME\fR \fR
166 .ad
167 .RS 16n
168 Return the read timeout in the \fBstruct timeval\fR pointed to by the argument.
169 If the timeout has been cleared with the \fBSBIOCCTIME\fR \fBioctl\fR, return
170 with an \fBERANGE\fR error.
171 .RE
173 .sp
174 .ne 2
175 .na
176 \fB\fBSBIOCCTIME\fR \fR
177 .ad
178 .RS 16n
179 Clear the read timeout, effectively setting its value to infinity. This results
180 in no timeouts being active and the chunk being delivered when it is full.
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fB\fBSBIOCSCHUNK\fR \fR
187 .ad
188 .RS 16n
189 Set the chunk size to the value referred to by the \fIuint_t\fR pointer given
190 as argument. See Notes for a description of effect on stream head high water
191 mark.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fBSBIOCGCHUNK\fR \fR
198 .ad
199 .RS 16n
200 Return the chunk size in the \fIuint_t\fR pointed to by the argument.
201 .RE
203 .sp
204 .ne 2
205 .na
206 \fB\fBSBIOCSSNAP\fR \fR
207 .ad
208 .RS 16n
209 Set the current snapshot length to the value given in the \fBuint_t\fR pointed
210 to by the \fBioctl\fR's final argument. \fBbufmod\fR interprets a snapshot
211 length value of zero as meaning infinity, so it will not alter the message. See
212 Notes for a description of effect on stream head high water mark.
213 .RE
215 .sp
216 .ne 2
217 .na
218 \fB\fBSBIOCGSNAP\fR \fR
219 .ad
220 .RS 16n
221 Returns the current snapshot length in the \fBuint_t\fR pointed to by the
222 \fBioctl\fR's final argument.
223 .RE
225 .sp
226 .ne 2
227 .na
228 \fB\fBSBIOCSFLAGS\fR \fR
229 .ad
230 .RS 16n
231 Set the current flags to the value given in the \fBuint_t\fR pointed to by the
232 \fBioctl\fR's final argument. Possible values are a combination of the
233 following.
234 .sp
235 .ne 2
236 .na
237 \fB\fBSB_SEND_ON_WRITE\fR \fR
238 .ad
239 .RS 21n
240 Transmit the read side chunk on arrival of a message on the write side.
241 .RE
243 .sp
244 .ne 2
245 .na
246 \fB\fBSB_NO_HEADER\fR \fR
247 .ad
248 .RS 21n
249 Do not add headers to read side messages.
250 .RE
252 .sp
253 .ne 2
254 .na
255 \fB\fBSB_NO_DROPS\fR \fR
256 .ad
257 .RS 21n
258 Do not drop messages due to flow control upstream.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fBSB_NO_PROTO_CVT\fR \fR
265 .ad
266 .RS 21n
267 Do not convert \fBM_PROTO\fR messages into \fBM_DATA\fR.
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fBSB_DEFER_CHUNK\fR \fR
274 .ad
275 .RS 21n
276 Begin buffering on arrival of the second read side message in a timeout
277 interval.
278 .RE
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fBSBIOCGFLAGS\fR \fR
286 .ad
287 .RS 16n
288 Returns the current flags in the \fBuint_t\fR pointed to by the \fBioctl\fR's
289 final argument.
290 .RE
292 .SH SEE ALSO
293 .sp
294 .LP
295 \fBdlpi\fR(7P), \fBpfmod\fR(7M)
296 .SH NOTES
297 .sp
298 .LP
299 Older versions of \fBbufmod\fR did not support the behavioral flexibility
300 controlled by the \fBSBIOCSFLAGS\fR \fBioctl\fR. Applications that wish to take
301 advantage of this flexibility can guard themselves against old versions of the
302 module by invoking the \fBSBIOCGFLAGS\fR ioctl and checking for an \fBEINVAL\fR
303 error return.
304 .sp
305 .LP
306 When buffering is enabled by issuing an \fBSBIOCSCHUNK\fR ioctl to set the
307 chunk size to a non zero value, \fBbufmod\fR sends a \fBSETOPTS\fR message to
308 adjust the stream head high and low water marks to accommodate the chunked
309 messages.
310 .sp
311 .LP
312 When buffering is disabled by setting the chunk size to zero, message
313 truncation can have a significant influence on data traffic at the stream head
314 and therefore the stream head high and low water marks are adjusted to new
315 values appropriate for the smaller truncated message sizes.
316 .SH BUGS
317 .sp
318 .LP
319 \fBbufmod\fR does not defend itself against allocation failures, so that it is
320 possible, although very unlikely, for the stream head to use inappropriate high
321 and low water marks after the chunk size or snapshot length have changed.