share/man/man4/ng_uni.4

   1 .\"
   2 .\" Copyright (c) 2001-2003
   3 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   4 .\"     All rights reserved.
   5 .\"
   6 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd October 6, 2003
  32 .Dt NG_UNI 4
  33 .Os
  34 .Sh NAME
  35 .Nm ng_uni
  36 .Nd netgraph UNI node type
  37 .Sh SYNOPSIS
  38 .In netnatm/msg/unistruct.h
  39 .In netnatm/sig/unidef.h
  40 .In netgraph/atm/ng_uni.h
  41 .Sh DESCRIPTION
  42 The
  43 .Nm uni
  44 netgraph node type implements ATM Forum signalling 4.0.
  45 .Pp
  46 After creation of the node, the UNI instance must be created by sending
  47 an
  48 .Dq enable
  49 message to the node.
  50 If the node is enabled, the UNI parameters
  51 can be retrieved and modified, and the protocol can be started.
  52 .Pp
  53 The node is shut down either by an
  54 .Dv NGM_SHUTDOWN
  55 message, or when all hooks are disconnected.
  56 .Sh HOOKS
  57 Each
  58 .Nm uni
  59 node has three hooks with fixed names:
  60 .Bl -tag -width ".Va upper"
  61 .It Va lower
  62 This hook is the interface of the UNI protocol to the transport layer of
  63 the ATM control plane.
  64 The node expects the interface exported by
  65 .Xr ng_sscfu 4
  66 at this hook.
  67 .It Va upper
  68 This hook is the
  69 .Dq user
  70 interface of the UNI protocol.
  71 Because there is no standardized interface
  72 at this point, this implementation follows more or less the interface
  73 specified by the SDL diagrams in ITU-T recommendations Q.2931 and Q.2971.
  74 Normally either a
  75 .Xr ng_ccatm 4
  76 or a switch CAC should be stacked at this interface.
  77 The message format at the
  78 .Va upper
  79 hook is described below.
  80 Because
  81 .Xr netgraph 4
  82 is functional, it makes sometimes sense to switch this hook to queueing mode
  83 from the peer node upon connection.
  84 .El
  85 .Pp
  86 The
  87 .Va upper
  88 interface of the
  89 .Nm uni
  90 node is loosely modelled after the interface specified in the ITU-T signalling
  91 standards.
  92 There is however one derivation from this: normally there exists
  93 four kinds of signals: requests, responses, indications and confirmations.
  94 These signals are usually triggered either by external events (receiving a
  95 message) or internal events (a timer or another signal).
  96 This scheme works
  97 fine for user APIs that are entirely asynchronous, and in cases where
  98 error handling is not taken into account.
  99 With synchronous APIs and error
 100 handling however, there is a problem.
 101 If, for example, the application
 102 issues a request to set up a connection,
 103 it may do it by sending a
 104 .Dv SETUP.request
 105 signal to the UNI.
 106 Normally, the UNI stack will send a SETUP message and
 107 receive a message from the switch (a RELEASE, CONNECT, CALL PROCEEDING or
 108 ALERTING), or a timer in the UNI stack will time out.
 109 In any of these cases,
 110 the UNI stack is supposed to report an event back to the application, and
 111 the application will unblock (in the case of a synchronous API) and handle
 112 the event.
 113 The problem occurs when an error happens.
 114 Suppose there is no
 115 memory to send the SETUP message and to start the timer.
 116 In this case, the
 117 application will block forever because no received message and no timer
 118 will wake it up.
 119 For this reason this implementation uses an additional message:
 120 for each signal sent from the application to the stack, the stack will
 121 respond with an error code.
 122 If this code is zero, the stack has accepted
 123 the signal and the application may block; if the code is non-zero, the signal
 124 is effectively ignored and the code describes what was wrong.
 125 This system
 126 makes it very easy to make a blocking interface out of the message based
 127 netgraph interface.
 128 .Pp
 129 The
 130 .Va upper
 131 interface uses the following structure:
 132 .Bd -literal
 133 struct uni_arg {
 134         uint32_t        sig;
 135         uint32_t        cookie;
 136         u_char          data[];
 137 };
 138 .Ed
 139 The
 140 .Va sig
 141 field contains the actual signal that is sent from the user to UNI or from
 142 UNI to the user.
 143 The
 144 .Va cookie
 145 can be used by the user to correlate requests with events and responses.
 146 If an error response, a confirmation or an indication was triggered by
 147 a request or response, the cookie from that request or response is carried in
 148 the message from the stack to the user.
 149 The
 150 .Va cookie
 151 field is followed by the actual data for the signal.
 152 .Pp
 153 The signal is one of the following:
 154 .Bd -literal
 155 enum uni_sig {
 156     UNIAPI_ERROR,                       /* UNI -> API */
 157
 158     UNIAPI_CALL_CREATED,                /* UNI -> API */
 159     UNIAPI_CALL_DESTROYED,              /* UNI -> API */
 160     UNIAPI_PARTY_CREATED,               /* UNI -> API */
 161     UNIAPI_PARTY_DESTROYED,             /* UNI -> API */
 162
 163     UNIAPI_LINK_ESTABLISH_request,      /* API -> UNI */
 164     UNIAPI_LINK_ESTABLISH_confirm,      /* UNI -> API */
 165     UNIAPI_LINK_RELEASE_request,        /* API -> UNI */
 166     UNIAPI_LINK_RELEASE_confirm,        /* UNI -> API */
 167
 168     UNIAPI_RESET_request,               /* API -> UNI */
 169     UNIAPI_RESET_confirm,               /* UNI -> API */
 170     UNIAPI_RESET_indication,            /* UNI -> API */
 171     UNIAPI_RESET_ERROR_indication,      /* UNI -> API */
 172     UNIAPI_RESET_response,              /* API -> UNI */
 173     UNIAPI_RESET_ERROR_response,        /* API -> UNI */
 174     UNIAPI_RESET_STATUS_indication,     /* UNI -> API */
 175
 176     UNIAPI_SETUP_request,               /* API -> UNI */
 177     UNIAPI_SETUP_indication,            /* UNI -> API */
 178     UNIAPI_SETUP_response,              /* API -> UNI */
 179     UNIAPI_SETUP_confirm,               /* UNI -> API */
 180     UNIAPI_SETUP_COMPLETE_indication,   /* UNI -> API */
 181     UNIAPI_ALERTING_request,            /* API -> UNI */
 182     UNIAPI_ALERTING_indication,         /* UNI -> API */
 183     UNIAPI_PROCEEDING_request,          /* API -> UNI */
 184     UNIAPI_PROCEEDING_indication,       /* UNI -> API */
 185     UNIAPI_RELEASE_request,             /* API -> UNI */
 186     UNIAPI_RELEASE_indication,          /* UNI -> API */
 187     UNIAPI_RELEASE_response,            /* API -> UNI */
 188     UNIAPI_RELEASE_confirm,             /* UNI -> API */
 189     UNIAPI_NOTIFY_request,              /* API -> UNI */
 190     UNIAPI_NOTIFY_indication,           /* UNI -> API */
 191     UNIAPI_STATUS_indication,           /* UNI -> API */
 192     UNIAPI_STATUS_ENQUIRY_request,      /* API -> UNI */
 193
 194     UNIAPI_ADD_PARTY_request,           /* API -> UNI */
 195     UNIAPI_ADD_PARTY_indication,        /* UNI -> API */
 196     UNIAPI_PARTY_ALERTING_request,      /* API -> UNI */
 197     UNIAPI_PARTY_ALERTING_indication,   /* UNI -> API */
 198     UNIAPI_ADD_PARTY_ACK_request,       /* API -> UNI */
 199     UNIAPI_ADD_PARTY_ACK_indication,    /* UNI -> API */
 200     UNIAPI_ADD_PARTY_REJ_request,       /* API -> UNI */
 201     UNIAPI_ADD_PARTY_REJ_indication,    /* UNI -> API */
 202     UNIAPI_DROP_PARTY_request,          /* API -> UNI */
 203     UNIAPI_DROP_PARTY_indication,       /* UNI -> API */
 204     UNIAPI_DROP_PARTY_ACK_request,      /* API -> UNI */
 205     UNIAPI_DROP_PARTY_ACK_indication,   /* UNI -> API */
 206
 207     UNIAPI_ABORT_CALL_request,          /* API -> UNI */
 208
 209     UNIAPI_MAXSIG
 210 };
 211 .Ed
 212 .Pp
 213 The meaning of most of the signals can be deduced from the ITU-T SDLs.
 214 A number of signals, however, is unique to this implementation:
 215 .Bl -tag -width foo
 216 .It Dv UNIAPI_ERROR
 217 This is the error response, mentioned earlier.
 218 It carries an error code or
 219 zero, if the signal was accepted by the stack.
 220 .It Dv UNIAPI_CALL_CREATED
 221 The UNI stack has created a call instance either from an incoming SETUP or
 222 from the user requesting an outgoing SETUP.
 223 This may be used to synchronize
 224 the creation and destroying of call data between the UNI stack and the user.
 225 .It Dv UNIAPI_CALL_DESTROYED
 226 A call instance has been destroyed and all resources have been freed.
 227 .It Dv UNIAPI_PARTY_CREATED
 228 A new party has been created for an existing point-to-multipoint call.
 229 This may be used to synchronize the creation and destroying of party data
 230 between the UNI stack and the user.
 231 .It Dv UNIAPI_PARTY_DESTROYED
 232 A party has been destroyed and all resources have been freed.
 233 .It Dv UNIAPI_ABORT_CALL_request
 234 This requests the stack to destroy the call instance
 235 and free all its resources,
 236 without sending any messages to the network.
 237 .It Dv UNIAPI_MAXSIG
 238 This is not a signal, but rather a definition to get the number of defined
 239 signals.
 240 .El
 241 .Pp
 242 Each of the signals is followed by a fixed size structure defined in
 243 .In netnatm/sig/unidef.h .
 244 .Sh CONTROL MESSAGES
 245 The
 246 .Nm uni
 247 node understands the standard control messages, plus the following:
 248 .Bl -tag -width foo
 249 .It Dv NGM_UNI_SETDEBUG Pq Ic setdebug
 250 Set debugging facility levels.
 251 The UNI stack defines a number of debugging
 252 facilities, each one associated with a debugging level.
 253 If the debugging level
 254 of a facility is non-zero, text output will be generated to the console.
 255 The message uses the following structure:
 256 .Bd -literal
 257 struct ngm_uni_debug {
 258         uint32_t        level[UNI_MAXFACILITY];
 259 };
 260 .Ed
 261 .It Dv NGM_UNI_GETDEBUG Pq Ic getdebug
 262 Get debugging facility levels.
 263 This returns an
 264 .Vt ngm_uni_debug
 265 structure.
 266 .It Dv NGM_UNI_GET_CONFIG Pq Ic get_config
 267 Retrieve the current configuration of the UNI instance.
 268 This message returns a
 269 .Vt uni_config
 270 structure:
 271 .Bd -literal
 272 struct uni_config {
 273         uint32_t proto;         /* which protocol */
 274         uint32_t popt;          /* protocol option */
 275         uint32_t option;        /* other options */
 276         uint32_t timer301;      /* T301 */
 277         uint32_t timer303;      /* T303 */
 278         uint32_t init303;       /* T303 retransmission count */
 279         uint32_t timer308;      /* T308 */
 280         uint32_t init308;       /* T308 retransmission count */
 281         uint32_t timer309;      /* T309 */
 282         uint32_t timer310;      /* T310 */
 283         uint32_t timer313;      /* T313 */
 284         uint32_t timer316;      /* T316 */
 285         uint32_t init316;       /* T316 retransmission count */
 286         uint32_t timer317;      /* T317 */
 287         uint32_t timer322;      /* T322 */
 288         uint32_t init322;       /* T322 retransmission count */
 289         uint32_t timer397;      /* T397 */
 290         uint32_t timer398;      /* T398 */
 291         uint32_t timer399;      /* T399 */
 292 };
 293 .Ed
 294 .Pp
 295 The field
 296 .Va proto
 297 specifies one of the following protocols:
 298 .Bd -literal
 299 enum uni_proto {
 300         UNIPROTO_UNI40U,        /* UNI4.0 user side */
 301         UNIPROTO_UNI40N,        /* UNI4.0 network side */
 302         UNIPROTO_PNNI10,        /* PNNI1.0 */
 303 };
 304 .Ed
 305 .Pp
 306 Some protocols may have options which can be set in
 307 .Va popt :
 308 .Bd -literal
 309 enum uni_popt {
 310         UNIPROTO_GFP,           /* enable GFP */
 311 };
 312 .Ed
 313 .Pp
 314 The
 315 .Va option
 316 field controls parsing and checking of messages:
 317 .Bd -literal
 318 enum uni_option {
 319         UNIOPT_GIT_HARD,        /* harder check of GIT IE */
 320         UNIOPT_BEARER_HARD,     /* harder check of BEARER IE */
 321         UNIOPT_CAUSE_HARD,      /* harder check of CAUSE IE */
 322 };
 323 .Ed
 324 .Pp
 325 All timer values are given in milliseconds.
 326 Note, however, that the actual
 327 resolution of the timers depend on system configuration (see
 328 .Xr timeout 9 ) .
 329 .It Dv NGM_UNI_SET_CONFIG Pq Ic set_config
 330 Change the UNI configuration.
 331 This takes a
 332 .Bd -literal
 333 struct ngm_uni_set_config {
 334         struct uni_config               config;
 335         struct ngm_uni_config_mask      mask;
 336 };
 337 struct ngm_uni_config_mask {
 338         uint32_t        mask;
 339         uint32_t        popt_mask;
 340         uint32_t        option_mask;
 341 };
 342 .Ed
 343 .Pp
 344 The fields of the
 345 .Vt ngm_uni_config_mask
 346 specify which configuration parameter to change.
 347 The
 348 .Va mask
 349 field contains bit definitions for all timers, retransmission counters
 350 and the
 351 .Va proto
 352 field,
 353 .Va popt_mask
 354 selects which of the protocol options to change, and
 355 .Va option_mask
 356 specifies which options should be changed.
 357 The following bits are defined:
 358 .Bd -literal
 359 enum uni_config_mask {
 360         UNICFG_PROTO,
 361         UNICFG_TIMER301,
 362         UNICFG_TIMER303,
 363         UNICFG_INIT303,
 364         UNICFG_TIMER308,
 365         UNICFG_INIT308,
 366         UNICFG_TIMER309,
 367         UNICFG_TIMER310,
 368         UNICFG_TIMER313,
 369         UNICFG_TIMER316,
 370         UNICFG_INIT316,
 371         UNICFG_TIMER317,
 372         UNICFG_TIMER322,
 373         UNICFG_INIT322,
 374         UNICFG_TIMER397,
 375         UNICFG_TIMER398,
 376         UNICFG_TIMER399,
 377 };
 378 .Ed
 379 .Pp
 380 For
 381 .Va popt_mask
 382 and
 383 .Va option_mask ,
 384 the definitions from
 385 .Vt "enum uni_popt"
 386 and
 387 .Vt "enum uni_option"
 388 should be used.
 389 .It Dv NGM_UNI_ENABLE Pq Ic enable
 390 Create the UNI instance and enable processing.
 391 Before the UNI is enabled parameters cannot be retrieved or set.
 392 .It Dv NGM_UNI_DISABLE Pq Ic disable
 393 Destroy the UNI instance and free all resources.
 394 Note, that connections are not released.
 395 .El
 396 .Sh SEE ALSO
 397 .Xr netgraph 4 ,
 398 .Xr ng_atm 4 ,
 399 .Xr ng_sscfu 4 ,
 400 .Xr ng_sscop 4 ,
 401 .Xr ngctl 8
 402 .Sh AUTHORS
 403 The
 404 .Nm uni
 405 netgraph node
 406 and this manual page were written by
 407 .An Harti Brandt Aq harti@FreeBSD.org
 408 .Sh BUGS
 409 .Bl -bullet -compact
 410 .It
 411 LIJ (leaf-initiated-join) is not implemented yet.
 412 .It
 413 GFP (generic functional protocol, Q.2932.1) is not yet implemented.
 414 .It
 415 More testing needed.
 416 .It
 417 PNNI not yet implemented.
 418 .It
 419 Need to implement connection modification and the Q.2931 amendments.
 420 .El