share/man/man4/ng_sscop.4

   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:
   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.
  14 .\"
  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
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .\" ng_sscop(4) man page
  32 .\"
  33 .Dd March 3, 2023
  34 .Dt NG_SSCOP 4
  35 .Os
  36 .Sh NAME
  37 .Nm ng_sscop
  38 .Nd netgraph SSCOP node type
  39 .Sh SYNOPSIS
  40 .In netnatm/saal/sscopdef.h
  41 .In netgraph/atm/ng_sscop.h
  42 .Sh DEPRECATION NOTICE
  43 .Nm
  44 is deprecated and may not be available in
  45 .Fx 14.0
  46 and later.
  47 .Sh DESCRIPTION
  48 The
  49 .Nm sscop
  50 netgraph node type implements the ITU-T standard Q.2110.
  51 This standard describes
  52 the so called Service Specific Connection Oriented Protocol (SSCOP) that
  53 is used to carry signalling messages over the private and public UNIs and
  54 the public NNI.
  55 This protocol is a transport protocol with selective
  56 acknowledgements, and can be tailored to the environment.
  57 This implementation is a full implementation of that standard.
  58 .Pp
  59 After creation of the node, the SSCOP instance must be created by sending
  60 an
  61 .Dq enable
  62 message to the node.
  63 If the node is enabled, the SSCOP parameters
  64 can be retrieved and modified and the protocol can be started.
  65 .Pp
  66 The node is shut down either by a
  67 .Dv NGM_SHUTDOWN
  68 message, or when all hooks are disconnected.
  69 .Sh HOOKS
  70 Each
  71 .Nm sscop
  72 node has three hooks with fixed names:
  73 .Bl -tag -width ".Va manage"
  74 .It Va lower
  75 This hook must be connected to a node that ensures
  76 transport of packets to and from the remote peer node.
  77 Normally this is a
  78 .Xr ng_atm 4
  79 node with an AAL5 hook, but the
  80 .Nm sscop
  81 node is able to work on any packet-transporting layer, like, for example,
  82 IP or UDP.
  83 The node handles flow control messages received on
  84 this hook: if it receives a
  85 .Dv NGM_HIGH_WATER_PASSED
  86 message, it declares the
  87 .Dq "lower layer busy"
  88 state.
  89 If a
  90 .Dv NGM_LOW_WATER_PASSED
  91 message is received, the busy state is cleared.
  92 Note that the node does not
  93 look at the message contents of these flow control messages.
  94 .It Va upper
  95 This is the interface to the SSCOP user.
  96 This interface uses the following message format:
  97 .Bd -literal
  98 struct sscop_arg {
  99         uint32_t sig;
 100         uint32_t arg;   /* opt. sequence number or clear-buff */
 101         u_char   data[];
 102 };
 103 .Ed
 104 .Pp
 105 The
 106 .Va sig
 107 field
 108 is one of the signals defined in the standard:
 109 .Bd -literal
 110 enum sscop_aasig {
 111     SSCOP_ESTABLISH_request,    /* <- UU, BR */
 112     SSCOP_ESTABLISH_indication, /* -> UU */
 113     SSCOP_ESTABLISH_response,   /* <- UU, BR */
 114     SSCOP_ESTABLISH_confirm,    /* -> UU */
 115
 116     SSCOP_RELEASE_request,      /* <- UU */
 117     SSCOP_RELEASE_indication,   /* -> UU, SRC */
 118     SSCOP_RELEASE_confirm,      /* -> */
 119
 120     SSCOP_DATA_request,         /* <- MU */
 121     SSCOP_DATA_indication,      /* -> MU, SN */
 122
 123     SSCOP_UDATA_request,        /* <- MU */
 124     SSCOP_UDATA_indication,     /* -> MU */
 125
 126     SSCOP_RECOVER_indication,   /* -> */
 127     SSCOP_RECOVER_response,     /* <- */
 128
 129     SSCOP_RESYNC_request,       /* <- UU */
 130     SSCOP_RESYNC_indication,    /* -> UU */
 131     SSCOP_RESYNC_response,      /* <- */
 132     SSCOP_RESYNC_confirm,       /* -> */
 133
 134     SSCOP_RETRIEVE_request,     /* <- RN */
 135     SSCOP_RETRIEVE_indication,  /* -> MU */
 136     SSCOP_RETRIEVE_COMPL_indication,/* -> */
 137 };
 138 .Ed
 139 .Pp
 140 The arrows in the comment show the direction of the signal, whether it
 141 is a signal that comes out of the node
 142 .Pq Ql -> ,
 143 or is sent by the node user to the node
 144 .Pq Ql <- .
 145 The
 146 .Va arg
 147 field contains the argument to some of the signals: it is either a PDU
 148 sequence number, or the
 149 .Dv CLEAR-BUFFER
 150 flag.
 151 There are a number of special sequence numbers for some operations:
 152 .Pp
 153 .Bl -tag -width ".Dv SSCOP_RETRIEVE_UNKNOWN" -offset indent -compact
 154 .It Dv SSCOP_MAXSEQNO
 155 maximum legal sequence number
 156 .It Dv SSCOP_RETRIEVE_UNKNOWN
 157 retrieve transmission queue
 158 .It Dv SSCOP_RETRIEVE_TOTAL
 159 retrieve transmission buffer and queue
 160 .El
 161 .Pp
 162 For signals that carry user data (as, for example,
 163 .Dv SSCOP_DATA_request )
 164 these two fields are followed by the variable sized user data.
 165 .Pp
 166 If the
 167 .Va upper
 168 hook is disconnected and the SSCOP instance is not in the idle
 169 state, and the
 170 .Va lower
 171 hook is still connected, an
 172 .Dv SSCOP_RELEASE_request
 173 is executed to release the SSCOP connection.
 174 .It Va manage
 175 This is the management interface defined in the standard.
 176 The data structure used here is:
 177 .Bd -literal
 178 struct sscop_marg {
 179         uint32_t sig;
 180         u_char   data[];
 181 };
 182 .Ed
 183 .Pp
 184 Here
 185 .Va sig
 186 is one of
 187 .Bd -literal
 188 enum sscop_maasig {
 189     SSCOP_MDATA_request,        /* <- MU */
 190     SSCOP_MDATA_indication,     /* -> MU */
 191     SSCOP_MERROR_indication,    /* -> CODE, CNT */
 192 };
 193 .Ed
 194 .Pp
 195 The
 196 .Dv SSCOP_MDATA
 197 signals are followed by the actual management data, where the
 198 .Dv SSCOP_MERROR
 199 signal has the form:
 200 .Bd -literal
 201 struct sscop_merr {
 202         uint32_t sig;
 203         uint32_t err;   /* error code */
 204         uint32_t cnt;   /* error count */
 205 };
 206 .Ed
 207 .El
 208 .Sh CONTROL MESSAGES
 209 The
 210 .Nm sscop
 211 node understands the generic control messages, plus the following:
 212 .Bl -tag -width foo
 213 .It Dv NGM_SSCOP_SETPARAM Pq Ic setparam
 214 Sets operational parameters of the SSCOP instance and takes the
 215 following structure:
 216 .Bd -literal
 217 struct ng_sscop_setparam {
 218         uint32_t                mask;
 219         struct sscop_param      param;
 220 };
 221 .Ed
 222 .Pp
 223 The sub-structure
 224 .Va param
 225 contains the parameters to set, and the
 226 .Va mask
 227 field contains a bit mask, telling which of the parameters to set, and which
 228 to ignore.
 229 If a bit is set, the corresponding parameter is set.
 230 The parameters are:
 231 .Bd -literal
 232 struct sscop_param {
 233         uint32_t timer_cc;      /* timer_cc in msec */
 234         uint32_t timer_poll;    /* timer_poll im msec */
 235         uint32_t timer_keep_alive;/* timer_keep_alive in msec */
 236         uint32_t timer_no_response;/*timer_no_response in msec */
 237         uint32_t timer_idle;    /* timer_idle in msec */
 238         uint32_t maxk;          /* maximum user data in bytes */
 239         uint32_t maxj;          /* maximum u-u info in bytes */
 240         uint32_t maxcc;         /* max. retransmissions for control packets */
 241         uint32_t maxpd;         /* max. vt(pd) before sending poll */
 242         uint32_t maxstat;       /* max. number of elements in stat list */
 243         uint32_t mr;            /* initial window */
 244         uint32_t flags;         /* flags */
 245 };
 246 .Ed
 247 .Pp
 248 The
 249 .Va flags
 250 field contains the following flags influencing SSCOP operation:
 251 .Pp
 252 .Bl -tag -width ".Dv SSCOP_POLLREX" -offset indent -compact
 253 .It Dv SSCOP_ROBUST
 254 enable atmf/97-0216 robustness enhancement
 255 .It Dv SSCOP_POLLREX
 256 send POLL after each retransmission
 257 .El
 258 .Pp
 259 The bitmap has the following bits:
 260 .Pp
 261 .Bl -tag -width ".Dv SSCOP_SET_POLLREX" -offset indent -compact
 262 .It Dv SSCOP_SET_TCC
 263 set
 264 .Va timer_cc
 265 .It Dv SSCOP_SET_TPOLL
 266 set
 267 .Va timer_poll
 268 .It Dv SSCOP_SET_TKA
 269 set
 270 .Va timer_keep_alive
 271 .It Dv SSCOP_SET_TNR
 272 set
 273 .Va timer_no_response
 274 .It Dv SSCOP_SET_TIDLE
 275 set
 276 .Va timer_idle
 277 .It Dv SSCOP_SET_MAXK
 278 set
 279 .Va maxk
 280 .It Dv SSCOP_SET_MAXJ
 281 set
 282 .Va maxj
 283 .It Dv SSCOP_SET_MAXCC
 284 set
 285 .Va maxcc
 286 .It Dv SSCOP_SET_MAXPD
 287 set
 288 .Va maxpd
 289 .It Dv SSCOP_SET_MAXSTAT
 290 set
 291 .Va maxstat
 292 .It Dv SSCOP_SET_MR
 293 set the initial window
 294 .It Dv SSCOP_SET_ROBUST
 295 set or clear
 296 .Dv SSCOP_ROBUST
 297 .It Dv SSCOP_SET_POLLREX
 298 set or clear
 299 .Dv SSCOP_POLLREX
 300 .El
 301 .Pp
 302 The node responds to the
 303 .Dv NGM_SSCOP_SETPARAM
 304 message with the following response:
 305 .Bd -literal
 306 struct ng_sscop_setparam_resp {
 307         uint32_t mask;
 308         int32_t  error;
 309 };
 310 .Ed
 311 .Pp
 312 Here
 313 .Va mask
 314 contains a bitmask of the parameters that the user requested to set,
 315 but that could not be set and
 316 .Va error
 317 is an
 318 .Xr errno 2
 319 code describing why the parameter could not be set.
 320 .It Dv NGM_SSCOP_GETPARAM Pq Ic getparam
 321 This message returns the current operational parameters of the SSCOP
 322 instance in a
 323 .Vt sscop_param
 324 structure.
 325 .It Dv NGM_SSCOP_ENABLE Pq Ic enable
 326 This message creates the actual SSCOP instance and initializes it.
 327 Until this is done, parameters may neither be retrieved nor set, and all
 328 messages received on any hook are discarded.
 329 .It Dv NGM_SSCOP_DISABLE Pq Ic disable
 330 Destroy the SSCOP instance.
 331 After this, all messages on any hooks are
 332 discarded.
 333 .It Dv NGM_SSCOP_SETDEBUG Pq Ic setdebug
 334 Set debugging flags.
 335 The argument is a
 336 .Vt uint32_t .
 337 .It Dv NGM_SSCOP_GETDEBUG Pq Ic getdebug
 338 Retrieve the actual debugging flags.
 339 Needs no arguments and responds with a
 340 .Vt uint32_t .
 341 .It Dv NGM_SSCOP_GETSTATE Pq Ic getstate
 342 Responds with the current state of the SSCOP instance in a
 343 .Vt uint32_t .
 344 If the node is not enabled, the retrieved state is 0.
 345 .El
 346 .Sh FLOW CONTROL
 347 Flow control works on the upper and on the lower layer interface.
 348 At the lower
 349 layer interface, the two messages,
 350 .Dv NGM_HIGH_WATER_PASSED
 351 and
 352 .Dv NGM_LOW_WATER_PASSED ,
 353 are used to declare or clear the
 354 .Dq "lower layer busy"
 355 state of the protocol.
 356 .Pp
 357 At the upper layer interface, the
 358 .Nm sscop
 359 node handles three types of flow control messages:
 360 .Bl -tag -width foo
 361 .It Dv NGM_HIGH_WATER_PASSED
 362 If this message is received, the SSCOP stops moving the receive window.
 363 Each time a data message is handed over to the upper layer, the receive
 364 window is moved by one message.
 365 Stopping these updates
 366 means that the window will start to close and if the peer has sent
 367 all messages allowed by the current window, it stops transmission.
 368 This means that the upper layer must be able to still receive a full window
 369 amount of messages.
 370 .It Dv NGM_LOW_WATER_PASSED
 371 This will re-enable the automatic window updates, and if the space indicated
 372 in the message is larger than the current window, the window will be opened
 373 by that amount.
 374 The space is computed as the difference of the
 375 .Va max_queuelen_packets
 376 and
 377 .Va current
 378 members of the
 379 .Vt ngm_queue_state
 380 structure.
 381 .It Dv NGM_SYNC_QUEUE_STATE
 382 If the upper layer buffer filling state, as indicated by
 383 .Va current ,
 384 is equal to or greater than
 385 .Va high_watermark
 386 then the message is ignored.
 387 If this is not the case, the amount
 388 of receiver space is computed as the difference of
 389 .Va max_queuelen_packets
 390 and
 391 .Va current
 392 if automatic window updates are currently allowed, and as the difference of
 393 .Va high_water_mark
 394 and
 395 .Va current
 396 if window updates are disabled.
 397 If the resulting value is larger than the current window, the current window
 398 is opened up to this value.
 399 Automatic window updates are enabled if they
 400 were disabled.
 401 .El
 402 .Sh SEE ALSO
 403 .Xr netgraph 4 ,
 404 .Xr ng_atm 4 ,
 405 .Xr ng_sscfu 4 ,
 406 .Xr ngctl 8
 407 .Sh AUTHORS
 408 .An Harti Brandt Aq Mt harti@FreeBSD.org