1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
|
.\"
.\" Copyright (c) 2001-2003
.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
.\" All rights reserved.
.\"
.\" Author: Hartmut Brandt <harti@freebsd.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd October 6, 2003
.Dt NG_UNI 4
.Os
.Sh NAME
.Nm ng_uni
.Nd netgraph UNI node type
.Sh SYNOPSIS
.In netnatm/sig/unidef.h
.In netgraph/atm/ng_uni.h
.Sh DESCIPTION
The
.Nm
netgraph node implements ATM Forum signalling 4.0.
.Pp
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.
.Pp
The node is shutdown either by a
.Dv NGM_SHUTDOWN
message or when all hooks are disconnected.
.Sh HOOKS
Each
.Nm
node has three hooks with fixed names:
.Bl -tag -width xxx
.It Dv 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
.Xr ng_sscfu 4
at this hook.
.It Dv upper
This hook is the
.Ql 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
.Xr ng_ccatm 4
or a switch CAC should be stacked at this interface.
The message format at the
.Dv upper
hook is described below.
Because
.Xt netgraph 4
is functional, it makes sometimes sense to switch this hook to queueing mode
from the peer node upon connection.
.El
.Pp
The
.Dv upper
interface of the
.Nm
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 setup a connection.
It may do it by sending a
.Dv 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.
.Pp
The
.Dv upper
interface uses the following structure:
.Bd -literal
struct uni_arg {
uint32_t sig;
uint32_t cookie;
u_char data[];
};
.Ed
The
.Fa sig
field contains the actual signal that is sent from the user to UNI or the
UNI to the user.
The
.Fa 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
.Fa cookie
field is followed by the actual data for the signal.
.Pp
The signal is one of the following:
.Bd -literal
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
};
.Ed
.Pp
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:
.Bl -tag -width xxx
.It Dv UNIAPI_ERROR
This is the error response, mentioned earlier.
It carries an error code or
zero, if the signal was accepted by the stack.
.It Dv 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.
.It Dv UNIAPI_CALL_DESTROYED
An call instance has been destroyed and all resources have been freed.
.It Dv 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.
.It Dv UNIAPI_PARTY_DESTROYED
A party has been destroyed and all resources have been freed.
.It Dv UNIAPI_ABORT_CALL_request
The requests the stack to destroy the call instance and free all it's resources
without sending any messages to the network.
.It Dv UNIAPI_MAXSIG
This is not a signal, but rather a definition to get the number of defined
signals.
.El
.Pp
Each of the signals is followed by a fixed size structure defined in
.Pa unidef.h .
.Sh CONTROL MESSAGES
The
.Nm
node understands the standard control messages plus the following:
.Bl -tag -width xxx
.It Dv NGM_UNI_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:
.Bd -literal
struct ngm_uni_debug {
uint32_t level[UNI_MAXFACILITY];
};
.Ed
.It Dv NGM_UNI_SETDEBUG
Get debugging facility levels.
This returns a
.Fa ngm_uni_debug
structure.
.It Dv NGM_UNI_GET_CONFIG
Retrieve the current configuration of the UNI instance.
This message returns a
.Fa uni_config
structure:
.Bd -literal
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 */
};
.Ed
.Pp
The field
.Fa proto
specifies one of the following protocols:
.Bd -literal
enum uni_proto {
UNIPROTO_UNI40U, /* UNI4.0 user side */
UNIPROTO_UNI40N, /* UNI4.0 network side */
UNIPROTO_PNNI10, /* PNNI1.0 */
};
.Ed
.Pp
Some protocols may have options which can be set in
.Fa popt :
.Bd -literal
enum uni_popt {
UNIPROTO_GFP, /* enable GFP */
};
.Ed
.Pp
The
.Fa option
field controls parsing and checking of messages:
.Bd -literal
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 */
};
.Ed
.Pp
All timer values are given in milliseconds.
Note, however, that the actual
resolution of the timers depend on system configuration (see
.Xr timeout 9 ).
.It Dv NGM_UNI_SET_CONFIG
Change the UNI configuration.
This takes a
.Bd -literal
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;
};
.Ed
.Pp
The fields of the
.Fa ngm_uni_config_mask
specify which configuration parameter to change.
The
.Fa mask
field contains bit definitions for all timers, retransmission counters
and the
.Fa proto
field,
.Fa popt_mask
selects which of the protocol options to change and
.Fa option_mask
specifies which options should be changed.
The following bits are defined:
.Bd -literal
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,
};
.Ed
.Pp
For the
.Fa popt_mask
and
.Fa option_mask
the definitions from
.Fa "enum uni_popt"
and
.Fa "enum uni_option"
should be used.
.It Dv NGM_UNI_ENABLE
Create the UNI instance and enable processing.
Before the UNI is enabled parameters cannot be retrieved or set.
.It Dv NGM_UNI_DISABLE
Destroy the UNI instance and free all resources.
Note, that connections are not released.
.El
.Sh SEE ALSO
.Xr netgraph 4 ,
.Xr ng_atm 4 ,
.Xr ng_sscfu 4 ,
.Xr ng_sscop 4 ,
.Xr ngctl 8
.Sh BUGS
.Bl -bullet -compact
.It
LIJ (leaf-initiated-join) is not implemented yet.
.It
GFP (generic functional protocol, Q.2932.1) is not yet implemented.
.It
More testing needed.
.It
PNNI not yet implemented.
.It
Need to implement connection modification and the Q.2931 amendments.
.Sh AUTHORS
The
.Nm
netgraph node
and this manual page was written by
.An Harti Brandt Aq harti@freebsd.org
|