Add a man page for ng_ccatm(4).

Reminded by:	brueffer

1 files changed, 320 insertions, 0 deletions

diff --git a/share/man/man4/ng_ccatm.4 b/share/man/man4/ng_ccatm.4
new file mode 100644
index 0000000..32031e0
--- /dev/null
+++ b/share/man/man4/ng_ccatm.4
@@ -0,0 +1,320 @@
+.\"
+.\" 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 10, 2005
+.Dt ng_ccatm 4
+.Os FreeBSD
+.Sh NAME
+.Nm ng_ccatm
+.Nd netgraph ATM Call Control node type
+.Sh SYNOPSIS
+.Fd #include <netnatm/unimsg.h>
+.Fd #include <netnatm/msg/unistruct.h>
+.Fd #include <netnatm/sig/unidef.h>
+.Fd #include <netnatm/api/unisap.h>
+.Fd #include <netnatm/api/atmapi.h>
+.Fd #include <netnatm/api/ccatm.h>
+.Fd #include <netgraph.h>
+.Fd #include <netgraph/ng_uni.h>
+.Fd #include <netgraph/ng_ccatm.h>
+.Sh DESCIPTION
+The
+.Nm
+node implements the API specified by the ATM Forum for access to ATM services
+(see ATM-Forum document 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
+.Ql port
+to the user of the node.
+It has also one hook connected to the ILMI daemon for management purposes.
+.Pp
+The node is removed when it receives a
+.Dv NGM_SHUTDOWN
+messages or 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 orphans
+.It Dv uniNNN
+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
+.Dv 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 Dv 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 Dv dump
+On receipt of a
+.Dv
+NGM_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
+.Fa 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
+.Pa atmapi.h
+and uses a structure
+.Bd -literal
+struct ccatm_op {
+	u_int32_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 xxx
+.It Dv ATMOP_RESP
+As discussed in
+.Xr ng_uni 4
+this is used to
+.Ql synchronify
+the interface.
+The argument is a struct
+.Bd -literal
+struct atm_resp {
+	int32_t		resp;
+	uint32_t	data;		/* type of attached data */
+};
+.Ed
+.Pp
+If the response code
+.Fa resp
+is zero, the node has accepted the user request.
+If something goes wrong,
+.Fa resp
+contains an error code.
+For requests that return data,
+.Fa data
+contains a code describing the type of data and the data itseld
+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
+listeing hooks or rejected.
+.Sh CONTROL MESSAGES
+Besides the generic messages the node understands the following special
+messages:
+.Bl -tag -width xxx
+.It Dv NGM_CCATM_DUMP
+This causes the internal state of the node to be dumped in ASCII to the
+.Dv dump
+hook.
+.It Dv NGM_CCATM_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
+.Pp
+.It Dv NGM_CCATM_START
+Start processing on the port.
+The argument is a
+.Fa ngm_ccatm_port
+structure.
+.It Dv NGM_CCATM_CLEAR
+This message takes a
+.Fa 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
+Get the list of all registered addresses on the given port.
+The argument is a
+.Fa ngm_ccatm_port
+structure and the result is a
+.Fa 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 {
+	u_int32_t	port;
+	struct uni_addr	addr;
+};
+.Ed
+.Pp
+If the
+.Fa 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
+.Fa count
+field.
+.It Dv NGM_CCATM_ADDRESS_REGISTERED
+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
+.Fa ngm_ccatm_address_req
+structure.
+.It Dv NGM_CCATM_ADDRESS_UNREGISTERED
+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
+.Fa ngm_ccatm_address_req
+structure.
+.It Dv NGM_CCATM_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
+.Fa num_addr
+field is ignored.
+.It Dv NGM_CCATM_GET_PORT_PARAM
+Retrieve the parameters of the given port.
+The argument is a
+.Fa ngm_ccatm_port
+and the result a
+.Fa ngm_ccatm_atm_port .
+.It Dv NGM_CCATM_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
+Return the state of a port.
+The argument is a
+.Fa struct ngm_ccatm_port
+and the return values as a
+.Ft uint32_t .
+.It Dv NGM_CCATM_SETLOG
+This requests sets a new logging level and returns the previous one.
+The argument is either a
+.Ft 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
+.Ft uint32_t .
+.It Dv NGM_CCATM_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 AUTHOR
+.An Harti Brandt Aq harti@freebsd.org