ng_uni(4)

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 trans
port 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 af
ter 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 ap
plication
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 RE
LEASE, 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 mes
sage 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 sig
nal 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 re
sponse, a confirmation or an indication was triggered by a request or re
sponse, the
cookie from that request or response is carried in the mes
sage from the
stack to the user. The cookie field is followed by the ac
tual 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 implementa
tion:
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 us
er.
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

CONTROL MESSAGES

The uni node understands the standard control messages, plus
the following:
NGM_UNI_SETDEBUG
Set debugging facility levels. The UNI stack de
fines a number of
debugging facilities, each one associated with a de
bugging 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_SETDEBUG
Get debugging facility levels. This returns an
ngm_uni_debug
structure.
NGM_UNI_GET_CONFIG
Retrieve the current configuration of the UNI in
stance. 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 retransmis
sion count */
uint32_t timer308; /* T308 */
uint32_t init308; /* T308 retransmis
sion count */
uint32_t timer309; /* T309 */
uint32_t timer310; /* T310 */
uint32_t timer313; /* T313 */
uint32_t timer316; /* T316 */
uint32_t init316; /* T316 retransmis
sion count */
uint32_t timer317; /* T317 */
uint32_t timer322; /* T322 */
uint32_t init322; /* T322 retransmis
sion count */
uint32_t timer397; /* T397 */
uint32_t timer398; /* T398 */
uint32_t timer399; /* T399 */
};
The field proto specifies one of the following pro
tocols:
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
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
Create the UNI instance and enable processing. Be
fore the UNI is
enabled parameters cannot be retrieved or set.
NGM_UNI_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

+o LIJ (leaf-initiated-join) is not implemented yet.
+o GFP (generic functional protocol, Q.2932.1) is not yet
implemented.
+o More testing needed.
+o PNNI not yet implemented.
+o Need to implement connection modification and the Q.2931
amendments.
BSD October 6, 2003
Copyright © 2010-2019 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout