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