diff options
author | harti <harti@FreeBSD.org> | 2003-11-07 09:12:07 +0000 |
---|---|---|
committer | harti <harti@FreeBSD.org> | 2003-11-07 09:12:07 +0000 |
commit | 95fb3f9279d63e253796f0b63d8130815a577112 (patch) | |
tree | 39cb7dbb2b71225fbb6ffafe3ff7ab86bd741719 /share/man/man4/ng_uni.4 | |
parent | 0defd13ce39d267cb0444cc68c84e8f41efac90b (diff) | |
download | FreeBSD-src-95fb3f9279d63e253796f0b63d8130815a577112.zip FreeBSD-src-95fb3f9279d63e253796f0b63d8130815a577112.tar.gz |
The man page for the layer 3 (signalling) netgraph node of NgATM.
Diffstat (limited to 'share/man/man4/ng_uni.4')
-rw-r--r-- | share/man/man4/ng_uni.4 | 410 |
1 files changed, 410 insertions, 0 deletions
diff --git a/share/man/man4/ng_uni.4 b/share/man/man4/ng_uni.4 new file mode 100644 index 0000000..66b86a1 --- /dev/null +++ b/share/man/man4/ng_uni.4 @@ -0,0 +1,410 @@ +.\" +.\" Copyright (c) 2001-2003 +.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). +.\" All rights reserved. +.\" +.\" Author: Hartmut Brandt <harti@freebsd.org> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 6, 2003 +.Dt ng_uni 4 +.Os FreeBSD +.Sh NAME +.Nm ng_uni +.Nd netgraph UNI node type +.Sh SYNOPSIS +.Fd #include <netnatm/sig/unidef.h> +.Fd #include <netgraph/atm/ng_uni.h> +.Sh DESCIPTION +The +.Nm +netgraph node implements ATM Forum signalling 4.0. +.Pp +After creation of the node, the UNI instance must be created by sending +an enable message to the node. +If the node is enabled, the UNI parameters +can be retrieved and modified and the protocol can be started. +.Pp +The node is shutdown either by a +.Dv NGM_SHUTDOWN +message or when all hooks are disconnected. +.Sh HOOKS +Each +.Nm +node has three hooks with fixed names: +.Bl -tag -width xxx +.It Dv lower +This hook is the interface of the UNI protocol to the transport layer of +the ATM control plane. +The node expectes the interface exported by +.Xr ng_sscfu 4 +at this hook. +.It Dv upper +This hook is the +.Ql user +interface of the UNI protocol. +Because there is no standardized interface +at this point, this implementation follows more or less the interface +specified by the SDL diagrams in ITU-T recommendations Q.2931 and Q.2971. +Normally either a +.Xr ng_ccatm 4 +or a switch CAC should be stacked at this interface. +The message format at the +.Dv upper +hook is described below. +Because +.Xt netgraph 4 +is functional, it makes sometimes sense to switch this hook to queueing mode +from the peer node upon connection. +.El +.Pp +The +.Dv upper +interface of the +.Nm +node is loosely modelled after the interface specified in the ITU-T signalling +standards. +There is however one derivation from this: normally there exists +four kinds of signals: requests, responses, indications and confirmations. +These signals are usually triggered either by external events (receiving a +message) or internal events (a timer or another signal). +This scheme works +fine for user APIs that are entirely asynchronuous and in cases, where +error handling is not taken into account. +With synchronuous APIs and error +handling, however there is a problem. +If, for example, the application +issues a request to setup a connection. +It may do it by sending a +.Dv SETUP.request +signal to the UNI. +Normally the UNI stack will send a SETUP message and +receive a message from the switch (a RELEASE, CONNECT, CALL PROCEEDING or +ALERTING) or a timer in the UNI stack will time out. +In any of these cases +the UNI stack is supposed to report an event back to the application and +the application will unblock (in the case of a synchronuous API) and handle +the event. +The problem occurs, when an error happens. +Suppose there is no +memory to send the SETUP message and to start the timer. +In this case the +application will block forever, because no received message and no timer +will wake it up. +For this reason this implementation uses an additional message: +for each signal sent from the application to the stack, the stack will +respond with an error code. +If this code is zero, the stack has accepted +the signal and the application may block, if the code is non-zero, the signal +is effectivly ignored and the code describes, what was wrong. +This system +makes it very easy to make a blocking interface out of the message based +netgraph interface. +.Pp +The +.Dv upper +interface uses the following structure: +.Bd -literal +struct uni_arg { + uint32_t sig; + uint32_t cookie; + u_char data[]; +}; +.Ed +The +.Fa sig +field contains the actual signal that is sent from the user to UNI or the +UNI to the user. +The +.Fa cookie +can be used by the user to correlate requests with events and responses. +If an error response, a confirmation or an indication was triggered by +a request or response, the cookie from that request or response is carried in +the message from the stack to the user. +The +.Fa cookie +field is followed by the actual data for the signal. +.Pp +The signal is one of the following: +.Bd -literal +enum uni_sig { + UNIAPI_ERROR, /* UNI -> API */ + + UNIAPI_CALL_CREATED, /* UNI -> API */ + UNIAPI_CALL_DESTROYED, /* UNI -> API */ + UNIAPI_PARTY_CREATED, /* UNI -> API */ + UNIAPI_PARTY_DESTROYED, /* UNI -> API */ + + UNIAPI_LINK_ESTABLISH_request, /* API -> UNI */ + UNIAPI_LINK_ESTABLISH_confirm, /* UNI -> API */ + UNIAPI_LINK_RELEASE_request, /* API -> UNI */ + UNIAPI_LINK_RELEASE_confirm, /* UNI -> API */ + + UNIAPI_RESET_request, /* API -> UNI */ + UNIAPI_RESET_confirm, /* UNI -> API */ + UNIAPI_RESET_indication, /* UNI -> API */ + UNIAPI_RESET_ERROR_indication, /* UNI -> API */ + UNIAPI_RESET_response, /* API -> UNI */ + UNIAPI_RESET_ERROR_response, /* API -> UNI */ + UNIAPI_RESET_STATUS_indication, /* UNI -> API */ + + UNIAPI_SETUP_request, /* API -> UNI */ + UNIAPI_SETUP_indication, /* UNI -> API */ + UNIAPI_SETUP_response, /* API -> UNI */ + UNIAPI_SETUP_confirm, /* UNI -> API */ + UNIAPI_SETUP_COMPLETE_indication, /* UNI -> API */ + UNIAPI_ALERTING_request, /* API -> UNI */ + UNIAPI_ALERTING_indication, /* UNI -> API */ + UNIAPI_PROCEEDING_request, /* API -> UNI */ + UNIAPI_PROCEEDING_indication, /* UNI -> API */ + UNIAPI_RELEASE_request, /* API -> UNI */ + UNIAPI_RELEASE_indication, /* UNI -> API */ + UNIAPI_RELEASE_response, /* API -> UNI */ + UNIAPI_RELEASE_confirm, /* UNI -> API */ + UNIAPI_NOTIFY_request, /* API -> UNI */ + UNIAPI_NOTIFY_indication, /* UNI -> API */ + UNIAPI_STATUS_indication, /* UNI -> API */ + UNIAPI_STATUS_ENQUIRY_request, /* API -> UNI */ + + UNIAPI_ADD_PARTY_request, /* API -> UNI */ + UNIAPI_ADD_PARTY_indication, /* UNI -> API */ + UNIAPI_PARTY_ALERTING_request, /* API -> UNI */ + UNIAPI_PARTY_ALERTING_indication, /* UNI -> API */ + UNIAPI_ADD_PARTY_ACK_request, /* API -> UNI */ + UNIAPI_ADD_PARTY_ACK_indication, /* UNI -> API */ + UNIAPI_ADD_PARTY_REJ_request, /* API -> UNI */ + UNIAPI_ADD_PARTY_REJ_indication, /* UNI -> API */ + UNIAPI_DROP_PARTY_request, /* API -> UNI */ + UNIAPI_DROP_PARTY_indication, /* UNI -> API */ + UNIAPI_DROP_PARTY_ACK_request, /* API -> UNI */ + UNIAPI_DROP_PARTY_ACK_indication, /* UNI -> API */ + + UNIAPI_ABORT_CALL_request, /* API -> UNI */ + + UNIAPI_MAXSIG +}; +.Ed +.Pp +The meaning of most of the signals can be deduced from the ITU-T SDLs. +A number of signals, however, is unique to this implementation: +.Bl -tag -width xxx +.It Dv UNIAPI_ERROR +This is the error response, mentioned earlier. +It carries an error code or +zero, if the signal was accepted by the stack. +.It Dv UNIAPI_CALL_CREATED +The UNI stack has created a call instance either from an incoming SETUP or +from the user requesting an outgoing SETUP. +This may be used to synchronize +the creation and destroying of call data between the UNI stack and the user. +.It Dv UNIAPI_CALL_DESTROYED +An call instance has been destroyed and all resources have been freed. +.It Dv UNIAPI_PARTY_CREATED +A new party has been created for an existing point-to-multipoint call. +This may be used to synchronize the creation and destroying of party data +between the UNI stack and the user. +.It Dv UNIAPI_PARTY_DESTROYED +A party has been destroyed and all resources have been freed. +.It Dv UNIAPI_ABORT_CALL_request +The requests the stack to destroy the call instance and free all it's resources +without sending any messages to the network. +.It Dv UNIAPI_MAXSIG +This is not a signal, but rather a definition to get the number of defined +signals. +.El +.Pp +Each of the signals is followed by a fixed size structure defined in +.Pa unidef.h . +.Sh CONTROL MESSAGES +The +.Nm +node understands the standard control messages plus the following: +.Bl -tag -width xxx +.It Dv NGM_UNI_SETDEBUG +Set debugging facility levels. +The UNI stack defines a number of debugging +facilities, each one associated with a debugging level. +If the debugging level +of a facility is non-zero, text output will be generated to the console. +The message uses the following structure: +.Bd -literal +struct ngm_uni_debug { + uint32_t level[UNI_MAXFACILITY]; +}; +.Ed +.It Dv NGM_UNI_SETDEBUG +Get debugging facility levels. +This returns a +.Fa ngm_uni_debug +structure. +.It Dv NGM_UNI_GET_CONFIG +Retrieve the current configuration of the UNI instance. +This message returns a +.Fa uni_config +structure: +.Bd -literal +struct uni_config { + uint32_t proto; /* which protocol */ + uint32_t popt; /* protocol option */ + uint32_t option; /* other options */ + uint32_t timer301; /* T301 */ + uint32_t timer303; /* T303 */ + uint32_t init303; /* T303 retransmission count */ + uint32_t timer308; /* T308 */ + uint32_t init308; /* T308 retransmission count */ + uint32_t timer309; /* T309 */ + uint32_t timer310; /* T310 */ + uint32_t timer313; /* T313 */ + uint32_t timer316; /* T316 */ + uint32_t init316; /* T316 retransmission count */ + uint32_t timer317; /* T317 */ + uint32_t timer322; /* T322 */ + uint32_t init322; /* T322 retransmission count */ + uint32_t timer397; /* T397 */ + uint32_t timer398; /* T398 */ + uint32_t timer399; /* T399 */ +}; +.Ed +.Pp +The field +.Fa proto +specifies one of the following protocols: +.Bd -literal +enum uni_proto { + UNIPROTO_UNI40U, /* UNI4.0 user side */ + UNIPROTO_UNI40N, /* UNI4.0 network side */ + UNIPROTO_PNNI10, /* PNNI1.0 */ +}; +.Ed +.Pp +Some protocols may have options which can be set in +.Fa popt : +.Bd -literal +enum uni_popt { + UNIPROTO_GFP, /* enable GFP */ +}; +.Ed +.Pp +The +.Fa option +field controls parsing and checking of messages: +.Bd -literal +enum uni_option { + UNIOPT_GIT_HARD, /* harder check of GIT IE */ + UNIOPT_BEARER_HARD, /* harder check of BEARER IE */ + UNIOPT_CAUSE_HARD, /* harder check of CAUSE IE */ +}; +.Ed +.Pp +All timer values are given in milliseconds. +Note, however, that the actual +resolution of the timers depend on system configuration (see +.Xr timeout 9 ). +.It Dv NGM_UNI_SET_CONFIG +Change the UNI configuration. +This takes a +.Bd -literal +struct ngm_uni_set_config { + struct uni_config config; + struct ngm_uni_config_mask mask; +}; +struct ngm_uni_config_mask { + uint32_t mask; + uint32_t popt_mask; + uint32_t option_mask; +}; +.Ed +.Pp +The fields of the +.Fa ngm_uni_config_mask +specify which configuration parameter to change. +The +.Fa mask +field contains bit definitions for all timers, retransmission counters +and the +.Fa proto +field, +.Fa popt_mask +selects which of the protocol options to change and +.Fa option_mask +specifies which options should be changed. The following bits are defined: +.Bd -literal +enum uni_config_mask { + UNICFG_PROTO, + UNICFG_TIMER301, + UNICFG_TIMER303, + UNICFG_INIT303, + UNICFG_TIMER308, + UNICFG_INIT308, + UNICFG_TIMER309, + UNICFG_TIMER310, + UNICFG_TIMER313, + UNICFG_TIMER316, + UNICFG_INIT316, + UNICFG_TIMER317, + UNICFG_TIMER322, + UNICFG_INIT322, + UNICFG_TIMER397, + UNICFG_TIMER398, + UNICFG_TIMER399, +}; +.Ed +.Pp +For the +.Fa popt_mask +and +.Fa option_mask +the definitions from +.Fa "enum uni_popt" +and +.Fa "enum uni_option" +should be used. +.It Dv NGM_UNI_ENABLE +Create the UNI instance and enable processing. +Before the UNI is enabled parameters cannot be retrieved or set. +.It Dv NGM_UNI_DISABLE +Destroy the UNI instance and free all resources. +Note, that connections are not released. +.El +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_atm 4 , +.Xr ng_sscfu 4 , +.Xr ng_sscop 4 , +.Xr ngctl 8 +.Sh BUGS +.Bl -bullet -compact +.It +LIJ (leaf-initiated-join) is not implemented yet. +.It +GFP (generic functional protocol, Q.2932.1) is not yet implemented. +.It +More testing needed. +.It +PNNI not yet implemented. +.It +Need to implement connection modification and the Q.2931 amandements. +.Sh AUTHORS +.An Harti Brandt Aq harti@freebsd.org |