Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NG_UNI(4)		 BSD Kernel Interfaces Manual		     NG_UNI(4)

NAME
     ng_uni -- netgraph	UNI node type

SYNOPSIS
     #include <netnatm/msg/unistruct.h>
     #include <netnatm/sig/unidef.h>
     #include <netgraph/atm/ng_uni.h>

DESCRIPTION
     The uni netgraph node type	implements ATM Forum signalling	4.0.

     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 parame-
     ters can be retrieved and modified, and the protocol can be started.

     The node is shut down either by an	NGM_SHUTDOWN message, or when all
     hooks are disconnected.

HOOKS
     Each uni node has three hooks with	fixed names:

     lower  This hook is the interface of the UNI protocol to the transport
	    layer of the ATM control plane.  The node expects the interface
	    exported by	ng_sscfu(4) at this hook.

     upper  This hook is the "user" interface of the UNI protocol.  Because
	    there is no	standardized interface at this point, this implementa-
	    tion follows more or less the interface specified by the SDL dia-
	    grams in ITU-T recommendations Q.2931 and Q.2971.  Normally	either
	    a ng_ccatm(4) or a switch CAC should be stacked at this interface.
	    The	message	format at the upper hook is described below.  Because
	    netgraph(4)	is functional, it makes	sometimes sense	to switch this
	    hook to queueing mode from the peer	node upon connection.

     The upper interface of the	uni node is loosely modelled after the inter-
     face specified in the ITU-T signalling standards.	There is however one
     derivation	from this: normally there exists four kinds of signals:	re-
     quests, responses,	indications and	confirmations.	These signals are usu-
     ally triggered either by external events (receiving a message) or inter-
     nal events	(a timer or another signal).  This scheme works	fine for user
     APIs that are entirely asynchronous, and in cases where error handling is
     not taken into account.  With synchronous APIs and	error handling how-
     ever, there is a problem.	If, for	example, the application issues	a re-
     quest to set up a connection, it may do it	by sending a 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 applica-
     tion, and the application will unblock (in	the case of a synchronous 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 effectively ignored and the code de-
     scribes what was wrong.  This system makes	it very	easy to	make a block-
     ing interface out of the message based netgraph interface.

     The upper interface uses the following structure:

     struct uni_arg {
	     uint32_t	     sig;
	     uint32_t	     cookie;
	     u_char	     data[];
     };
     The sig field contains the	actual signal that is sent from	the user to
     UNI or from UNI to	the user.  The cookie can be used by the user to cor-
     relate requests with events and responses.	 If an error response, a con-
     firmation 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 cookie field is followed by the actual data for
     the signal.

     The signal	is one of the following:

     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
     };

     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:

     UNIAPI_ERROR
	     This is the error response, mentioned earlier.  It	carries	an er-
	     ror code or zero, if the signal was accepted by the stack.

     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 be-
	     tween the UNI stack and the user.

     UNIAPI_CALL_DESTROYED
	     A call instance has been destroyed	and all	resources have been
	     freed.

     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 destroy-
	     ing of party data between the UNI stack and the user.

     UNIAPI_PARTY_DESTROYED
	     A party has been destroyed	and all	resources have been freed.

     UNIAPI_ABORT_CALL_request
	     This requests the stack to	destroy	the call instance and free all
	     its resources, without sending any	messages to the	network.

     UNIAPI_MAXSIG
	     This is not a signal, but rather a	definition to get the number
	     of	defined	signals.

     Each of the signals is followed by	a fixed	size structure defined in
     <netnatm/sig/unidef.h>.

CONTROL	MESSAGES
     The uni node understands the standard control messages, plus the follow-
     ing:

     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:

	     struct ngm_uni_debug {
		     uint32_t	     level[UNI_MAXFACILITY];
	     };

     NGM_UNI_SETDEBUG
	     Get debugging facility levels.  This returns an ngm_uni_debug
	     structure.

     NGM_UNI_GET_CONFIG
	     Retrieve the current configuration	of the UNI instance.  This
	     message returns a uni_config structure:

	     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 */
	     };

	     The field proto specifies one of the following protocols:

	     enum uni_proto {
		     UNIPROTO_UNI40U,	     /*	UNI4.0 user side */
		     UNIPROTO_UNI40N,	     /*	UNI4.0 network side */
		     UNIPROTO_PNNI10,	     /*	PNNI1.0	*/
	     };

	     Some protocols may	have options which can be set in popt:

	     enum uni_popt {
		     UNIPROTO_GFP,	     /*	enable GFP */
	     };

	     The option	field controls parsing and checking of messages:

	     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 */
	     };

	     All timer values are given	in milliseconds.  Note,	however, that
	     the actual	resolution of the timers depend	on system configura-
	     tion (see timeout(9)).

     NGM_UNI_SET_CONFIG
	     Change the	UNI configuration.  This takes a

	     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;
	     };

	     The fields	of the ngm_uni_config_mask specify which configuration
	     parameter to change.  The mask field contains bit definitions for
	     all timers, retransmission	counters and the proto field,
	     popt_mask selects which of	the protocol options to	change,	and
	     option_mask specifies which options should	be changed.  The fol-
	     lowing bits are defined:

	     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,
	     };

	     For popt_mask and option_mask, the	definitions from enum uni_popt
	     and enum uni_option should	be used.

     NGM_UNI_ENABLE
	     Create the	UNI instance and enable	processing.  Before the	UNI is
	     enabled parameters	cannot be retrieved or set.

     NGM_UNI_DISABLE
	     Destroy the UNI instance and free all resources.  Note, that con-
	     nections are not released.

SEE ALSO
     netgraph(4), ng_atm(4), ng_sscfu(4), ng_sscop(4), ngctl(8)

AUTHORS
     The uni netgraph node and this manual page	were written by	Harti Brandt
     <harti@FreeBSD.org>

BUGS
     +o	 LIJ (leaf-initiated-join) is not implemented yet.
     +o	 GFP (generic functional protocol, Q.2932.1) is	not yet	implemented.
     +o	 More testing needed.
     +o	 PNNI not yet implemented.
     +o	 Need to implement connection modification and the Q.2931 amendments.

BSD				October	6, 2003				   BSD

NAME | SYNOPSIS | DESCRIPTION | HOOKS | CONTROL MESSAGES | SEE ALSO | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ng_uni&sektion=4&manpath=FreeBSD+7.0-RELEASE>

home | help