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 45The 46.Nm atm 47netgraph node type allows 48.Xr natm 4 49ATM drivers to be connected to the 50.Xr netgraph 4 51networking subsystem. 52When the 53.Nm 54module is loaded a node is automatically created for each 55.Xr natm 4 56ATM interface. 57The nodes are named with the same name as the 58interface. 59Nodes are also created if a driver for an ATM 60card is loaded after 61.Nm 62was loaded. 63.Pp 64The 65.Nm atm 66nodes are persistent. 67They are removed when the interface is removed. 68.Dv NGM_SHUTDOWN 69messages are ignored by the node. 70.Sh HOOKS 71Four special hooks with fixed names and an unlimited number of hooks with user 72defined names are supported. 73Three of the fixed hooks are attached to 74strategic points in the information flow in the 75.Xr natm 4 76system and support only reading. 77The fourth fixed hook behaves like the other 78user hooks, but a number of management messages are sent along the hook. 79The other hooks can be attached to VCIs dynamically by means of 80control messages to the 81.Nm atm 82node and can be written and read. 83.Pp 84The four fixed hooks are: 85.Bl -tag -width ".Va orphans" 86.It Va input 87This is a connection to the raw input stream from the network. 88If this hook is connected, all incoming packets are delivered out to 89this hook. 90Note that this redirects ALL input. 91Neither 92.Xr natm 4 93nor the user hooks will see any input if 94.Va input 95is connected. 96An 97.Vt atm_pseudohdr 98(see 99.Xr natm 4 ) 100is prepended to the actual data. 101.It Va output 102This is a connection to the raw output stream to the network device. 103If this hook is connected, all outgoing packets are handed over to 104the netgraph system and delivered to the hook instead of being delivered 105to the ATM driver. 106An 107.Vt atm_pseudohdr 108(see 109.Xr natm 4 ) 110is prepended to the actual data. 111.It Va orphans 112This hook receives all packets that are unrecognized, i.e., do not belong to 113either a 114.Xr natm 4 115socket, a 116.Nm 117VCI or 118.Xr natm 4 119IP. 120Because ATM is connection oriented and packets are received on a given VCI only 121when someone initiates this VCI, packets should never be orphaned. 122There is 123however one exception: if you use 124.Xr natm 4 125IP with LLC/SNAP encapsulation packets with do not have the IP protocol 126indicated in the packet header are delivered out of this hook. 127An 128.Vt atm_pseudohdr 129(see 130.Xr natm 4 ) 131is prepended to the actual data send out to the hook. 132.It Va manage 133This hook behaves exactly like a normal user hook (see below) except that 134the node at the other hand will receive management messages. 135.El 136.Pp 137Hooks for dynamically initiated VCIs can have whatever name is allowed by 138.Xr netgraph 4 139as long as the name does not collide with one of the three predefined names. 140.Pp 141To initiate packet sending and receiving on a dynamic hook, one has to issue 142a 143.Dv NGM_ATM_CPCS_INIT 144control message. 145To terminate sending and receiving one must send a 146.Dv NGM_ATM_CPCS_TERM 147message (see 148.Sx CONTROL MESSAGES ) . 149The data sent and received on these hooks has no additional 150headers. 151.Sh CONTROL MESSAGES 152This node type supports the generic messages plus the following: 153.Bl -tag -width 4n 154.It Dv NGM_ATM_GET_IFNAME Pq Ic getifname 155Return the name of the interface as a 156.Dv NUL Ns 157-terminated string. 158This is normally the same name as that of the node. 159.It Dv NGM_ATM_GET_CONFIG Pq Ic getconfig 160Returns a structure defining the configuration of the interface: 161.Bd -literal 162struct 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 171Returns the table of open VCCs from the driver. 172This table consists of 173a header and a variable sized array of entries, one for each open VCC: 174.Bd -literal 175struct atmio_vcctable { 176 uint32_t count; /* number of vccs */ 177 struct atmio_vcc vccs[0]; /* array of VCCs */ 178}; 179struct 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}; 189struct 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 205Note that this is the driver's table, so all VCCs opened via 206.Xr natm 4 207sockets and IP are also shown. 208They can, however, be distinguished by 209their flags. 210The 211.Va flags 212field contains the following flags: 213.Pp 214.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact 215.It Dv ATM_PH_AAL5 216use AAL5 instead of AAL0 217.It Dv ATM_PH_LLCSNAP 218if AAL5 use LLC SNAP encapsulation 219.It Dv ATM_FLAG_NG 220this is a netgraph VCC 221.It Dv ATM_FLAG_HARP 222this is a HARP VCC 223.It Dv ATM_FLAG_NORX 224transmit only VCC 225.It Dv ATM_FLAG_NOTX 226receive only VCC 227.It Dv ATMIO_FLAG_PVC 228treat channel as a PVC 229.El 230.Pp 231If the 232.Dv ATM_FLAG_NG 233flag is set, then 234.Va traffic 235and 236.Va tparam 237contain meaningful information. 238.Pp 239The 240.Va aal 241field 242contains one of the following values: 243.Pp 244.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact 245.It Dv ATMIO_AAL_0 246AAL 0 (raw cells) 247.It Dv ATMIO_AAL_34 248AAL 3 or AAL 4 249.It Dv ATMIO_AAL_5 250AAL 5 251.It Dv ATMIO_AAL_RAW 252device specific raw cells 253.El 254.Pp 255The 256.Va traffic 257field 258can have one of the following values (not all drivers support 259all 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 268Initialize a VCC for sending and receiving. 269The argument is a structure: 270.Bd -literal 271struct 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 295The 296.Va name 297field 298is the name of the hook for which sending and receiving should be enabled. 299This hook must already be connected. 300The 301.Va vpi 302and 303.Va vci 304fields 305are the respective VPI and VCI values to use for the ATM cells. 306They must be 307within the range, given by the 308.Va maxvpi 309and 310.Va maxvci 311fields of the 312.Vt ng_atm_config 313structure. 314The 315.Va flags 316field 317contains the flags (see above) and the other fields describe the 318type of traffic. 319.It Dv NGM_ATM_CPCS_TERM Pq Ic cpcsterm 320Stop sending and receiving on the indicated hook. 321The argument is a 322.Bd -literal 323struct ngm_atm_cpcs_term { 324 char name[NG_HOOKSIZ]; 325}; 326.Ed 327.It Dv NGM_ATM_GET_STATS Pq Ic getstats 328This command returns a message, containing node statistics. The 329structure of the message is: 330.Bd -literal 331struct 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 340If the 341.Va manage 342hook is connected, certain messages are sent along the hook. 343They are 344received 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 348A permanent VCC has been added, deleted or changed. 349This is used by 350.Xr ilmid 8 351to generate the appropriate ILMI traps. 352The structure of the message is: 353.Bd -literal 354struct ngm_atm_vcc_change { 355 uint32_t node; 356 uint16_t vci; 357 uint8_t vpi; 358 uint8_t state; 359}; 360.Ed 361Where 362.Va state 363is 0 if the PVC was deleted, and 1 if it was added or modified. 364.El 365.Sh FLOW CONTROL 366If the hardware driver supports it, the node can emit flow control messages 367along a user hook. 368The format of these messages is described in 369.In netgraph/ng_message.h . 370The 371.Nm atm 372node may generate 373.Dv NGM_HIGH_WATER_PASSED 374and 375.Dv NGM_LOW_WATER_PASSED 376messages. 377The first one indicates that the hardware driver has stopped output 378on the channel and drops new packets, the second one reports that 379output was reenabled. 380Currently, the structures are not filled with 381information. 382.Sh SHUTDOWN 383The nodes are persistent as long as the corresponding interface exists. 384Upon receipt of a 385.Dv NGM_SHUTDOWN 386messages, all hooks are disconnected and the node is reinitialized. 387All 388VCCs opened via 389.Xr netgraph 4 390are closed. 391When the ATM interface is unloaded, 392the node disappears. 393If the node is compiled with 394.Dv NGATM_DEBUG 395there is a sysctl 396.Va net.graph.atm.allow_shutdown 397which, when set to a non-zero value, allows the nodes to shut down. 398Note that this is intended for development only and may lead to kernel 399panics 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 Mt harti@FreeBSD.org 407