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 private and public UNIs and the public NNI. This protocol is a

transport
protocol with selective acknowledgements, and can be tai

lored to the
environment. This implementation is a full implementation

of that standard.

After creation of the node, the SSCOP instance must be cre

ated 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 en

sures 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 con

trol 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 op

erations:

SSCOP_MAXSEQNO maximum legal

sequence num

ber

SSCOP_RETRIEVE_UNKNOWN retrieve

transmission queue
SSCOP_RETRIEVE_TOTAL retrieve

transmission

buffer and

queue

For signals that carry user data (as, for exam

ple,
SSCOP_DATA_request) these two fields are fol

lowed 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 ac

tual 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_re

sponse 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. retransmis

sions for control packets */
uint32_t maxpd; /* max. vt(pd) be

fore 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 influ

encing SSCOP
operation:

SSCOP_ROBUST enable atmf/97-0216 robust

ness enhance

ment

SSCOP_POLLREX send POLL after each re

transmission

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_RO

BUST
SSCOP_SET_POLLREX set or clear SS

COP_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 parame

ters 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 dis

carded.

NGM_SSCOP_DISABLE

Destroy the SSCOP instance. After this, all mes

sages 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 argu

ments and
responds with a uint32_t.

NGM_SSCOP_GETSTATE

Responds with the current state of the SSCOP in

stance 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 in

terface. At the
lower layer interface, the two messages, NGM_HIGH_WA

TER_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 cur

rent 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 indicat

ed by current,
is equal to or greater than high_watermark then the

message is
ignored. If this is not the case, the amount of re

ceiver 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>

BSD October 24, 2003

BSD