diff options
Diffstat (limited to 'share/man/man4/ng_atm.4')
| -rw-r--r-- | share/man/man4/ng_atm.4 | 416 |
1 files changed, 416 insertions, 0 deletions
diff --git a/share/man/man4/ng_atm.4 b/share/man/man4/ng_atm.4 new file mode 100644 index 000000000000..df4c2e341ef9 --- /dev/null +++ b/share/man/man4/ng_atm.4 @@ -0,0 +1,416 @@ +.\" +.\" 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$ +.\" +.\" 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 +.In sys/types.h +.In net/if_atm.h +.In netgraph.h +.In 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. +.Pp +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. +.Pp +The four fixed hooks are: +.Bl -tag -width ".Va orphans" +.It 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. +.It 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. +.It 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. +.It 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 +.Pp +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. +.Pp +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: +.Bl -tag -width 4n +.It 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. +.It Dv NGM_ATM_GET_CONFIG +Returns a structure defining the configuration of the interface: +.Bd -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 +.It 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: +.Bd -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 +.Pp +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: +.Pp +.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact +.It Dv ATM_PH_AAL5 +use AAL5 instead of AAL0 +.It Dv ATM_PH_LLCSNAP +if AAL5 use LLC SNAP encapsulation +.It Dv ATM_FLAG_NG +this is a netgraph VCC +.It Dv ATM_FLAG_HARP +this is a HARP VCC +.It Dv ATM_FLAG_NORX +transmit only VCC +.It Dv ATM_FLAG_NOTX +receive only VCC +.It Dv ATMIO_FLAG_PVC +treat channel as a PVC +.El +.Pp +If the +.Dv ATM_FLAG_NG +flag is set, then +.Va traffic +and +.Va tparam +contain meaningful information. +.Pp +The +.Va aal +field +contains one of the following values: +.Pp +.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact +.It Dv ATMIO_AAL_0 +AAL 0 (raw cells) +.It Dv ATMIO_AAL_34 +AAL 3 or AAL 4 +.It Dv ATMIO_AAL_5 +AAL 5 +.It Dv ATMIO_AAL_RAW +device specific raw cells +.El +.Pp +The +.Va traffic +field +can have one of the following values (not all drivers support +all traffic types however): +.Pp +.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact +.It Dv ATMIO_TRAFFIC_UBR +.It Dv ATMIO_TRAFFIC_CBR +.It Dv ATMIO_TRAFFIC_ABR +.It Dv ATMIO_TRAFFIC_VBR +.El +.It Dv NGM_ATM_CPCS_INIT +Initialize a VCC for sending and receiving. +The argument is a structure: +.Bd -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 +.Pp +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. +.It Dv NGM_ATM_CPCS_TERM +Stop sending and receiving on the indicated hook. +The argument is a +.Bd -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 . +.Bl -tag -width 4n +.It Dv NGM_ATM_CARRIER_CHANGE +The carrier state of the ATM physical interface has changed. +The message has the following structure: +.Bd -literal +struct ng_atm_carrier_change { + uint32_t node; + uint32_t state; +}; +.Ed +.Pp +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. +.It 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: +.Bd -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 +.In 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 |