/share/man/man4/ng_ccatm.4

  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.\" $FreeBSD$
 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
 51The
 52.Nm
 53node implements the API specified by the ATM Forum for access to ATM services
 54(see ATM-Forum document
 55.Pa af-saa-0108 ) .
 56This document specifies the semantics
 57of the API, not the exact language binding.
 58For this reason, it is expected that
 59this implementation is neither compile-time nor binary compatible with
 60other implementations of this API.
 61It should, however, be fairly straightforward
 62to convert between different API implementations.
 63.Pp
 64This node is usually stacked on top of one or more UNI nodes (see
 65.Xr ng_uni 4 ) .
 66Each of these hooks appears as a
 67.Dq port
 68to the user of the node.
 69It also has one hook connected to the ILMI daemon for management purposes.
 70.Pp
 71The node is removed when it receives a
 72.Dv NGM_SHUTDOWN
 73messages or when all hooks are disconnected.
 74.Sh HOOKS
 75The node understands a number of hooks with predefined names and an
 76unlimited number of hooks for user connections.
 77The predefined names are:
 78.Bl -tag -width ".Va orphans"
 79.It Va uni Ns Ar NNN
 80These hooks stack the
 81.Nm
 82node on top of a UNI stack.
 83The node expects the interface on these hooks
 84to conform to the upper interface specified in
 85.Xr ng_uni 4 .
 86These hooks are forced into queuing mode, so that there are no circular
 87calls from call control to UNI and UNI back to call control.
 88The
 89.Ar NNN
 90in the hook name is the decimal port number and should not be zero.
 91The port number is a 32-bit unsigned integer.
 92.It Va manage
 93This hook should be connected to the ILMI daemon.
 94No data is ever sent on this hook and all received data is discarded.
 95The hook is used to send control messages along.
 96.It Va dump
 97On receipt of a
 98.Dv NGM_CCATM_DUMP
 99command a textual description of the current state of the node is sent
100out of this hook.
101This text is sent as one large message consisting of more
102than one
103.Vt mbuf .
104.El
105.Pp
106All other hook names are taken to be user hooks and correspond to an
107ATM endpoint as specified in the ATM Forum document.
108The interface on these hooks is defined in
109.In atmapi.h
110and uses a structure
111.Bd -literal
112struct ccatm_op {
113	uint32_t	op;	/* request code */
114	u_char		data[];	/* optional data */
115};
116.Ed
117.Pp
118This structure is followed directly by the data for the operation.
119The opcode is one of the following:
120.Bd -literal
121enum 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
147These codes correspond directly to the operations specified in the ATM
148Forum document with the following exceptions:
149.Bl -tag -width indent
150.It Dv ATMOP_RESP
151As discussed in
152.Xr ng_uni 4 ,
153this is used to
154.Dq synchronify
155the interface.
156The argument is a
157.Bd -literal
158struct atm_resp {
159	int32_t		resp;
160	uint32_t	data;		/* type of attached data */
161};
162.Ed
163.Pp
164If the response code
165.Va resp
166is zero, the node has accepted the user request.
167If something goes wrong,
168.Va resp
169contains an error code.
170For requests that return data,
171.Va data
172contains a code describing the type of data and the data itself
173starts immediately after the structure.
174.It Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES_X
175This is the same as
176.Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES
177except that it allows to query several attributes
178within one request.
179.It Dv ATMOP_SET_CONNECTION_ATTRIBUTES_X
180This is the same as
181.Dv ATMOP_SET_CONNECTION_ATTRIBUTES
182except that it allows to set several attributes
183within one request.
184The list of attributes is followed directly by the attributes in the same
185order as they appear in the list.
186.El
187.Pp
188If a user hook is disconnected, an active connection on that hook is released.
189Incoming connections waiting to be accepted are reoffered to other
190listening hooks or rejected.
191.Sh CONTROL MESSAGES
192Besides the generic messages the node understands the following special
193messages:
194.Bl -tag -width indent
195.It Dv NGM_CCATM_DUMP
196This causes the internal state of the node to be dumped in ASCII to the
197.Va dump
198hook.
199.It Dv NGM_CCATM_STOP
200This message causes all connections on that port to be aborted (not released!\&)
201and all ATM endpoints which are bound to that port to be closed.
202It stops processing of all messages from the UNI stack on that port UNI stack.
203The argument is a
204.Bd -literal
205struct ngm_ccatm_port {
206	uint32_t	port;
207};
208.Ed
209.Pp
210.It Dv NGM_CCATM_START
211Start processing on the port.
212The argument is a
213.Vt ngm_ccatm_port
214structure.
215.It Dv NGM_CCATM_CLEAR
216This message takes a
217.Vt ngm_ccatm_port
218structure and clears all prefixes and addresses on that port.
219If the port number is zero, all ports are cleared.
220.It Dv NGM_CCATM_GET_ADDRESSES
221Get the list of all registered addresses on the given port.
222The argument is a
223.Vt ngm_ccatm_port
224structure and the result is a
225.Vt ngm_ccatm_get_addresses
226structure:
227.Bd -literal
228struct ngm_ccatm_get_addresses {
229	uint32_t	count;
230	struct ngm_ccatm_address_req addr[0];
231};
232struct ngm_ccatm_address_req {
233	uint32_t	port;
234	struct uni_addr	addr;
235};
236.Ed
237.Pp
238If the
239.Va port
240field is zero in the request, all addresses on all ports
241are returned.
242If it is not zero, only the addresses on that port are reported.
243The number of addresses is returned in the
244.Va count
245field.
246.It Dv NGM_CCATM_ADDRESS_REGISTERED
247This message is used by ILMI to inform the
248.Nm
249node that a previous address registration request was successful.
250This causes the node to activate that address.
251The argument to the message is a
252.Vt ngm_ccatm_address_req
253structure.
254.It Dv NGM_CCATM_ADDRESS_UNREGISTERED
255This message is used by ILMI to inform the
256.Nm
257node that an address has been unregistered.
258The node clears that address from its tables.
259The argument is a
260.Vt ngm_ccatm_address_req
261structure.
262.It Dv NGM_CCATM_SET_PORT_PARAM
263This request sets the parameters on the given port.
264The argument is a
265.Bd -literal
266struct 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
279This should be used only by ILMI and when that port is stopped and the
280address and prefix tables of that port are empty.
281The
282.Va num_addr
283field is ignored.
284.It Dv NGM_CCATM_GET_PORT_PARAM
285Retrieve the parameters of the given port.
286The argument is a
287.Vt ngm_ccatm_port
288and the result a
289.Vt ngm_ccatm_atm_port .
290.It Dv NGM_CCATM_GET_PORTLIST
291Get a list of all available ports on that node.
292This is returned as a
293.Bd -literal
294struct ngm_ccatm_portlist {
295	uint32_t	nports;
296	uint32_t	ports[];
297};
298.Ed
299.It Dv NGM_CCATM_GETSTATE
300Return the state of a port.
301The argument is a
302.Vt "struct ngm_ccatm_port"
303and the return values as a
304.Vt uint32_t .
305.It Dv NGM_CCATM_SETLOG
306This requests sets a new logging level and returns the previous one.
307The argument is either a
308.Vt uint32_t
309in which case it specifies the new logging level, or may be empty
310in which case just the old level is returned as a
311.Vt uint32_t .
312.It Dv NGM_CCATM_RESET
313Reset the node.
314This is allowed only if the number of user hooks and connected UNI stacks is
315zero.
316.It Dv NGM_CCATM_GET_EXSTAT
317Return 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