Documentation/networking/slicecom.txt

   1
   2 SliceCOM adapter user's documentation - for the 0.51 driver version
   3
   4 Written by Bartók István <bartoki@itc.hu>
   5
   6 English translation: Lakatos György <gyuri@itc.hu>
   7 Mon Dec 11 15:28:42 CET 2000
   8
   9 Last modified: Wed Aug 29 17:25:37 CEST 2001
  10
  11 -----------------------------------------------------------------
  12
  13 Usage:
  14
  15 Compiling the kernel:
  16
  17 Code maturity level options
  18         [*] Prompt for development and/or incomplete code/drivers
  19
  20 Network device support
  21         Wan interfaces
  22                 <M> MultiGate (COMX) synchronous
  23                         <M> Support for MUNICH based boards: SliceCOM, PCICOM (NEW)
  24                         <M> Support for HDLC and syncPPP...
  25
  26
  27 Loading the modules:
  28
  29 modprobe comx
  30
  31 modprobe comx-proto-ppp         # module for  Cisco-HDLC and SyncPPP protocols
  32
  33 modprobe comx-hw-munich         # the module logs information by the kernel
  34                                 # about the detected boards
  35
  36
  37 Configuring the board:
  38
  39 # This interface will use the Cisco-HDLC line protocol,
  40 # the timeslices assigned are 1,2 (128 KiBit line speed)
  41 # (the first data timeslice in the G.703 frame is no. 1)
  42 #
  43 mkdir /proc/comx/comx0.1/
  44 echo slicecom   >/proc/comx/comx0.1/boardtype
  45 echo hdlc       >/proc/comx/comx0.1/protocol
  46 echo 1 2        >/proc/comx/comx0.1/timeslots
  47
  48
  49 # This interface uses SyncPPP line protocol, the assigned
  50 # is no. 3 (64 KiBit line speed)
  51 #
  52 mkdir /proc/comx/comx0.2/
  53 echo slicecom   >/proc/comx/comx0.2/boardtype
  54 echo ppp        >/proc/comx/comx0.2/protocol
  55 echo 3          >/proc/comx/comx0.2/timeslots
  56
  57 ...
  58
  59 ifconfig comx0.1 up
  60 ifconfig comx0.2 up
  61
  62 -----------------------------------------------------------------
  63
  64 The COMX interfaces use a 10 packet transmit queue by default, however WAN
  65 networks sometimes use bigger values (20 to 100), to utilize the line better
  66 by large traffic (though the line delay increases because of more packets
  67 join the queue).
  68
  69 # ifconfig comx0 txqueuelen 50
  70
  71 This option is only supported by the ifconfig command of the later
  72 distributions, which came with 2.2 kernels, such as RedHat 6.1 or Debian 2.2.
  73
  74 You can download a newer netbase packet from
  75 http://www.debian.org/~rcw/2.2/netbase/ for Debian 2.1, which has a new
  76 ifconfig. You can get further information about using 2.2 kernel with
  77 Debian 2.1 from http://www.debian.org/releases/stable/running-kernel-2.2
  78
  79 -----------------------------------------------------------------
  80
  81 The SliceCom LEDs:
  82
  83 red     - on, if the interface is unconfigured, or it gets Remote Alarm-s
  84 green   - on, if the board finds frame-sync in the received signal
  85
  86 A bit more detailed:
  87
  88 red:    green:  meaning:
  89
  90 -       -       no frame-sync, no signal received, or signal SNAFU.
  91 -       on      "Everything is OK"
  92 on      on      Reception is ok, but the remote end sends Remote Alarm
  93 on      -       The interface is unconfigured
  94
  95 -----------------------------------------------------------------
  96
  97 A more detailed description of the hardware setting options:
  98
  99 The general and the protocol layer options described in the 'comx.txt' file
 100 apply to the SliceCom as well, I only summarize the SliceCom hardware specific
 101 settings below.
 102
 103 The '/proc/comx' configuring interface:
 104
 105 An interface directory should be created for every timeslot group with
 106 'mkdir', e,g: 'comx0', 'comx1' etc. The timeslots can be assigned here to the
 107 specific interface. The Cisco-like naming convention (serial3:1 - first
 108 timeslot group of the 3rd. board) can't be used here, because these mean IP
 109 aliasing in Linux.
 110
 111 You can give any meaningful name to keep the configuration clear;
 112 e.g: 'comx0.1', 'comx0.2', 'comx1.1', comx1.2', if you have two boards
 113 with two interfaces each.
 114
 115 Settings, which apply to the board:
 116
 117 Neither 'io' nor 'irq' settings required, the driver uses the resources
 118 given by the PCI BIOS.
 119
 120 comx0/boardnum  - board number of the SliceCom in the PC (using the 'natural'
 121                 PCI order) as listed in '/proc/pci' or the output of the
 122                 'lspci' command, generally the slots nearer to the motherboard
 123                 PCI driver chips have the lower numbers.
 124
 125                 Default: 0 (the counting starts with 0)
 126
 127 Though the options below are to be set on a single interface, they apply to the
 128 whole board. The restriction, to use them on 'UP' interfaces, is because the
 129 command sequence below could lead to unpredictable results.
 130
 131         # echo 0        >boardnum
 132         # echo internal >clock_source
 133         # echo 1        >boardnum
 134
 135 The sequence would set the clock source of board 0.
 136
 137 These settings will persist after all the interfaces are cleared, but are
 138 cleared when the driver module is unloaded and loaded again.
 139
 140 comx0/clock_source - source of the transmit clock
 141         Usage:
 142
 143         # echo line     >/proc/comx/comx0/clock_source
 144         # echo internal >/proc/comx/comx0/clock_source
 145
 146         line    - The Tx clock is being decoded if the input data stream,
 147                 if no clock seen on the input, then the board will use it's
 148                 own clock generator.
 149
 150         internal - The Tx clock is supplied by the builtin clock generator.
 151
 152         Default: line
 153
 154         Normally, the telecommunication company's end device (the HDSL
 155         modem) provides the Tx clock, that's why 'line' is the default.
 156
 157 comx0/framing   - Switching CRC4 off/on
 158
 159         CRC4: 16 PCM frames (The 32 64Kibit channels are multiplexed into a
 160         PCM frame, nothing to do with HDLC frames) are divided into 2x8
 161         groups, each group has a 4 bit CRC.
 162
 163         # echo crc4     >/proc/comx/comx0/framing
 164         # echo no-crc4  >/proc/comx/comx0/framing
 165
 166         Default is 'crc4', the Hungarian MATAV lines behave like this.
 167         The traffic generally passes if this setting on both ends don't match.
 168
 169 comx0/linecode  - Setting the line coding
 170
 171         # echo hdb3     >/proc/comx/comx0/linecode
 172         # echo ami      >/proc/comx/comx0/linecode
 173
 174         Default a 'hdb3', MATAV lines use this.
 175
 176         (AMI coding is rarely used with E1 lines). Frame sync may occur, if
 177         this setting doesn't match the other end's, but CRC4 and data errors
 178         will come, which will result in CRC errors on HDLC/SyncPPP level.
 179
 180 comx0/reg       - direct access to the board's MUNICH (reg) and FALC (lbireg)
 181 comx0/lbireg    circuit's registers
 182
 183         # echo >reg 0x04 0x0    - write 0 to register 4
 184         # echo >reg 0x104       - write the contents of register 4 with
 185                                 printk() to syslog
 186
 187 WARNING! These are only for development purposes, messing with this will
 188         result much trouble!
 189
 190 comx0/loopback - Places a loop to the board's G.703 signals
 191
 192         # echo none   >/proc/comx/comx0/loopback
 193         # echo local  >/proc/comx/comx0/loopback
 194         # echo remote >/proc/comx/comx0/loopback
 195
 196         none   - normal operation, no loop
 197         local  - the board receives it's own output
 198         remote - the board sends the received data to the remote side
 199
 200         Default: none
 201
 202 -----------------------------------------------------------------
 203
 204 Interface (channel group in Cisco terms) settings:
 205
 206 comx0/timeslots - which timeslots belong to the given interface
 207
 208         Setting:
 209
 210         # echo '1 5 2 6 7 8' >/proc/comx/comx0/timeslots
 211
 212         # cat /proc/comx/comx0/timeslots
 213         1 2 5 6 7 8
 214         #
 215
 216         Finding a timeslot:
 217
 218         # grep ' 4' /proc/comx/comx*/timeslots
 219         /proc/comx/comx0/timeslots:1 3 4 5 6
 220         #
 221
 222         The timeslots can be in any order, '1 2 3' is the same as '1 3 2'.
 223
 224         The interface has to be DOWN during the setting ('ifconfig comx0
 225         down'), but the other interfaces could operate normally.
 226
 227         The driver checks if the assigned timeslots are vacant, if not, then
 228         the setting won't be applied.
 229
 230         The timeslot values are treated as decimal numbers, not to misunderstand
 231         values of 08, 09 form.
 232
 233 -----------------------------------------------------------------
 234
 235 Checking the interface and board status:
 236
 237 - Lines beginning with ' ' (space) belong to the original output, the lines
 238 which begin with '//' are the comments.
 239
 240  papaya:~$ cat /proc/comx/comx1/status
 241  Interface administrative status is UP, modem status is UP, protocol is UP
 242  Modem status changes: 0, Transmitter status is IDLE, tbusy: 0
 243  Interface load (input): 978376 / 947808 / 951024 bits/s (5s/5m/15m)
 244                (output): 978376 / 947848 / 951024 bits/s (5s/5m/15m)
 245  Debug flags: none
 246  RX errors: len: 22, overrun: 1, crc: 0, aborts: 0
 247             buffer overrun: 0, pbuffer overrun: 0
 248  TX errors: underrun: 0
 249  Line keepalive (value: 10) status UP [0]
 250
 251 // The hardware specific part starts here:
 252  Controller status:
 253          No alarms
 254
 255 // Alarm:
 256 //
 257 // No alarms - Everything OK
 258 //
 259 // LOS  - Loss Of Signal - No signal sensed on the input
 260 // AIS  - Alarm Indication Signal - The remote side sends '11111111'-s,
 261 //      it tells, that there's an error condition, or it's not
 262 //      initialised.
 263 // AUXP - Auxiliary Pattern Indication - 01010101.. received.
 264 // LFA  - Loss of Frame Alignment - no frame sync received.
 265 // RRA  - Receive Remote Alarm - the remote end's OK, but signals error cond.
 266 // LMFA - Loss of CRC4 Multiframe Alignment - no CRC4 multiframe sync.
 267 // NMF  - No Multiframe alignment Found after 400 msec - no such alarm using
 268 //      no-crc4 or crc4 framing, see below.
 269 //
 270 // Other possible error messages:
 271 //
 272 // Transmit Line Short - the board felt, that it's output is short-circuited,
 273 //      so it switched the transmission off. (The board can't definitely tell,
 274 //      that it's output is short-circuited.)
 275
 276 // Chained list of the received packets, for debug purposes:
 277
 278  Rx ring:
 279          rafutott: 0
 280          lastcheck: 50845731, jiffies: 51314281
 281          base: 017b1858
 282          rx_desc_ptr: 0
 283          rx_desc_ptr: 017b1858
 284          hw_curr_ptr: 017b1858
 285          06040000 017b1868 017b1898 c016ff00
 286          06040000 017b1878 017b1e9c c016ff00
 287          46040000 017b1888 017b24a0 c016ff00
 288          06040000 017b1858 017b2aa4 c016ff00
 289
 290 // All the interfaces using the board: comx1, using the 1,2,...16 timeslots,
 291 // comx2, using timeslot 17, etc.
 292
 293  Interfaces using this board: (channel-group, interface, timeslots)
 294           0 comx1: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
 295           1 comx2: 17
 296           2 comx3: 18
 297           3 comx4: 19
 298           4 comx5: 20
 299           5 comx6: 21
 300           6 comx7: 22
 301           7 comx8: 23
 302           8 comx9: 24
 303           9 comx10: 25
 304          10 comx11: 26
 305          11 comx12: 27
 306          12 comx13: 28
 307          13 comx14: 29
 308          14 comx15: 30
 309          15 comx16: 31
 310
 311 // The number of events handled by the driver during an interrupt cycle:
 312
 313  Interrupt work histogram:
 314  hist[ 0]:        0 hist[ 1]:        2 hist[ 2]:    18574 hist[ 3]:       79
 315  hist[ 4]:       14 hist[ 5]:        1 hist[ 6]:        0 hist[ 7]:        1
 316  hist[ 8]:        0 hist[ 9]:        7
 317
 318 // The number of packets to send in the Tx ring, when a new one arrived:
 319
 320  Tx ring histogram:
 321  hist[ 0]:     2329 hist[ 1]:        0 hist[ 2]:        0 hist[ 3]:        0
 322
 323 // The error counters of the E1 interface, according to the RFC2495,
 324 // (similar to the Cisco "show controllers e1" command's output:
 325 // http://www.cisco.com/univercd/cc/td/doc/product/software/ios11/rbook/rinterfc.htm#xtocid25669126)
 326
 327 Data in current interval (91 seconds elapsed):
 328    9516 Line Code Violations, 65 Path Code Violations, 2 E-Bit Errors
 329    0 Slip Secs, 2 Fr Loss Secs, 2 Line Err Secs, 0 Degraded Mins
 330    0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 11 Unavail Secs
 331 Data in Interval 1 (15 minutes):
 332    0 Line Code Violations, 0 Path Code Violations, 0 E-Bit Errors
 333    0 Slip Secs, 0 Fr Loss Secs, 0 Line Err Secs, 0 Degraded Mins
 334    0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 0 Unavail Secs
 335 Data in last 4 intervals (1 hour):
 336    0 Line Code Violations, 0 Path Code Violations, 0 E-Bit Errors
 337    0 Slip Secs, 0 Fr Loss Secs, 0 Line Err Secs, 0 Degraded Mins
 338    0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 0 Unavail Secs
 339 Data in last 96 intervals (24 hours):
 340    0 Line Code Violations, 0 Path Code Violations, 0 E-Bit Errors
 341    0 Slip Secs, 0 Fr Loss Secs, 0 Line Err Secs, 0 Degraded Mins
 342    0 Errored Secs, 0 Bursty Err Secs, 0 Severely Err Secs, 0 Unavail Secs
 343
 344 -----------------------------------------------------------------
 345
 346 Some unique options, (may get into the driver later):
 347 Treat them very carefully, these can cause much trouble!
 348
 349         modified CRC-4, for improved interworking of CRC-4 and non-CRC-4
 350         devices: (see page 107 and g706 Annex B)
 351                 lbireg[ 0x1b ] |= 0x08
 352                 lbireg[ 0x1c ] |= 0xc0
 353
 354         - The NMF - 'No Multiframe alignment Found after 400 msec' alarm
 355         comes into account.
 356
 357         FALC - the line driver chip.
 358         local loop - I hear my transmission back.
 359         remote loop - I echo the remote transmission back.
 360
 361         Something useful for finding errors:
 362
 363                 - local loop for timeslot 1 in the FALC chip:
 364
 365         # echo >lbireg 0x1d 0x21
 366
 367                 - Switching the loop off:
 368
 369         # echo >lbireg 0x1d 0x00