1 .\" Copyright (c) 2003 David Boggs. (boggs@boggs.palo-alto.ca.us)
2 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" GNU General Public License:
29 .\" This program is free software; you can redistribute it and/or modify it
30 .\" under the terms of the GNU General Public License as published by the Free
31 .\" Software Foundation; either version 2 of the License, or (at your option)
32 .\" any later version.
34 .\" This program is distributed in the hope that it will be useful, but WITHOUT
35 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
36 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
39 .\" You should have received a copy of the GNU General Public License along with
40 .\" this program; if not, write to the Free Software Foundation, Inc., 59
41 .\" Temple Place - Suite 330, Boston, MA 02111-1307, USA.
50 .Nd configuration program for
54 wide-area network interface cards
58 .Op Fl abBcCdDeEfhLmMpPrsStTuwxXyYzZ?
62 .Op Fl aABceEfFgiIlLpPstTuUxX
71 is the configuration program for the
73 wide-area network device driver.
74 It sets control values, such as T3 framing format,
75 and it displays status, such as that of integrated modems,
76 that are beyond the scope of
82 displays the interface status when no parameters are specified;
84 For this case only, if no
86 is specified, it defaults to
89 Only the super-user may modify the configuration of a network interface.
91 The following options are available:
92 .Bl -tag -width indent
94 This is the name of the interface; the default is
98 is present and the interface name ends with a colon
99 then Netgraph control messages are used,
102 kernel interface and socket
104 system calls are used.
106 All parameters after this apply to the T1E1 card.
108 All parameters after this apply to the T3 card.
110 .Ss Commands for all cards
111 The following parameters apply to more than one card type.
112 .Bl -tag -width indent
114 Set Transmitter clock source to
117 .Bl -column "1" "External connector" "T1E1, HSSIc" -offset 2m -compact
118 .It "1" Ta "TxClk from modem" Ta "T1E1, HSSI" Ta "default"
119 .It "2" Ta "Internal source" Ta "T1E1, HSSI"
120 .It "3" Ta "RxClk from modem" Ta "T1E1, HSSIc" Ta "loop timed"
121 .It "4" Ta "External connector" Ta "T1E1, HSSIc"
124 An HSSI card normally takes its Tx clock from the modem connector
125 (it is a DTE) but can use the PCI bus clock (typically 33 MHz)
126 for loopback and null modem testing; values 3 and 4 are only
127 applicable to a few rare CompactPCI/HSSI cards.
129 A T1E1 card uses an on-board synthesized oscillator
130 if the value is 1 or 2; it
132 (uses the clock recovered by the receiver as the transmitter clock)
133 if the value is 3; and it uses a clock from a header connector on
134 the card if the value is 4.
136 TxClk source is not applicable to other card types.
139 Print the first 256 locations.
140 The BIOS ROM is not used and not present on some cards.
143 Write the first 256 locations with an address pattern.
145 Use HDLC's 16-bit CRC polynomial: X^16+X^12+X^5+1 (default).
147 Use HDLC's 32-bit CRC polynomial:
148 X^32+X^26+X^23+X^22+X^16+X^12+X^11+X^10+X^8+X^7+X^5+X^4+X^2+X+1
150 Clear the driver-level debug flag.
151 Non-critical log messages are suppressed.
153 Set the driver-level debug flag.
154 The driver generates more log messages.
155 The driver also generates more log messages if the interface-level debug
159 Set DTE (Data Terminal Equipment) mode (default).
160 An SSI card transmitter uses the Tx clock signal from the modem connector
161 and receives the Data Carrier Detect pin (DCD).
162 DTE/DCE is not applicable to other card types except
163 a few rare CompactPCI/HSSI cards.
165 Set DCE (Data Communication Equipment) mode.
166 An SSI card transmitter uses an on-board synthesized oscillator
167 and drives the Data Carrier Detect pin (DCD).
169 Set the frequency of the built-in synthesized oscillator to
172 The nearest frequency that the synthesizer can generate will be used.
173 Only SSI cards and a few rare CompactPCI/HSSI cards have synthesizers.
175 Set SPPP line protocol to Frame-Relay.
180 Print help (usage message).
182 Set interface name (e.g.\&
188 .Bl -column "99" "payload" "inward thru drvrs/rcvrsxxx" "HSSI, SSI" -offset 1m -compact
189 .It "1" Ta "none" Ta "default" Ta \&
190 .It "2" Ta "payload" Ta "outward thru framer" Ta "T1E1. T3"
191 .It "3" Ta "line" Ta "outward thru line if" Ta "T1E1, T3, HSSIc"
192 .It "4" Ta "other" Ta "inward thru line if" Ta "T1E1, T3"
193 .It "5" Ta "inward" Ta "inward thru framer" Ta "T1E1, T3"
194 .It "6" Ta "dual" Ta "inward and outward" Ta "T1E1, T3"
195 .It "16" Ta "tulip" Ta "inward thru Tulip chip" Ta "all cards"
196 .It "17" Ta "pins" Ta "inward thru drvrs/rcvrs" Ta "SSI"
197 .It "18" Ta "LA/LL" Ta "assert LA/LL modem pin" Ta "HSSI, SSI"
198 .It "19" Ta "LB/RL" Ta "assert LB/RL modem pin" Ta "HSSI, SSI"
201 Read Tulip MII registers.
202 Print the 32 16-bit registers in the Media Independent Interface.
203 .It Fl M Ar addr Ar data
204 Write Tulip MII register.
210 Read Tulip PCI configuration registers.
211 Print the first 16 32-bit registers in the PCI configuration space.
212 .It Fl P Ar addr Ar data
213 Write Tulip PCI configuration register.
220 Print the 64 16-bit locations.
221 The PCI subsystem vendor and device IDs are kept here.
224 Initializes the Tulip SROM to card type
227 .Bl -column "9" -offset 1m -compact
234 .It 0 Ta auto-set from MII PHYID
239 is zero, then the card type is computed from the gate array
240 microcode version field in the MII PHYID register.
242 if the SROM is incorrect, the card will be unusable!
247 must be edited and recompiled to enable it.
250 Print the 16 32-bit control and status registers.
251 .It Fl T Ar addr Ar data
259 is a CSR number (0-15) not a byte offset into CSR space.
261 Reset event counters to zero.
262 The driver counts events like packets in and out, errors, discards, etc.
263 The time when the counters are reset is remembered.
266 Not needed during normal operation; just for testing.
268 Set verbose mode: print more stuff.
270 Print the card configuration \[em] see the
274 Load gate array from on-board ROM.
275 Not needed during normal operation; just for testing.
277 Load gate array microcode from
280 Select RAWIP mode \[em] bypass line protocol code.
282 Select line protocol code rather than RAWIP mode.
284 Disable SPPP keep-alive packets.
286 Enable SPPP keep-alive packets.
288 Set SPPP line protocol to Cisco-HDLC.
290 Set SPPP line protocol to PPP.
292 Print help (usage message).
294 .Ss Commands for T1E1 cards
295 The following parameters apply to the T1E1 card type:
296 .Bl -tag -width indent
297 .It Fl a Sm Cm y | a | b Sm
298 Stop sending alarm signal.
300 .Bl -column "y" "Yellow Alarm" "unframed all ones; aka AIS" -offset 1m -compact
301 .It "y" Ta "Yellow Alarm" Ta "varies with framing"
302 .It "a" Ta "Red Alarm" Ta "unframed all ones; aka AIS"
303 .It "b" Ta "Blue Alarm" Ta "unframed all ones"
306 Red alarm, also known as AIS (Alarm Indication Signal),
307 and Blue alarm are identical in T1.
308 .It Fl A Sm Cm y | a | b Sm
309 Start sending alarm signal (see table above).
311 Send a Bit Oriented Protocol (BOP) message with code
313 BOP codes are six bits.
317 meters (default: 10 meters).
318 This is used to set receiver sensitivity
319 and transmitter line build-out.
321 Print the status of the on-board DSU/CSU \[em] see the
325 Set the framing format to
328 .Bl -column "99" -offset 1m -compact
330 .It 27 Ta T1-ESF/B8ZS (default)
334 .It 24 Ta E1-FAS+CRC+CAS
335 .It 32 Ta E1-NO-framing
338 Enable 64Kb time slots (TSs) for the T1E1 card.
342 is a 32-bit hex number (default 0xFFFFFFFF).
343 The LSB is TS0 and the MSB is TS31.
344 TS0 and TS25-31 are ignored in T1 mode.
345 TS0 and TS16 are determined by the framing format in E1 mode.
347 Read framer registers.
348 Print the 512 8-bit registers in the framer chip.
349 .It Fl F Ar addr Ar data
350 Write framer register.
356 Set receiver gain range to
359 .Bl -column "0x00" "Medium" "auto-set based on cable length (default)" -offset 1m -compact
360 .It "0x24" Ta "Short" Ta "0 to 20 dB of equalized gain"
361 .It "0x2C" Ta "Medium" Ta "0 to 30 dB of equalized gain"
362 .It "0x34" Ta "Long" Ta "0 to 40 dB of equalized gain"
363 .It "0x3F" Ta "Extend" Ta "0 to 64 dB of equalized gain (wide open)"
364 .It "0xFF" Ta "Auto" Ta "auto-set based on cable length (default)"
367 This sets the level at which
372 .Em CSU loopback deactivate
373 inband command (T1-SF only).
376 .Em CSU loopback activate
377 inband command (T1-SF only).
380 .Em line loopback deactivate
381 BOP message (T1-ESF only).
384 .Em line loopback activate
385 BOP message (T1-ESF only).
388 .Em payload loopback deactivate
389 BOP message (T1-ESF only).
392 .Em payload loopback activate
393 BOP message (T1-ESF only).
395 Print the status of the on-board DSU/CSU \[em] see the
399 Stop sending test pattern.
401 Start sending test pattern
404 .Bl -column "99" -offset 1m -compact
405 .It 0 Ta unframed X^11+X^9+1
406 .It 1 Ta unframed X^15+X^14+1
407 .It 2 Ta unframed X^20+X^17+1
408 .It 3 Ta unframed X^23+X^18+1
409 .It 4 Ta unframed X^11+X^9+1 with 7ZS
410 .It 5 Ta unframed X^15+X^14+1 with 7ZS
411 .It 6 Ta unframed X^20+X^17+1 with 14ZS (QRSS)
412 .It 7 Ta unframed X^23+X^18+1 with 14ZS
413 .It 8 Ta framed X^11+X^9+1
414 .It 9 Ta framed X^15+X^14+1
415 .It 10 Ta framed X^20+X^17+1
416 .It 11 Ta framed X^23+X^18+1
417 .It 12 Ta framed X^11+X^9+1 with 7ZS
418 .It 13 Ta framed X^15+X^14+1 with 7ZS
419 .It 14 Ta framed X^20+X^17+1 with 14ZS (QRSS)
420 .It 15 Ta framed X^23+X^18+1 with 14ZS
423 Set transmit pulse shape to
426 .Bl -column "99" -offset 1m -compact
427 .It 0 Ta T1 DSX 0 to 40 meters
428 .It 2 Ta T1 DSX 40 to 80 meters
429 .It 4 Ta T1 DSX 80 to 120 meters
430 .It 6 Ta T1 DSX 120 to 160 meters
431 .It 8 Ta T1 DSX 160 to 200 meters
432 .It 10 Ta E1 75-ohm coax pair
433 .It 12 Ta E1 120-ohm twisted pairs
434 .It 14 Ta T1 CSU 200 to 2000 meters; set LBO
435 .It 255 Ta auto-set based on cable length and framing format (default)
438 Set transmit line build-out to
441 .Bl -column "255" "22.5 dB" "FCC option A" -offset 1m -compact
442 .It " 0" Ta "0 dB" Ta "FCC option A"
443 .It " 16" Ta "7.5 dB" Ta "FCC option B"
444 .It " 32" Ta "15 dB" Ta "FCC option C"
445 .It " 48" Ta "22.5 dB" Ta "final span"
446 .It "255" Ta "auto-set based on cable length (default)" Ta \&
449 This is only applicable if the pulse shape is T1-CSU.
451 Set verbose mode: print more stuff.
453 Disable transmitter outputs.
455 Enable transmitter outputs.
457 .Ss Commands for T3 cards
458 The following parameters apply to the T3 card type:
459 .Bl -tag -width indent
460 .It Fl a Sm Cm y | a | b | i Sm
461 Stop sending alarm signal.
463 .Bl -column "y" "Yellow Alarm" "framed 1010... aka AIS" -offset 1m -compact
464 .It "y" Ta "Yellow Alarm" Ta "X-bits set to 0"
465 .It "a" Ta "Red Alarm" Ta "framed 1010... aka AIS"
466 .It "b" Ta "Blue Alarm" Ta "unframed all-ones"
467 .It "i" Ta "Idle signal" Ta "framed 11001100..."
469 .It Fl A Sm Cm y | a | b | i Sm
470 Start sending alarm signal (see table above).
472 Send a BOP (Bit Oriented Protocol) message with code
474 BOP codes are six bits.
478 meters (default: 10 meters).
479 This is used to set receiver sensitivity
480 and transmitter line build-out.
482 Print the status of the on-board T3 DSU \[em] see the
486 Set the framing format to
489 .Bl -column "100" -offset 1m -compact
490 .It 100 Ta T3-C-bit parity
491 .It 101 Ta T3-M13 format
494 Read framer registers.
495 Print the 22 8-bit registers in the framer chip.
496 .It Fl F Ar addr Ar data
497 Write framer register.
504 .Em line loopback deactivate
508 .Em line loopback activate
511 Print the status of the on-board T3 DSU \[em] see the
515 Set payload scrambler polynomial to
518 .Bl -column "9" -offset 1m -compact
519 .It 1 Ta payload scrambler disabled
520 .It 2 Ta X^43+1: DigitalLink and Kentrox
521 .It 3 Ta X^20+X^17+1 w/28ZS: Larscom
523 Payload scrambler polynomials are not standardized.
525 Set verbose mode: print more stuff.
527 Set transmit frequency offset to
529 Some T3 cards can offset the transmitter frequency from 44.736 MHz.
531 is in the range (0..4095); 2048 is zero offset; step size is about 3 Hz.
534 is written to a Digital-Analog Converter (DAC) which connects
535 to a Voltage Controlled Crystal Oscillator (VCXO).
538 The device driver counts many interesting events such as
539 packets in and out, errors and discards.
540 The table below lists the event counters and describes what they count.
541 .Bl -tag -width ".Va underruns"
543 Bytes received in packets with good ending status.
547 Packets received with good ending status.
551 Packets received with bad ending status.
553 Packets transmitted with bad ending status.
555 Packets received but discarded because
556 the input queue was full or the interface was down.
558 Packets presented for transmission but discarded because
559 the output queue was full or the interface was down.
561 Packets presented for transmission but queued and retried later
562 because no DMA descriptors were available.
563 This can happen during normal operation and is not an indication of trouble.
565 Packets that started to arrive, but were aborted because
566 the card was unable to DMA data to memory fast enough
567 to prevent the receiver fifo from overflowing.
569 Packets that started to transmit but were aborted because
570 the card was unable to DMA data from the memory fast enough
571 to prevent the transmitter fifo from underflowing.
572 When this happens, the transmitter threshold is increased,
573 so that more bytes are required to be in the fifo
574 before the transmitter is started.
576 Packets that are missed because the receiver is stopped.
578 Packets that are missed because the receiver
579 had no DMA descriptors available.
581 Packets received on the T1 Facility Data Link.
583 Cyclic Redundancy Checksum errors detected by the CRC-6 in
584 T1 Extended SuperFrames (ESF) or the CRC-4 in E1 frames.
586 Line Coding Violation errors:
587 Alternate Mark Inversion (AMI) errors for T1-SF,
588 Bipolar 8-Zero Substitution (B8ZS) errors for T1-ESF, or
589 High Density Bipolar with 3-Zero Substitution (HDB3) errors for E1 or
590 Bipolar 3-Zero Substitution (B3ZS) errors for T3.
592 T1 or T3 bit errors in the frame alignment signal.
594 Far End Block Errors:
595 T1 or T3 bit errors detected by the device at the far end of the link.
597 T3 bit errors detected by the hop-by-hop parity mechanism.
599 T3 bit errors detected by the end-to-end parity mechanism.
601 T3 bit errors in the multi-frame alignment signal.
604 The hardware counts transmit clocks divided by 2048.
605 The software computes
610 The transmit clock is the bit rate of the circuit divided by two if the
611 circuit is idle and divided by four if the circuit is carrying a packet.
612 So an idle circuit reports a Tx speed equal to its bit rate,
613 and a busy circuit reports a Tx speed equal to half its bit rate.
617 does not include circuit-level overhead bits
618 (such as T1 or T3 frame bits) but does include HDLC stuff bits.
619 An idle T1 circuit with a raw bit rate of 1544000 and a
620 bit-rate-minus-overhead of 1536000 will report a
622 of ((1536000 bitand 4095) plus or minus 4096).
623 Sometimes it will even get the correct answer of 1536000, and
624 if the link is fully loaded it will report about 768000 bits/sec.
626 It is not a perfect bit rate meter (the circuit must be idle),
627 but it is a useful circuit utilization meter if you know the
628 circuit bit rate and do some arithmetic.
629 Software recalculates
630 Tx speed once a second; the measurement period has some jitter.
635 .Dq Li lmcconfig lmc0
636 generates the following output:
637 .Bd -literal -offset 2m
639 Card type: SBE/LMC T1E1 card
642 Line Prot/Pkg: Frame-Relay/SPPP
643 SPPP Keep-alives: OFF
646 Tx Clk src: Internal source
647 Format-Frame/Code: T1-ESF/B8ZS
648 TimeSlot [31-0]: 0x01FFFFFE
649 Cable length: 10 meters
650 Tx pulse shape: auto-set to T1-DSX: 0 to 40 meters
651 Rx gain max: auto-set to 20.0 dB
652 Current time: Thu Sep 29 21:48:51 2005
653 Cntrs reset: Thu Sep 29 16:21:05 2005
664 .Dq Li "lmcconfig lmc0 -1 -d"
665 generates the following output:
666 .Bd -literal -offset 2m
667 Format-Frame/Code: T1-ESF/B8ZS
668 TimeSlot [31-0]: 0x01FFFFFE
669 Tx Clk src: Internal source
671 Tx pulse shape: T1-DSX: 0 to 40 meters
673 Line impedance: 100 ohms
674 Max line loss: 20.0 dB
675 Cur line loss: 3.1 dB
694 Change of Frm align: 0
695 Loss of Frame events: 0
696 Last Tx BOP msg: 0x00 (Yellow Alarm (far end LOF))
697 Last Rx BOP msg: 0x00 (Yellow Alarm (far end LOF))
698 SNMP Near-end performance data:
699 LCV=0 LOS=0 FE=0 CRC=0 AIS=0 SEF=0 OOF=0 RAI=0
700 ANSI Far-end performance reports:
701 SEQ=1 CRC=0 SE=0 FE=0 LV=0 SL=0 LB=0
702 SEQ=0 CRC=0 SE=0 FE=0 LV=0 SL=0 LB=0
703 SEQ=3 CRC=0 SE=0 FE=0 LV=0 SL=0 LB=0
704 SEQ=2 CRC=0 SE=0 FE=0 LV=0 SL=0 LB=0
707 Messages indicating the specified interface does not exist, or
708 the user is not privileged and tried to alter an interface's configuration.
716 .Pa http://www.sbei.com/
718 This is a total rewrite of the program
721 .An "Andrew Stanley-Jones" .
723 .An "David Boggs" Aq boggs@boggs.palo-alto.ca.us