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
  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