summaryrefslogtreecommitdiffstats
path: root/share/man/man4/ng_sscop.4
blob: 0c6f0d4564b90804792a47b35be735836ebb5f67 (plain)
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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
.\"
.\" Copyright (c) 2001-2003
.\"	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
.\" 	All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" Author: Hartmut Brandt <harti@FreeBSD.org>
.\"
.\" $FreeBSD$
.\"
.\" ng_sscop(4) man page
.\"
.Dd October 24, 2003
.Dt NG_SSCOP 4
.Os
.Sh NAME
.Nm ng_sscop
.Nd netgraph SSCOP node type
.Sh SYNOPSIS
.In netnatm/saal/sscopdef.h
.In netgraph/atm/ng_sscop.h
.Sh DESCRIPTION
The
.Nm sscop
netgraph node type implements the ITU-T standard Q.2110.
This standard describes
the so called Service Specific Connection Oriented Protocol (SSCOP) that
is used to carry signalling messages over the private and public UNIs and
the public NNI.
This protocol is a transport protocol with selective
acknowledgements, and can be tailored to the environment.
This implementation is a full implementation of that standard.
.Pp
After creation of the node, the SSCOP instance must be created by sending
an
.Dq enable
message to the node.
If the node is enabled, the SSCOP parameters
can be retrieved and modified and the protocol can be started.
.Pp
The node is shut down either by a
.Dv NGM_SHUTDOWN
message, or when all hooks are disconnected.
.Sh HOOKS
Each
.Nm sscop
node has three hooks with fixed names:
.Bl -tag -width ".Va manage"
.It Va lower
This hook must be connected to a node that ensures
transport of packets to and from the remote peer node.
Normally this is a
.Xr ng_atm 4
node with an AAL5 hook, but the
.Nm sscop
node is able to work on any packet-transporting layer, like, for example,
IP or UDP.
The node handles flow control messages received on
this hook: if it receives a
.Dv NGM_HIGH_WATER_PASSED
message, it declares the
.Dq "lower layer busy"
state.
If a
.Dv NGM_LOW_WATER_PASSED
message is received, the busy state is cleared.
Note that the node does not
look at the message contents of these flow control messages.
.It Va upper
This is the interface to the SSCOP user.
This interface uses the following message format:
.Bd -literal
struct sscop_arg {
	uint32_t sig;
	uint32_t arg;	/* opt. sequence number or clear-buff */
	u_char	 data[];
};
.Ed
.Pp
The
.Va sig
field
is one of the signals defined in the standard:
.Bd -literal
enum sscop_aasig {
    SSCOP_ESTABLISH_request,	/* <- UU, BR */
    SSCOP_ESTABLISH_indication,	/* -> UU */
    SSCOP_ESTABLISH_response,	/* <- UU, BR */
    SSCOP_ESTABLISH_confirm,	/* -> UU */

    SSCOP_RELEASE_request,	/* <- UU */
    SSCOP_RELEASE_indication,	/* -> UU, SRC */
    SSCOP_RELEASE_confirm,	/* -> */

    SSCOP_DATA_request,		/* <- MU */
    SSCOP_DATA_indication,	/* -> MU, SN */

    SSCOP_UDATA_request,	/* <- MU */
    SSCOP_UDATA_indication,	/* -> MU */

    SSCOP_RECOVER_indication,	/* -> */
    SSCOP_RECOVER_response,	/* <- */

    SSCOP_RESYNC_request,	/* <- UU */
    SSCOP_RESYNC_indication,	/* -> UU */
    SSCOP_RESYNC_response,	/* <- */
    SSCOP_RESYNC_confirm,	/* -> */

    SSCOP_RETRIEVE_request,	/* <- RN */
    SSCOP_RETRIEVE_indication,	/* -> MU */
    SSCOP_RETRIEVE_COMPL_indication,/* -> */
};
.Ed
.Pp
The arrows in the comment show the direction of the signal, whether it
is a signal that comes out of the node
.Pq Ql -> ,
or is sent by the node user to the node
.Pq Ql <- .
The
.Va arg
field contains the argument to some of the signals: it is either a PDU
sequence number, or the
.Dv CLEAR-BUFFER
flag.
There are a number of special sequence numbers for some operations:
.Pp
.Bl -tag -width ".Dv SSCOP_RETRIEVE_UNKNOWN" -offset indent -compact
.It Dv SSCOP_MAXSEQNO
maximum legal sequence number
.It Dv SSCOP_RETRIEVE_UNKNOWN
retrieve transmission queue
.It Dv SSCOP_RETRIEVE_TOTAL
retrieve transmission buffer and queue
.El
.Pp
For signals that carry user data (as, for example,
.Dv SSCOP_DATA_request )
these two fields are followed by the variable sized user data.
.Pp
If the
.Va upper
hook is disconnected and the SSCOP instance is not in the idle
state, and the
.Va lower
hook is still connected, an
.Dv SSCOP_RELEASE_request
is executed to release the SSCOP connection.
.It Va manage
This is the management interface defined in the standard.
The data structure used here is:
.Bd -literal
struct sscop_marg {
	uint32_t sig;
	u_char	 data[];
};
.Ed
.Pp
Here
.Va sig
is one of
.Bd -literal
enum sscop_maasig {
    SSCOP_MDATA_request,	/* <- MU */
    SSCOP_MDATA_indication,	/* -> MU */
    SSCOP_MERROR_indication,	/* -> CODE, CNT */
};
.Ed
.Pp
The
.Dv SSCOP_MDATA
signals are followed by the actual management data, where the
.Dv SSCOP_MERROR
signal has the form:
.Bd -literal
struct sscop_merr {
	uint32_t sig;
	uint32_t err;	/* error code */
	uint32_t cnt;	/* error count */
};
.Ed
.El
.Sh CONTROL MESSAGES
The
.Nm sscop
node understands the generic control messages, plus the following:
.Bl -tag -width indent
.It Dv NGM_SSCOP_SETPARAM
Sets operational parameters of the SSCOP instance and takes the
following structure:
.Bd -literal
struct ng_sscop_setparam {
	uint32_t		mask;
	struct sscop_param	param;
};
.Ed
.Pp
The sub-structure
.Va param
contains the parameters to set, and the
.Va mask
field contains a bit mask, telling which of the parameters to set, and which
to ignore.
If a bit is set, the corresponding parameter is set.
The parameters are:
.Bd -literal
struct sscop_param {
	uint32_t timer_cc;	/* timer_cc in msec */
	uint32_t timer_poll;	/* timer_poll im msec */
	uint32_t timer_keep_alive;/* timer_keep_alive in msec */
	uint32_t timer_no_response;/*timer_no_response in msec */
	uint32_t timer_idle;	/* timer_idle in msec */
	uint32_t maxk;		/* maximum user data in bytes */
	uint32_t maxj;		/* maximum u-u info in bytes */
	uint32_t maxcc;		/* max. retransmissions for control packets */
	uint32_t maxpd;		/* max. vt(pd) before sending poll */
	uint32_t maxstat;	/* max. number of elements in stat list */
	uint32_t mr;		/* initial window */
	uint32_t flags;		/* flags */
};
.Ed
.Pp
The
.Va flags
field contains the following flags influencing SSCOP operation:
.Pp
.Bl -tag -width ".Dv SSCOP_POLLREX" -offset indent -compact
.It Dv SSCOP_ROBUST
enable atmf/97-0216 robustness enhancement
.It Dv SSCOP_POLLREX
send POLL after each retransmission
.El
.Pp
The bitmap has the following bits:
.Pp
.Bl -tag -width ".Dv SSCOP_SET_POLLREX" -offset indent -compact
.It Dv SSCOP_SET_TCC
set
.Va timer_cc
.It Dv SSCOP_SET_TPOLL
set
.Va timer_poll
.It Dv SSCOP_SET_TKA
set
.Va timer_keep_alive
.It Dv SSCOP_SET_TNR
set
.Va timer_no_response
.It Dv SSCOP_SET_TIDLE
set
.Va timer_idle
.It Dv SSCOP_SET_MAXK
set
.Va maxk
.It Dv SSCOP_SET_MAXJ
set
.Va maxj
.It Dv SSCOP_SET_MAXCC
set
.Va maxcc
.It Dv SSCOP_SET_MAXPD
set
.Va maxpd
.It Dv SSCOP_SET_MAXSTAT
set
.Va maxstat
.It Dv SSCOP_SET_MR
set the initial window
.It Dv SSCOP_SET_ROBUST
set or clear
.Dv SSCOP_ROBUST
.It Dv SSCOP_SET_POLLREX
set or clear
.Dv SSCOP_POLLREX
.El
.Pp
The node responds to the
.Dv NGM_SSCOP_SETPARAM
message with the following response:
.Bd -literal
struct ng_sscop_setparam_resp {
	uint32_t mask;
	int32_t	 error;
};
.Ed
.Pp
Here
.Va mask
contains a bitmask of the parameters that the user requested to set,
but that could not be set and
.Va error
is an
.Xr errno 2
code describing why the parameter could not be set.
.It Dv NGM_SSCOP_GETPARAM
This message returns the current operational parameters of the SSCOP
instance in a
.Vt sscop_param
structure.
.It Dv NGM_SSCOP_ENABLE
This message creates the actual SSCOP instance and initializes it.
Until this is done, parameters may neither be retrieved nor set, and all
messages received on any hook are discarded.
.It Dv NGM_SSCOP_DISABLE
Destroy the SSCOP instance.
After this, all messages on any hooks are
discarded.
.It Dv NGM_SSCOP_SETDEBUG
Set debugging flags.
The argument is a
.Vt uint32_t .
.It Dv NGM_SSCOP_GETDEBUG
Retrieve the actual debugging flags.
Needs no arguments and responds with a
.Vt uint32_t .
.It Dv NGM_SSCOP_GETSTATE
Responds with the current state of the SSCOP instance in a
.Vt uint32_t .
If the node is not enabled, the retrieved state is 0.
.El
.Sh FLOW CONTROL
Flow control works on the upper and on the lower layer interface.
At the lower
layer interface, the two messages,
.Dv NGM_HIGH_WATER_PASSED
and
.Dv NGM_LOW_WATER_PASSED ,
are used to declare or clear the
.Dq "lower layer busy"
state of the protocol.
.Pp
At the upper layer interface, the
.Nm sscop
node handles three types of flow control messages:
.Bl -tag -width indent
.It Dv NGM_HIGH_WATER_PASSED
If this message is received, the SSCOP stops moving the receive window.
Each time a data message is handed over to the upper layer, the receive
window is moved by one message.
Stopping these updates
means that the window will start to close and if the peer has sent
all messages allowed by the current window, it stops transmission.
This means that the upper layer must be able to still receive a full window
amount of messages.
.It Dv NGM_LOW_WATER_PASSED
This will re-enable the automatic window updates, and if the space indicated
in the message is larger than the current window, the window will be opened
by that amount.
The space is computed as the difference of the
.Va max_queuelen_packets
and
.Va current
members of the
.Vt ngm_queue_state
structure.
.It Dv NGM_SYNC_QUEUE_STATE
If the upper layer buffer filling state, as indicated by
.Va current ,
is equal to or greater than
.Va high_watermark
then the message is ignored.
If this is not the case, the amount
of receiver space is computed as the difference of
.Va max_queuelen_packets
and
.Va current
if automatic window updates are currently allowed, and as the difference of
.Va high_water_mark
and
.Va current
if window updates are disabled.
If the resulting value is larger than the current window, the current window
is opened up to this value.
Automatic window updates are enabled if they
were disabled.
.El
.Sh SEE ALSO
.Xr netgraph 4 ,
.Xr ng_atm 4 ,
.Xr ng_sscfu 4 ,
.Xr ngctl 8
.Sh AUTHORS
.An Harti Brandt Aq harti@FreeBSD.org
OpenPOWER on IntegriCloud