NG_SSCOP(4)

🌸 NAME 🌸

ng_sscop — netgraph SSCOP node type 💖 (yes bestie, we're in the Kernel Interfaces Manual, section 4, and this page is about the sscop netgraph node type, periodt)

---

✨ SYNOPSIS ✨

#include <netnatm/saal/sscopdef.h>
#include <netgraph/atm/ng_sscop.h>

---

🦋 DESCRIPTION 🦋

Okay so the sscop netgraph node type implements the ITU-T standard Q.2110. That standard describes the so-called Service Specific Connection Oriented Protocol (SSCOP), which is what carries signalling messages over the private and public UNIs and the public NNI. It's a transport protocol with selective acknowledgements, and it can be tailored to the environment. And this implementation? Full implementation of that standard. No shortcuts. Iconic behavior only. 👑

After you create the node, the SSCOP instance itself doesn't exist yet — you have to send an enable message to the node to actually bring it to life. Once the node is enabled, you can retrieve and modify the SSCOP parameters and start the protocol. Vibe check passed ✅

The node gets shut down either by a NGM_SHUTDOWN message, or when all hooks are disconnected. Either way, it's gone, bestie. 💀

---

🎀 HOOKS 🎀

Every sscop node has three hooks, and their names are fixed (no renaming, no negotiating, they are what they are):

• lower — this hook has to be connected to a node that ensures transport of packets to and from the remote peer node. Normally that's an ng_atm(4) node with an AAL5 hook, but honestly the sscop node can work on any packet-transporting layer — like, for example, IP or UDP. She's flexible. 💅 The node handles flow control messages received on this hook: if it receives an NGM_HIGH_WATER_PASSED message, it declares the "lower layer busy" state. If it receives an NGM_LOW_WATER_PASSED message, that busy state gets cleared. Note that the node does not look at the message contents of these flow control messages — it just vibes off the message type.
• upper — this is the interface to the SSCOP user. And 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 comments show the direction of the signal — whether it's a signal that comes out of the node (->) or is sent by the node user to the node (<-). The arg field holds the argument to some of the signals: it's either a PDU sequence number, or the CLEAR-BUFFER flag. And there are a few 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 (like, for example, SSCOP_DATA_request), those two fields are followed by the variable-sized user data. 🍓

And heads up: if the upper hook gets disconnected while 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. She cleans up after herself.

• 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. It 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 that tells 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) — destroys the SSCOP instance. After this, all messages on any hooks are discarded.
• NGM_SSCOP_SETDEBUG (setdebug) — sets debugging flags. The argument is a uint32_t.
• NGM_SSCOP_GETDEBUG (getdebug) — retrieves 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 the window will start to close, and if the peer has sent all messages allowed by the current window, it stops transmission. Which means the upper layer must be able to still receive a full window's worth of messages. No pressure or anything. 😭
• NGM_LOW_WATER_PASSED — this re-enables 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 that's 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. Slay. ✨

---

🫶 SEE ALSO 🫶

netgraph(4), ng_atm(4), ng_sscfu(4), ngctl(8)

---

👑 AUTHORS 👑

Harti Brandt <harti@FreeBSD.org>

---

And that's the whole page, bestie — this one shipped out of Debian on October 24, 2003, so shoutout to the Debian crew for keeping the lore alive. Study it, love it, go connect some hooks. 💖🦋🌸