Provided by: freebsd-manpages_11.1-3_all bug

NAME

     ng_uni — netgraph UNI node type

SYNOPSIS

     #include <netnatm/msg/unistruct.h>
     #include <netnatm/sig/unidef.h>
     #include <netgraph/atm/ng_uni.h>

DESCRIPTION

     The uni netgraph node type implements ATM Forum signalling 4.0.

     After creation of the node, the UNI instance must be created by sending an “enable” message
     to the node.  If the node is enabled, the UNI parameters can be retrieved and modified, and
     the protocol can be started.

     The node is shut down either by an NGM_SHUTDOWN message, or when all hooks are disconnected.

HOOKS

     Each uni node has three hooks with fixed names:

     lower  This hook is the interface of the UNI protocol to the transport layer of the ATM
            control plane.  The node expects the interface exported by ng_sscfu(4) at this hook.

     upper  This hook is the “user” interface of the UNI protocol.  Because there is no
            standardized interface at this point, this implementation follows more or less the
            interface specified by the SDL diagrams in ITU-T recommendations Q.2931 and Q.2971.
            Normally either a ng_ccatm(4) or a switch CAC should be stacked at this interface.
            The message format at the upper hook is described below.  Because netgraph(4) is
            functional, it makes sometimes sense to switch this hook to queueing mode from the
            peer node upon connection.

     The upper interface of the uni node is loosely modelled after the interface specified in the
     ITU-T signalling standards.  There is however one derivation from this: normally there
     exists four kinds of signals: requests, responses, indications and confirmations.  These
     signals are usually triggered either by external events (receiving a message) or internal
     events (a timer or another signal).  This scheme works fine for user APIs that are entirely
     asynchronous, and in cases where error handling is not taken into account.  With synchronous
     APIs and error handling however, there is a problem.  If, for example, the application
     issues a request to set up a connection, it may do it by sending a SETUP.request signal to
     the UNI.  Normally, the UNI stack will send a SETUP message and receive a message from the
     switch (a RELEASE, CONNECT, CALL PROCEEDING or ALERTING), or a timer in the UNI stack will
     time out.  In any of these cases, the UNI stack is supposed to report an event back to the
     application, and the application will unblock (in the case of a synchronous API) and handle
     the event.  The problem occurs when an error happens.  Suppose there is no memory to send
     the SETUP message and to start the timer.  In this case, the application will block forever
     because no received message and no timer will wake it up.  For this reason this
     implementation uses an additional message: for each signal sent from the application to the
     stack, the stack will respond with an error code.  If this code is zero, the stack has
     accepted the signal and the application may block; if the code is non-zero, the signal is
     effectively ignored and the code describes what was wrong.  This system makes it very easy
     to make a blocking interface out of the message based netgraph interface.

     The upper interface uses the following structure:

     struct uni_arg {
             uint32_t        sig;
             uint32_t        cookie;
             u_char          data[];
     };
     The sig field contains the actual signal that is sent from the user to UNI or from UNI to
     the user.  The cookie can be used by the user to correlate requests with events and
     responses.  If an error response, a confirmation or an indication was triggered by a request
     or response, the cookie from that request or response is carried in the message from the
     stack to the user.  The cookie field is followed by the actual data for the signal.

     The signal is one of the following:

     enum uni_sig {
         UNIAPI_ERROR,                       /* UNI -> API */

         UNIAPI_CALL_CREATED,                /* UNI -> API */
         UNIAPI_CALL_DESTROYED,              /* UNI -> API */
         UNIAPI_PARTY_CREATED,               /* UNI -> API */
         UNIAPI_PARTY_DESTROYED,             /* UNI -> API */

         UNIAPI_LINK_ESTABLISH_request,      /* API -> UNI */
         UNIAPI_LINK_ESTABLISH_confirm,      /* UNI -> API */
         UNIAPI_LINK_RELEASE_request,        /* API -> UNI */
         UNIAPI_LINK_RELEASE_confirm,        /* UNI -> API */

         UNIAPI_RESET_request,               /* API -> UNI */
         UNIAPI_RESET_confirm,               /* UNI -> API */
         UNIAPI_RESET_indication,            /* UNI -> API */
         UNIAPI_RESET_ERROR_indication,      /* UNI -> API */
         UNIAPI_RESET_response,              /* API -> UNI */
         UNIAPI_RESET_ERROR_response,        /* API -> UNI */
         UNIAPI_RESET_STATUS_indication,     /* UNI -> API */

         UNIAPI_SETUP_request,               /* API -> UNI */
         UNIAPI_SETUP_indication,            /* UNI -> API */
         UNIAPI_SETUP_response,              /* API -> UNI */
         UNIAPI_SETUP_confirm,               /* UNI -> API */
         UNIAPI_SETUP_COMPLETE_indication,   /* UNI -> API */
         UNIAPI_ALERTING_request,            /* API -> UNI */
         UNIAPI_ALERTING_indication,         /* UNI -> API */
         UNIAPI_PROCEEDING_request,          /* API -> UNI */
         UNIAPI_PROCEEDING_indication,       /* UNI -> API */
         UNIAPI_RELEASE_request,             /* API -> UNI */
         UNIAPI_RELEASE_indication,          /* UNI -> API */
         UNIAPI_RELEASE_response,            /* API -> UNI */
         UNIAPI_RELEASE_confirm,             /* UNI -> API */
         UNIAPI_NOTIFY_request,              /* API -> UNI */
         UNIAPI_NOTIFY_indication,           /* UNI -> API */
         UNIAPI_STATUS_indication,           /* UNI -> API */
         UNIAPI_STATUS_ENQUIRY_request,      /* API -> UNI */

         UNIAPI_ADD_PARTY_request,           /* API -> UNI */
         UNIAPI_ADD_PARTY_indication,        /* UNI -> API */
         UNIAPI_PARTY_ALERTING_request,      /* API -> UNI */
         UNIAPI_PARTY_ALERTING_indication,   /* UNI -> API */
         UNIAPI_ADD_PARTY_ACK_request,       /* API -> UNI */
         UNIAPI_ADD_PARTY_ACK_indication,    /* UNI -> API */
         UNIAPI_ADD_PARTY_REJ_request,       /* API -> UNI */
         UNIAPI_ADD_PARTY_REJ_indication,    /* UNI -> API */
         UNIAPI_DROP_PARTY_request,          /* API -> UNI */
         UNIAPI_DROP_PARTY_indication,       /* UNI -> API */
         UNIAPI_DROP_PARTY_ACK_request,      /* API -> UNI */
         UNIAPI_DROP_PARTY_ACK_indication,   /* UNI -> API */

         UNIAPI_ABORT_CALL_request,          /* API -> UNI */

         UNIAPI_MAXSIG
     };

     The meaning of most of the signals can be deduced from the ITU-T SDLs.  A number of signals,
     however, is unique to this implementation:

     UNIAPI_ERROR
          This is the error response, mentioned earlier.  It carries an error code or zero, if
          the signal was accepted by the stack.

     UNIAPI_CALL_CREATED
          The UNI stack has created a call instance either from an incoming SETUP or from the
          user requesting an outgoing SETUP.  This may be used to synchronize the creation and
          destroying of call data between the UNI stack and the user.

     UNIAPI_CALL_DESTROYED
          A call instance has been destroyed and all resources have been freed.

     UNIAPI_PARTY_CREATED
          A new party has been created for an existing point-to-multipoint call.  This may be
          used to synchronize the creation and destroying of party data between the UNI stack and
          the user.

     UNIAPI_PARTY_DESTROYED
          A party has been destroyed and all resources have been freed.

     UNIAPI_ABORT_CALL_request
          This requests the stack to destroy the call instance and free all its resources,
          without sending any messages to the network.

     UNIAPI_MAXSIG
          This is not a signal, but rather a definition to get the number of defined signals.

     Each of the signals is followed by a fixed size structure defined in <netnatm/sig/unidef.h>.

CONTROL MESSAGES

     The uni node understands the standard control messages, plus the following:

     NGM_UNI_SETDEBUG (setdebug)
          Set debugging facility levels.  The UNI stack defines a number of debugging facilities,
          each one associated with a debugging level.  If the debugging level of a facility is
          non-zero, text output will be generated to the console.  The message uses the following
          structure:

          struct ngm_uni_debug {
                  uint32_t        level[UNI_MAXFACILITY];
          };

     NGM_UNI_GETDEBUG (getdebug)
          Get debugging facility levels.  This returns an ngm_uni_debug structure.

     NGM_UNI_GET_CONFIG (get_config)
          Retrieve the current configuration of the UNI instance.  This message returns a
          uni_config structure:

          struct uni_config {
                  uint32_t proto;         /* which protocol */
                  uint32_t popt;          /* protocol option */
                  uint32_t option;        /* other options */
                  uint32_t timer301;      /* T301 */
                  uint32_t timer303;      /* T303 */
                  uint32_t init303;       /* T303 retransmission count */
                  uint32_t timer308;      /* T308 */
                  uint32_t init308;       /* T308 retransmission count */
                  uint32_t timer309;      /* T309 */
                  uint32_t timer310;      /* T310 */
                  uint32_t timer313;      /* T313 */
                  uint32_t timer316;      /* T316 */
                  uint32_t init316;       /* T316 retransmission count */
                  uint32_t timer317;      /* T317 */
                  uint32_t timer322;      /* T322 */
                  uint32_t init322;       /* T322 retransmission count */
                  uint32_t timer397;      /* T397 */
                  uint32_t timer398;      /* T398 */
                  uint32_t timer399;      /* T399 */
          };

          The field proto specifies one of the following protocols:

          enum uni_proto {
                  UNIPROTO_UNI40U,        /* UNI4.0 user side */
                  UNIPROTO_UNI40N,        /* UNI4.0 network side */
                  UNIPROTO_PNNI10,        /* PNNI1.0 */
          };

          Some protocols may have options which can be set in popt:

          enum uni_popt {
                  UNIPROTO_GFP,           /* enable GFP */
          };

          The option field controls parsing and checking of messages:

          enum uni_option {
                  UNIOPT_GIT_HARD,        /* harder check of GIT IE */
                  UNIOPT_BEARER_HARD,     /* harder check of BEARER IE */
                  UNIOPT_CAUSE_HARD,      /* harder check of CAUSE IE */
          };

          All timer values are given in milliseconds.  Note, however, that the actual resolution
          of the timers depend on system configuration (see timeout(9)).

     NGM_UNI_SET_CONFIG (set_config)
          Change the UNI configuration.  This takes a

          struct ngm_uni_set_config {
                  struct uni_config               config;
                  struct ngm_uni_config_mask      mask;
          };
          struct ngm_uni_config_mask {
                  uint32_t        mask;
                  uint32_t        popt_mask;
                  uint32_t        option_mask;
          };

          The fields of the ngm_uni_config_mask specify which configuration parameter to change.
          The mask field contains bit definitions for all timers, retransmission counters and the
          proto field, popt_mask selects which of the protocol options to change, and option_mask
          specifies which options should be changed.  The following bits are defined:

          enum uni_config_mask {
                  UNICFG_PROTO,
                  UNICFG_TIMER301,
                  UNICFG_TIMER303,
                  UNICFG_INIT303,
                  UNICFG_TIMER308,
                  UNICFG_INIT308,
                  UNICFG_TIMER309,
                  UNICFG_TIMER310,
                  UNICFG_TIMER313,
                  UNICFG_TIMER316,
                  UNICFG_INIT316,
                  UNICFG_TIMER317,
                  UNICFG_TIMER322,
                  UNICFG_INIT322,
                  UNICFG_TIMER397,
                  UNICFG_TIMER398,
                  UNICFG_TIMER399,
          };

          For popt_mask and option_mask, the definitions from enum uni_popt and enum uni_option
          should be used.

     NGM_UNI_ENABLE (enable)
          Create the UNI instance and enable processing.  Before the UNI is enabled parameters
          cannot be retrieved or set.

     NGM_UNI_DISABLE (disable)
          Destroy the UNI instance and free all resources.  Note, that connections are not
          released.

SEE ALSO

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

AUTHORS

     The uni netgraph node and this manual page were written by Harti Brandt <harti@FreeBSD.org>

BUGS

        LIJ (leaf-initiated-join) is not implemented yet.
        GFP (generic functional protocol, Q.2932.1) is not yet implemented.
        More testing needed.
        PNNI not yet implemented.
        Need to implement connection modification and the Q.2931 amendments.