LMC(4)                  NetBSD Kernel Interfaces Manual                 LMC(4)

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 loaded into a running kernel with modload(8).
           modload if_lmc.o
     The kernel must be built with support for Loadable Kernel Modules,
     lkm(8).
           options   LKM
     securelevel must be 0 to load modules; see init(8).

     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 con-
     figured 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 syn-
     chronous 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) architec-
     tures.

     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 scat-
                  ter/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 proto-
     col 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 nor-
     mal operation only a few are needed.

           lmcconfig lmc0
     displays interface configuration and status.

           lmcconfig lmc0 -X 1
     selects the built-in RawIP line protocol stack.

           lmcconfig lmc0 -X 2 -x 2
     selects the SPPP stack and the PPP protocol.

     Some configuration options are available through ifconfig as well as
     lmcconfig.
           ifconfig -m lmc0
     lists the available media options.

           ifconfig lmc0 mediaopt loopback
     loops the interface transmitter to the receiver for testing.  This loop-
     back uses a path present in every card type.  lmcconfig can select card-
     specific loopbacks, such as outbound payload loopback.

           ifconfig lmc0 debug
     enables debugging output from the device driver and from the line proto-
     col stack above it.

           lmcconfig lmc0 -D
     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 equip-
     ment, 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).  Trans-
                  mit 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
                        lmcconfig lmc0 -a 2
                  ``-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 nor-
                  mally 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
                        lmcconfig lmc0 -a 2
                  ``-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 lock-
                  ing 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
           ifconfig lmc0 mtu 2000
     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 con-
     nections 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(1):
           ping 10.0.0.1
     and in a different window:
           tcpdump -i lmc0
     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 occasion-
     ally.

     The kernel must be configured with
           options bpfilter

   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 suffi-
     cient 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.  Sig-
     nalling 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 pub-
     lic 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 sup-
     ported.

   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
     tcpdump(1), ioctl(2), bpf(4), de(4), sppp(4), altq.conf(5), altqd(8),
     ifconfig(8), init(8), lkm(8), lmcconfig(8), modload(8), ping(8),
     tcpdump(8), altq(9), ifnet(9)

     http://www.sbei.net/

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 aquired 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>

NetBSD 5.0_STABLE               April 11, 2006               NetBSD 5.0_STABLE
