| ng_uni.4 (131726) | ng_uni.4 (131861) |
|---|---|
| 1.\" 2.\" Copyright (c) 2001-2003 3.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). 4.\" All rights reserved. 5.\" | 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> | 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 --- 6 unchanged lines hidden (view full) --- 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.\" | 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 --- 6 unchanged lines hidden (view full) --- 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: head/share/man/man4/ng_uni.4 131726 2004-07-06 20:43:24Z ru $ | 29.\" $FreeBSD: head/share/man/man4/ng_uni.4 131861 2004-07-09 07:26:15Z ru $ |
| 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/sig/unidef.h 39.In netgraph/atm/ng_uni.h 40.Sh DESCRIPTION 41The | 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/sig/unidef.h 39.In netgraph/atm/ng_uni.h 40.Sh DESCRIPTION 41The |
| 42.Nm 43netgraph node implements ATM Forum signalling 4.0. | 42.Nm uni 43netgraph node type implements ATM Forum signalling 4.0. |
| 44.Pp 45After creation of the node, the UNI instance must be created by sending | 44.Pp 45After creation of the node, the UNI instance must be created by sending |
| 46an enable message to the node. | 46an 47.Dq enable 48message to the node. |
| 47If the node is enabled, the UNI parameters | 49If the node is enabled, the UNI parameters |
| 48can be retrieved and modified and the protocol can be started. | 50can be retrieved and modified, and the protocol can be started. |
| 49.Pp | 51.Pp |
| 50The node is shutdown either by a | 52The node is shut down either by an |
| 51.Dv NGM_SHUTDOWN | 53.Dv NGM_SHUTDOWN |
| 52message or when all hooks are disconnected. | 54message, or when all hooks are disconnected. |
| 53.Sh HOOKS 54Each | 55.Sh HOOKS 56Each |
| 55.Nm | 57.Nm uni |
| 56node has three hooks with fixed names: | 58node has three hooks with fixed names: |
| 57.Bl -tag -width xxx 58.It Dv lower | 59.Bl -tag -width ".Va upper" 60.It Va lower |
| 59This hook is the interface of the UNI protocol to the transport layer of 60the ATM control plane. 61The node expects the interface exported by 62.Xr ng_sscfu 4 63at this hook. | 61This hook is the interface of the UNI protocol to the transport layer of 62the ATM control plane. 63The node expects the interface exported by 64.Xr ng_sscfu 4 65at this hook. |
| 64.It Dv upper | 66.It Va upper |
| 65This hook is the | 67This hook is the |
| 66.Ql user | 68.Dq user |
| 67interface of the UNI protocol. 68Because there is no standardized interface 69at this point, this implementation follows more or less the interface 70specified by the SDL diagrams in ITU-T recommendations Q.2931 and Q.2971. 71Normally either a 72.Xr ng_ccatm 4 73or a switch CAC should be stacked at this interface. 74The message format at the | 69interface of the UNI protocol. 70Because there is no standardized interface 71at this point, this implementation follows more or less the interface 72specified by the SDL diagrams in ITU-T recommendations Q.2931 and Q.2971. 73Normally either a 74.Xr ng_ccatm 4 75or a switch CAC should be stacked at this interface. 76The message format at the |
| 75.Dv upper | 77.Va upper |
| 76hook is described below. 77Because | 78hook is described below. 79Because |
| 78.Xt netgraph 4 | 80.Xr netgraph 4 |
| 79is functional, it makes sometimes sense to switch this hook to queueing mode 80from the peer node upon connection. 81.El 82.Pp 83The | 81is functional, it makes sometimes sense to switch this hook to queueing mode 82from the peer node upon connection. 83.El 84.Pp 85The |
| 84.Dv upper | 86.Va upper |
| 85interface of the | 87interface of the |
| 86.Nm | 88.Nm uni |
| 87node is loosely modelled after the interface specified in the ITU-T signalling 88standards. 89There is however one derivation from this: normally there exists 90four kinds of signals: requests, responses, indications and confirmations. 91These signals are usually triggered either by external events (receiving a 92message) or internal events (a timer or another signal). 93This scheme works | 89node is loosely modelled after the interface specified in the ITU-T signalling 90standards. 91There is however one derivation from this: normally there exists 92four kinds of signals: requests, responses, indications and confirmations. 93These signals are usually triggered either by external events (receiving a 94message) or internal events (a timer or another signal). 95This scheme works |
| 94fine for user APIs that are entirely asynchronous and in cases, where | 96fine for user APIs that are entirely asynchronous, and in cases where |
| 95error handling is not taken into account. 96With synchronous APIs and error | 97error handling is not taken into account. 98With synchronous APIs and error |
| 97handling, however there is a problem. | 99handling however, there is a problem. |
| 98If, for example, the application | 100If, for example, the application |
| 99issues a request to setup a connection. 100It may do it by sending a | 101issues a request to set up a connection, 102it may do it by sending a |
| 101.Dv SETUP.request 102signal to the UNI. | 103.Dv SETUP.request 104signal to the UNI. |
| 103Normally the UNI stack will send a SETUP message and | 105Normally, the UNI stack will send a SETUP message and |
| 104receive a message from the switch (a RELEASE, CONNECT, CALL PROCEEDING or | 106receive a message from the switch (a RELEASE, CONNECT, CALL PROCEEDING or |
| 105ALERTING) or a timer in the UNI stack will time out. 106In any of these cases 107the UNI stack is supposed to report an event back to the application and | 107ALERTING), or a timer in the UNI stack will time out. 108In any of these cases, 109the UNI stack is supposed to report an event back to the application, and |
| 108the application will unblock (in the case of a synchronous API) and handle 109the event. | 110the application will unblock (in the case of a synchronous API) and handle 111the event. |
| 110The problem occurs, when an error happens. | 112The problem occurs when an error happens. |
| 111Suppose there is no 112memory to send the SETUP message and to start the timer. | 113Suppose there is no 114memory to send the SETUP message and to start the timer. |
| 113In this case the 114application will block forever, because no received message and no timer | 115In this case, the 116application will block forever because no received message and no timer |
| 115will wake it up. 116For this reason this implementation uses an additional message: 117for each signal sent from the application to the stack, the stack will 118respond with an error code. 119If this code is zero, the stack has accepted | 117will wake it up. 118For this reason this implementation uses an additional message: 119for each signal sent from the application to the stack, the stack will 120respond with an error code. 121If this code is zero, the stack has accepted |
| 120the signal and the application may block, if the code is non-zero, the signal 121is effectively ignored and the code describes, what was wrong. | 122the signal and the application may block; if the code is non-zero, the signal 123is effectively ignored and the code describes what was wrong. |
| 122This system 123makes it very easy to make a blocking interface out of the message based 124netgraph interface. 125.Pp 126The | 124This system 125makes it very easy to make a blocking interface out of the message based 126netgraph interface. 127.Pp 128The |
| 127.Dv upper | 129.Va upper |
| 128interface uses the following structure: 129.Bd -literal 130struct uni_arg { 131 uint32_t sig; 132 uint32_t cookie; 133 u_char data[]; 134}; 135.Ed 136The | 130interface uses the following structure: 131.Bd -literal 132struct uni_arg { 133 uint32_t sig; 134 uint32_t cookie; 135 u_char data[]; 136}; 137.Ed 138The |
| 137.Fa sig 138field contains the actual signal that is sent from the user to UNI or the | 139.Va sig 140field contains the actual signal that is sent from the user to UNI or from |
| 139UNI to the user. 140The | 141UNI to the user. 142The |
| 141.Fa cookie | 143.Va cookie |
| 142can be used by the user to correlate requests with events and responses. 143If an error response, a confirmation or an indication was triggered by 144a request or response, the cookie from that request or response is carried in 145the message from the stack to the user. 146The | 144can be used by the user to correlate requests with events and responses. 145If an error response, a confirmation or an indication was triggered by 146a request or response, the cookie from that request or response is carried in 147the message from the stack to the user. 148The |
| 147.Fa cookie | 149.Va cookie |
| 148field is followed by the actual data for the signal. 149.Pp 150The signal is one of the following: 151.Bd -literal 152enum uni_sig { 153 UNIAPI_ERROR, /* UNI -> API */ 154 155 UNIAPI_CALL_CREATED, /* UNI -> API */ --- 48 unchanged lines hidden (view full) --- 204 UNIAPI_ABORT_CALL_request, /* API -> UNI */ 205 206 UNIAPI_MAXSIG 207}; 208.Ed 209.Pp 210The meaning of most of the signals can be deduced from the ITU-T SDLs. 211A number of signals, however, is unique to this implementation: | 150field is followed by the actual data for the signal. 151.Pp 152The signal is one of the following: 153.Bd -literal 154enum uni_sig { 155 UNIAPI_ERROR, /* UNI -> API */ 156 157 UNIAPI_CALL_CREATED, /* UNI -> API */ --- 48 unchanged lines hidden (view full) --- 206 UNIAPI_ABORT_CALL_request, /* API -> UNI */ 207 208 UNIAPI_MAXSIG 209}; 210.Ed 211.Pp 212The meaning of most of the signals can be deduced from the ITU-T SDLs. 213A number of signals, however, is unique to this implementation: |
| 212.Bl -tag -width xxx | 214.Bl -tag -width indent |
| 213.It Dv UNIAPI_ERROR 214This is the error response, mentioned earlier. 215It carries an error code or 216zero, if the signal was accepted by the stack. 217.It Dv UNIAPI_CALL_CREATED 218The UNI stack has created a call instance either from an incoming SETUP or 219from the user requesting an outgoing SETUP. 220This may be used to synchronize 221the creation and destroying of call data between the UNI stack and the user. 222.It Dv UNIAPI_CALL_DESTROYED | 215.It Dv UNIAPI_ERROR 216This is the error response, mentioned earlier. 217It carries an error code or 218zero, if the signal was accepted by the stack. 219.It Dv UNIAPI_CALL_CREATED 220The UNI stack has created a call instance either from an incoming SETUP or 221from the user requesting an outgoing SETUP. 222This may be used to synchronize 223the creation and destroying of call data between the UNI stack and the user. 224.It Dv UNIAPI_CALL_DESTROYED |
| 223An call instance has been destroyed and all resources have been freed. | 225A call instance has been destroyed and all resources have been freed. |
| 224.It Dv UNIAPI_PARTY_CREATED 225A new party has been created for an existing point-to-multipoint call. 226This may be used to synchronize the creation and destroying of party data 227between the UNI stack and the user. 228.It Dv UNIAPI_PARTY_DESTROYED 229A party has been destroyed and all resources have been freed. 230.It Dv UNIAPI_ABORT_CALL_request | 226.It Dv UNIAPI_PARTY_CREATED 227A new party has been created for an existing point-to-multipoint call. 228This may be used to synchronize the creation and destroying of party data 229between the UNI stack and the user. 230.It Dv UNIAPI_PARTY_DESTROYED 231A party has been destroyed and all resources have been freed. 232.It Dv UNIAPI_ABORT_CALL_request |
| 231The requests the stack to destroy the call instance and free all it's resources | 233This requests the stack to destroy the call instance 234and free all its resources, |
| 232without sending any messages to the network. 233.It Dv UNIAPI_MAXSIG 234This is not a signal, but rather a definition to get the number of defined 235signals. 236.El 237.Pp 238Each of the signals is followed by a fixed size structure defined in | 235without sending any messages to the network. 236.It Dv UNIAPI_MAXSIG 237This is not a signal, but rather a definition to get the number of defined 238signals. 239.El 240.Pp 241Each of the signals is followed by a fixed size structure defined in |
| 239.Pa unidef.h . | 242.In netnatm/sig/unidef.h . |
| 240.Sh CONTROL MESSAGES 241The | 243.Sh CONTROL MESSAGES 244The |
| 242.Nm 243node understands the standard control messages plus the following: 244.Bl -tag -width xxx | 245.Nm uni 246node understands the standard control messages, plus the following: 247.Bl -tag -width indent |
| 245.It Dv NGM_UNI_SETDEBUG 246Set debugging facility levels. 247The UNI stack defines a number of debugging 248facilities, each one associated with a debugging level. 249If the debugging level 250of a facility is non-zero, text output will be generated to the console. 251The message uses the following structure: 252.Bd -literal 253struct ngm_uni_debug { 254 uint32_t level[UNI_MAXFACILITY]; 255}; 256.Ed 257.It Dv NGM_UNI_SETDEBUG 258Get debugging facility levels. | 248.It Dv NGM_UNI_SETDEBUG 249Set debugging facility levels. 250The UNI stack defines a number of debugging 251facilities, each one associated with a debugging level. 252If the debugging level 253of a facility is non-zero, text output will be generated to the console. 254The message uses the following structure: 255.Bd -literal 256struct ngm_uni_debug { 257 uint32_t level[UNI_MAXFACILITY]; 258}; 259.Ed 260.It Dv NGM_UNI_SETDEBUG 261Get debugging facility levels. |
| 259This returns a 260.Fa ngm_uni_debug | 262This returns an 263.Vt ngm_uni_debug |
| 261structure. 262.It Dv NGM_UNI_GET_CONFIG 263Retrieve the current configuration of the UNI instance. 264This message returns a | 264structure. 265.It Dv NGM_UNI_GET_CONFIG 266Retrieve the current configuration of the UNI instance. 267This message returns a |
| 265.Fa uni_config | 268.Vt uni_config |
| 266structure: 267.Bd -literal 268struct uni_config { 269 uint32_t proto; /* which protocol */ 270 uint32_t popt; /* protocol option */ 271 uint32_t option; /* other options */ 272 uint32_t timer301; /* T301 */ 273 uint32_t timer303; /* T303 */ --- 10 unchanged lines hidden (view full) --- 284 uint32_t init322; /* T322 retransmission count */ 285 uint32_t timer397; /* T397 */ 286 uint32_t timer398; /* T398 */ 287 uint32_t timer399; /* T399 */ 288}; 289.Ed 290.Pp 291The field | 269structure: 270.Bd -literal 271struct uni_config { 272 uint32_t proto; /* which protocol */ 273 uint32_t popt; /* protocol option */ 274 uint32_t option; /* other options */ 275 uint32_t timer301; /* T301 */ 276 uint32_t timer303; /* T303 */ --- 10 unchanged lines hidden (view full) --- 287 uint32_t init322; /* T322 retransmission count */ 288 uint32_t timer397; /* T397 */ 289 uint32_t timer398; /* T398 */ 290 uint32_t timer399; /* T399 */ 291}; 292.Ed 293.Pp 294The field |
| 292.Fa proto | 295.Va proto |
| 293specifies one of the following protocols: 294.Bd -literal 295enum uni_proto { 296 UNIPROTO_UNI40U, /* UNI4.0 user side */ 297 UNIPROTO_UNI40N, /* UNI4.0 network side */ 298 UNIPROTO_PNNI10, /* PNNI1.0 */ 299}; 300.Ed 301.Pp 302Some protocols may have options which can be set in | 296specifies one of the following protocols: 297.Bd -literal 298enum uni_proto { 299 UNIPROTO_UNI40U, /* UNI4.0 user side */ 300 UNIPROTO_UNI40N, /* UNI4.0 network side */ 301 UNIPROTO_PNNI10, /* PNNI1.0 */ 302}; 303.Ed 304.Pp 305Some protocols may have options which can be set in |
| 303.Fa popt : | 306.Va popt : |
| 304.Bd -literal 305enum uni_popt { 306 UNIPROTO_GFP, /* enable GFP */ 307}; 308.Ed 309.Pp 310The | 307.Bd -literal 308enum uni_popt { 309 UNIPROTO_GFP, /* enable GFP */ 310}; 311.Ed 312.Pp 313The |
| 311.Fa option | 314.Va option |
| 312field controls parsing and checking of messages: 313.Bd -literal 314enum uni_option { 315 UNIOPT_GIT_HARD, /* harder check of GIT IE */ 316 UNIOPT_BEARER_HARD, /* harder check of BEARER IE */ 317 UNIOPT_CAUSE_HARD, /* harder check of CAUSE IE */ 318}; 319.Ed 320.Pp 321All timer values are given in milliseconds. 322Note, however, that the actual 323resolution of the timers depend on system configuration (see | 315field controls parsing and checking of messages: 316.Bd -literal 317enum uni_option { 318 UNIOPT_GIT_HARD, /* harder check of GIT IE */ 319 UNIOPT_BEARER_HARD, /* harder check of BEARER IE */ 320 UNIOPT_CAUSE_HARD, /* harder check of CAUSE IE */ 321}; 322.Ed 323.Pp 324All timer values are given in milliseconds. 325Note, however, that the actual 326resolution of the timers depend on system configuration (see |
| 324.Xr timeout 9 ). | 327.Xr timeout 9 ) . |
| 325.It Dv NGM_UNI_SET_CONFIG 326Change the UNI configuration. 327This takes a 328.Bd -literal 329struct ngm_uni_set_config { 330 struct uni_config config; 331 struct ngm_uni_config_mask mask; 332}; 333struct ngm_uni_config_mask { 334 uint32_t mask; 335 uint32_t popt_mask; 336 uint32_t option_mask; 337}; 338.Ed 339.Pp 340The fields of the | 328.It Dv NGM_UNI_SET_CONFIG 329Change the UNI configuration. 330This takes a 331.Bd -literal 332struct ngm_uni_set_config { 333 struct uni_config config; 334 struct ngm_uni_config_mask mask; 335}; 336struct ngm_uni_config_mask { 337 uint32_t mask; 338 uint32_t popt_mask; 339 uint32_t option_mask; 340}; 341.Ed 342.Pp 343The fields of the |
| 341.Fa ngm_uni_config_mask | 344.Vt ngm_uni_config_mask |
| 342specify which configuration parameter to change. 343The | 345specify which configuration parameter to change. 346The |
| 344.Fa mask | 347.Va mask |
| 345field contains bit definitions for all timers, retransmission counters 346and the | 348field contains bit definitions for all timers, retransmission counters 349and the |
| 347.Fa proto | 350.Va proto |
| 348field, | 351field, |
| 349.Fa popt_mask 350selects which of the protocol options to change and 351.Fa option_mask | 352.Va popt_mask 353selects which of the protocol options to change, and 354.Va option_mask |
| 352specifies which options should be changed. 353The following bits are defined: 354.Bd -literal 355enum uni_config_mask { 356 UNICFG_PROTO, 357 UNICFG_TIMER301, 358 UNICFG_TIMER303, 359 UNICFG_INIT303, --- 8 unchanged lines hidden (view full) --- 368 UNICFG_TIMER322, 369 UNICFG_INIT322, 370 UNICFG_TIMER397, 371 UNICFG_TIMER398, 372 UNICFG_TIMER399, 373}; 374.Ed 375.Pp | 355specifies which options should be changed. 356The following bits are defined: 357.Bd -literal 358enum uni_config_mask { 359 UNICFG_PROTO, 360 UNICFG_TIMER301, 361 UNICFG_TIMER303, 362 UNICFG_INIT303, --- 8 unchanged lines hidden (view full) --- 371 UNICFG_TIMER322, 372 UNICFG_INIT322, 373 UNICFG_TIMER397, 374 UNICFG_TIMER398, 375 UNICFG_TIMER399, 376}; 377.Ed 378.Pp |
| 376For the 377.Fa popt_mask | 379For 380.Va popt_mask |
| 378and | 381and |
| 379.Fa option_mask | 382.Va option_mask , |
| 380the definitions from | 383the definitions from |
| 381.Fa "enum uni_popt" | 384.Vt "enum uni_popt" |
| 382and | 385and |
| 383.Fa "enum uni_option" | 386.Vt "enum uni_option" |
| 384should be used. 385.It Dv NGM_UNI_ENABLE 386Create the UNI instance and enable processing. 387Before the UNI is enabled parameters cannot be retrieved or set. 388.It Dv NGM_UNI_DISABLE 389Destroy the UNI instance and free all resources. 390Note, that connections are not released. 391.El --- 10 unchanged lines hidden (view full) --- 402.It 403GFP (generic functional protocol, Q.2932.1) is not yet implemented. 404.It 405More testing needed. 406.It 407PNNI not yet implemented. 408.It 409Need to implement connection modification and the Q.2931 amendments. | 387should be used. 388.It Dv NGM_UNI_ENABLE 389Create the UNI instance and enable processing. 390Before the UNI is enabled parameters cannot be retrieved or set. 391.It Dv NGM_UNI_DISABLE 392Destroy the UNI instance and free all resources. 393Note, that connections are not released. 394.El --- 10 unchanged lines hidden (view full) --- 405.It 406GFP (generic functional protocol, Q.2932.1) is not yet implemented. 407.It 408More testing needed. 409.It 410PNNI not yet implemented. 411.It 412Need to implement connection modification and the Q.2931 amendments. |
| 413.El |
|
| 410.Sh AUTHORS 411The | 414.Sh AUTHORS 415The |
| 412.Nm | 416.Nm uni |
| 413netgraph node | 417netgraph node |
| 414and this manual page was written by 415.An Harti Brandt Aq harti@freebsd.org | 418and this manual page were written by 419.An Harti Brandt Aq harti@FreeBSD.org |