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