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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
NG_UNI(4)	       FreeBSD 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
     parameters	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:
     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 asynchronous, and in cases where error	han-
     dling is not taken	into account.  With synchronous	APIs and error han-
     dling however, there is a problem.	 If, for example, the application
     issues a request 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 application, 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 rea-
     son 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 describes what was wrong.  This system makes it very
     easy to make a blocking 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	error
	  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 between
	  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 destroying
	  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 (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 struc-
	  ture:

	  struct ngm_uni_debug {
		  uint32_t	  level[UNI_MAXFACILITY];
	  };

     NGM_UNI_GETDEBUG (getdebug)
	  Get debugging	facility levels.  This returns an ngm_uni_debug	struc-
	  ture.

     NGM_UNI_GET_CONFIG	(get_config)
	  Retrieve the current configuration of	the UNI	instance.  This	mes-
	  sage 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 configuration (see
	  timeout(9)).

     NGM_UNI_SET_CONFIG	(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 following 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 (enable)
	  Create the UNI instance and enable processing.  Before the UNI is
	  enabled parameters cannot be retrieved or set.

     NGM_UNI_DISABLE (disable)
	  Destroy the UNI instance and free all	resources.  Note, that connec-
	  tions	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.

FreeBSD	9.3			October	6, 2003			   FreeBSD 9.3

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

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

home | help