share/man/man4/ng_atm.4

   1 .\"
   2 .\" Copyright (c) 2001-2003
   3 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   4 .\"     All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .\" ng_atm(4) man page
  32 .\"
  33 .Dd November 2, 2012
  34 .Dt NG_ATM 4
  35 .Os
  36 .Sh NAME
  37 .Nm ng_atm
  38 .Nd netgraph ATM node type
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In net/if_atm.h
  42 .In netgraph.h
  43 .In netgraph/atm/ng_atm.h
  44 .Sh DESCRIPTION
  45 The
  46 .Nm atm
  47 netgraph node type allows
  48 .Xr natm 4
  49 ATM drivers to be connected to the
  50 .Xr netgraph 4
  51 networking subsystem.
  52 When the
  53 .Nm
  54 module is loaded a node is automatically created for each
  55 .Xr natm 4
  56 ATM interface.
  57 The nodes are named with the same name as the
  58 interface.
  59 Nodes are also created if a driver for an ATM
  60 card is loaded after
  61 .Nm
  62 was loaded.
  63 .Pp
  64 The
  65 .Nm atm
  66 nodes are persistent.
  67 They are removed when the interface is removed.
  68 .Dv NGM_SHUTDOWN
  69 messages are ignored by the node.
  70 .Sh HOOKS
  71 Four special hooks with fixed names and an unlimited number of hooks with user
  72 defined names are supported.
  73 Three of the fixed hooks are attached to
  74 strategic points in the information flow in the
  75 .Xr natm 4
  76 system and support only reading.
  77 The fourth fixed hook behaves like the other
  78 user hooks, but a number of management messages are sent along the hook.
  79 The other hooks can be attached to VCIs dynamically by means of
  80 control messages to the
  81 .Nm atm
  82 node and can be written and read.
  83 .Pp
  84 The four fixed hooks are:
  85 .Bl -tag -width ".Va orphans"
  86 .It Va input
  87 This is a connection to the raw input stream from the network.
  88 If this hook is connected, all incoming packets are delivered out to
  89 this hook.
  90 Note that this redirects ALL input.
  91 Neither
  92 .Xr natm 4
  93 nor the user hooks will see any input if
  94 .Va input
  95 is connected.
  96 An
  97 .Vt atm_pseudohdr
  98 (see
  99 .Xr natm 4 )
 100 is prepended to the actual data.
 101 .It Va output
 102 This is a connection to the raw output stream to the network device.
 103 If this hook is connected, all outgoing packets are handed over to
 104 the netgraph system and delivered to the hook instead of being delivered
 105 to the ATM driver.
 106 An
 107 .Vt atm_pseudohdr
 108 (see
 109 .Xr natm 4 )
 110 is prepended to the actual data.
 111 .It Va orphans
 112 This hook receives all packets that are unrecognized, i.e., do not belong to
 113 either a
 114 .Xr natm 4
 115 socket, a
 116 .Nm
 117 VCI or
 118 .Xr natm 4
 119 IP.
 120 Because ATM is connection oriented and packets are received on a given VCI only
 121 when someone initiates this VCI, packets should never be orphaned.
 122 There is
 123 however one exception: if you use
 124 .Xr natm 4
 125 IP with LLC/SNAP encapsulation packets with do not have the IP protocol
 126 indicated in the packet header are delivered out of this hook.
 127 An
 128 .Vt atm_pseudohdr
 129 (see
 130 .Xr natm 4 )
 131 is prepended to the actual data send out to the hook.
 132 .It Va manage
 133 This hook behaves exactly like a normal user hook (see below) except that
 134 the node at the other hand will receive management messages.
 135 .El
 136 .Pp
 137 Hooks for dynamically initiated VCIs can have whatever name is allowed by
 138 .Xr netgraph 4
 139 as long as the name does not collide with one of the three predefined names.
 140 .Pp
 141 To initiate packet sending and receiving on a dynamic hook, one has to issue
 142 a
 143 .Dv NGM_ATM_CPCS_INIT
 144 control message.
 145 To terminate sending and receiving one must send a
 146 .Dv NGM_ATM_CPCS_TERM
 147 message (see
 148 .Sx CONTROL MESSAGES ) .
 149 The data sent and received on these hooks has no additional
 150 headers.
 151 .Sh CONTROL MESSAGES
 152 This node type supports the generic messages plus the following:
 153 .Bl -tag -width 4n
 154 .It Dv NGM_ATM_GET_IFNAME Pq Ic getifname
 155 Return the name of the interface as a
 156 .Dv NUL Ns
 157 -terminated string.
 158 This is normally the same name as that of the node.
 159 .It Dv NGM_ATM_GET_CONFIG Pq Ic getconfig
 160 Returns a structure defining the configuration of the interface:
 161 .Bd -literal
 162 struct ngm_atm_config {
 163         uint32_t        pcr;            /* peak cell rate */
 164         uint32_t        vpi_bits;       /* number of active VPI bits */
 165         uint32_t        vci_bits;       /* number of active VCI bits */
 166         uint32_t        max_vpcs;       /* maximum number of VPCs */
 167         uint32_t        max_vccs;       /* maximum number of VCCs */
 168 };
 169 .Ed
 170 .It Dv NGM_ATM_GET_VCCS Pq Ic getvccs
 171 Returns the table of open VCCs from the driver.
 172 This table consists of
 173 a header and a variable sized array of entries, one for each open VCC:
 174 .Bd -literal
 175 struct atmio_vcctable {
 176         uint32_t        count;          /* number of vccs */
 177         struct atmio_vcc vccs[0];       /* array of VCCs */
 178 };
 179 struct atmio_vcc {
 180         uint16_t        flags;          /* flags */
 181         uint16_t        vpi;            /* VPI */
 182         uint16_t        vci;            /* VCI */
 183         uint16_t        rmtu;           /* Receive maximum CPCS size */
 184         uint16_t        tmtu;           /* Transmit maximum CPCS size */
 185         uint8_t         aal;            /* aal type */
 186         uint8_t         traffic;        /* traffic type */
 187         struct atmio_tparam tparam;     /* traffic parameters */
 188 };
 189 struct atmio_tparam {
 190         uint32_t        pcr;    /* 24bit: Peak Cell Rate */
 191         uint32_t        scr;    /* 24bit: VBR Sustainable Cell Rate */
 192         uint32_t        mbs;    /* 24bit: VBR Maximum burst size */
 193         uint32_t        mcr;    /* 24bit: ABR/VBR/UBR+MCR MCR */
 194         uint32_t        icr;    /* 24bit: ABR ICR */
 195         uint32_t        tbe;    /* 24bit: ABR TBE (1...2^24-1) */
 196         uint8_t         nrm;    /*  3bit: ABR Nrm */
 197         uint8_t         trm;    /*  3bit: ABR Trm */
 198         uint16_t        adtf;   /* 10bit: ABR ADTF */
 199         uint8_t         rif;    /*  4bit: ABR RIF */
 200         uint8_t         rdf;    /*  4bit: ABR RDF */
 201         uint8_t         cdf;    /*  3bit: ABR CDF */
 202 };
 203 .Ed
 204 .Pp
 205 Note that this is the driver's table, so all VCCs opened via
 206 .Xr natm 4
 207 sockets and IP are also shown.
 208 They can, however, be distinguished by
 209 their flags.
 210 The
 211 .Va flags
 212 field contains the following flags:
 213 .Pp
 214 .Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
 215 .It Dv ATM_PH_AAL5
 216 use AAL5 instead of AAL0
 217 .It Dv ATM_PH_LLCSNAP
 218 if AAL5 use LLC SNAP encapsulation
 219 .It Dv ATM_FLAG_NG
 220 this is a netgraph VCC
 221 .It Dv ATM_FLAG_HARP
 222 this is a HARP VCC
 223 .It Dv ATM_FLAG_NORX
 224 transmit only VCC
 225 .It Dv ATM_FLAG_NOTX
 226 receive only VCC
 227 .It Dv ATMIO_FLAG_PVC
 228 treat channel as a PVC
 229 .El
 230 .Pp
 231 If the
 232 .Dv ATM_FLAG_NG
 233 flag is set, then
 234 .Va traffic
 235 and
 236 .Va tparam
 237 contain meaningful information.
 238 .Pp
 239 The
 240 .Va aal
 241 field
 242 contains one of the following values:
 243 .Pp
 244 .Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
 245 .It Dv ATMIO_AAL_0
 246 AAL 0 (raw cells)
 247 .It Dv ATMIO_AAL_34
 248 AAL 3 or AAL 4
 249 .It Dv ATMIO_AAL_5
 250 AAL 5
 251 .It Dv ATMIO_AAL_RAW
 252 device specific raw cells
 253 .El
 254 .Pp
 255 The
 256 .Va traffic
 257 field
 258 can have one of the following values (not all drivers support
 259 all traffic types however):
 260 .Pp
 261 .Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
 262 .It Dv ATMIO_TRAFFIC_UBR
 263 .It Dv ATMIO_TRAFFIC_CBR
 264 .It Dv ATMIO_TRAFFIC_ABR
 265 .It Dv ATMIO_TRAFFIC_VBR
 266 .El
 267 .It Dv NGM_ATM_CPCS_INIT Pq Ic cpcsinit
 268 Initialize a VCC for sending and receiving.
 269 The argument is a structure:
 270 .Bd -literal
 271 struct ngm_atm_cpcs_init {
 272         char            name[NG_HOOKSIZ];
 273         uint32_t        flags;          /* flags. (if_atm.h) */
 274         uint16_t        vci;            /* VCI to open */
 275         uint16_t        vpi;            /* VPI to open */
 276         uint16_t        rmtu;           /* receive maximum PDU */
 277         uint16_t        tmtu;           /* transmit maximum PDU */
 278         uint8_t         aal;            /* AAL type (if_atm.h) */
 279         uint8_t         traffic;        /* traffic type (if_atm.h) */
 280         uint32_t        pcr;            /* Peak cell rate */
 281         uint32_t        scr;            /* VBR: Sustainable cell rate */
 282         uint32_t        mbs;            /* VBR: Maximum burst rate */
 283         uint32_t        mcr;            /* UBR+: Minimum cell rate */
 284         uint32_t        icr;            /* ABR: Initial cell rate */
 285         uint32_t        tbe;            /* ABR: Transmit buffer exposure */
 286         uint8_t         nrm;            /* ABR: Nrm */
 287         uint8_t         trm;            /* ABR: Trm */
 288         uint16_t        adtf;           /* ABR: ADTF */
 289         uint8_t         rif;            /* ABR: RIF */
 290         uint8_t         rdf;            /* ABR: RDF */
 291         uint8_t         cdf;            /* ABR: CDF */
 292 };
 293 .Ed
 294 .Pp
 295 The
 296 .Va name
 297 field
 298 is the name of the hook for which sending and receiving should be enabled.
 299 This hook must already be connected.
 300 The
 301 .Va vpi
 302 and
 303 .Va vci
 304 fields
 305 are the respective VPI and VCI values to use for the ATM cells.
 306 They must be
 307 within the range, given by the
 308 .Va maxvpi
 309 and
 310 .Va maxvci
 311 fields of the
 312 .Vt ng_atm_config
 313 structure.
 314 The
 315 .Va flags
 316 field
 317 contains the flags (see above) and the other fields describe the
 318 type of traffic.
 319 .It Dv NGM_ATM_CPCS_TERM Pq Ic cpcsterm
 320 Stop sending and receiving on the indicated hook.
 321 The argument is a
 322 .Bd -literal
 323 struct ngm_atm_cpcs_term {
 324         char            name[NG_HOOKSIZ];
 325 };
 326 .Ed
 327 .It Dv NGM_ATM_GET_STATS Pq Ic getstats
 328 This command returns a message, containing node statistics. The
 329 structure of the message is:
 330 .Bd -literal
 331 struct ngm_atm_stats {
 332         uint64_t        in_packets;
 333         uint64_t        in_errors;
 334         uint64_t        out_packets;
 335         uint64_t        out_errors;
 336 };
 337 .Ed
 338 .El
 339 .Sh MANAGEMENT MESSAGES
 340 If the
 341 .Va manage
 342 hook is connected, certain messages are sent along the hook.
 343 They are
 344 received by the peer node with a cookie of
 345 .Dv NG_ATM_COOKIE .
 346 .Bl -tag -width 4n
 347 .It Dv NGM_ATM_VCC_CHANGE Pq Ic vcc_change
 348 A permanent VCC has been added, deleted or changed.
 349 This is used by
 350 .Xr ilmid 8
 351 to generate the appropriate ILMI traps.
 352 The structure of the message is:
 353 .Bd -literal
 354 struct ngm_atm_vcc_change {
 355         uint32_t        node;
 356         uint16_t        vci;
 357         uint8_t         vpi;
 358         uint8_t         state;
 359 };
 360 .Ed
 361 Where
 362 .Va state
 363 is 0 if the PVC was deleted, and 1 if it was added or modified.
 364 .El
 365 .Sh FLOW CONTROL
 366 If the hardware driver supports it, the node can emit flow control messages
 367 along a user hook.
 368 The format of these messages is described in
 369 .In netgraph/ng_message.h .
 370 The
 371 .Nm atm
 372 node may generate
 373 .Dv NGM_HIGH_WATER_PASSED
 374 and
 375 .Dv NGM_LOW_WATER_PASSED
 376 messages.
 377 The first one indicates that the hardware driver has stopped output
 378 on the channel and drops new packets, the second one reports that
 379 output was reenabled.
 380 Currently, the structures are not filled with
 381 information.
 382 .Sh SHUTDOWN
 383 The nodes are persistent as long as the corresponding interface exists.
 384 Upon receipt of a
 385 .Dv NGM_SHUTDOWN
 386 messages, all hooks are disconnected and the node is reinitialized.
 387 All
 388 VCCs opened via
 389 .Xr netgraph 4
 390 are closed.
 391 When the ATM interface is unloaded,
 392 the node disappears.
 393 If the node is compiled with
 394 .Dv NGATM_DEBUG
 395 there is a sysctl
 396 .Va net.graph.atm.allow_shutdown
 397 which, when set to a non-zero value, allows the nodes to shut down.
 398 Note that this is intended for development only and may lead to kernel
 399 panics if set.
 400 .Sh SEE ALSO
 401 .Xr natm 4 ,
 402 .Xr netgraph 4 ,
 403 .Xr ng_ether 4 ,
 404 .Xr ngctl 8
 405 .Sh AUTHORS
 406 .An Harti Brandt Aq harti@FreeBSD.org