Provided by: freebsd-manpages_8.2-1_all bug

NAME

     ng_atm — netgraph ATM node type

SYNOPSIS

     #include <sys/types.h>
     #include <net/if_atm.h>
     #include <netgraph.h>
     #include <netgraph/atm/ng_atm.h>

DESCRIPTION

     The atm netgraph node type allows natm(4) ATM drivers to be connected to the netgraph(4)
     networking subsystem.  When the ng_atm module is loaded a node is automatically created for
     each 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 ng_atm was loaded.

     The atm nodes are persistent.  They are removed when the interface is removed.  NGM_SHUTDOWN
     messages are ignored by the node.

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 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 atm node and
     can be written and read.

     The four fixed hooks are:

     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 natm(4) nor the user hooks will see any input if
              input is connected.  An atm_pseudohdr (see natm(4)) is prepended to the actual
              data.

     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
              atm_pseudohdr (see natm(4)) is prepended to the actual data.

     orphans  This hook receives all packets that are unrecognized, i.e., do not belong to either
              a natm(4) socket, a ng_atm VCI or 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
              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 atm_pseudohdr
              (see natm(4)) is prepended to the actual data send out to the hook.

     manage   This hook behaves exactly like a normal user hook (see below) except that the node
              at the other hand will receive management messages.

     Hooks for dynamically initiated VCIs can have whatever name is allowed by netgraph(4) as
     long as the name does not collide with one of the three predefined names.

     To initiate packet sending and receiving on a dynamic hook, one has to issue a
     NGM_ATM_CPCS_INIT control message.  To terminate sending and receiving one must send a
     NGM_ATM_CPCS_TERM message (see CONTROL MESSAGES).  The data sent and received on these hooks
     has no additional headers.

CONTROL MESSAGES

     This node type supports the generic messages plus the following:

     NGM_ATM_GET_IFNAME
           Return the name of the interface as a NUL-terminated string.  This is normally the
           same name as that of the node.

     NGM_ATM_GET_CONFIG
           Returns a structure defining the configuration of the interface:

           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 */
           };

     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:

           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 */
           };

           Note that this is the driver's table, so all VCCs opened via natm(4) sockets and IP
           are also shown.  They can, however, be distinguished by their flags.  The flags field
           contains the following flags:

                 ATM_PH_AAL5     use AAL5 instead of AAL0
                 ATM_PH_LLCSNAP  if AAL5 use LLC SNAP encapsulation
                 ATM_FLAG_NG     this is a netgraph VCC
                 ATM_FLAG_HARP   this is a HARP VCC
                 ATM_FLAG_NORX   transmit only VCC
                 ATM_FLAG_NOTX   receive only VCC
                 ATMIO_FLAG_PVC  treat channel as a PVC

           If the ATM_FLAG_NG flag is set, then traffic and tparam contain meaningful
           information.

           The aal field contains one of the following values:

                 ATMIO_AAL_0     AAL 0 (raw cells)
                 ATMIO_AAL_34    AAL 3 or AAL 4
                 ATMIO_AAL_5     AAL 5
                 ATMIO_AAL_RAW   device specific raw cells

           The traffic field can have one of the following values (not all drivers support all
           traffic types however):

                 ATMIO_TRAFFIC_UBR
                 ATMIO_TRAFFIC_CBR
                 ATMIO_TRAFFIC_ABR
                 ATMIO_TRAFFIC_VBR

     NGM_ATM_CPCS_INIT
           Initialize a VCC for sending and receiving.  The argument is a structure:

           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 */
           };

           The name field is the name of the hook for which sending and receiving should be
           enabled.  This hook must already be connected.  The vpi and vci fields are the
           respective VPI and VCI values to use for the ATM cells.  They must be within the
           range, given by the maxvpi and maxvci fields of the ng_atm_config structure.  The
           flags field contains the flags (see above) and the other fields describe the type of
           traffic.

     NGM_ATM_CPCS_TERM
           Stop sending and receiving on the indicated hook.  The argument is a

           struct ng_atm_cpcs_term {
                   char            name[NG_HOOKSIZ];
           };

MANAGEMENT MESSAGES

     If the manage hook is connected, certain messages are sent along the hook.  They are
     received by the peer node with a cookie of NG_ATM_COOKIE.

     NGM_ATM_CARRIER_CHANGE
           The carrier state of the ATM physical interface has changed.  The message has the
           following structure:

           struct ng_atm_carrier_change {
                   uint32_t        node;
                   uint32_t        state;
           };

           The node field is the node ID of the ATM node.  This can be used by the managing
           entity (for example ilmid(8)) to manage several interfaces at the same time through
           the same node.  The state field is 1 if the carrier was detected, and 0 if it was
           lost.

     NGM_ATM_VCC_CHANGE
           A permanent VCC has been added, deleted or changed.  This is used by ilmid(8) to
           generate the appropriate ILMI traps.  The structure of the message is:

           struct ng_atm_vcc_change {
                   uint32_t        node;
                   uint16_t        vci;
                   uint8_t         vpi;
                   uint8_t         state;
           };
           Where state is 0 if the PVC was deleted, and 1 if it was added or modified.

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 <netgraph/ng_message.h>.  The atm node
     may generate NGM_HIGH_WATER_PASSED and 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.

SHUTDOWN

     The nodes are persistent as long as the corresponding interface exists.  Upon receipt of a
     NGM_SHUTDOWN messages, all hooks are disconnected and the node is reinitialized.  All VCCs
     opened via netgraph(4) are closed.  When the ATM interface is unloaded, the node disappears.
     If the node is compiled with NGATM_DEBUG there is a sysctl 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.

SEE ALSO

     natm(4), netgraph(4), ng_ether(4), ngctl(8)

AUTHORS

     Harti Brandt <harti@FreeBSD.org>