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 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 .In netnatm/saal/sscopdef.h
  41 .In netgraph/atm/ng_sscop.h
  42 .Sh DESCRIPTION
  43 The
  44 .Nm sscop
  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
  49 the public NNI.
  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.
  53 .Pp
  54 After creation of the node, the SSCOP instance must be created by sending
  55 an
  56 .Dq enable
  57 message to the node.
  58 If the node is enabled, the SSCOP parameters
  59 can be retrieved and modified and the protocol can be started.
  60 .Pp
  61 The node is shut down either by a
  62 .Dv NGM_SHUTDOWN
  63 message, or when all hooks are disconnected.
  64 .Sh HOOKS
  65 Each
  66 .Nm sscop
  67 node has three hooks with fixed names:
  68 .Bl -tag -width ".Va manage"
  69 .It Va lower
  70 This hook must be connected to a node that ensures
  71 transport of packets to and from the remote peer node.
  72 Normally this is a
  73 .Xr ng_atm 4
  74 node with an AAL5 hook, but the
  75 .Nm sscop
  76 node is able to work on any packet-transporting layer, like, for example,
  77 IP or UDP.
  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"
  83 state.
  84 If a
  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.
  89 .It Va upper
  90 This is the interface to the SSCOP user.
  91 This interface uses the following message format:
  92 .Bd -literal
  93 struct 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
 100 The
 101 .Va sig
 102 field
 103 is one of the signals defined in the standard:
 104 .Bd -literal
 105 enum 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
 111     SSCOP_RELEASE_request,      /* <- UU */
 112     SSCOP_RELEASE_indication,   /* -> UU, SRC */
 113     SSCOP_RELEASE_confirm,      /* -> */
 114
 115     SSCOP_DATA_request,         /* <- MU */
 116     SSCOP_DATA_indication,      /* -> MU, SN */
 117
 118     SSCOP_UDATA_request,        /* <- MU */
 119     SSCOP_UDATA_indication,     /* -> MU */
 120
 121     SSCOP_RECOVER_indication,   /* -> */
 122     SSCOP_RECOVER_response,     /* <- */
 123
 124     SSCOP_RESYNC_request,       /* <- UU */
 125     SSCOP_RESYNC_indication,    /* -> UU */
 126     SSCOP_RESYNC_response,      /* <- */
 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
 135 The arrows in the comment show the direction of the signal, whether it
 136 is a signal that comes out of the node
 137 .Pq Ql -> ,
 138 or is sent by the node user to the node
 139 .Pq Ql <- .
 140 The
 141 .Va arg
 142 field contains the argument to some of the signals: it is either a PDU
 143 sequence number, or the
 144 .Dv CLEAR-BUFFER
 145 flag.
 146 There are a number of special sequence numbers for some operations:
 147 .Pp
 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
 155 .El
 156 .Pp
 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.
 160 .Pp
 161 If the
 162 .Va upper
 163 hook is disconnected and the SSCOP instance is not in the idle
 164 state, and the
 165 .Va lower
 166 hook is still connected, an
 167 .Dv SSCOP_RELEASE_request
 168 is executed to release the SSCOP connection.
 169 .It Va manage
 170 This is the management interface defined in the standard.
 171 The data structure used here is:
 172 .Bd -literal
 173 struct sscop_marg {
 174         uint32_t sig;
 175         u_char   data[];
 176 };
 177 .Ed
 178 .Pp
 179 Here
 180 .Va sig
 181 is one of
 182 .Bd -literal
 183 enum sscop_maasig {
 184     SSCOP_MDATA_request,        /* <- MU */
 185     SSCOP_MDATA_indication,     /* -> MU */
 186     SSCOP_MERROR_indication,    /* -> CODE, CNT */
 187 };
 188 .Ed
 189 .Pp
 190 The
 191 .Dv SSCOP_MDATA
 192 signals are followed by the actual management data, where the
 193 .Dv SSCOP_MERROR
 194 signal has the form:
 195 .Bd -literal
 196 struct sscop_merr {
 197         uint32_t sig;
 198         uint32_t err;   /* error code */
 199         uint32_t cnt;   /* error count */
 200 };
 201 .Ed
 202 .El
 203 .Sh CONTROL MESSAGES
 204 The
 205 .Nm sscop
 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
 210 following structure:
 211 .Bd -literal
 212 struct ng_sscop_setparam {
 213         uint32_t                mask;
 214         struct sscop_param      param;
 215 };
 216 .Ed
 217 .Pp
 218 The sub-structure
 219 .Va param
 220 contains the parameters to set, and the
 221 .Va mask
 222 field contains a bit mask, telling which of the parameters to set, and which
 223 to ignore.
 224 If a bit is set, the corresponding parameter is set.
 225 The parameters are:
 226 .Bd -literal
 227 struct 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 */
 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 */
 240 };
 241 .Ed
 242 .Pp
 243 The
 244 .Va flags
 245 field contains the following flags influencing SSCOP operation:
 246 .Pp
 247 .Bl -tag -width ".Dv SSCOP_POLLREX" -offset indent -compact
 248 .It Dv SSCOP_ROBUST
 249 enable atmf/97-0216 robustness enhancement
 250 .It Dv SSCOP_POLLREX
 251 send POLL after each retransmission
 252 .El
 253 .Pp
 254 The bitmap has the following bits:
 255 .Pp
 256 .Bl -tag -width ".Dv SSCOP_SET_POLLREX" -offset indent -compact
 257 .It Dv SSCOP_SET_TCC
 258 set
 259 .Va timer_cc
 260 .It Dv SSCOP_SET_TPOLL
 261 set
 262 .Va timer_poll
 263 .It Dv SSCOP_SET_TKA
 264 set
 265 .Va timer_keep_alive
 266 .It Dv SSCOP_SET_TNR
 267 set
 268 .Va timer_no_response
 269 .It Dv SSCOP_SET_TIDLE
 270 set
 271 .Va timer_idle
 272 .It Dv SSCOP_SET_MAXK
 273 set
 274 .Va maxk
 275 .It Dv SSCOP_SET_MAXJ
 276 set
 277 .Va maxj
 278 .It Dv SSCOP_SET_MAXCC
 279 set
 280 .Va maxcc
 281 .It Dv SSCOP_SET_MAXPD
 282 set
 283 .Va maxpd
 284 .It Dv SSCOP_SET_MAXSTAT
 285 set
 286 .Va maxstat
 287 .It Dv SSCOP_SET_MR
 288 set the initial window
 289 .It Dv SSCOP_SET_ROBUST
 290 set or clear
 291 .Dv SSCOP_ROBUST
 292 .It Dv SSCOP_SET_POLLREX
 293 set or clear
 294 .Dv SSCOP_POLLREX
 295 .El
 296 .Pp
 297 The node responds to the
 298 .Dv NGM_SSCOP_SETPARAM
 299 message with the following response:
 300 .Bd -literal
 301 struct ng_sscop_setparam_resp {
 302         uint32_t mask;
 303         int32_t  error;
 304 };
 305 .Ed
 306 .Pp
 307 Here
 308 .Va mask
 309 contains a bitmask of the parameters that the user requested to set,
 310 but that could not be set and
 311 .Va error
 312 is an
 313 .Xr errno 2
 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
 317 instance in a
 318 .Vt sscop_param
 319 structure.
 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
 327 discarded.
 328 .It Dv NGM_SSCOP_SETDEBUG
 329 Set debugging flags.
 330 The argument is a
 331 .Vt uint32_t .
 332 .It Dv NGM_SSCOP_GETDEBUG
 333 Retrieve the actual debugging flags.
 334 Needs no arguments and responds with a
 335 .Vt uint32_t .
 336 .It Dv NGM_SSCOP_GETSTATE
 337 Responds with the current state of the SSCOP instance in a
 338 .Vt uint32_t .
 339 If the node is not enabled, the retrieved state is 0.
 340 .El
 341 .Sh FLOW CONTROL
 342 Flow control works on the upper and on the lower layer interface.
 343 At the lower
 344 layer interface, the two messages,
 345 .Dv NGM_HIGH_WATER_PASSED
 346 and
 347 .Dv NGM_LOW_WATER_PASSED ,
 348 are used to declare or clear the
 349 .Dq "lower layer busy"
 350 state of the protocol.
 351 .Pp
 352 At the upper layer interface, the
 353 .Nm sscop
 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
 364 amount of messages.
 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
 368 by that amount.
 369 The space is computed as the difference of the
 370 .Va max_queuelen_packets
 371 and
 372 .Va current
 373 members of the
 374 .Vt ngm_queue_state
 375 structure.
 376 .It Dv NGM_SYNC_QUEUE_STATE
 377 If the upper layer buffer filling state, as indicated by
 378 .Va current ,
 379 is equal to or greater than
 380 .Va high_watermark
 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
 385 and
 386 .Va current
 387 if automatic window updates are currently allowed, and as the difference of
 388 .Va high_water_mark
 389 and
 390 .Va current
 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
 395 were disabled.
 396 .El
 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
 403 .An Harti Brandt Aq harti@FreeBSD.org