Deleted Added
full compact
ng_sscop.4 (131726) ng_sscop.4 (131861)
1.\"
2.\" Copyright (c) 2001-2003
3.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:

--- 10 unchanged lines hidden (view full) ---

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
25.\" SUCH DAMAGE.
26.\"
1.\"
2.\" Copyright (c) 2001-2003
3.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:

--- 10 unchanged lines hidden (view full) ---

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
25.\" SUCH DAMAGE.
26.\"
27.\" Author: Hartmut Brandt <harti@freebsd.org>
27.\" Author: Hartmut Brandt <harti@FreeBSD.org>
28.\"
28.\"
29.\" $FreeBSD: head/share/man/man4/ng_sscop.4 131726 2004-07-06 20:43:24Z ru $
29.\" $FreeBSD: head/share/man/man4/ng_sscop.4 131861 2004-07-09 07:26:15Z ru $
30.\"
31.\" ng_sscop(4) man page
32.\"
33.Dd October 24, 2003
34.Dt NG_SSCOP 4
35.Os
36.Sh NAME
37.Nm ng_sscop
38.Nd netgraph SSCOP node type
39.Sh SYNOPSIS
30.\"
31.\" ng_sscop(4) man page
32.\"
33.Dd October 24, 2003
34.Dt NG_SSCOP 4
35.Os
36.Sh NAME
37.Nm ng_sscop
38.Nd netgraph SSCOP node type
39.Sh SYNOPSIS
40.Fd #include <netnatm/saal/sscopdef.h>
41.Fd #include <netgraph/atm/ng_sscop.h>
40.In netnatm/saal/sscopdef.h
41.In netgraph/atm/ng_sscop.h
42.Sh DESCRIPTION
43The
42.Sh DESCRIPTION
43The
44.Nm
45netgraph node implements the ITU-T standard Q.2110.
44.Nm sscop
45netgraph node type implements the ITU-T standard Q.2110.
46This standard describes
47the so called Service Specific Connection Oriented Protocol (SSCOP) that
48is used to carry signalling messages over the private and public UNIs and
49the public NNI.
50This protocol is a transport protocol with selective
46This standard describes
47the so called Service Specific Connection Oriented Protocol (SSCOP) that
48is used to carry signalling messages over the private and public UNIs and
49the public NNI.
50This protocol is a transport protocol with selective
51acknowledgements and can be tailored to the environment.
51acknowledgements, and can be tailored to the environment.
52This implementation is a full implementation of that standard.
53.Pp
54After creation of the node, the SSCOP instance must be created by sending
52This implementation is a full implementation of that standard.
53.Pp
54After creation of the node, the SSCOP instance must be created by sending
55an enable message to the node.
55an
56.Dq enable
57message to the node.
56If the node is enabled, the SSCOP parameters
57can be retrieved and modified and the protocol can be started.
58.Pp
58If the node is enabled, the SSCOP parameters
59can be retrieved and modified and the protocol can be started.
60.Pp
59The node is shutdown either by a
61The node is shut down either by a
60.Dv NGM_SHUTDOWN
62.Dv NGM_SHUTDOWN
61message or when all hooks are disconnected.
63message, or when all hooks are disconnected.
62.Sh HOOKS
63Each
64.Sh HOOKS
65Each
64.Nm
66.Nm sscop
65node has three hooks with fixed names:
67node has three hooks with fixed names:
66.Bl -tag -width manage
67.It Dv lower
68This hook is the hook that must be connected to a node that ensures
68.Bl -tag -width ".Va manage"
69.It Va lower
70This hook must be connected to a node that ensures
69transport of packets to and from the remote peer node.
70Normally this is a
71.Xr ng_atm 4
72node with an AAL5 hook, but the
71transport of packets to and from the remote peer node.
72Normally this is a
73.Xr ng_atm 4
74node with an AAL5 hook, but the
73.Nm
75.Nm sscop
74node is able to work on any packet-transporting layer, like, for example,
75IP or UDP.
76The node handles flow control messages received on
77this hook: if it receives a
78.Dv NGM_HIGH_WATER_PASSED
76node is able to work on any packet-transporting layer, like, for example,
77IP or UDP.
78The node handles flow control messages received on
79this hook: if it receives a
80.Dv NGM_HIGH_WATER_PASSED
79message it declares the
80.Ql lower layer busy
81message, it declares the
82.Dq "lower layer busy"
81state.
82If a
83.Dv NGM_LOW_WATER_PASSED
83state.
84If a
85.Dv NGM_LOW_WATER_PASSED
84message is received the busy state is cleared.
85Note, that the node does not
86message is received, the busy state is cleared.
87Note that the node does not
86look at the message contents of these flow control messages.
88look at the message contents of these flow control messages.
87.It Dv upper
89.It Va upper
88This is the interface to the SSCOP user.
89This interface uses the following message format:
90.Bd -literal
91struct sscop_arg {
92 uint32_t sig;
93 uint32_t arg; /* opt. sequence number or clear-buff */
94 u_char data[];
95};
96.Ed
97.Pp
90This is the interface to the SSCOP user.
91This interface uses the following message format:
92.Bd -literal
93struct sscop_arg {
94 uint32_t sig;
95 uint32_t arg; /* opt. sequence number or clear-buff */
96 u_char data[];
97};
98.Ed
99.Pp
98.Fa sig
100The
101.Va sig
102field
99is one of the signals defined in the standard:
100.Bd -literal
101enum sscop_aasig {
102 SSCOP_ESTABLISH_request, /* <- UU, BR */
103 SSCOP_ESTABLISH_indication, /* -> UU */
104 SSCOP_ESTABLISH_response, /* <- UU, BR */
105 SSCOP_ESTABLISH_confirm, /* -> UU */
106

--- 16 unchanged lines hidden (view full) ---

123 SSCOP_RESYNC_confirm, /* -> */
124
125 SSCOP_RETRIEVE_request, /* <- RN */
126 SSCOP_RETRIEVE_indication, /* -> MU */
127 SSCOP_RETRIEVE_COMPL_indication,/* -> */
128};
129.Ed
130.Pp
103is one of the signals defined in the standard:
104.Bd -literal
105enum sscop_aasig {
106 SSCOP_ESTABLISH_request, /* <- UU, BR */
107 SSCOP_ESTABLISH_indication, /* -> UU */
108 SSCOP_ESTABLISH_response, /* <- UU, BR */
109 SSCOP_ESTABLISH_confirm, /* -> UU */
110

--- 16 unchanged lines hidden (view full) ---

127 SSCOP_RESYNC_confirm, /* -> */
128
129 SSCOP_RETRIEVE_request, /* <- RN */
130 SSCOP_RETRIEVE_indication, /* -> MU */
131 SSCOP_RETRIEVE_COMPL_indication,/* -> */
132};
133.Ed
134.Pp
131The arrows in the comment show the direction of the signal whether it
135The arrows in the comment show the direction of the signal, whether it
132is a signal that comes out of the node
136is a signal that comes out of the node
133.Ql ->
137.Pq Ql -> ,
134or is sent by the node user to the node
138or is sent by the node user to the node
135.Ql <- .
139.Pq Ql <- .
136The
140The
137.Fa arg
141.Va arg
138field contains the argument to some of the signals: it is either a PDU
142field contains the argument to some of the signals: it is either a PDU
139sequence number or the
143sequence number, or the
140.Dv CLEAR-BUFFER
141flag.
142There are a number of special sequence numbers for some operations:
144.Dv CLEAR-BUFFER
145flag.
146There are a number of special sequence numbers for some operations:
143.Bl -column SSCOP_RETRIEVE_UNKNOWN -offset indent
144.It Dv SSCOP_MAXSEQNO Ta maximum legal sequence number
145.It Dv SSCOP_RETRIEVE_UNKNOWN Ta retrieve transmission queue
146.It Dv SSCOP_RETRIEVE_TOTAL Ta retrieve transmission buffer and queue
147.Pp
148.Bl -tag -width ".Dv SSCOP_RETRIEVE_UNKNOWN" -offset indent -compact
149.It Dv SSCOP_MAXSEQNO
150maximum legal sequence number
151.It Dv SSCOP_RETRIEVE_UNKNOWN
152retrieve transmission queue
153.It Dv SSCOP_RETRIEVE_TOTAL
154retrieve transmission buffer and queue
147.El
148.Pp
149For signals that carry user data (as, for example,
150.Dv SSCOP_DATA_request )
151these two fields are followed by the variable sized user data.
152.Pp
155.El
156.Pp
157For signals that carry user data (as, for example,
158.Dv SSCOP_DATA_request )
159these two fields are followed by the variable sized user data.
160.Pp
153If the upper hook is disconnected and the SSCOP instance is not in the idle
154state and the lower hook is still connected, an
161If the
162.Va upper
163hook is disconnected and the SSCOP instance is not in the idle
164state, and the
165.Va lower
166hook is still connected, an
155.Dv SSCOP_RELEASE_request
156is executed to release the SSCOP connection.
167.Dv SSCOP_RELEASE_request
168is executed to release the SSCOP connection.
157.It Dv manage
169.It Va manage
158This is the management interface defined in the standard.
159The data structure used here is:
160.Bd -literal
161struct sscop_marg {
162 uint32_t sig;
163 u_char data[];
164};
165.Ed
166.Pp
167Here
170This is the management interface defined in the standard.
171The data structure used here is:
172.Bd -literal
173struct sscop_marg {
174 uint32_t sig;
175 u_char data[];
176};
177.Ed
178.Pp
179Here
168.Dv sig
180.Va sig
169is one of
170.Bd -literal
171enum sscop_maasig {
172 SSCOP_MDATA_request, /* <- MU */
173 SSCOP_MDATA_indication, /* -> MU */
174 SSCOP_MERROR_indication, /* -> CODE, CNT */
175};
176.Ed

--- 5 unchanged lines hidden (view full) ---

182signal has the form:
183.Bd -literal
184struct sscop_merr {
185 uint32_t sig;
186 uint32_t err; /* error code */
187 uint32_t cnt; /* error count */
188};
189.Ed
181is one of
182.Bd -literal
183enum sscop_maasig {
184 SSCOP_MDATA_request, /* <- MU */
185 SSCOP_MDATA_indication, /* -> MU */
186 SSCOP_MERROR_indication, /* -> CODE, CNT */
187};
188.Ed

--- 5 unchanged lines hidden (view full) ---

194signal has the form:
195.Bd -literal
196struct sscop_merr {
197 uint32_t sig;
198 uint32_t err; /* error code */
199 uint32_t cnt; /* error count */
200};
201.Ed
202.El
190.Sh CONTROL MESSAGES
191The
203.Sh CONTROL MESSAGES
204The
192.Nm
193node understands the generic messages plus the following:
194.Bl -tag -width xxx
205.Nm sscop
206node understands the generic control messages, plus the following:
207.Bl -tag -width indent
195.It Dv NGM_SSCOP_SETPARAM
208.It Dv NGM_SSCOP_SETPARAM
196Set operational parameters of the SSCOP instance and takes the
209Sets operational parameters of the SSCOP instance and takes the
197following structure:
198.Bd -literal
199struct ng_sscop_setparam {
200 uint32_t mask;
201 struct sscop_param param;
202};
203.Ed
204.Pp
205The sub-structure
210following structure:
211.Bd -literal
212struct ng_sscop_setparam {
213 uint32_t mask;
214 struct sscop_param param;
215};
216.Ed
217.Pp
218The sub-structure
206.Dv param
207contains the parameters to set and the
208.Dv mask
209field contains a bit mask, telling which of the parameters to set and which
219.Va param
220contains the parameters to set, and the
221.Va mask
222field contains a bit mask, telling which of the parameters to set, and which
210to ignore.
211If a bit is set, the corresponding parameter is set.
212The parameters are:
213.Bd -literal
214struct sscop_param {
215 uint32_t timer_cc; /* timer_cc in msec */
216 uint32_t timer_poll; /* timer_poll im msec */
217 uint32_t timer_keep_alive;/* timer_keep_alive in msec */

--- 5 unchanged lines hidden (view full) ---

223 uint32_t maxpd; /* max. vt(pd) before sending poll */
224 uint32_t maxstat; /* max. number of elements in stat list */
225 uint32_t mr; /* initial window */
226 uint32_t flags; /* flags */
227};
228.Ed
229.Pp
230The
223to ignore.
224If a bit is set, the corresponding parameter is set.
225The parameters are:
226.Bd -literal
227struct sscop_param {
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 */

--- 5 unchanged lines hidden (view full) ---

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 */
240};
241.Ed
242.Pp
243The
231.Dv flags
244.Va flags
232field contains the following flags influencing SSCOP operation:
245field contains the following flags influencing SSCOP operation:
233.Bl -column SSCOP_POLLREX -offset indent
234.It Dv SSCOP_ROBUST Ta enable atmf/97-0216 robustness enhancement
235.It Dv SSCOP_POLLREX Ta send POLL after each retransmission
246.Pp
247.Bl -tag -width ".Dv SSCOP_POLLREX" -offset indent -compact
248.It Dv SSCOP_ROBUST
249enable atmf/97-0216 robustness enhancement
250.It Dv SSCOP_POLLREX
251send POLL after each retransmission
236.El
237.Pp
238The bitmap has the following bits:
252.El
253.Pp
254The bitmap has the following bits:
239.Bl -column SSCOP_POLLREXx -offset indent
240.It Dv SSCOP_SET_TCC Ta set Dv timer_cc
241.It Dv SSCOP_SET_TPOLL Ta set Dv timer_poll
242.It Dv SSCOP_SET_TKA Ta set Dv timer_keep_alive
243.It Dv SSCOP_SET_TNR Ta set Dv timer_no_response
244.It Dv SSCOP_SET_TIDLE Ta set Dv timer_idle
245.It Dv SSCOP_SET_MAXK Ta set Dv maxk
246.It Dv SSCOP_SET_MAXJ Ta set Dv maxj
247.It Dv SSCOP_SET_MAXCC Ta set Dv maxcc
248.It Dv SSCOP_SET_MAXPD Ta set Dv maxpd
249.It Dv SSCOP_SET_MAXSTAT Ta set Dv maxstat
250.It Dv SSCOP_SET_MR Ta set the initial window
251.It Dv SSCOP_SET_ROBUST Ta set or clear Dv SSCOP_ROBUST
252.It Dv SSCOP_SET_POLLREX Ta set or clear Dv SSCOP_POLLREX
255.Pp
256.Bl -tag -width ".Dv SSCOP_SET_POLLREX" -offset indent -compact
257.It Dv SSCOP_SET_TCC
258set
259.Va timer_cc
260.It Dv SSCOP_SET_TPOLL
261set
262.Va timer_poll
263.It Dv SSCOP_SET_TKA
264set
265.Va timer_keep_alive
266.It Dv SSCOP_SET_TNR
267set
268.Va timer_no_response
269.It Dv SSCOP_SET_TIDLE
270set
271.Va timer_idle
272.It Dv SSCOP_SET_MAXK
273set
274.Va maxk
275.It Dv SSCOP_SET_MAXJ
276set
277.Va maxj
278.It Dv SSCOP_SET_MAXCC
279set
280.Va maxcc
281.It Dv SSCOP_SET_MAXPD
282set
283.Va maxpd
284.It Dv SSCOP_SET_MAXSTAT
285set
286.Va maxstat
287.It Dv SSCOP_SET_MR
288set the initial window
289.It Dv SSCOP_SET_ROBUST
290set or clear
291.Dv SSCOP_ROBUST
292.It Dv SSCOP_SET_POLLREX
293set or clear
294.Dv SSCOP_POLLREX
253.El
254.Pp
255The node responds to the
256.Dv NGM_SSCOP_SETPARAM
257message with the following response:
258.Bd -literal
259struct ng_sscop_setparam_resp {
260 uint32_t mask;
261 int32_t error;
262};
263.Ed
264.Pp
265Here
295.El
296.Pp
297The node responds to the
298.Dv NGM_SSCOP_SETPARAM
299message with the following response:
300.Bd -literal
301struct ng_sscop_setparam_resp {
302 uint32_t mask;
303 int32_t error;
304};
305.Ed
306.Pp
307Here
266.Dv mask
267contains the a bitmask of the parameters that the user requested to set,
308.Va mask
309contains a bitmask of the parameters that the user requested to set,
268but that could not be set and
310but that could not be set and
269.Dv error
311.Va error
270is an
271.Xr errno 3
272code describing why the parameter could not be set.
273.It Dv NGM_SSCOP_GETPARAM
274This message returns the current operational parameters of the SSCOP
275instance in a
312is an
313.Xr errno 3
314code describing why the parameter could not be set.
315.It Dv NGM_SSCOP_GETPARAM
316This message returns the current operational parameters of the SSCOP
317instance in a
276.Fa sscop_param
318.Vt sscop_param
277structure.
278.It Dv NGM_SSCOP_ENABLE
279This message creates the actual SSCOP instance and initializes it.
319structure.
320.It Dv NGM_SSCOP_ENABLE
321This message creates the actual SSCOP instance and initializes it.
280Until this is done, parameters may neither be retrieved not set and all
281message received on any hook are discarded.
322Until this is done, parameters may neither be retrieved nor set, and all
323messages received on any hook are discarded.
282.It Dv NGM_SSCOP_DISABLE
283Destroy the SSCOP instance.
324.It Dv NGM_SSCOP_DISABLE
325Destroy the SSCOP instance.
284After this all messages on any hooks are
326After this, all messages on any hooks are
285discarded.
286.It Dv NGM_SSCOP_SETDEBUG
287Set debugging flags.
327discarded.
328.It Dv NGM_SSCOP_SETDEBUG
329Set debugging flags.
288The argument is an
330The argument is a
289.Vt uint32_t .
290.It Dv NGM_SSCOP_GETDEBUG
291Retrieve the actual debugging flags.
331.Vt uint32_t .
332.It Dv NGM_SSCOP_GETDEBUG
333Retrieve the actual debugging flags.
292Needs no arguments and responds with an
334Needs no arguments and responds with a
293.Vt uint32_t .
294.It Dv NGM_SSCOP_GETSTATE
335.Vt uint32_t .
336.It Dv NGM_SSCOP_GETSTATE
295Responds with the current state of the SSCOP instance in an
337Responds with the current state of the SSCOP instance in a
296.Vt uint32_t .
338.Vt uint32_t .
297If the node is not enabled the retrieved state is 0.
339If the node is not enabled, the retrieved state is 0.
298.El
299.Sh FLOW CONTROL
300Flow control works on the upper and on the lower layer interface.
301At the lower
340.El
341.Sh FLOW CONTROL
342Flow control works on the upper and on the lower layer interface.
343At the lower
302layer interface the two messages
344layer interface, the two messages,
303.Dv NGM_HIGH_WATER_PASSED
304and
345.Dv NGM_HIGH_WATER_PASSED
346and
305.Dv NGM_LOW_WATER_PASSED
347.Dv NGM_LOW_WATER_PASSED ,
306are used to declare or clear the
348are used to declare or clear the
307.Ql lower layer busy
349.Dq "lower layer busy"
308state of the protocol.
309.Pp
350state of the protocol.
351.Pp
310At the upper layer interface the
311.Nm
352At the upper layer interface, the
353.Nm sscop
312node handles three types of flow control messages:
354node handles three types of flow control messages:
313.Bl -tag -width xxx
355.Bl -tag -width indent
314.It Dv NGM_HIGH_WATER_PASSED
356.It Dv NGM_HIGH_WATER_PASSED
315If this message is received the SSCOP stops moving the receive window.
316Each time a data message is handed over to the upper layer the receive
357If this message is received, the SSCOP stops moving the receive window.
358Each time a data message is handed over to the upper layer, the receive
317window is moved by one message.
318Stopping these updates
319means that the window will start to close and if the peer has sent
320all messages allowed by the current window, it stops transmission.
359window is moved by one message.
360Stopping these updates
361means that the window will start to close and if the peer has sent
362all messages allowed by the current window, it stops transmission.
321This means, that the upper layer must be able to receive still a full window
363This means that the upper layer must be able to still receive a full window
322amount of messages.
323.It Dv NGM_LOW_WATER_PASSED
364amount of messages.
365.It Dv NGM_LOW_WATER_PASSED
324This will re-enable the automatic window updates and if the space indicated
366This will re-enable the automatic window updates, and if the space indicated
325in the message is larger than the current window, the window will be opened
326by that amount.
327The space is computed as the difference of the
367in the message is larger than the current window, the window will be opened
368by that amount.
369The space is computed as the difference of the
328.Fa max_queuelen_packets
370.Va max_queuelen_packets
329and
371and
330.Fa current
372.Va current
331members of the
373members of the
332.Fa ngm_queue_state
374.Vt ngm_queue_state
333structure.
334.It Dv NGM_SYNC_QUEUE_STATE
375structure.
376.It Dv NGM_SYNC_QUEUE_STATE
335If the upper layer buffer filling state as indicated by
336.Fa current
337is equal too or higher than
338.Fa high_watermark
339than the message is ignored.
340If this is not the case the amount
377If the upper layer buffer filling state, as indicated by
378.Va current ,
379is equal to or greater than
380.Va high_watermark
381then the message is ignored.
382If this is not the case, the amount
341of receiver space is computed as the difference of
383of receiver space is computed as the difference of
342.Fa max_queuelen_packets
384.Va max_queuelen_packets
343and
385and
344.Fa current ,
345if automatic window updates are currently allowed and as the difference of
346.Fa high_water_mark
386.Va current
387if automatic window updates are currently allowed, and as the difference of
388.Va high_water_mark
347and
389and
348.Fa current ,
390.Va current
349if window updates are disabled.
350If the resulting value is larger than the current window, the current window
351is opened up to this value.
391if window updates are disabled.
392If the resulting value is larger than the current window, the current window
393is opened up to this value.
352Automatic window updates are enabled, if they
394Automatic window updates are enabled if they
353were disabled.
395were disabled.
396.El
354.Sh SEE ALSO
355.Xr netgraph 4 ,
356.Xr ng_atm 4 ,
357.Xr ng_sscfu 4 ,
358.Xr ngctl 8
359.Sh AUTHORS
397.Sh SEE ALSO
398.Xr netgraph 4 ,
399.Xr ng_atm 4 ,
400.Xr ng_sscfu 4 ,
401.Xr ngctl 8
402.Sh AUTHORS
360.An Harti Brandt Aq harti@freebsd.org
403.An Harti Brandt Aq harti@FreeBSD.org