contrib/ngatm/snmp_atm/snmp_atm.3

   1 .\"
   2 .\" Copyright (c) 2001-2002
   3 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   4 .\"     All rights reserved.
   5 .\" Copyright (c) 2003-2004
   6 .\"     Hartmut Brandt.
   7 .\"     All rights reserved.
   8 .\"
   9 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Begemot: libunimsg/snmp_atm/snmp_atm.3,v 1.2 2005/05/23 12:00:29 brandt_h Exp $
  33 .\"
  34 .Dd May 23, 2005
  35 .Dt SNMP_ATM 3
  36 .Os
  37 .Sh NAME
  38 .Nm atmif_event_f ,
  39 .Nm atm_find_if_name ,
  40 .Nm atm_find_if ,
  41 .Nm atm_notify_aif ,
  42 .Nm atm_unnotify_aif
  43 .Nd "ATM driver module for snmpd.
  44 .Sh LIBRARY
  45 .Pq begemotSnmpdModulePath."netgraph" = "@MODPATH@snmp_netgraph.so" (FreeBSD)
  46 .Pq begemotSnmpdModulePath."mibII" = "@MODPATH@snmp_mibII.so"
  47 .Pq begemotSnmpdModulePath."atm" = "@MODPATH@snmp_atm.so"
  48 .Sh SYNOPSIS
  49 .In bsnmp/snmpmod.h
  50 .In bsnmp/snmp_mibII.h
  51 .In bsnmp/snmp_atm.h
  52 .Ft typedef void
  53 .Fn (*atmif_event_f) "struct atmif *aif" "enum atmif_notify event" "uintptr_t data" "void *uarg"
  54 .Ft struct atmif *
  55 .Fn atm_find_if_name "const char *name"
  56 .Ft struct atmif *
  57 .Fn atm_find_if "u_int ifindex"
  58 .Ft void *
  59 .Fn atm_notify_aif "struct atmif *aif" "const struct lmodule *mod" "atmif_event_f func" "void *uarg"
  60 .Ft void
  61 .Fn atm_unnotify_aif "void *not"
  62 .Sh DESCRIPTION
  63 The
  64 .Nm snmp_atm
  65 module implements a number of tables and scalars that enable remote access to
  66 the ATM devices in the system. It also exports a number of
  67 functions, that allow other modules to easily access ATM devices.
  68 .Pp
  69 The module maintains an extension to the interface structure exported by
  70 .Xr snmp_mibII 3
  71 for all ATM devices. This structure has the following fields:
  72 .Bd -literal -offset indent
  73 struct atmif {
  74         struct mibif    *ifp;           /* common interface data */
  75         struct atmif_mib *mib;          /* ATM MIB */
  76         enum atmif_carrier_state carrier;
  77         enum atmif_suni_mode mode;      /* SUNI mode SDH or SONET */
  78 };
  79 .Ed
  80 .Pp
  81 The fields have the following meaning:
  82 .Bl -tag -width XXX
  83 .It Fa ifp
  84 The field points to the
  85 .Xr snmp_mibII 3
  86 interface structure.
  87 .It Fa mib
  88 The special ATM interface MIB (see below).
  89 .It Fa carrier
  90 The current state of the carrier. One of the following:
  91 .Bl -tag -width XXX
  92 .It Dv ATMIF_CARRIER_ON
  93 carrier detected,
  94 .It Dv ATMIF_CARRIER_OFF
  95 no carrier,
  96 .It Dv ATMIF_CARRIER_UNKNOWN
  97 the state of the carrier is unknown,
  98 .It Dv ATMIF_CARRIER_NONE
  99 the device has no notion of carrier or is not able to sense it.
 100 .El
 101 .It Fa mode
 102 For ATM devices with a SUNI chip this is the current mode of the interface:
 103 .Bl -tag -width XXX
 104 .It Dv ATMIF_SUNI_MODE_SONET
 105 The interface is in SONET mode.
 106 .It Dv ATMIF_SUNI_MODE_SDH
 107 The interface is in SDH mode.
 108 .It Dv ATMIF_SUNI_MODE_UNKNOWN
 109 The interface either has no SUNI interface or the mode is unknown (for example,
 110 interface is down).
 111 .El
 112 .El
 113 .Pp
 114 An ATM interface can be found by name or by SNMP interface index (see
 115 .Xr snmp_mibII 3
 116 for a discussion of interface indexes).
 117 The function
 118 .Fn atm_find_if_name
 119 searches an interface given a name.
 120 The function
 121 .Fn atm_find_if
 122 searches an interface by its interface index.
 123 Both functions return NULL if an interface cannot be found.
 124 .Pp
 125 The ATM MIB contains the following fields:
 126 .Bd -literal -offset indent
 127 struct atmif_mib {
 128         u_int   version;        /* currently 0 */
 129
 130         u_int   device;         /* type of hardware (system specific) */
 131         u_int   serial;         /* card serial number (device specific) */
 132         u_int   hw_version;     /* card version (device specific) */
 133         u_int   sw_version;     /* firmware version (device specific) */
 134         u_int   media;          /* physical media (see MIB) */
 135
 136         u_char  esi[6];         /* end system identifier (MAC) */
 137         u_int   pcr;            /* supported peak cell rate */
 138         u_int   vpi_bits;       /* number of used bits in VPI field */
 139         u_int   vci_bits;       /* number of used bits in VCI field */
 140         u_int   max_vpcs;       /* maximum number of VPCs */
 141         u_int   max_vccs;       /* maximum number of VCCs */
 142 };
 143 .Ed
 144 .Ss NOTIFICATIONS
 145 An other module can register with
 146 .Nm
 147 to receive notifications when certain events happen on the ATM interface.
 148 The registration is done with
 149 .Fn atm_notify_aif
 150 which takes a pointer to the interface, the calling module pointer, a callback
 151 function and a user argument that is passed to the callback function.
 152 The callback function is called with the interface pointer, a notification
 153 code, a notification argument and the user argument. The following
 154 notifications are defined:
 155 .Bl -tag -width XXX
 156 .It Dv ATMIF_NOTIFY_DESTROY
 157 The interface is destroyed. The notification argument is not used.
 158 .It Dv ATMIF_NOTIFY_CARRIER
 159 The carrier state on the interface has changed. The argument is the
 160 .Em old
 161 state of the carrier. The new state can be obtained from the interface
 162 structure.
 163 .It Dv ATMIF_NOTIFY_VCC
 164 A permanent VCC has been created or destroyed. The argument is an u_int that
 165 can be decoded as follows:
 166 .Bd -literal -offset indent
 167 vpi = (arg >> 24) & 0xff;
 168 vci = (arg >>  8) & 0xffff;
 169 state = arg & 1;
 170 .Ed
 171 .Pp
 172 .Va state
 173 is 0 if the VCC was destroyed and 1 if it was created.
 174 .El
 175 The registration for notification can be undone by passing the return
 176 value from
 177 .Fn atm_notify_aif
 178 to
 179 .Fn atm_unnotify_aif .
 180 The registrations is automatically removed if the interface is destroyed.
 181 .Ss MIB
 182 The MIB implemented by the module is defined in
 183 .Pa BEGEMOT-ATM.txt .
 184 In the generic part there are two tables and one scalar, there is also
 185 a system specific group:
 186 .Bl -tag -width XXX
 187 .It Va begemotAtmIfTable
 188 This table is an extension of
 189 .Va ifTable .
 190 It contains a row for each ATM interface and is index with
 191 .Va ifIndex .
 192 All fields are read-only except the
 193 .Va begemotAtmIfMode
 194 column.
 195 .It Va begemotAtmIfTableLastChange
 196 Contains the tick when a row was created or destroyed in the above table or
 197 0, if the table did not change since start of the SNMP agent.
 198 .It Va begemotAtmHWTable
 199 Is also indexed by
 200 .Va ifIndex
 201 and contains hardware specific information. This table is read-only.
 202 .El
 203 .Sh FILES
 204 .Bl -tag -width "XXXXXXXXX"
 205 .It Pa @DEFPATH@atm_tree.def
 206 The description of the MIB tree implemented by
 207 .Nm .
 208 .It Pa @MIBSPATH@BEGEMOT-ATM.txt
 209 This is the MIB that is implemented by this module.
 210 .El
 211 .Sh SEE ALSO
 212 .Xr bsnmpd 1 ,
 213 .Xr gensnmptree 1 ,
 214 .Xr snmp_mibII 3 ,
 215 .Xr snmpmod 3 ,
 216 .Xr snmp_netgraph 3
 217 .Sh AUTHORS
 218 .An Hartmut Brandt Aq harti@FreeBSD.org