NAME
lmc —
device driver for LMC (and some
SBE) wide-area network interface cards
SYNOPSIS
This driver is built into the GENERIC kernel so it should "just work".
The driver can be built into a kernel by adding the following to
/sys/arch/ARCH/conf/YOURKERNEL:
lmc* at pci?
options ALTQ
options ALTQ_HFSC # for altq example
pseudo-device sppp
pseudo-device bpfilter
The driver can send and receive raw IP packets even if SPPP is not configured
into the kernel.
DESCRIPTION
This is an open-source Unix device driver for PCI-bus wide-area network
interface cards. It sends and receives packets in HDLC frames over synchronous
circuits. A computer plus
UNIX plus some LMC cards
makes an
open wide-area network router.
The
lmc driver works with
FreeBSD,
NetBSD,
OpenBSD, BSD/OS, and
Linux OSs. It has been tested on i386 (SMP 32-bit little-end), PowerPC (32-bit
big-end), Alpha (64-bit little-end), and Sparc (64-bit big-end) architectures.
The
lmc driver works with the following cards:
-
-
- LMC5200
- HSSI—High Speed Serial Interface,
EIA612/613, 50-pin connector,
0 to 52 Mb/s, DTE only.
-
-
- LMC5245
- T3, 2xBNC conns, 75 ohm
C-Parity or M13 Framing,
DSX-3 up to 910 ft.
-
-
- LMC1000
- SSI—Synchronous Serial Interface,
V.35, X.21, EIA449, EIA530(A), EIA232,
0 to 10 Mb/s, DTE or DCE.
-
-
- LMC1200
- T1/E1, RJ45 conn, 100 or 120 ohms,
T1-B8ZS-ESF, T1-AMI-SF, E1-HDB3-many,
DSX-1 up to 1500 ft; CSU up to 6 Kft.
LMC cards contain a high-performance
PCI interface, an
HDLC function and either integrated
modems
(T1, T3) or
modem interfaces (HSSI and SSI).
-
-
- PCI
- The PCI interface is a DEC 21140A Tulip Fast Ethernet chip.
This chip has an efficient PCI implementation with scatter/gather DMA, and
can run at 100 Mb/s full duplex (twice as fast as needed here).
-
-
- HDLC
- The HDLC functions (ISO-3309: flags, bit-stuffing, CRC) are
implemented in a Field Programmable Gate Array (FPGA) which talks to the
Ethernet chip through a Media Independent Interface (MII). The hardware in
the FPGA translates between Ethernet packets and HDLC frames on-the-fly;
think of it as a WAN PHY chip for Ethernet.
-
-
- Modem
- The modem chips are the main differences between cards.
HSSI cards use ECL10K chips to implement the EIA-612/613 interface. T3
cards use a TranSwitch TXC-03401 framer chip. SSI cards use Linear
Technology LTC1343 modem interface chips. T1 cards use a
BrookTree/Conexant/Mindspeed Bt8370 framer and line interface chip.
Line protocol stacks exist above device drivers and below internet protocol
stacks. They typically encapsulate packets in HDLC frames and deal with
higher-level issues like protocol multiplexing and security. The driver is
compatible with several line protocol stacks:
-
-
- SPPP
- sppp(4)
implements Synchronous-PPP and Cisco-HDLC in the kernel.
-
-
- RawIP
- The null line protocol, built into the driver, sends and
receives raw IPv4 and IPv6 packets in HDLC frames with no extra bytes of
overhead and no state at the end points.
EXAMPLES
ifconfig and lmcconfig
The program
lmcconfig(8)
manipulates interface parameters beyond the scope of
ifconfig(8).
lmcconfig has many flags and options, but in normal
operation only a few are needed.
displays interface configuration and status.
selects the built-in RawIP line protocol stack.
selects the SPPP stack and the PPP protocol.
Some configuration options are available through
ifconfig as
well as
lmcconfig.
lists the available media options.
ifconfig lmc0 mediaopt loopback
loops the interface transmitter to the receiver for testing. This loopback uses
a path present in every card type.
lmcconfig can select
card-specific loopbacks, such as outbound payload loopback.
enables debugging output from the device driver and from the line protocol stack
above it.
enables debugging output from the device driver.
Debugging messages that appear on the console are also written to file
/var/log/messages.
Caution: when things go
very wrong, a torrent of debugging messages can swamp the console and bring a
machine to its knees.
Operation
Configure a PPP link using SPPP with
lmcconfig lmc0 -X 2 -x 2
ifconfig lmc0 10.0.0.1 10.0.0.2
Configure a Cisco-HDLC link using SPPP with
lmcconfig lmc0 -X 2 -x 3
ifconfig lmc0 10.0.0.1 10.0.0.2
Configure a RAWIP link with
lmcconfig lmc0 -X 1
ifconfig lmc0 10.0.0.1 10.0.0.2
TESTING
Testing with Loopbacks
Testing with loopbacks requires only one card and can test everything on that
card. Packets can be looped back at many points: in the PCI chip, in the modem
chips, through a loopback plug, in the local external equipment, or at the far
end of a circuit.
All cards can be looped through the PCI chip. Cards with internal modems can be
looped through the modem framer and the modem line interface. Cards for
external modems can be looped through the driver/receiver chips. See
lmcconfig(8) for details.
Configure the card with
ifconfig lmc0 10.0.0.1 10.0.0.1
-
-
- HSSI
- Loopback plugs can be ordered from SBE (and others).
Transmit clock is normally supplied by the external modem. When an HSSI
card is operated with a loopback plug, the PCI bus clock must be used as
the transmit clock, typically 33 MHz. When testing an HSSI card with a
loopback plug, configure it with
“-a
2
” selects the PCI
bus clock as the transmit clock.
-
-
- T3
- Connect the two BNC jacks with a short coax cable.
-
-
- SSI
- Loopback plugs can be ordered from SBE (only). Transmit
clock is normally supplied by the external modem. When an SSI card is
operated with a loopback plug, the on-board clock synthesizer must be
used. When testing an SSI card with a loopback plug, configure it with
lmcconfig lmc0 -E -f 10000000
“-E”
puts the card in DCE mode to source a transmit clock.
“-f 10000000
” sets
the internal clock source to 10 Mb/s.
-
-
- T1/E1
- A loopback plug is a modular plug with two wires connecting
pin 1 to pin 4 and pin 2 to pin 5.
One can also test by connecting to a local modem (HSSI and SSI) or NI (T1 and
T3) configured to loop back. Cards can generate signals to loopback remote
equipment so that complete circuits can be tested; see
lmcconfig(8) for details.
Testing with a Modem
Testing with a modem requires two cards of different types. The cards can be in
the same machine or different machines.
Configure the two cards with
ifconfig lmc0 10.0.0.1 10.0.0.2
ifconfig lmc1 10.0.0.2 10.0.0.1
-
-
- T3/HSSI
- If you have a T3 modem with an HSSI interface (made by
Digital Link, Larscom, Kentrox etc.) then use an HSSI card and a T3 card.
The coax cables between the card and the modem must “cross
over” (see below).
-
-
- T1/V.35
- If you have a T1 (or E1) modem with a V.35, X.21 or EIA530
interface, then use an SSI card and a T1 card. Use a T1 null modem cable
(see below) between the external modem and the T1 card.
Testing with a Null Modem
Cable
Testing with a null modem cable requires two cards of the same type. The cards
can be in the same machine or different machines.
Configure the two cards with
ifconfig lmc0 10.0.0.1 10.0.0.2
ifconfig lmc1 10.0.0.2 10.0.0.1
-
-
- HSSI
- Three-meter HSSI null-modem cables can be ordered from SBE.
In a pinch, a 50-pin SCSI-II cable up to a few meters will work as a
straight HSSI cable (not a null modem cable). Longer cables should be
purpose-built HSSI cables because the cable impedance is different.
Transmit clock is normally supplied by the external modem. When an HSSI
card is connected by a null modem cable, the PCI bus clock can be used as
the transmit clock, typically 33 MHz. When testing an HSSI card with a
null modem cable, configure it with
“-a
2
” selects the PCI
bus clock as the transmit clock.
-
-
- T3
- T3 null modem cables are just 75-ohm coax cables with BNC
connectors. TX OUT on one card should be connected to RX IN on the other
card. In a pinch, 50-ohm thin Ethernet cables usually
work up to a few meters, but they will not work for
longer runs—75-ohm coax is required.
-
-
- SSI
- Three-meter SSI null modem cables can be ordered from SBE.
An SSI null modem cable reports a cable type of V.36/EIA449. Transmit
clock is normally supplied by the external modem. When an SSI card is
connected by a null modem cable, an on-board clock synthesizer is used.
When testing an SSI card with a null modem cable, configure it with
lmcconfig lmc0 -E -f 10000000
“-E”
puts the card in DCE mode to source a transmit clock.
“-f 10000000
” sets
the internal clock source to 10 Mb/s.
-
-
- T1/E1
- A T1 null modem cable has two twisted pairs that connect
pins 1 and 2 on one plug to pins 4 and 5 on the other plug. Looking into
the cable entry hole of a plug, with the locking tab oriented down, pin 1
is on the left. A twisted pair Ethernet cable makes an excellent straight
T1 cable. Alas, Ethernet cross-over cables do not work as T1 null modem
cables.
OPERATING NOTES
LEDs
HSSI and SSI cards should be operational if all three green LEDs are on (the
upper-left one should be blinking) and the red LED is off.
RED |
upper-right |
No Transmit clock |
GREEN |
upper-left |
Device driver is alive if
blinking |
GREEN |
lower-right |
Modem signals are
good |
GREEN |
lower-left |
Cable is plugged in (SSI
only) |
T1/E1 and T3 cards should be operational if the upper-left green LED is blinking
and all other LEDs are off. For the T3 card, if other LEDs are on or blinking,
try swapping the coax cables!
RED |
upper-right |
Received signal is
wrong |
GREEN |
upper-left |
Device driver is alive if
blinking |
BLUE |
lower-right |
Alarm Information Signal
(AIS) |
YELLOW |
lower-left |
Remote Alarm Indication
(RAI) |
RED |
blinks if an outward
loopback is active. |
GREEN |
blinks if the device
driver is alive. |
BLUE |
blinks if sending AIS, on
solid if receiving AIS. |
YELLOW |
blinks if sending RAI, on
solid if receiving RAI. |
Packet Lengths
Maximum transmit and receive packet length is unlimited.
Minimum transmit and receive packet length is one byte.
Cleaning up after one packet and setting up for the next packet involves making
several DMA references. This can take longer than the duration of a short
packet, causing the adapter to fall behind. For typical PCI bus traffic levels
and memory system latencies, back-to-back packets longer than about 20 bytes
will always work (53 byte cells work), but a burst of several hundred
back-to-back packets shorter than 20 bytes will cause packets to be dropped.
This usually is not a problem since an IPv4 packet header is at least 20 bytes
long.
The device driver imposes no constraints on packet size. Most operating systems
set the default Maximum Transmission Unit (MTU) to 1500 bytes; the legal range
is usually (72..65535). This can be changed with
SPPP enforces an MTU of 1500 bytes for PPP and Cisco-HDLC. RAWIP sets the
default MTU to 4032 bytes, but allows it to be changed to anything.
ALTQ: Alternate
Output Queue Disciplines
The driver has hooks for
altq(9),
the Alternate Queueing package. To see ALTQ in action, use your favorite
traffic generation program to generate three flows sending down one T3
circuit. Without ALTQ, the speeds of the three connections will vary
chaotically. Enable ALTQ and two of the connections will run at about 20 Mb/s
and the third will run at about 2 Mb/s.
Enable
altqd(8) and add the
following lines to
/etc/altq.conf:
interface lmc0 bandwidth 44M hfsc
class hfsc lmc0 a root pshare 48
filter lmc0 a 10.0.0.2 12345 10.0.0.1 0 6
filter lmc0 a 10.0.0.1 0 10.0.0.2 12345 6
class hfsc lmc0 b root pshare 48
filter lmc0 b 10.0.0.2 12346 10.0.0.1 0 6
filter lmc0 b 10.0.0.1 0 10.0.0.2 12346 6
class hfsc lmc0 c root pshare 4 default
filter lmc0 c 10.0.0.2 12347 10.0.0.1 0 6
filter lmc0 c 10.0.0.1 0 10.0.0.2 12347 6
The example above requires the
altq(4) Hierarchical Fair Service
Curve queue discipline to be configured in
conf/YOURKERNEL:
options ALTQ
options ALTQ_HFSC.
BPF: Berkeley Packet Filter
The driver has hooks for
bpf(4), the
Berkeley Packet Filter, a protocol-independent raw interface to data link
layers.
To test the BPF kernel interface, bring up a link between two machines, then run
ping(8) and
tcpdump(8):
and in a different window:
The output from tcpdump should look like this:
03:54:35.979965 10.0.0.2 > 10.0.0.1: icmp: echo request
03:54:35.981423 10.0.0.1 > 10.0.0.2: icmp: echo reply
Line protocol control packets may appear among the ping packets occasionally.
The kernel must be configured with
SNMP: Simple
Network Management Protocol
The driver is aware of what is required to be a Network Interface Object managed
by an Agent of the Simple Network Management Protocol. The driver exports
SNMP-formatted configuration and status information sufficient for an SNMP
Agent to create MIBs for:
- RFC-2233
- Interfaces group
- RFC-2496
- DS3 interfaces
- RFC-2495
- DS1/E1 interfaces
- RFC-1659
- RS232-like interfaces
An SNMP Agent is a user program, not a kernel function. Agents can retrieve
configuration and status information by using
ioctl(2) system calls. User
programs should poll
sc->cfg.ticks which increments
once per second after the SNMP state has been updated.
E1 Framing
Phone companies usually insist that customers put a
Frame
Alignment Signal (FAS) in time slot 0. A Cyclic Redundancy Checksum (CRC)
can also ride in time slot 0.
Channel Associated Signalling
(CAS) uses Time Slot 16. In telco-speak
signalling is on/off
hook, ringing, busy, etc. Signalling is not needed here and consumes 64 Kb/s.
Only use E1-CAS formats if the other end insists on it! Use E1-FAS+CRC framing
format on a public circuit. Depending on the equipment installed in a private
circuit, it may be possible to use all 32 time slots for data (E1-NONE).
T3 Framing
M13 is a technique for multiplexing 28 T1s into a T3. Muxes use the C-bits for
speed-matching the tributaries. Muxing is not needed here and usurps the FEBE
and FEAC bits. Only use T3-M13 format if the other end insists on it! Use
T3-CParity framing format if possible. Loop Timing, Fractional T3, and HDLC
packets in the Facility Data Link are
not supported.
T1 & T3 Frame
Overhead Functions
Performance Report Messages (PRMs) are enabled in T1-ESF.
Bit Oriented Protocol (BOP) messages are enabled in T1-ESF.
In-band loopback control (framed or not) is enabled in T1-SF.
Far End Alarm and Control (FEAC) msgs are enabled in T3-CPar.
Far End Block Error (FEBE) reports are enabled in T3-CPar.
Remote Alarm Indication (RAI) is enabled in T3-Any.
Loopbacks initiated remotely time out after 300 seconds.
T1/E1 'Fractional' 64
kb/s Time Slots
T1 uses time slots 24..1; E1 uses time slots 31..0. E1 uses TS0 for FAS overhead
and TS16 for CAS overhead. E1-NONE has
no overhead, so all
32 TSs are available for data. Enable/disable time slots by setting 32 1s/0s
in a config param. Enabling an E1 overhead time slot, or enabling TS0 or
TS25-TS31 for T1, is ignored by the driver, which knows better. The default TS
param, 0xFFFFFFFF, enables the maximum number of time slots for whatever frame
format is selected. 56 Kb/s time slots are
not supported.
SEE ALSO
ioctl(2),
bpf(4),
de(4),
sppp(4),
altq.conf(5),
altqd(8),
ifconfig(8),
init(8),
lmcconfig(8),
modload(8),
ping(8),
tcpdump(8),
altq(9),
ifnet(9)
HISTORY
Ron Crane had the idea to use a Fast Ethernet chip as a
PCI interface and add an Ethernet-to-HDLC gate array to make a WAN card.
David Boggs designed the Ethernet-to-HDLC gate array
and PC cards. We did this at our company, LAN Media Corporation (LMC). SBE
Corporation acquired LMC and continues to make the cards.
Since the cards use Tulip Ethernet chips, we started with
Matt
Thomas' ubiquitous
de(4)
driver.
Michael Graff stripped out the Ethernet stuff
and added HSSI stuff.
Basil Gunn ported it to Solaris
(lost) and
Rob Braun ported it to Linux.
Andrew Stanley-Jones added support for three more
cards.
David Boggs rewrote everything and now feels
responsible for it.
AUTHORS
David Boggs
<
boggs@boggs.palo-alto.ca.us>