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
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.
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
message is received, the busy
state is cleared. Note that the node does not look at the message contents
of these flow control messages.
- 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 connection.
- 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 following:
NGM_SSCOP_SETPARAM
- Sets operational parameters of the SSCOP instance and takes
the following 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 operation:
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 following 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
- This message returns the current operational parameters of
the SSCOP instance in a sscop_param structure.
NGM_SSCOP_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
- Destroy the SSCOP instance. After this, all messages on any
hooks are discarded.
NGM_SSCOP_SETDEBUG
- Set debugging flags. The argument is a
uint32_t.
NGM_SSCOP_GETDEBUG
- Retrieve the actual debugging flags. Needs no arguments and
responds with a uint32_t.
NGM_SSCOP_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 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 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
window 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 window 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 window 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⟩