Copyright (c) 2001-2003
Fraunhofer Institute for Open Communication Systems (FhG Fokus).
All rights reserved.
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 THE 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 THE 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.
Author: Hartmut Brandt <harti@FreeBSD.org>
$FreeBSD: head/share/man/man4/ng_atm.4 141350 2005-02-05 11:31:31Z ru $
ng_atm(4) man page
.Dd June 24, 2003 .Dt NG_ATM 4 .Os .Sh NAME .Nm ng_atm .Nd netgraph ATM node type .Sh SYNOPSIS n sys/types.h n net/if_atm.h n netgraph.h n netgraph/atm/ng_atm.h .Sh DESCRIPTION The .Nm atm netgraph node type allows .Xr natm 4 ATM drivers to be connected to the .Xr netgraph 4 networking subsystem. When the .Nm module is loaded a node is automatically created for each .Xr natm 4 ATM interface. The nodes are named with the same name as the interface. Nodes are also created if a driver for an ATM card is loaded after .Nm was loaded.
p The .Nm atm nodes are persistent. They are removed when the interface is removed. .Dv NGM_SHUTDOWN messages are ignored by the node. .Sh HOOKS Four special hooks with fixed names and an unlimited number of hooks with user defined names are supported. Three of the fixed hooks are attached to strategic points in the information flow in the .Xr natm 4 system and support only reading. The fourth fixed hook behaves like the other user hooks, but a number of management messages are sent along the hook. The other hooks can be attached to VCIs dynamically by means of control messages to the .Nm atm node and can be written and read.
p The four fixed hooks are: l -tag -width ".Va orphans" t Va input This is a connection to the raw input stream from the network. If this hook is connected, all incoming packets are delivered out to this hook. Note that this redirects ALL input. Neither .Xr natm 4 nor the user hooks will see any input if .Va input is connected. An .Vt atm_pseudohdr (see .Xr natm 4 ) is prepended to the actual data. t Va output This is a connection to the raw output stream to the network device. If this hook is connected, all outgoing packets are handed over to the netgraph system and delivered to the hook instead of being delivered to the ATM driver. An .Vt atm_pseudohdr (see .Xr natm 4 ) is prepended to the actual data. t Va orphans This hook receives all packets that are unrecognized, i.e., do not belong to either a .Xr natm 4 socket, a .Nm VCI or .Xr natm 4 IP. Because ATM is connection oriented and packets are received on a given VCI only when someone initiates this VCI, packets should never be orphaned. There is however one exception: if you use .Xr natm 4 IP with LLC/SNAP encapsulation packets with do not have the IP protocol indicated in the packet header are delivered out of this hook. An .Vt atm_pseudohdr (see .Xr natm 4 ) is prepended to the actual data send out to the hook. t Va manage This hook behaves exactly like a normal user hook (see below) except that the node at the other hand will receive management messages. .El
p Hooks for dynamically initiated VCIs can have whatever name is allowed by .Xr netgraph 4 as long as the name does not collide with one of the three predefined names.
p To initiate packet sending an receiving on a dynamic hook one has to issue a .Dv NGM_ATM_CPCS_INIT control message. To terminate sending and receiving one must send a .Dv NGM_ATM_CPCS_TERM message (see .Sx CONTROL MESSAGES ) . The data sent and received on these hooks has no additional headers. .Sh CONTROL MESSAGES This node type supports the generic messages plus the following: l -tag -width 4n t Dv NGM_ATM_GET_IFNAME Return the name of the interface as a .Dv NUL Ns -terminated string. This is normally the same name as that of the node. t Dv NGM_ATM_GET_CONFIG Returns a structure defining the configuration of the interface: d -literal struct ng_atm_config { uint32_t pcr; /* peak cell rate */ uint32_t maxvpi; /* maximum vpi */ uint32_t maxvci; /* maximum vci */ uint32_t max_vpcs; /* maximum number of VPCs */ uint32_t max_vccs; /* maximum number of VCCs */ }; .Ed t Dv NGM_ATM_GET_VCCS Returns the table of open VCCs from the driver. This table consists of a header and a variable sized array of entries, one for each open VCC: d -literal struct atmio_vcctable { uint32_t count; /* number of vccs */ struct atmio_vcc vccs[0]; /* array of VCCs */ }; struct atmio_vcc { uint16_t flags; /* flags */ uint16_t vpi; /* VPI */ uint16_t vci; /* VCI */ uint16_t rmtu; /* Receive maximum CPCS size */ uint16_t tmtu; /* Transmit maximum CPCS size */ uint8_t aal; /* aal type */ uint8_t traffic; /* traffic type */ struct atmio_tparam tparam; /* traffic parameters */ }; struct atmio_tparam { uint32_t pcr; /* 24bit: Peak Cell Rate */ uint32_t scr; /* 24bit: VBR Sustainable Cell Rate */ uint32_t mbs; /* 24bit: VBR Maximum burst size */ uint32_t mcr; /* 24bit: MCR */ uint32_t icr; /* 24bit: ABR ICR */ uint32_t tbe; /* 24bit: ABR TBE (1...2^24-1) */ uint8_t nrm; /* 3bit: ABR Nrm */ uint8_t trm; /* 3bit: ABR Trm */ uint16_t adtf; /* 10bit: ABR ADTF */ uint8_t rif; /* 4bit: ABR RIF */ uint8_t rdf; /* 4bit: ABR RDF */ uint8_t cdf; /* 3bit: ABR CDF */ }; .Ed
p Note that this is the driver's table, so all VCCs opened via .Xr natm 4 sockets and IP are also shown. They can, however, be distinguished by their flags. The .Va flags field contains the following flags:
p l -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact t Dv ATM_PH_AAL5 use AAL5 instead of AAL0 t Dv ATM_PH_LLCSNAP if AAL5 use LLC SNAP encapsulation t Dv ATM_FLAG_NG this is a netgraph VCC t Dv ATM_FLAG_HARP this is a HARP VCC t Dv ATM_FLAG_NORX transmit only VCC t Dv ATM_FLAG_NOTX receive only VCC t Dv ATMIO_FLAG_PVC treat channel as a PVC .El
p If the .Dv ATM_FLAG_NG flag is set, then .Va traffic and .Va tparam contain meaningful information.
p The .Va aal field contains one of the following values:
p l -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact t Dv ATMIO_AAL_0 AAL 0 (raw cells) t Dv ATMIO_AAL_34 AAL 3 or AAL 4 t Dv ATMIO_AAL_5 AAL 5 t Dv ATMIO_AAL_RAW device specific raw cells .El
p The .Va traffic field can have one of the following values (not all drivers support all traffic types however):
p l -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact t Dv ATMIO_TRAFFIC_UBR t Dv ATMIO_TRAFFIC_CBR t Dv ATMIO_TRAFFIC_ABR t Dv ATMIO_TRAFFIC_VBR .El t Dv NGM_ATM_CPCS_INIT Initialize a VCC for sending and receiving. The argument is a structure: d -literal struct ng_atm_cpcs_init { char name[NG_HOOKSIZ]; uint32_t flags; /* flags. (if_natmio.h) */ uint16_t vci; /* VCI to open */ uint16_t vpi; /* VPI to open */ uint16_t rmtu; /* receive maximum PDU */ uint16_t tmtu; /* transmit maximum PDU */ uint8_t aal; /* AAL type (if_natmio.h) */ uint8_t traffic; /* traffic type (if_natmio.h) */ uint32_t pcr; /* Peak cell rate */ uint32_t scr; /* Sustainable cell rate */ uint32_t mbs; /* Maximum burst size */ uint32_t mcr; /* Minimum cell rate */ uint32_t icr; /* ABR: Initial cell rate */ uint32_t tbe; /* ABR: Transmit buffer exposure */ uint8_t nrm; /* ABR: Nrm */ uint8_t trm; /* ABR: Trm */ uint16_t adtf; /* ABR: ADTF */ uint8_t rif; /* ABR: RIF */ uint8_t rdf; /* ABR: RDF */ uint8_t cdf; /* ABR: CDF */ }; .Ed
p The .Va name field is the name of the hook for which sending and receiving should be enabled. This hook must already be connected. The .Va vpi and .Va vci fields are the respective VPI and VCI values to use for the ATM cells. They must be within the range, given by the .Va maxvpi and .Va maxvci fields of the .Vt ng_atm_config structure. The .Va flags field contains the flags (see above) and the other fields describe the type of traffic. t Dv NGM_ATM_CPCS_TERM Stop sending and receiving on the indicated hook. The argument is a d -literal struct ng_atm_cpcs_term { char name[NG_HOOKSIZ]; }; .Ed .El .Sh MANAGEMENT MESSAGES If the .Va manage hook is connected, certain messages are sent along the hook. They are received by the peer node with a cookie of .Dv NG_ATM_COOKIE . l -tag -width 4n t Dv NGM_ATM_CARRIER_CHANGE The carrier state of the ATM physical interface has changed. The message has the following structure: d -literal struct ng_atm_carrier_change { uint32_t node; uint32_t state; }; .Ed
p The .Va node field is the node ID of the ATM node. This can be used by the managing entity (for example .Xr ilmid 8 ) to manage several interfaces at the same time through the same node. The .Va state field is 1 if the carrier was detected, and 0 if it was lost. t Dv NGM_ATM_VCC_CHANGE A permanent VCC has been added, deleted or changed. This is used by .Xr ilmid 8 to generate the appropriate ILMI traps. The structure of the message is: d -literal struct ng_atm_vcc_change { uint32_t node; uint16_t vci; uint8_t vpi; uint8_t state; }; .Ed Where .Va state is 0 if the PVC was deleted, and 1 if it was added or modified. .El .Sh FLOW CONTROL If the hardware driver supports it, the node can emit flow control messages along a user hook. The format of these messages is described in n netgraph/ng_message.h . The .Nm atm node may generate .Dv NGM_HIGH_WATER_PASSED and .Dv NGM_LOW_WATER_PASSED messages. The first one indicates that the hardware driver has stopped output on the channel and drops new packets, the second one reports that output was reenabled. Currently, the structures are not filled with information. .Sh SHUTDOWN The nodes are persistent as long as the corresponding interface exists. Upon receipt of a .Dv NGM_SHUTDOWN messages, all hooks are disconnected and the node is reinitialized. All VCCs opened via .Xr netgraph 4 are closed. When the ATM interface is unloaded, the node disappears. If the node is compiled with .Dv NGATM_DEBUG there is a sysctl .Va net.graph.atm.allow_shutdown which, when set to a non-zero value, allows the nodes to shut down. Note that this is intended for development only and may lead to kernel panics if set. .Sh SEE ALSO .Xr natm 4 , .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ngctl 8 .Sh AUTHORS .An Harti Brandt Aq harti@FreeBSD.org