freebsd-skq/share/man/man4/lmc.4

.\"
.\" $FreeBSD$
.\"
.\" Copyright (c) 2002-2005 David Boggs. (boggs@boggs.palo-alto.ca.us)
.\" All rights reserved.
.\"
.\" BSD License:
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" GNU General Public License:
.\"
.\" This program is free software; you can redistribute it and/or modify it 
.\" under the terms of the GNU General Public License as published by the Free 
.\" Software Foundation; either version 2 of the License, or (at your option) 
.\" any later version.
.\" 
.\" This program is distributed in the hope that it will be useful, but WITHOUT 
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for 
.\" more details.
.\"
.\" You should have received a copy of the GNU General Public License along with
.\" this program; if not, write to the Free Software Foundation, Inc., 59 
.\" Temple Place - Suite 330, Boston, MA  02111-1307, USA.
.\"
.\" I forget these things:
.\" groff -Tascii -mdoc lmc.4 > lmc.0
.\" groff -Tps    -mdoc lmc.4 > lmc.ps
.\" groff -Thtml  -mdoc lmc.4 > lmc.html (buggy)
.\"
.Dd October 3, 2005
.Dt LMC 4
.Os
.\"
.Sh NAME
.\"
.Nm lmc
.Nd device driver for
.Tn LMC
(now
.Tn SBE )
wide-area network interface cards.
.\"
.Sh SYNOPSIS
.\"
.Cd "device lmc"
.\"
.Sh DESCRIPTION
.\"
This is an open-source Unix device driver for PCI-bus WAN interface cards.
It sends and receives packets in HDLC frames over synchronous circuits.
A generic PC plus Unix plus some
.Tn "LMC" /
.Tn "SBE"
cards makes an
.Em open
router.
This driver works with FreeBSD, NetBSD, OpenBSD, BSD/OS and Linux OSs.
It has been tested on i386 (SMP 32-bit little-end), Sparc (64-bit big-end),
and Alpha (64-bit little-end) architectures.
.Pp
The
.Nm
driver works with the following cards:
.Bd -literal -offset 2m
SBE wanADAPT-HSSI       High Speed Serial Interface,
    (LMC5200)           EIA612/613, 50-pin connector,
                        0 to 52 Mb/s, DTE only.
SBE wanADAPT-T3         T3: two 75-ohm BNC connectors,
    (LMC5245)           C-Parity or M13 Framing,
                        44.736 Mb/s, up to 950 ft.
SBE wanADAPT-SSI        Synchronous Serial Interface,
    (LMC1000)           V.35, X.21, EIA449, EIA530(A), EIA232,
                        0 to 10 Mb/s, DTE or DCE.
SBE wanADAPT-T1E1       T1 or E1: RJ45 conn, 100 or 120 ohms,
    (LMC1200)           T1-ESF-B8ZS, T1-SF-AMI, E1-(many)-HDB3,
                        1.544 Mb/s or 2.048 Mb/s, up to 6 Kft.
.Ed
.Pp
Cards contain a high-performance
.Sy "PCI"
interface, an
.Sy "HDLC"
function and
either integrated
.Sy "modems"
(T1, T3) or
.Sy "modem"
interfaces (HSSI and SSI).
.Bl -tag -width "Modem"
.It Sy "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).
.It Sy "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 it as a WAN PHY chip for Ethernet.
.It Sy "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.
.El
.Pp
Line protocols exist above device drivers and below internet protocols.
They typically encapsulate packets in HDLC frames and deal with
higher-level issues like protocol multiplexing and security.
This driver is compatible with several line protocol packages:
.Bl -tag -width "Generic HDLC"
.It Sy "Netgraph"
.Xr Netgraph 4
implements many basic packet-handling functions as kernel loadable modules.
They can be interconnected in a graph to implement many protocols.
Configuration is done from userland without rebuilding the kernel.
Packets are sent and received through this interface if the driver's
.Em rawdata
hook is connected, otherwise the ifnet interface (SPPP and RawIP) is used.
ASCII configuration control messages are
.Em not
currently supported.
.It Sy "SPPP"
.Xr sppp 4
implements Synchronous-PPP, Frame-Relay and Cisco-HDLC in the kernel.
.It Sy "RawIP"
This null line protocol, built into the driver, sends and receives
raw IPv4 and IPv6 packets in HDLC frames (aka IP-in-HDLC) with
no extra bytes of overhead and no state at the end points.
.El
.\"
.Sh EXAMPLES
.\"
.Ss ifconfig and lmcconfig
.\"
The program
.Xr lmcconfig 8
manipulates interface parameters beyond the scope of
.Xr ifconfig 8 .
In normal operation only a few arguments are needed:
.Bl -inset -offset 4n -compact
.It Sy "-X\0\0"
selects the external
SPPP
line protocol package.
.It Sy "-x\0\0"
selects the built-in RawIP line protocol package.
.It Sy "-Z\0\0"
selects PPP line protocol.
.It Sy "-z\0\0"
selects Cisco-HDLC line protocol.
.It Sy "-F\0\0"
selects Frame-Relay line protocol.
.El
.Pp
.Ic "lmcconfig lmc0"
.br
displays interface configuration and status.
.Pp
.Ic "lmcconfig lmc0 -D"
.br
enables debugging output from the device driver only.
.br
.Ic "ifconfig lmc0 debug"
.br
enables debugging output from the device driver and from
the line protocol module above it.
Debugging messages that appear on the console are also
written to file
.Ic "/var/log/messages" .
.Em Caution :
when things go very wrong, a torrent of debugging messages
can swamp the console and bring a machine to its knees.
.\"
.Ss Patching Ethernet Drivers
.\"
Since these cards use DEC 21140A Tulip Ethernet chips,
be aware that an Ethernet driver may mistake one for an
Ethernet card and try to drive it.
For some versions of some operating systems, it is
sufficient to list the
.Nm
cards before any Ethernet cards in the kernel configuration.
Another solution is to unplug all 21140-based Ethernet cards
and remove their device drivers from the kernel configuration.
Finally, one can patch the Ethernet drivers to ignore
.Nm
cards.
In any case, you must make a custom kernel.
Chapter 9 of the FreeBSD Handbook
explains how to configure and build custom kernels.
.Pp
To patch an Ethernet device driver:
.br
add this line to
.Ic "tulip_pci_probe()"
in
.Ic "sys/pci/if_de.c" :
.br
.Ic "if (pci_get_subvendor(dev)==0x1376)"
.br
.Ic "   return ENXIO;"
.br
This driver should already be patched.
Make sure you patch the correct routine: many Ethernet drivers
contain probe/match routines for several operating systems inside
.Ic "#ifdefs" .
.Pp
.Ic "/var/log/messages"
should contain a boot message like this:
.br
.Ic "freebsd-4: pci0: <unknown card> (vendor=0x1011, dev=0x0009) at 18.0 irq 9"
.br
.Ic "freebsd-5: pci0: <network, ethernet> at device 18.0 (no driver attached)"
.\"
.Ss FreeBSD Configuration
.\"
Put the source files in
.Ic "/sys/dev/lmc" .
You may need to create the directory.
.Pp
Add the following line to
.Ic "/sys/conf/files" :
.br
.Ic "dev/lmc/if_lmc.c	optional	lmc pci"
.br
Put it near other
.Ic "dev/l*"
entries.
.br
For FreeBSD-5, change
.Ic optional
to
.Ic count
in the entry for sppp:
.br
.Ic "net/if_spppsubr.c	count	sppp"
.Pp
To wire this driver into your kernel:
Add the following line to
.Ic "/sys/ARCH/conf/YOURKERNEL" :
.br
.Ic "device	lmc	# LMC/SBE WAN cards"
.br
Put this line near lines for other network devices.
To load the driver into a running kernel, see KLD below.
.Pp
To wire a line protocol into your kernel, add:
.br
.Ic "options	netgraph	# wired into the kernel"
.br
.Ic "pseudo-device	sppp	# FreeBSD-4"
.br
.Ic "device		sppp	# FreeBSD-5"
.br
It is not necessary to wire line protocols into your kernel.
This driver and line protocols can be loaded later with kldload(8).
The driver can send and receive raw IP packets even if neither
SPPP nor Netgraph are configured into the kernel.
Netgraph and SPPP can both be enabled; netgraph will be used if the
.Em "rawdata"
hook is connected.
.\"
.Ss FreeBSD Kernel Loadable Modules ("KLD" mechanism)
.\"
To make this driver into a standard kernel loadable module:
.br
Make a directory named
.Ic "/sys/modules/lmc" .
.br
Copy
.Ic "/sys/dev/lmc/Makefile"
to
.Ic "/sys/modules/lmc/Makefile" .
.br
Add
.Ic "lmc"
to
.Ic "/sys/modules/Makefile"
for your machine architecture.
.Pp
While standing in
.Ic /sys/ARCH/compile/YOURKERNEL:
.br
.Ic "make modules-depend"
generates all module dependencies.
.br
.Ic "make modules"
creates all modules.
.br
.Ic "make modules-install"
installs all modules.
.Pp
To make this driver into a kernel loadable module "by hand":
.br
While standing in
.Ic "/sys/dev/lmc" :
.br
.Ic "make depend"
generates lmc module dependencies.
.br
.Ic "make all"
creates the lmc module.
.br
.Ic "make install"
installs the lmc module.
.br
.Ic "make depend all install"
does everything.
.Pp
While standing anywhere (as root):
.br
.Ic "kldload if_lmc"
loads the driver and starts it.
.br
.Ic "kldunload if_lmc"
stops the driver and unloads it.
.br
.Ic "kldstat"
displays status of loaded modules.
.Pp
.Ic "securelevel"
must be 0 to load modules; see
.Xr init 8 .
.Pp
To load this module at boot time, add
.br
.Ic "if_lmc_load=""YES"""
.br
to
.Ic "/boot/loader.conf"; see
.Xr loader.conf 5 .
.\"
.Ss FreeBSD Operation
.\"
Activate a PPP link using SPPP and Netgraph with:
.br
.Ic "ngctl mkpeer lmc0: sppp rawdata downstream"
.br
.Ic "ifconfig sppp0 10.0.0.1 10.0.0.2"
.Pp
Activate a PPP link using only SPPP with:
.br
.Ic "lmcconfig lmc0 -XYZ"
.br
.Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
.Pp
Activate a Cisco-HDLC link using SPPP and Netgraph with:
.br
.Ic "ngctl mkpeer lmc0: sppp rawdata downstream"
.br
.Ic "ifconfig sppp0 10.0.0.1 10.0.0.2 link2"
.Pp
Activate a Cisco-HDLC link using only SPPP with:
.br
.Ic "lmcconfig lmc0 -XYz"
.br
.Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
.Pp
Activate a Cisco-HDLC link using only Netgraph with:
.br
.Ic "ngctl mkpeer lmc0: cisco rawdata downstream"
.br
.Ic "ngctl mkpeer lmc0:rawdata iface inet inet"
.br
.Ic "ifconfig ng0 10.0.0.1 10.0.0.2"
.Pp
Activate a Frame-Relay DTE link using SPPP with:
.br
.Ic "lmcconfig lmc0 -XYF"
.br
.Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
.br
SPPP implements the ANSI T1.617 annex D LMI.
.Pp
Activate a Frame-Relay DTE link using Netgraph with:
.br
.Ic "ngctl mkpeer  lmc0: frame_relay rawdata downstream"
.br
.Ic "ngctl mkpeer  lmc0:rawdata lmi dlci0 auto0"
.br
.Ic "ngctl connect lmc0:rawdata dlci0 dlci1023 auto1023"
.br
.Ic "ngctl mkpeer  lmc0:rawdata rfc1490 dlci500 downstream"
.br
.Ic "ngctl mkpeer  lmc0:rawdata.dlci500 iface inet inet"
.br
.Ic "ifconfig ng0 10.0.0.1 10.0.0.2"
.br
This is
.Em "ONE"
possible Frame Relay configuration; there are many.
.Pp
Activate a RAWIP link using only the driver with:
.br
.Ic "lmcconfig lmc0 -x"
.br
.Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
.Pp
Activate a RAWIP link using Netgraph with:
.br
.Ic "ngctl mkpeer lmc0: iface rawdata inet"
.br
.Ic "ifconfig ng0 10.0.0.1 10.0.0.2"
.br
If the driver is kldunloaded and then kldloaded, reconnect hooks by:
.br
.Ic "ngctl connect lmc0: ng0: rawdata inet"
.\"
.\"
.\"
.Sh TESTING
.\"
.Ss Testing with Loopbacks
.\"
Testing with loopbacks requires only one 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.
.Pp
Activate the card with ifconfig:
.br
.Ic "ifconfig lmc0 10.0.0.1 10.0.0.1"
.Pp
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
.Xr lmcconfig 8
for details.
.Pp
Loopback plugs test everything on the card.
.Bl -tag -width "T1/E1" -offset 2m -compact
.It Sy "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 lmcconfig:
.br
.Ic "lmcconfig lmc0 -a 2
.br
.Ic "-a 2  "
selects the PCI bus clock as the transmit clock.
.It Sy "T3"
Connect the two BNC jacks with a short coax cable.
.It Sy "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:
.br
.Ic "lmcconfig lmc0 -E -f 10000000"
.br
.Ic "-E  "
puts the card in DCE mode to source a transmit clock.
.br
.Ic "-f 10000000  "
sets the internal clock source to 10 Mb/s.
.br
.It Sy "T1/E1"
A loopback plug is a modular plug with two wires
connecting pin 1 to pin 4 and pin 2 to pin 5.
.El
.Pp
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
.Xr lmcconfig 8
for details.
.\"
.Ss Testing with a Modem
.\"
Testing with a modem requires two cards of different types.
.Bl -tag -width "T3/HSSI"
.It Sy "T3/HSSI"
If you have a T3 modem with an HSSI interface
(made by Digital Link, Larscom, Kentrox etc.)
then use an HSSI card in one machine and a T3 card in the other machine.
The T3 coax cables must use the null modem configuration (see below).
.It Sy "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 in one machine and a T1 card in the other machine.
Use a T1 null modem cable (see below).
.El
.\"
.Ss Testing with a Null Modem Cable
.\"
Testing with a null modem cable requires two cards of the same type.
.Bl -tag -width "T1/E1"
.It Sy "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 lmcconfig:
.br
.Ic "lmcconfig lmc0 -a 2
.br
.Ic "-a 2  "
selects the PCI bus clock as the transmit clock.
.It Sy "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
.Em usually
work up to a few meters, but they will
.Em not
work for longer runs -- 75-ohm coax is
.Em required .
.It Sy "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:
.br
.Ic "lmcconfig lmc0 -E -f 10000000"
.br
.Ic "-E  "
puts the card in DCE mode to source a transmit clock.
.br
.Ic "-f 10000000  "
sets the internal clock source to 10 Mb/s.
.br
.Pp
.It Sy "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.
.El
.\"
.Sh OPERATION NOTES
.\"
.Ss Packet Lengths
Maximum transmit and receive packet length is unlimited.
.br
Minimum transmit and receive packet length is one byte.
.Pp
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 isn't a problem since an IPv4 packet header is
at least 20 bytes long.
.Pp
This 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
.br
.Ic "ifconfig lmc0 mtu 2000" .
.br
SPPP enforces an MTU of (128..far-end-MRU) for PPP
and 1500 bytes for Cisco-HDLC.
RAWIP sets the default MTU to 4032 bytes,
but it can be changed to anything.
.\"
.Ss ALTQ - Alternate Output Queue Disciplines
.\"
This driver has hooks for
.Xr altq 4 ,
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.
Turn on Altq and two of the connections will run at 21 Mb/s and
the third will run at 1.5 Mb/s.
.Pp
To include ALTQ in your kernel,
add the following line to
.Ic "conf/YOURKERNEL" :
.br
.Ic "options ALTQ        # ALTQ enabled"
.br
The example below requires the Hierarchical
Fair Service Curve (HSFC) queue discipline:
.br
.Ic "options ALTQ_HFSC   # queue discipline"
.Pp
Enable
.Xr altqd 8
and create file
.Ic "/etc/altq.conf"
containing:
.br
.Bd -literal -offset 2m -compact
.Ic "interface lmc0 bandwidth 44M hfsc"
.br
.Ic "class hfsc lmc0 a root pshare 49"
.br
.Ic "filter lmc0 a 10.0.0.2 12345 10.0.0.1 0 6"
.br
.Ic "filter lmc0 a 10.0.0.1 0 10.0.0.2 12345 6"
.br
.Ic "class hfsc lmc0 b root pshare 49"
.br
.Ic "filter lmc0 b 10.0.0.2 12346 10.0.0.1 0 6"
.br
.Ic "filter lmc0 b 10.0.0.1 0 10.0.0.2 12346 6"
.br
.Ic "class hfsc lmc0 c root pshare 2 default"
.br
.Ic "filter lmc0 c 10.0.0.2 12347 10.0.0.1 0 6"
.br
.Ic "filter lmc0 c 10.0.0.1 0 10.0.0.2 12347 6"
.br
.Ed
.\"
.Ss BPF - Berkeley Packet Filter
.\"
This driver has hooks for
.Xr bpf 4 ,
the Berkeley Packet Filter.
The line protocol header length reported to BPF is four bytes
for SPPP and P2P line protocols and zero bytes for RawIP.
.Pp
To include BPF for ifnet in your kernel,
add the following line to
.Ic "conf/YOURKERNEL" :
.br
.Ic "pseudo-device	bpf	# FreeBSD-4, NetBSD, OpenBSD, BSD/OS"
.br
.Ic "device		bpf	# FreeBSD-5"
.Pp
To test the BPF kernel interface,
bring up a link between two machines, then run
.Xr ping 8
and
.Xr tcpdump 1 :
.br
.Ic "ping 10.0.0.1"
.br
and in a different window:
.br
.Ic "tcpdump -i lmc0"
.br
The output from tcpdump should look like this:
.br
.Ic "03:54:35.979965 10.0.0.2 > 10.0.0.1: icmp: echo request"
.br
.Ic "03:54:35.981423 10.0.0.1 > 10.0.0.2: icmp: echo reply"
.br
Line protocol control packets will appear among the 
ping packets occasionally.
.\"
.Ss Device Polling
.\"
A T3 receiver can generate over 100K interrupts per second,
This can cause a system to "live-lock": spend all of its
time servicing interrupts.
Linux and FreeBSD have polling mechanisms to prevent live-lock.
.Pp
FreeBSD's mechanism permanently disables interrupts from the card
and instead the card's interrupt service routine is called each
time the kernel is entered (syscall, timer interrupt, etc) and
from the kernel idle loop; this adds some latency.
The driver is permitted to process a limited number of packets.
The percentage of the CPU that can be consumed this way is settable.
.Pp
FreeBSD's
.Xr polling 4
mechanism is enabled with:
.br
.Ic "sysctl kern.polling.enable=1"
.br
The kernel must be built with polling enabled:
.br
.Ic "options DEVICE_POLLING"
.br
.Ic "options HZ=1000"
.\"
.Ss SNMP: Simple Network Management Protocol
.\"
This 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:
.Bl -inset -compact -offset 2m
.It RFC-2233: Interfaces group,
.It RFC-2496: DS3 interfaces,
.It RFC-2495: DS1/E1 interfaces,
.It RFC-1659: RS232-like interfaces.
.El
.Pp
An SNMP Agent is a user program, not a kernel function.
Agents can retrieve configuration and status information
by using
Netgraph control messages or
.Xr ioctl 2
system calls.
User programs should poll
.Ic sc->cfg.ticks
which increments once per second after the SNMP state has been updated.
.\"
.Ss HSSI and SSI LEDs
.\"
The card should be operational if all three green LEDs are on
(the upper-left one should be blinking) and the red LED is off.
All four LEDs turn on at power-on and module-unload.
.Bl -column -compact -offset 2m "YELLOW" "upper-right" "Software"
.It "RED"   Ta "upper-right" Ta "No Transmit clock"
.It "GREEN" Ta "upper-left"  Ta "Device driver is alive if blinking"
.It "GREEN" Ta "lower-right" Ta "Modem signals are good"
.It "GREEN" Ta "lower-left"  Ta "Cable is plugged in (SSI only)"
.El
.\"
.Ss T1E1 and T3 LEDs
.\"
The card 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!
All four LEDs turn on at power-on and module-unload.
.Bl -column -compact -offset 2m "YELLOW" "upper-right" "Received"
.It "RED"    Ta "upper-right" Ta "Received signal is wrong"
.It "GREEN"  Ta "upper-left"  Ta "Device driver is alive if blinking"
.It "BLUE"   Ta "lower-right" Ta "Alarm Information Signal (AIS)"
.It "YELLOW" Ta "lower-left"  Ta "Remote Alarm Indication (RAI)"
.El \" YELLOW
.Bl -column -compact "The yellow" "LED"
.It "The green"  Ta "LED blinks if the device driver is alive."
.It "The red"    Ta "LED blinks if an outward loopback is active."
.It "The blue"   Ta "LED blinks if sending AIS, on solid if receiving AIS."
.It "The yellow" Ta "LED blinks if sending RAI, on solid if receiving RAI."
.El \" LED
.\"
.Ss E1 Framing
.\"
Phone companies usually insist that customers put a
.Em Frame Alignment Signal
(FAS) in time slot 0.
A Cyclic Redundancy Checksum (CRC) can also ride in time slot 0.
.Em Channel Associated Signalling
(CAS) uses Time Slot 16.
In telco-speak
.Em 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).
.\"
.Ss 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
.Em not
supported.
.\"
.Ss T1 & T3 Frame Overhead Functions
.\"
Performance Report Messages (PRMs) are enabled in T1-ESF.
.br
Bit Oriented Protocol (BOP) messages are enabled in T1-ESF.
.br
In-band loopback control (framed or not) is enabled in T1-SF.
.br
Far End Alarm and Control (FEAC) msgs are enabled in T3-CPar.
.br
Far End Block Error (FEBE) reports are enabled in T3-CPar.
.br
Remote Alarm Indication (RAI) is enabled in T3-Any.
.br
Loopbacks initiated remotely time out after 300 seconds.
.\"
.Ss 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
.Em 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
.Em not
supported.
.\"
.Ss T1 Raw Mode
.\"
Special gate array microcode exists for the T1/E1 card.
Each T1 frame of 24 bytes is treated as a packet.
A raw T1 byte stream can be delivered to main memory
and transmitted from main memory.
The T1 card adds or deletes framing bits but does not
touch the data.
ATM cells can be transmitted and received this way, with
the software doing all the work.
But that's not hard; after all it's only 1.5 Mb/s second!
.\"
.Ss T3 Circuit Emulation Mode
.\"
Special gate array microcode exists for the T3 card.
Each T3 frame of 595 bytes is treated as a packet.
A raw T3 signal can be
.Em packetized ,
transported through a
packet network (using some protocol) and then
.Em reconstituted
as a T3 signal at the far end.  The output transmitter's
bit rate can be controlled from software so that it can be
.Em frequency locked
to the distant input signal.
.\"
.Ss HSSI and SSI Transmit Clocks
.\"
Synchronous interfaces use two transmit clocks to eliminate
.Em skew
caused by speed-of-light delays in the modem cable.
DCEs (modems) drive ST, Send Timing. the first transmit clock.
DTEs (hosts) receive ST and use it to clock transmit data, TD,
onto the modem cable.
DTEs also drive a copy of ST back towards the DCE and call it TT,
Transmit Timing. the second trasmit clock.
DCEs receive TT and TD and use TT to clock TD into a flip flop.
TT experiences the same delay as (and has no
.Em skew
relative to) TD.
Thus, cable length does not affect data/clock timing.
.\"
.Sh SEE ALSO
.\"
.Xr tcpdump 1 ,
.Xr ioctl 2 ,
.Xr altq 4 ,
.Xr bpf 4 ,
.Xr kld 4 ,
.Xr loader.conf 5 ,
.Xr netgraph 4 ,
.Xr polling 4 ,
.Xr sppp 4 ,
.Xr altqd 8 ,
.Xr ifconfig 8 ,
.Xr init 8 ,
.Xr mpd 8 ,
.Xr ngctl 8 ,
.Xr ping 8 ,
.Xr lmcconfig 8 ,
.Xr ifnet 9 .
.Pp
.Pa /usr/ports/net/mpd .
.Pp
.Pa http://www.sbei.com .
.\"
.Sh 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
.Tn (LMC) .
.Tn SBE
Corp aquired
.Tn LMC
and continues to make the cards.
.Pp
Since the cards use Tulip Ethernet chips, we started with Matt Thomas'
ubiquitous "de" 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 and wrote the first version of lmcconfig.
David Boggs rewrote everything and now feels responsible for it.
.\"
.Sh AUTHOR
.\"
.An "David Boggs" Aq boggs@boggs.palo-alto.ca.us .