Man pages for the NgATM SAAL protocol nodes.

1 files changed, 355 insertions, 0 deletions

diff --git a/share/man/man4/ng_sscop.4 b/share/man/man4/ng_sscop.4
new file mode 100644
index 000000000000..4beb9d53ae42
--- /dev/null
+++ b/share/man/man4/ng_sscop.4
@@ -0,0 +1,355 @@
+.\"
+.\" Copyright (c) 2001-2003
+.\"	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
+.\" 	All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" Author: Hartmut Brandt <harti@freebsd.org>
+.\"
+.\" $FreeBSD$
+.\"
+.\" ng_sscop(4) man page
+.\"
+.Dd October 24, 2003
+.Dt ng_sscop 4
+.Os FreeBSD
+.Sh NAME
+.Nm ng_sscop
+.Nd netgraph SSCOP node type
+.Sh SYNOPSIS
+.Fd #include <netnatm/saal/sscopdef.h>
+.Fd #include <netgraph/atm/ng_sscop.h>
+.Sh DESCIPTION
+The
+.Nm
+netgraph node 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 private 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 standard.
+.Pp
+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.
+.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 manage
+.It Dv lower
+This hook is the hook that must be connected to a node that ensures
+transport of packets to and from the remote peer node. Normally this is a
+.Xr ng_atm 4
+node with an AAL5 hook, but the
+.Nm
+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
+.Dv NGM_HIGH_WATER_PASSED
+message it declares the
+.Ql lower layer busy
+state.
+If a
+.Dv NGM_LOW_WATER_PASSED
+message is received the busy state is cleared.
+Note, that the node does not
+look at the message contents of these flow control messages.
+.It Dv upper
+This is the interface to the SSCOP user.
+This interface uses the following message format:
+.Bd -literal
+struct sscop_arg {
+	uint32_t sig;
+	uint32_t arg;	/* opt. sequence number or clear-buff */
+	u_char	 data[];
+};
+.Ed
+.Pp
+.Fa sig
+is one of the signals defined in the standard:
+.Bd -literal
+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,/* -> */
+};
+.Ed
+.Pp
+The arrows in the comment show the direction of the signal whether it
+is a signal that comes out of the node
+.Ql ->
+or is sent by the node user to the node
+.Ql <- .
+The
+.Fa arg
+field contains the argument to some of the signals: it is either a PDU
+sequence number or the
+.Dv CLEAR-BUFFER
+flag.
+There are a number of special sequence numbers for some operations:
+.Bl -column SSCOP_RETRIEVE_UNKNOWN -offset indent
+.It Dv SSCOP_MAXSEQNO Ta maximum legal sequence number
+.It Dv SSCOP_RETRIEVE_UNKNOWN Ta retrieve transmission queue
+.It Dv SSCOP_RETRIEVE_TOTAL Ta retrieve transmission buffer and queue
+.El
+.Pp
+For signals that carry user data (as, for example,
+.Dv SSCOP_DATA_request )
+these two fields are followed by the variable sized user data.
+.Pp
+If the upper hook is disconnected and the SSCOP instance is not in the idle
+state and the lower hook is still connected, an
+.Dv SSCOP_RELEASE_request
+is executed to release the SSCOP connection.
+.It Dv manage
+This is the management interface defined in the standard. 
+The data structure used here is:
+.Bd -literal
+struct sscop_marg {
+	uint32_t sig;
+	u_char	 data[];
+};
+.Ed
+.Pp
+Here
+.Dv sig
+is one of
+.Bd -literal
+enum sscop_maasig {
+    SSCOP_MDATA_request,	/* <- MU */
+    SSCOP_MDATA_indication,	/* -> MU */
+    SSCOP_MERROR_indication,	/* -> CODE, CNT */
+};
+.Ed
+.Pp
+The
+.Dv SSCOP_MDATA
+signals are followed by the actual management data, where the
+.Dv SSCOP_MERROR
+signal has the form:
+.Bd -literal
+struct sscop_merr {
+	uint32_t sig;
+	uint32_t err;	/* error code */
+	uint32_t cnt;	/* error count */
+};
+.Ed
+.Sh CONTROL MESSAGES
+The
+.Nm
+node understands the generic messages plus the following:
+.Bl -tag -width xxx
+.It Dv NGM_SSCOP_SETPARAM 
+Set operational parameters of the SSCOP instance and takes the
+following structure:
+.Bd -literal
+struct ng_sscop_setparam {
+	uint32_t		mask;
+	struct sscop_param	param;
+};
+.Ed
+.Pp
+The sub-structure
+.Dv param
+contains the parameters to set and the
+.Dv 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:
+.Bd -literal
+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 */
+};
+.Ed
+.Pp
+The
+.Dv flags
+field contains the following flags influencing SSCOP operation:
+.Bl -column SSCOP_POLLREX -offset indent
+.It Dv SSCOP_ROBUST Ta enable atmf/97-0216 robustness enhancement
+.It Dv SSCOP_POLLREX Ta send POLL after each retransmission
+.El
+.Pp
+The bitmap has the following bits:
+.Bl -column SSCOP_POLLREXx -offset indent
+.It Dv SSCOP_SET_TCC Ta set Dv timer_cc
+.It Dv SSCOP_SET_TPOLL Ta set Dv timer_poll
+.It Dv SSCOP_SET_TKA Ta set Dv timer_keep_alive
+.It Dv SSCOP_SET_TNR Ta set Dv timer_no_response
+.It Dv SSCOP_SET_TIDLE Ta set Dv timer_idle
+.It Dv SSCOP_SET_MAXK Ta set Dv maxk
+.It Dv SSCOP_SET_MAXJ Ta set Dv maxj
+.It Dv SSCOP_SET_MAXCC Ta set Dv maxcc
+.It Dv SSCOP_SET_MAXPD Ta set Dv maxpd
+.It Dv SSCOP_SET_MAXSTAT Ta set Dv maxstat
+.It Dv SSCOP_SET_MR Ta set the initial window
+.It Dv SSCOP_SET_ROBUST Ta set or clear Dv SSCOP_ROBUST
+.It Dv SSCOP_SET_POLLREX Ta set or clear Dv SSCOP_POLLREX
+.El
+.Pp
+The node responds to the
+.Dv NGM_SSCOP_SETPARAM
+message with the following response:
+.Bd -literal
+struct ng_sscop_setparam_resp {
+	uint32_t mask;
+	int32_t	 error;
+};
+.Ed
+.Pp
+Here
+.Dv mask
+contains the a bitmask of the parameters that the user requested to set,
+but that could not be set and
+.Dv error
+is an
+.Xr errno 3
+code describing why the parameter could not be set.
+.It Dv NGM_SSCOP_GETPARAM 
+This message returns the current operational parameters of the SSCOP
+instance in a
+.Fa sscop_param
+structure.
+.It Dv NGM_SSCOP_ENABLE 
+This message creates the actual SSCOP instance and initializes it.
+Until this is done, parameters may neither be retrieved not set and all
+message received on any hook are discarded.
+.It Dv NGM_SSCOP_DISABLE 
+Destroy the SSCOP instance. After this all messages on any hooks are
+discarded.
+.It Dv NGM_SSCOP_SETDEBUG
+Set debugging flags. The argument is an
+.Vt uint32_t .
+.It Dv NGM_SSCOP_GETDEBUG
+Retrieve the actual debugging flags.
+Needs no arguments and responds with an
+.Vt uint32_t .
+.It Dv NGM_SSCOP_GETSTATE
+Responds with the current state of the SSCOP instance in an
+.Vt uint32_t .
+If the node is not enabled the retrieved state is 0.
+.El
+.Sh FLOW CONTROL
+Flow control works on the upper and on the lower layer interface. At the lower
+layer interface the two messages
+.Dv NGM_HIGH_WATER_PASSED
+and
+.Dv NGM_LOW_WATER_PASSED
+are used to declare or clear the
+.Ql lower layer busy
+state of the protocol.
+.Pp
+At the upper layer interface the
+.Nm
+node handles three types of flow control messages:
+.Bl -tag -width xxx
+.It Dv NGM_HIGH_WATER_PASSED
+If this message is received the SSCOP stops moving the receive window.
+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 receive still a full window
+amount of messages.
+.It Dv 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 window will be opened
+by that amount.
+The space is computed as the difference of the
+.Fa max_queuelen_packets
+and
+.Fa current
+members of the 
+.Fa ngm_queue_state
+structure.
+.It Dv NGM_SYNC_QUEUE_STATE
+If the upper layer buffer filling state as indicated by
+.Fa current
+is equal too or higher than
+.Fa high_watermark
+than the message is ignored.
+If this is not the case the amount
+of receiver space is computed as the difference of
+.Fa max_queuelen_packets
+and
+.Fa current ,
+if automatic window updates are currently allowed and as the difference of
+.Fa high_water_mark
+and
+.Fa current ,
+if window updates are disabled.
+If the resulting value is larger than the current window, the current window
+is opened up to this value.
+Automatic window updates are enabled, if they
+were disabled.
+.Sh SEE ALSO
+.Xr netgraph 4 ,
+.Xr ng_atm 4 ,
+.Xr ng_sscfu 4 ,
+.Xr ngctl 8
+.Sh AUTHORS
+.An Harti Brandt Aq harti@freebsd.org