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_SSCOP(4)	       FreeBSD Kernel Interfaces Manual		   NG_SSCOP(4)

NAME
     ng_sscop -- netgraph SSCOP	node type

SYNOPSIS
     #include <netnatm/saal/sscopdef.h>
     #include <netgraph/atm/ng_sscop.h>

DESCRIPTION
     The sscop netgraph	node type implements the ITU-T standard	Q.2110.	 This
     standard describes	the so called Service Specific Connection Oriented
     Protocol (SSCOP) that is used to carry signalling messages	over the pri-
     vate and public UNIs and the public NNI.  This protocol is	a transport
     protocol with selective acknowledgements, and can be tailored to the
     environment.  This	implementation is a full implementation	of that	stan-
     dard.

     After creation of the node, the SSCOP instance must be created by sending
     an	``enable'' message to the node.	 If the	node is	enabled, the SSCOP
     parameters	can be retrieved and modified and the protocol can be started.

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

HOOKS
     Each sscop	node has three hooks with fixed	names:

     lower   This hook must be connected to a node that	ensures	transport of
	     packets to	and from the remote peer node.	Normally this is a
	     ng_atm(4) node with an AAL5 hook, but the sscop node is able to
	     work on any packet-transporting layer, like, for example, IP or
	     UDP.  The node handles flow control messages received on this
	     hook: if it receives a NGM_HIGH_WATER_PASSED message, it declares
	     the ``lower layer busy'' state.  If a NGM_LOW_WATER_PASSED	mes-
	     sage is received, the busy	state is cleared.  Note	that the node
	     does not look at the message contents of these flow control mes-
	     sages.

     upper   This is the interface to the SSCOP	user.  This interface uses the
	     following message format:

	     struct sscop_arg {
		     uint32_t sig;
		     uint32_t arg;   /*	opt. sequence number or	clear-buff */
		     u_char   data[];
	     };

	     The sig field is one of the signals defined in the	standard:

	     enum sscop_aasig {
		 SSCOP_ESTABLISH_request,    /*	<- UU, BR */
		 SSCOP_ESTABLISH_indication, /*	-> UU */
		 SSCOP_ESTABLISH_response,   /*	<- UU, BR */
		 SSCOP_ESTABLISH_confirm,    /*	-> UU */

		 SSCOP_RELEASE_request,	     /*	<- UU */
		 SSCOP_RELEASE_indication,   /*	-> UU, SRC */
		 SSCOP_RELEASE_confirm,	     /*	-> */

		 SSCOP_DATA_request,	     /*	<- MU */
		 SSCOP_DATA_indication,	     /*	-> MU, SN */

		 SSCOP_UDATA_request,	     /*	<- MU */
		 SSCOP_UDATA_indication,     /*	-> MU */

		 SSCOP_RECOVER_indication,   /*	-> */
		 SSCOP_RECOVER_response,     /*	<- */

		 SSCOP_RESYNC_request,	     /*	<- UU */
		 SSCOP_RESYNC_indication,    /*	-> UU */
		 SSCOP_RESYNC_response,	     /*	<- */
		 SSCOP_RESYNC_confirm,	     /*	-> */

		 SSCOP_RETRIEVE_request,     /*	<- RN */
		 SSCOP_RETRIEVE_indication,  /*	-> MU */
		 SSCOP_RETRIEVE_COMPL_indication,/* -> */
	     };

	     The arrows	in the comment show the	direction of the signal,
	     whether it	is a signal that comes out of the node (`->'), or is
	     sent by the node user to the node (`<-').	The arg	field contains
	     the argument to some of the signals: it is	either a PDU sequence
	     number, or	the CLEAR-BUFFER flag.	There are a number of special
	     sequence numbers for some operations:

		   SSCOP_MAXSEQNO	   maximum legal sequence number
		   SSCOP_RETRIEVE_UNKNOWN  retrieve transmission queue
		   SSCOP_RETRIEVE_TOTAL	   retrieve transmission buffer	and
					   queue

	     For signals that carry user data (as, for example,
	     SSCOP_DATA_request) these two fields are followed by the variable
	     sized user	data.

	     If	the upper hook is disconnected and the SSCOP instance is not
	     in	the idle state,	and the	lower hook is still connected, an
	     SSCOP_RELEASE_request is executed to release the SSCOP connec-
	     tion.

     manage  This is the management interface defined in the standard.	The
	     data structure used here is:

	     struct sscop_marg {
		     uint32_t sig;
		     u_char   data[];
	     };

	     Here sig is one of

	     enum sscop_maasig {
		 SSCOP_MDATA_request,	     /*	<- MU */
		 SSCOP_MDATA_indication,     /*	-> MU */
		 SSCOP_MERROR_indication,    /*	-> CODE, CNT */
	     };

	     The SSCOP_MDATA signals are followed by the actual	management
	     data, where the SSCOP_MERROR signal has the form:

	     struct sscop_merr {
		     uint32_t sig;
		     uint32_t err;   /*	error code */
		     uint32_t cnt;   /*	error count */
	     };

CONTROL	MESSAGES
     The sscop node understands	the generic control messages, plus the follow-
     ing:

     NGM_SSCOP_SETPARAM	(setparam)
	  Sets operational parameters of the SSCOP instance and	takes the fol-
	  lowing structure:

	  struct ng_sscop_setparam {
		  uint32_t		  mask;
		  struct sscop_param	  param;
	  };

	  The sub-structure param contains the parameters to set, and the mask
	  field	contains a bit mask, telling which of the parameters to	set,
	  and which to ignore.	If a bit is set, the corresponding parameter
	  is set.  The parameters are:

	  struct sscop_param {
		  uint32_t timer_cc;	  /* timer_cc in msec */
		  uint32_t timer_poll;	  /* timer_poll	im msec	*/
		  uint32_t timer_keep_alive;/* timer_keep_alive	in msec	*/
		  uint32_t timer_no_response;/*timer_no_response in msec */
		  uint32_t timer_idle;	  /* timer_idle	in msec	*/
		  uint32_t maxk;	  /* maximum user data in bytes	*/
		  uint32_t maxj;	  /* maximum u-u info in bytes */
		  uint32_t maxcc;	  /* max. retransmissions for control packets */
		  uint32_t maxpd;	  /* max. vt(pd) before	sending	poll */
		  uint32_t maxstat;	  /* max. number of elements in	stat list */
		  uint32_t mr;		  /* initial window */
		  uint32_t flags;	  /* flags */
	  };

	  The flags field contains the following flags influencing SSCOP oper-
	  ation:

		SSCOP_ROBUST   enable atmf/97-0216 robustness enhancement
		SSCOP_POLLREX  send POLL after each retransmission

	  The bitmap has the following bits:

		SSCOP_SET_TCC	   set timer_cc
		SSCOP_SET_TPOLL	   set timer_poll
		SSCOP_SET_TKA	   set timer_keep_alive
		SSCOP_SET_TNR	   set timer_no_response
		SSCOP_SET_TIDLE	   set timer_idle
		SSCOP_SET_MAXK	   set maxk
		SSCOP_SET_MAXJ	   set maxj
		SSCOP_SET_MAXCC	   set maxcc
		SSCOP_SET_MAXPD	   set maxpd
		SSCOP_SET_MAXSTAT  set maxstat
		SSCOP_SET_MR	   set the initial window
		SSCOP_SET_ROBUST   set or clear	SSCOP_ROBUST
		SSCOP_SET_POLLREX  set or clear	SSCOP_POLLREX

	  The node responds to the NGM_SSCOP_SETPARAM message with the follow-
	  ing response:

	  struct ng_sscop_setparam_resp	{
		  uint32_t mask;
		  int32_t  error;
	  };

	  Here mask contains a bitmask of the parameters that the user
	  requested to set, but	that could not be set and error	is an errno(2)
	  code describing why the parameter could not be set.

     NGM_SSCOP_GETPARAM	(getparam)
	  This message returns the current operational parameters of the SSCOP
	  instance in a	sscop_param structure.

     NGM_SSCOP_ENABLE (enable)
	  This message creates the actual SSCOP	instance and initializes it.
	  Until	this is	done, parameters may neither be	retrieved nor set, and
	  all messages received	on any hook are	discarded.

     NGM_SSCOP_DISABLE (disable)
	  Destroy the SSCOP instance.  After this, all messages	on any hooks
	  are discarded.

     NGM_SSCOP_SETDEBUG	(setdebug)
	  Set debugging	flags.	The argument is	a uint32_t.

     NGM_SSCOP_GETDEBUG	(getdebug)
	  Retrieve the actual debugging	flags.	Needs no arguments and
	  responds with	a uint32_t.

     NGM_SSCOP_GETSTATE	(getstate)
	  Responds with	the current state of the SSCOP instance	in a uint32_t.
	  If the node is not enabled, the retrieved state is 0.

FLOW CONTROL
     Flow control works	on the upper and on the	lower layer interface.	At the
     lower layer interface, the	two messages, NGM_HIGH_WATER_PASSED and
     NGM_LOW_WATER_PASSED, are used to declare or clear	the ``lower layer
     busy'' state of the protocol.

     At	the upper layer	interface, the sscop node handles three	types of flow
     control messages:

     NGM_HIGH_WATER_PASSED
	  If this message is received, the SSCOP stops moving the receive win-
	  dow.	Each time a data message is handed over	to the upper layer,
	  the receive window is	moved by one message.  Stopping	these updates
	  means	that the window	will start to close and	if the peer has	sent
	  all messages allowed by the current window, it stops transmission.
	  This means that the upper layer must be able to still	receive	a full
	  window amount	of messages.

     NGM_LOW_WATER_PASSED
	  This will re-enable the automatic window updates, and	if the space
	  indicated in the message is larger than the current window, the win-
	  dow will be opened by	that amount.  The space	is computed as the
	  difference of	the max_queuelen_packets and current members of	the
	  ngm_queue_state structure.

     NGM_SYNC_QUEUE_STATE
	  If the upper layer buffer filling state, as indicated	by current, is
	  equal	to or greater than high_watermark then the message is ignored.
	  If this is not the case, the amount of receiver space	is computed as
	  the difference of max_queuelen_packets and current if	automatic win-
	  dow updates are currently allowed, and as the	difference of
	  high_water_mark and current if window	updates	are disabled.  If the
	  resulting value is larger than the current window, the current win-
	  dow is opened	up to this value.  Automatic window updates are
	  enabled if they were disabled.

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

AUTHORS
     Harti Brandt <harti@FreeBSD.org>

FreeBSD	10.1		       October 24, 2003			  FreeBSD 10.1

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

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

home | help