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