aboutsummaryrefslogtreecommitdiff
path: root/share/man/man4/ng_ccatm.4
blob: 02a5a5f011b58c3388dd97afc044461049a42a06 (plain) (blame)
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
.\"
.\" Copyright (c) 2001-2004
.\"	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
.\"	All rights reserved.
.\" Copyright (c) 2005
.\"	Hartmut Brandt.
.\"	All rights reserved.
.\"
.\" Author: Harti 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 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 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 March 3, 2023
.Dt NG_CCATM 4
.Os
.Sh NAME
.Nm ng_ccatm
.Nd "ATM Call Control netgraph node type"
.Sh SYNOPSIS
.In netnatm/unimsg.h
.In netnatm/msg/unistruct.h
.In netnatm/sig/unidef.h
.In netnatm/api/unisap.h
.In netnatm/api/atmapi.h
.In netnatm/api/ccatm.h
.In netgraph.h
.In netgraph/ng_uni.h
.In netgraph/ng_ccatm.h
.Sh DEPRECATION NOTICE
.Nm
is deprecated and may not be available in
.Fx 14.0
and later.
.Sh DESCRIPTION
The
.Nm
node implements the API specified by the ATM Forum for access to ATM services
(see ATM-Forum document
.Pa af-saa-0108 ) .
This document specifies the semantics
of the API, not the exact language binding.
For this reason, it is expected that
this implementation is neither compile-time nor binary compatible with
other implementations of this API.
It should, however, be fairly straightforward
to convert between different API implementations.
.Pp
This node is usually stacked on top of one or more UNI nodes (see
.Xr ng_uni 4 ) .
Each of these hooks appears as a
.Dq port
to the user of the node.
It also has one hook connected to the ILMI daemon for management purposes.
.Pp
The node is removed when it receives a
.Dv NGM_SHUTDOWN
messages or when all hooks are disconnected.
.Sh HOOKS
The node understands a number of hooks with predefined names and an
unlimited number of hooks for user connections.
The predefined names are:
.Bl -tag -width ".Va orphans"
.It Va uni Ns Ar NNN
These hooks stack the
.Nm
node on top of a UNI stack.
The node expects the interface on these hooks
to conform to the upper interface specified in
.Xr ng_uni 4 .
These hooks are forced into queuing mode, so that there are no circular
calls from call control to UNI and UNI back to call control.
The
.Ar NNN
in the hook name is the decimal port number and should not be zero.
The port number is a 32-bit unsigned integer.
.It Va manage
This hook should be connected to the ILMI daemon.
No data is ever sent on this hook and all received data is discarded.
The hook is used to send control messages along.
.It Va dump
On receipt of a
.Dv NGM_CCATM_DUMP
command a textual description of the current state of the node is sent
out of this hook.
This text is sent as one large message consisting of more
than one
.Vt mbuf .
.El
.Pp
All other hook names are taken to be user hooks and correspond to an
ATM endpoint as specified in the ATM Forum document.
The interface on these hooks is defined in
.In atmapi.h
and uses a structure
.Bd -literal
struct ccatm_op {
	uint32_t	op;	/* request code */
	u_char		data[];	/* optional data */
};
.Ed
.Pp
This structure is followed directly by the data for the operation.
The opcode is one of the following:
.Bd -literal
enum atmop {
	ATMOP_RESP,
	ATMOP_ABORT_CONNECTION,
	ATMOP_ACCEPT_INCOMING_CALL,
	ATMOP_ADD_PARTY,
	ATMOP_ADD_PARTY_REJECT,
	ATMOP_ADD_PARTY_SUCCESS,
	ATMOP_ARRIVAL_OF_INCOMING_CALL,
	ATMOP_CALL_RELEASE,
	ATMOP_CONNECT_OUTGOING_CALL,
	ATMOP_DROP_PARTY,
	ATMOP_GET_LOCAL_PORT_INFO,
	ATMOP_P2MP_CALL_ACTIVE,
	ATMOP_P2P_CALL_ACTIVE,
	ATMOP_PREPARE_INCOMING_CALL,
	ATMOP_PREPARE_OUTGOING_CALL,
	ATMOP_QUERY_CONNECTION_ATTRIBUTES,
	ATMOP_REJECT_INCOMING_CALL,
	ATMOP_SET_CONNECTION_ATTRIBUTES,
	ATMOP_WAIT_ON_INCOMING_CALL,
	ATMOP_SET_CONNECTION_ATTRIBUTES_X,
	ATMOP_QUERY_CONNECTION_ATTRIBUTES_X,
	ATMOP_QUERY_STATE
};
.Ed
.Pp
These codes correspond directly to the operations specified in the ATM
Forum document with the following exceptions:
.Bl -tag -width foo
.It Dv ATMOP_RESP
As discussed in
.Xr ng_uni 4 ,
this is used to
.Dq synchronify
the interface.
The argument is a
.Bd -literal
struct atm_resp {
	int32_t		resp;
	uint32_t	data;		/* type of attached data */
};
.Ed
.Pp
If the response code
.Va resp
is zero, the node has accepted the user request.
If something goes wrong,
.Va resp
contains an error code.
For requests that return data,
.Va data
contains a code describing the type of data and the data itself
starts immediately after the structure.
.It Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES_X
This is the same as
.Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES
except that it allows to query several attributes
within one request.
.It Dv ATMOP_SET_CONNECTION_ATTRIBUTES_X
This is the same as
.Dv ATMOP_SET_CONNECTION_ATTRIBUTES
except that it allows to set several attributes
within one request.
The list of attributes is followed directly by the attributes in the same
order as they appear in the list.
.El
.Pp
If a user hook is disconnected, an active connection on that hook is released.
Incoming connections waiting to be accepted are reoffered to other
listening hooks or rejected.
.Sh CONTROL MESSAGES
Besides the generic messages the node understands the following special
messages:
.Bl -tag -width foo
.It Dv NGM_CCATM_DUMP Pq Ic dump
This causes the internal state of the node to be dumped in ASCII to the
.Va dump
hook.
.It Dv NGM_CCATM_STOP Pq Ic stop
This message causes all connections on that port to be aborted (not released!\&)
and all ATM endpoints which are bound to that port to be closed.
It stops processing of all messages from the UNI stack on that port UNI stack.
The argument is a
.Bd -literal
struct ngm_ccatm_port {
	uint32_t	port;
};
.Ed
.It Dv NGM_CCATM_START Pq Ic start
Start processing on the port.
The argument is a
.Vt ngm_ccatm_port
structure.
.It Dv NGM_CCATM_CLEAR Pq Ic clear
This message takes a
.Vt ngm_ccatm_port
structure and clears all prefixes and addresses on that port.
If the port number is zero, all ports are cleared.
.It Dv NGM_CCATM_GET_ADDRESSES Pq Ic get_addresses
Get the list of all registered addresses on the given port.
The argument is a
.Vt ngm_ccatm_port
structure and the result is a
.Vt ngm_ccatm_get_addresses
structure:
.Bd -literal
struct ngm_ccatm_get_addresses {
	uint32_t	count;
	struct ngm_ccatm_address_req addr[0];
};
struct ngm_ccatm_address_req {
	uint32_t	port;
	struct uni_addr	addr;
};
.Ed
.Pp
If the
.Va port
field is zero in the request, all addresses on all ports
are returned.
If it is not zero, only the addresses on that port are reported.
The number of addresses is returned in the
.Va count
field.
.It Dv NGM_CCATM_ADDRESS_REGISTERED Pq Ic address_reg
This message is used by ILMI to inform the
.Nm
node that a previous address registration request was successful.
This causes the node to activate that address.
The argument to the message is a
.Vt ngm_ccatm_address_req
structure.
.It Dv NGM_CCATM_ADDRESS_UNREGISTERED Pq Ic address_unreg
This message is used by ILMI to inform the
.Nm
node that an address has been unregistered.
The node clears that address from its tables.
The argument is a
.Vt ngm_ccatm_address_req
structure.
.It Dv NGM_CCATM_SET_PORT_PARAM Pq Ic set_port_param
This request sets the parameters on the given port.
The argument is a
.Bd -literal
struct ngm_ccatm_atm_port {
	uint32_t port;		/* port for which to set parameters */
	uint32_t pcr;		/* port peak cell rate */
	uint32_t max_vpi_bits;
	uint32_t max_vci_bits;
	uint32_t max_svpc_vpi;
	uint32_t max_svcc_vpi;
	uint32_t min_svcc_vci;
	uint8_t	 esi[6];
	uint32_t num_addr;
};
.Ed
.Pp
This should be used only by ILMI and when that port is stopped and the
address and prefix tables of that port are empty.
The
.Va num_addr
field is ignored.
.It Dv NGM_CCATM_GET_PORT_PARAM Pq Ic get_port_param
Retrieve the parameters of the given port.
The argument is a
.Vt ngm_ccatm_port
and the result a
.Vt ngm_ccatm_atm_port .
.It Dv NGM_CCATM_GET_PORTLIST Pq Ic get_portlist
Get a list of all available ports on that node.
This is returned as a
.Bd -literal
struct ngm_ccatm_portlist {
	uint32_t	nports;
	uint32_t	ports[];
};
.Ed
.It Dv NGM_CCATM_GETSTATE Pq Ic getstate
Return the state of a port.
The argument is a
.Vt "struct ngm_ccatm_port"
and the return values as a
.Vt uint32_t .
.It Dv NGM_CCATM_SETLOG Pq Ic setlog
This requests sets a new logging level and returns the previous one.
The argument is either a
.Vt uint32_t
in which case it specifies the new logging level, or may be empty
in which case just the old level is returned as a
.Vt uint32_t .
.It Dv NGM_CCATM_RESET Pq Ic reset
Reset the node.
This is allowed only if the number of user hooks and connected UNI stacks is
zero.
.It Dv NGM_CCATM_GET_EXSTAT
Return extended status information from the node.
.El
.Sh SEE ALSO
.Xr netgraph 4 ,
.Xr ng_uni 4 ,
.Xr ngctl 8
.Sh AUTHORS
.An Harti Brandt Aq Mt harti@FreeBSD.org