407 lines
11 KiB
Groff
407 lines
11 KiB
Groff
.\"
|
|
.\" 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 November 2, 2012
|
|
.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 and 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 Pq Ic getifname
|
|
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 Pq Ic getconfig
|
|
Returns a structure defining the configuration of the interface:
|
|
.Bd -literal
|
|
struct ngm_atm_config {
|
|
uint32_t pcr; /* peak cell rate */
|
|
uint32_t vpi_bits; /* number of active VPI bits */
|
|
uint32_t vci_bits; /* number of active VCI bits */
|
|
uint32_t max_vpcs; /* maximum number of VPCs */
|
|
uint32_t max_vccs; /* maximum number of VCCs */
|
|
};
|
|
.Ed
|
|
.It Dv NGM_ATM_GET_VCCS Pq Ic getvccs
|
|
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: ABR/VBR/UBR+MCR 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 Pq Ic cpcsinit
|
|
Initialize a VCC for sending and receiving.
|
|
The argument is a structure:
|
|
.Bd -literal
|
|
struct ngm_atm_cpcs_init {
|
|
char name[NG_HOOKSIZ];
|
|
uint32_t flags; /* flags. (if_atm.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_atm.h) */
|
|
uint8_t traffic; /* traffic type (if_atm.h) */
|
|
uint32_t pcr; /* Peak cell rate */
|
|
uint32_t scr; /* VBR: Sustainable cell rate */
|
|
uint32_t mbs; /* VBR: Maximum burst rate */
|
|
uint32_t mcr; /* UBR+: 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 Pq Ic cpcsterm
|
|
Stop sending and receiving on the indicated hook.
|
|
The argument is a
|
|
.Bd -literal
|
|
struct ngm_atm_cpcs_term {
|
|
char name[NG_HOOKSIZ];
|
|
};
|
|
.Ed
|
|
.It Dv NGM_ATM_GET_STATS Pq Ic getstats
|
|
This command returns a message, containing node statistics.
|
|
The structure of the message is:
|
|
.Bd -literal
|
|
struct ngm_atm_stats {
|
|
uint64_t in_packets;
|
|
uint64_t in_errors;
|
|
uint64_t out_packets;
|
|
uint64_t out_errors;
|
|
};
|
|
.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_VCC_CHANGE Pq Ic 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 ngm_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 Mt harti@FreeBSD.org
|