2 .\" Copyright (c) 2001-2003
3 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
31 .\" ng_sscop(4) man page
38 .Nd netgraph SSCOP node type
40 .In netnatm/saal/sscopdef.h
41 .In netgraph/atm/ng_sscop.h
45 netgraph node type implements the ITU-T standard Q.2110.
46 This standard describes
47 the so called Service Specific Connection Oriented Protocol (SSCOP) that
48 is used to carry signalling messages over the private and public UNIs and
50 This protocol is a transport protocol with selective
51 acknowledgements, and can be tailored to the environment.
52 This implementation is a full implementation of that standard.
54 After creation of the node, the SSCOP instance must be created by sending
58 If the node is enabled, the SSCOP parameters
59 can be retrieved and modified and the protocol can be started.
61 The node is shut down either by a
63 message, or when all hooks are disconnected.
67 node has three hooks with fixed names:
68 .Bl -tag -width ".Va manage"
70 This hook must be connected to a node that ensures
71 transport of packets to and from the remote peer node.
74 node with an AAL5 hook, but the
76 node is able to work on any packet-transporting layer, like, for example,
78 The node handles flow control messages received on
79 this hook: if it receives a
80 .Dv NGM_HIGH_WATER_PASSED
81 message, it declares the
82 .Dq "lower layer busy"
85 .Dv NGM_LOW_WATER_PASSED
86 message is received, the busy state is cleared.
87 Note that the node does not
88 look at the message contents of these flow control messages.
90 This is the interface to the SSCOP user.
91 This interface uses the following message format:
95 uint32_t arg; /* opt. sequence number or clear-buff */
103 is one of the signals defined in the standard:
106 SSCOP_ESTABLISH_request, /* <- UU, BR */
107 SSCOP_ESTABLISH_indication, /* -> UU */
108 SSCOP_ESTABLISH_response, /* <- UU, BR */
109 SSCOP_ESTABLISH_confirm, /* -> UU */
111 SSCOP_RELEASE_request, /* <- UU */
112 SSCOP_RELEASE_indication, /* -> UU, SRC */
113 SSCOP_RELEASE_confirm, /* -> */
115 SSCOP_DATA_request, /* <- MU */
116 SSCOP_DATA_indication, /* -> MU, SN */
118 SSCOP_UDATA_request, /* <- MU */
119 SSCOP_UDATA_indication, /* -> MU */
121 SSCOP_RECOVER_indication, /* -> */
122 SSCOP_RECOVER_response, /* <- */
124 SSCOP_RESYNC_request, /* <- UU */
125 SSCOP_RESYNC_indication, /* -> UU */
126 SSCOP_RESYNC_response, /* <- */
127 SSCOP_RESYNC_confirm, /* -> */
129 SSCOP_RETRIEVE_request, /* <- RN */
130 SSCOP_RETRIEVE_indication, /* -> MU */
131 SSCOP_RETRIEVE_COMPL_indication,/* -> */
135 The arrows in the comment show the direction of the signal, whether it
136 is a signal that comes out of the node
138 or is sent by the node user to the node
142 field contains the argument to some of the signals: it is either a PDU
143 sequence number, or the
146 There are a number of special sequence numbers for some operations:
148 .Bl -tag -width ".Dv SSCOP_RETRIEVE_UNKNOWN" -offset indent -compact
149 .It Dv SSCOP_MAXSEQNO
150 maximum legal sequence number
151 .It Dv SSCOP_RETRIEVE_UNKNOWN
152 retrieve transmission queue
153 .It Dv SSCOP_RETRIEVE_TOTAL
154 retrieve transmission buffer and queue
157 For signals that carry user data (as, for example,
158 .Dv SSCOP_DATA_request )
159 these two fields are followed by the variable sized user data.
163 hook is disconnected and the SSCOP instance is not in the idle
166 hook is still connected, an
167 .Dv SSCOP_RELEASE_request
168 is executed to release the SSCOP connection.
170 This is the management interface defined in the standard.
171 The data structure used here is:
184 SSCOP_MDATA_request, /* <- MU */
185 SSCOP_MDATA_indication, /* -> MU */
186 SSCOP_MERROR_indication, /* -> CODE, CNT */
192 signals are followed by the actual management data, where the
198 uint32_t err; /* error code */
199 uint32_t cnt; /* error count */
206 node understands the generic control messages, plus the following:
207 .Bl -tag -width indent
208 .It Dv NGM_SSCOP_SETPARAM
209 Sets operational parameters of the SSCOP instance and takes the
212 struct ng_sscop_setparam {
214 struct sscop_param param;
220 contains the parameters to set, and the
222 field contains a bit mask, telling which of the parameters to set, and which
224 If a bit is set, the corresponding parameter is set.
228 uint32_t timer_cc; /* timer_cc in msec */
229 uint32_t timer_poll; /* timer_poll im msec */
230 uint32_t timer_keep_alive;/* timer_keep_alive in msec */
231 uint32_t timer_no_response;/*timer_no_response in msec */
232 uint32_t timer_idle; /* timer_idle in msec */
233 uint32_t maxk; /* maximum user data in bytes */
234 uint32_t maxj; /* maximum u-u info in bytes */
235 uint32_t maxcc; /* max. retransmissions for control packets */
236 uint32_t maxpd; /* max. vt(pd) before sending poll */
237 uint32_t maxstat; /* max. number of elements in stat list */
238 uint32_t mr; /* initial window */
239 uint32_t flags; /* flags */
245 field contains the following flags influencing SSCOP operation:
247 .Bl -tag -width ".Dv SSCOP_POLLREX" -offset indent -compact
249 enable atmf/97-0216 robustness enhancement
251 send POLL after each retransmission
254 The bitmap has the following bits:
256 .Bl -tag -width ".Dv SSCOP_SET_POLLREX" -offset indent -compact
260 .It Dv SSCOP_SET_TPOLL
268 .Va timer_no_response
269 .It Dv SSCOP_SET_TIDLE
272 .It Dv SSCOP_SET_MAXK
275 .It Dv SSCOP_SET_MAXJ
278 .It Dv SSCOP_SET_MAXCC
281 .It Dv SSCOP_SET_MAXPD
284 .It Dv SSCOP_SET_MAXSTAT
288 set the initial window
289 .It Dv SSCOP_SET_ROBUST
292 .It Dv SSCOP_SET_POLLREX
297 The node responds to the
298 .Dv NGM_SSCOP_SETPARAM
299 message with the following response:
301 struct ng_sscop_setparam_resp {
309 contains a bitmask of the parameters that the user requested to set,
310 but that could not be set and
314 code describing why the parameter could not be set.
315 .It Dv NGM_SSCOP_GETPARAM
316 This message returns the current operational parameters of the SSCOP
320 .It Dv NGM_SSCOP_ENABLE
321 This message creates the actual SSCOP instance and initializes it.
322 Until this is done, parameters may neither be retrieved nor set, and all
323 messages received on any hook are discarded.
324 .It Dv NGM_SSCOP_DISABLE
325 Destroy the SSCOP instance.
326 After this, all messages on any hooks are
328 .It Dv NGM_SSCOP_SETDEBUG
332 .It Dv NGM_SSCOP_GETDEBUG
333 Retrieve the actual debugging flags.
334 Needs no arguments and responds with a
336 .It Dv NGM_SSCOP_GETSTATE
337 Responds with the current state of the SSCOP instance in a
339 If the node is not enabled, the retrieved state is 0.
342 Flow control works on the upper and on the lower layer interface.
344 layer interface, the two messages,
345 .Dv NGM_HIGH_WATER_PASSED
347 .Dv NGM_LOW_WATER_PASSED ,
348 are used to declare or clear the
349 .Dq "lower layer busy"
350 state of the protocol.
352 At the upper layer interface, the
354 node handles three types of flow control messages:
355 .Bl -tag -width indent
356 .It Dv NGM_HIGH_WATER_PASSED
357 If this message is received, the SSCOP stops moving the receive window.
358 Each time a data message is handed over to the upper layer, the receive
359 window is moved by one message.
360 Stopping these updates
361 means that the window will start to close and if the peer has sent
362 all messages allowed by the current window, it stops transmission.
363 This means that the upper layer must be able to still receive a full window
365 .It Dv NGM_LOW_WATER_PASSED
366 This will re-enable the automatic window updates, and if the space indicated
367 in the message is larger than the current window, the window will be opened
369 The space is computed as the difference of the
370 .Va max_queuelen_packets
376 .It Dv NGM_SYNC_QUEUE_STATE
377 If the upper layer buffer filling state, as indicated by
379 is equal to or greater than
381 then the message is ignored.
382 If this is not the case, the amount
383 of receiver space is computed as the difference of
384 .Va max_queuelen_packets
387 if automatic window updates are currently allowed, and as the difference of
391 if window updates are disabled.
392 If the resulting value is larger than the current window, the current window
393 is opened up to this value.
394 Automatic window updates are enabled if they
403 .An Harti Brandt Aq harti@FreeBSD.org