Provided by: freebsd-manpages_12.2-1_all bug

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 (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 (getparam)
          This message returns the current operational parameters of the SSCOP instance in a
          sscop_param structure.

     NGM_SSCOP_ENABLE (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 (disable)
          Destroy the SSCOP instance.  After this, all messages on any hooks are discarded.

     NGM_SSCOP_SETDEBUG (setdebug)
          Set debugging flags.  The argument is a uint32_t.

     NGM_SSCOP_GETDEBUG (getdebug)
          Retrieve the actual debugging flags.  Needs no arguments and responds with a uint32_t.

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