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

FreeBSD 11.0-PRERELEASE        October 24, 2003        FreeBSD 11.0-PRERELEASE

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

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

home | help