1 |
.\" |
2 |
.\" Copyright (c) 2001-2004 |
3 |
.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). |
4 |
.\" All rights reserved. |
5 |
.\" Copyright (c) 2005 |
6 |
.\" Hartmut Brandt. |
7 |
.\" All rights reserved. |
8 |
.\" |
9 |
.\" Author: Harti Brandt <harti@FreeBSD.org> |
10 |
.\" |
11 |
.\" Redistribution and use in source and binary forms, with or without |
12 |
.\" modification, are permitted provided that the following conditions |
13 |
.\" are met: |
14 |
.\" 1. Redistributions of source code must retain the above copyright |
15 |
.\" notice, this list of conditions and the following disclaimer. |
16 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
17 |
.\" notice, this list of conditions and the following disclaimer in the |
18 |
.\" documentation and/or other materials provided with the distribution. |
19 |
.\" |
20 |
.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
21 |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
22 |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
23 |
.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE |
24 |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
25 |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
26 |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
27 |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
28 |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
29 |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
30 |
.\" SUCH DAMAGE. |
31 |
.\" |
32 |
.\" $MidnightBSD$ |
33 |
.\" |
34 |
.Dd March 10, 2005 |
35 |
.Dt NG_CCATM 4 |
36 |
.Os |
37 |
.Sh NAME |
38 |
.Nm ng_ccatm |
39 |
.Nd "ATM Call Control netgraph node type" |
40 |
.Sh SYNOPSIS |
41 |
.In netnatm/unimsg.h |
42 |
.In netnatm/msg/unistruct.h |
43 |
.In netnatm/sig/unidef.h |
44 |
.In netnatm/api/unisap.h |
45 |
.In netnatm/api/atmapi.h |
46 |
.In netnatm/api/ccatm.h |
47 |
.In netgraph.h |
48 |
.In netgraph/ng_uni.h |
49 |
.In netgraph/ng_ccatm.h |
50 |
.Sh DESCRIPTION |
51 |
The |
52 |
.Nm |
53 |
node implements the API specified by the ATM Forum for access to ATM services |
54 |
(see ATM-Forum document |
55 |
.Pa af-saa-0108 ) . |
56 |
This document specifies the semantics |
57 |
of the API, not the exact language binding. |
58 |
For this reason, it is expected that |
59 |
this implementation is neither compile-time nor binary compatible with |
60 |
other implementations of this API. |
61 |
It should, however, be fairly straightforward |
62 |
to convert between different API implementations. |
63 |
.Pp |
64 |
This node is usually stacked on top of one or more UNI nodes (see |
65 |
.Xr ng_uni 4 ) . |
66 |
Each of these hooks appears as a |
67 |
.Dq port |
68 |
to the user of the node. |
69 |
It also has one hook connected to the ILMI daemon for management purposes. |
70 |
.Pp |
71 |
The node is removed when it receives a |
72 |
.Dv NGM_SHUTDOWN |
73 |
messages or when all hooks are disconnected. |
74 |
.Sh HOOKS |
75 |
The node understands a number of hooks with predefined names and an |
76 |
unlimited number of hooks for user connections. |
77 |
The predefined names are: |
78 |
.Bl -tag -width ".Va orphans" |
79 |
.It Va uni Ns Ar NNN |
80 |
These hooks stack the |
81 |
.Nm |
82 |
node on top of a UNI stack. |
83 |
The node expects the interface on these hooks |
84 |
to conform to the upper interface specified in |
85 |
.Xr ng_uni 4 . |
86 |
These hooks are forced into queuing mode, so that there are no circular |
87 |
calls from call control to UNI and UNI back to call control. |
88 |
The |
89 |
.Ar NNN |
90 |
in the hook name is the decimal port number and should not be zero. |
91 |
The port number is a 32-bit unsigned integer. |
92 |
.It Va manage |
93 |
This hook should be connected to the ILMI daemon. |
94 |
No data is ever sent on this hook and all received data is discarded. |
95 |
The hook is used to send control messages along. |
96 |
.It Va dump |
97 |
On receipt of a |
98 |
.Dv NGM_CCATM_DUMP |
99 |
command a textual description of the current state of the node is sent |
100 |
out of this hook. |
101 |
This text is sent as one large message consisting of more |
102 |
than one |
103 |
.Vt mbuf . |
104 |
.El |
105 |
.Pp |
106 |
All other hook names are taken to be user hooks and correspond to an |
107 |
ATM endpoint as specified in the ATM Forum document. |
108 |
The interface on these hooks is defined in |
109 |
.In atmapi.h |
110 |
and uses a structure |
111 |
.Bd -literal |
112 |
struct ccatm_op { |
113 |
u_int32_t op; /* request code */ |
114 |
u_char data[]; /* optional data */ |
115 |
}; |
116 |
.Ed |
117 |
.Pp |
118 |
This structure is followed directly by the data for the operation. |
119 |
The opcode is one of the following: |
120 |
.Bd -literal |
121 |
enum atmop { |
122 |
ATMOP_RESP, |
123 |
ATMOP_ABORT_CONNECTION, |
124 |
ATMOP_ACCEPT_INCOMING_CALL, |
125 |
ATMOP_ADD_PARTY, |
126 |
ATMOP_ADD_PARTY_REJECT, |
127 |
ATMOP_ADD_PARTY_SUCCESS, |
128 |
ATMOP_ARRIVAL_OF_INCOMING_CALL, |
129 |
ATMOP_CALL_RELEASE, |
130 |
ATMOP_CONNECT_OUTGOING_CALL, |
131 |
ATMOP_DROP_PARTY, |
132 |
ATMOP_GET_LOCAL_PORT_INFO, |
133 |
ATMOP_P2MP_CALL_ACTIVE, |
134 |
ATMOP_P2P_CALL_ACTIVE, |
135 |
ATMOP_PREPARE_INCOMING_CALL, |
136 |
ATMOP_PREPARE_OUTGOING_CALL, |
137 |
ATMOP_QUERY_CONNECTION_ATTRIBUTES, |
138 |
ATMOP_REJECT_INCOMING_CALL, |
139 |
ATMOP_SET_CONNECTION_ATTRIBUTES, |
140 |
ATMOP_WAIT_ON_INCOMING_CALL, |
141 |
ATMOP_SET_CONNECTION_ATTRIBUTES_X, |
142 |
ATMOP_QUERY_CONNECTION_ATTRIBUTES_X, |
143 |
ATMOP_QUERY_STATE |
144 |
}; |
145 |
.Ed |
146 |
.Pp |
147 |
These codes correspond directly to the operations specified in the ATM |
148 |
Forum document with the following exceptions: |
149 |
.Bl -tag -width indent |
150 |
.It Dv ATMOP_RESP |
151 |
As discussed in |
152 |
.Xr ng_uni 4 , |
153 |
this is used to |
154 |
.Dq synchronify |
155 |
the interface. |
156 |
The argument is a |
157 |
.Bd -literal |
158 |
struct atm_resp { |
159 |
int32_t resp; |
160 |
uint32_t data; /* type of attached data */ |
161 |
}; |
162 |
.Ed |
163 |
.Pp |
164 |
If the response code |
165 |
.Va resp |
166 |
is zero, the node has accepted the user request. |
167 |
If something goes wrong, |
168 |
.Va resp |
169 |
contains an error code. |
170 |
For requests that return data, |
171 |
.Va data |
172 |
contains a code describing the type of data and the data itself |
173 |
starts immediately after the structure. |
174 |
.It Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES_X |
175 |
This is the same as |
176 |
.Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES |
177 |
except that it allows to query several attributes |
178 |
within one request. |
179 |
.It Dv ATMOP_SET_CONNECTION_ATTRIBUTES_X |
180 |
This is the same as |
181 |
.Dv ATMOP_SET_CONNECTION_ATTRIBUTES |
182 |
except that it allows to set several attributes |
183 |
within one request. |
184 |
The list of attributes is followed directly by the attributes in the same |
185 |
order as they appear in the list. |
186 |
.El |
187 |
.Pp |
188 |
If a user hook is disconnected, an active connection on that hook is released. |
189 |
Incoming connections waiting to be accepted are reoffered to other |
190 |
listening hooks or rejected. |
191 |
.Sh CONTROL MESSAGES |
192 |
Besides the generic messages the node understands the following special |
193 |
messages: |
194 |
.Bl -tag -width indent |
195 |
.It Dv NGM_CCATM_DUMP |
196 |
This causes the internal state of the node to be dumped in ASCII to the |
197 |
.Va dump |
198 |
hook. |
199 |
.It Dv NGM_CCATM_STOP |
200 |
This message causes all connections on that port to be aborted (not released!\&) |
201 |
and all ATM endpoints which are bound to that port to be closed. |
202 |
It stops processing of all messages from the UNI stack on that port UNI stack. |
203 |
The argument is a |
204 |
.Bd -literal |
205 |
struct ngm_ccatm_port { |
206 |
uint32_t port; |
207 |
}; |
208 |
.Ed |
209 |
.Pp |
210 |
.It Dv NGM_CCATM_START |
211 |
Start processing on the port. |
212 |
The argument is a |
213 |
.Vt ngm_ccatm_port |
214 |
structure. |
215 |
.It Dv NGM_CCATM_CLEAR |
216 |
This message takes a |
217 |
.Vt ngm_ccatm_port |
218 |
structure and clears all prefixes and addresses on that port. |
219 |
If the port number is zero, all ports are cleared. |
220 |
.It Dv NGM_CCATM_GET_ADDRESSES |
221 |
Get the list of all registered addresses on the given port. |
222 |
The argument is a |
223 |
.Vt ngm_ccatm_port |
224 |
structure and the result is a |
225 |
.Vt ngm_ccatm_get_addresses |
226 |
structure: |
227 |
.Bd -literal |
228 |
struct ngm_ccatm_get_addresses { |
229 |
uint32_t count; |
230 |
struct ngm_ccatm_address_req addr[0]; |
231 |
}; |
232 |
struct ngm_ccatm_address_req { |
233 |
u_int32_t port; |
234 |
struct uni_addr addr; |
235 |
}; |
236 |
.Ed |
237 |
.Pp |
238 |
If the |
239 |
.Va port |
240 |
field is zero in the request, all addresses on all ports |
241 |
are returned. |
242 |
If it is not zero, only the addresses on that port are reported. |
243 |
The number of addresses is returned in the |
244 |
.Va count |
245 |
field. |
246 |
.It Dv NGM_CCATM_ADDRESS_REGISTERED |
247 |
This message is used by ILMI to inform the |
248 |
.Nm |
249 |
node that a previous address registration request was successful. |
250 |
This causes the node to activate that address. |
251 |
The argument to the message is a |
252 |
.Vt ngm_ccatm_address_req |
253 |
structure. |
254 |
.It Dv NGM_CCATM_ADDRESS_UNREGISTERED |
255 |
This message is used by ILMI to inform the |
256 |
.Nm |
257 |
node that an address has been unregistered. |
258 |
The node clears that address from its tables. |
259 |
The argument is a |
260 |
.Vt ngm_ccatm_address_req |
261 |
structure. |
262 |
.It Dv NGM_CCATM_SET_PORT_PARAM |
263 |
This request sets the parameters on the given port. |
264 |
The argument is a |
265 |
.Bd -literal |
266 |
struct ngm_ccatm_atm_port { |
267 |
uint32_t port; /* port for which to set parameters */ |
268 |
uint32_t pcr; /* port peak cell rate */ |
269 |
uint32_t max_vpi_bits; |
270 |
uint32_t max_vci_bits; |
271 |
uint32_t max_svpc_vpi; |
272 |
uint32_t max_svcc_vpi; |
273 |
uint32_t min_svcc_vci; |
274 |
uint8_t esi[6]; |
275 |
uint32_t num_addr; |
276 |
}; |
277 |
.Ed |
278 |
.Pp |
279 |
This should be used only by ILMI and when that port is stopped and the |
280 |
address and prefix tables of that port are empty. |
281 |
The |
282 |
.Va num_addr |
283 |
field is ignored. |
284 |
.It Dv NGM_CCATM_GET_PORT_PARAM |
285 |
Retrieve the parameters of the given port. |
286 |
The argument is a |
287 |
.Vt ngm_ccatm_port |
288 |
and the result a |
289 |
.Vt ngm_ccatm_atm_port . |
290 |
.It Dv NGM_CCATM_GET_PORTLIST |
291 |
Get a list of all available ports on that node. |
292 |
This is returned as a |
293 |
.Bd -literal |
294 |
struct ngm_ccatm_portlist { |
295 |
uint32_t nports; |
296 |
uint32_t ports[]; |
297 |
}; |
298 |
.Ed |
299 |
.It Dv NGM_CCATM_GETSTATE |
300 |
Return the state of a port. |
301 |
The argument is a |
302 |
.Vt "struct ngm_ccatm_port" |
303 |
and the return values as a |
304 |
.Vt uint32_t . |
305 |
.It Dv NGM_CCATM_SETLOG |
306 |
This requests sets a new logging level and returns the previous one. |
307 |
The argument is either a |
308 |
.Vt uint32_t |
309 |
in which case it specifies the new logging level, or may be empty |
310 |
in which case just the old level is returned as a |
311 |
.Vt uint32_t . |
312 |
.It Dv NGM_CCATM_RESET |
313 |
Reset the node. |
314 |
This is allowed only if the number of user hooks and connected UNI stacks is |
315 |
zero. |
316 |
.It Dv NGM_CCATM_GET_EXSTAT |
317 |
Return extended status information from the node. |
318 |
.El |
319 |
.Sh SEE ALSO |
320 |
.Xr netgraph 4 , |
321 |
.Xr ng_uni 4 , |
322 |
.Xr ngctl 8 |
323 |
.Sh AUTHORS |
324 |
.An Harti Brandt Aq harti@FreeBSD.org |