356 lines
11 KiB
Groff
356 lines
11 KiB
Groff
.\"
|
|
.\" 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
|