.\"- .\" Copyright (c) 2002-2006 David Boggs. (boggs@boggs.palo-alto.ca.us) .\" All rights reserved. I wrote this man page from scratch. .\" .\" 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. .\" .\" * * * * * * * * * * * * * .\" * ATTENTION MDOC POLICE * .\" * * * * * * * * * * * * * * * * * * * * * * * * * * * * * .\" * This device driver works on FIVE OSs with NO changes. * .\" * IFDEFS are used to ignore C and Groff code that is * .\" * not relevant to a particular Operating System. * .\" * Author will merge local changes and re-sync copies. * .\" * Please feel free to correct my groff usage, but... * .\" * * * * * * * * * * * * * * * * * * * * * * * * * * * * * .\" * PLEASE DO NOT "UN-IFDEF" THIS FILE! * .\" * * * * * * * * * * * * * * * * * * * * * .\" .\" $NetBSD: lmc.4,v 1.14 2006/12/23 06:58:20 wiz Exp $ .\" .Dd April 11, 2006 .Dt LMC 4 .Os .\" Os sets \*(oS or \*[operating-system] .\" substring works differently before Groff version 1.19 .ie (\n(.y < 19) .nr ssfix 1 .el .nr ssfix 0 .\" Is the OS name FreeBSD? .ie "\*[operating-system]"" .ds aa \*(oS .el .ds aa \*[operating-system] .substring aa (0+\n[ssfix] (6+\n[ssfix]) .ie "\*(aa"FreeBSD" .nr fbsd 1 .el .nr fbsd 0 .\" Is the OS name NetBSD? .ie "\*[operating-system]"" .ds aa \*(oS .el .ds aa \*[operating-system] .substring aa (0+\n[ssfix]) (5+\n[ssfix]) .ie "\*(aa"NetBSD" .nr nbsd 1 .el .nr nbsd 0 .\" Is the OS name OpenBSD? .ie "\*[operating-system]"" .ds aa \*(oS .el .ds aa \*[operating-system] .substring aa (0+\n[ssfix]) (7+\n[ssfix]) .ie "\*(aa"OpenBSD" .nr obsd 1 .el .nr obsd 0 .\" Is the OS name BSDI? .ie "\*[operating-system]"" .ds aa \*(oS .el .ds aa \*[operating-system] .substring aa (0+\n[ssfix]) (4+\n[ssfix]) .ie "\*(aa"BSDI" .nr bsdi 1 .el .nr bsdi 0 .\" Is the OS name BSD (i.e. Linux)? .ie "\*[operating-system]"" .ds aa \*(oS .el .ds aa \*[operating-system] .ie "\*(aa"BSD" .nr linux 1 .el .nr linux 0 .\" If no operating system matched then select all OSs. .if !(\n[fbsd] : \n[nbsd] : \n[obsd] : \n[bsdi] : \n[linux]) \{\ .nr allos 1 .nr fbsd 1 .nr nbsd 1 .nr obsd 1 .nr bsdi 1 .nr linux 1 \} .\" .Sh NAME .\" .Nm lmc .Nd device driver for .Tn LMC (and some .Tn SBE ) wide-area network interface cards .\" .Sh SYNOPSIS .if \n[allos] .Ss FreeBSD Synopsis .if \n[fbsd] \{\ The driver can be loaded into a kernel at boot-time by adding .Bd -unfilled -offset indent -compact .Cd if_lmc_load="YES" .Ed to .Pa /boot/loader.conf ; see .Xr loader.conf 5 . .Pp The driver can be loaded into a running kernel after boot-time with .Xr kldload 8 . .Bd -unfilled -offset indent -compact .Ic kldload if_lmc .Ed .Ic securelevel must be 0 to load modules after boot-time; see .Xr init 8 . .Pp The driver can be built into a kernel by adding the following to .Pa /sys/ARCH/conf/YOURKERNEL : .Bd -unfilled -offset indent -compact .Cd device lmc .Cd device sppp .Cd device bpf .Cd device pf # for altq .Cd options ALTQ .Cd options ALTQ_HFSC # for altq example .Cd options NETGRAPH .Cd options DEVICE_POLLING .Ed .Pp The driver can send and receive raw IP packets even if neither SPPP nor Netgraph are configured into the kernel. .\} \" FreeBSD Synopsis .if \n[allos] .Ss NetBSD & OpenBSD Synopsis .if (\n[nbsd] : \n[obsd]) \{\ This driver is built into the GENERIC kernel so it should "just work". The driver can be loaded into a running kernel with .Xr modload 8 . .Bd -unfilled -offset indent -compact .Ic modload if_lmc.o .Ed The kernel must be built with support for Loadable Kernel Modules, .Xr lkm 8 . .Bd -unfilled -offset indent -compact .if \n[nbsd] .Cd options LKM .if \n[obsd] .Cd option LKM .Ed .Ic securelevel must be 0 to load modules; see .Xr init 8 . .Pp The driver can be built into a kernel by adding the following to .Pa /sys/arch/ARCH/conf/YOURKERNEL : .Bd -unfilled -offset indent -compact .Cd lmc* at pci? .if \n[nbsd] \{\ .Cd options ALTQ .Cd options ALTQ_HFSC # for altq example\} .if \n[obsd] \{\ .Cd option ALTQ .Cd option ALTQ_HFSC # for altq example\} .Cd pseudo-device sppp .Cd pseudo-device bpfilter .Ed .Pp The driver can send and receive raw IP packets even if SPPP is not configured into the kernel. .\} \" NetBSD & OpenBSD Synopsis .if \n[allos] .Ss BSD/OS Synopsis .if \n[bsdi] \{\ The driver can be built into a custom kernel by adding the following to .Pa /sys/i386/conf/YOURKERNEL : .Bd -unfilled -offset indent -compact .Cd lmc* at pci? .Cd options PPP .Cd options FR .Cd options CISCO_HDLC .Cd pseudo-device bpfilter 16 .Ed .Pp The driver can send and receive raw IP packets even if P2P is not configured into the kernel. .\} \" BSD/OS Synopsis .if \n[allos] .Ss Linux Synopsis .if \n[linux] \{\ Configure the driver and line protocol for your kernel with .Bd -unfilled -offset indent -compact .Ic make menuconfig .Ed Navigating through the menus, select this device driver and the GenericHDLC layer as loadable kernel modules or built into the kernel: .Bd -unfilled -offset indent -compact .Ic Device Drivers ---> .Ic Networking Support ---> .Ic Wan interfaces ---> .Ed .Pp Selecting LanMedia support selects the GenericHDLC and SyncPPP layers: .Bd -unfilled -offset indent -compact .Ic LanMedia (and some SBE) WAN card support .Ic [*] Use NAPI to prevent livelock .Ic [*] Use the Generic HDLC layer .Ic [*] Use the SyncPPP layer .Ed .Pp Selecting the GenericHDLC layer selects these protocols: .Bd -unfilled -offset indent -compact .Ic Generic HDLC layer .Ic [*] Synchronous Point-to-Point Protocol (PPP) support .Ic [*] Cisco-HDLC support .Ic [*] Frame Relay support .Ic [*] Raw HDLC support .Ic [*] Raw HDLC Ethernet device support .Ed .Pp Selecting the SyncPPP layer includes support for PPP and Cisco-HDLC protocols. .Bd -unfilled -offset indent -compact .Ic SyncPPP layer .Ed .Pp If configured as above, the kernel will recognize an LMC card when it boots and load this driver and the GenericHDLC code. Messages similar to the following will appear in .Pa /var/log/messages : .Bd -unfilled -offset indent -compact .Ic Cronyx Ltd, Synchronous PPP and CISCO HDLC (c) 1994 .Ic Linux port (c) 1998 Building Number Three Ltd & Jan 'Yenya' Kasprzak. .Ic HDLC support module revision 1.18 .Ic LMC Driver version 2006/1/20; Options NAPI GEN_HDLC SYNC_PPP. .Ic hdlc0: at pci 0000:00:13.0 irq 11 .Ed .Pp The driver can send and receive raw IP packets even if neither SyncPPP nor GenericHDLC are configured into the kernel. The device name will be .Ic hdlc if GenericHDLC layer is configured, or .Ic lmc otherwise. .Pp The driver accepts two optional parameters: .Bl -tag -width "verbose" -offset indent .It Va debug Sets the driver's .Sy debug flag at initialization time\[em]earlier than it can be set using .Ic lmcconfig or .Ic ifconfig . .It Va verbose Enables additional log messages describing the hardware while booting or module-loading. .El .Pp If the driver is built into the kernel, parameters are passed on the kernel command line: .Bd -unfilled -offset indent -compact .Ic if_lmc.debug=1 .Ed If the driver is loaded into the kernel as a module, parameters are passed in the .Xr modprobe 8 command: .Bd -unfilled -offset indent -compact .Ic modprobe if_lmc debug=1 .Ed .\} \" linux Synopsis .\" .Sh DESCRIPTION .\" This is an open-source .Tn 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 .Ux plus some .Tn LMC cards makes an .Em open wide-area network router. .Pp The .Nm driver works with .Tn FreeBSD , .Tn NetBSD , .Tn OpenBSD , .Tn BSD/OS , and .Tn Linux OSs. It has been tested on .Tn i386 (SMP 32-bit little-end), .Tn PowerPC (32-bit big-end), .Tn Alpha (64-bit little-end), and .Tn Sparc (64-bit big-end) architectures. .Pp The .Nm driver works with the following cards: .Bl -tag -width "LMC5200" -offset indent .It Sy LMC5200 HSSI\[em]High Speed Serial Interface, .Bd -unfilled -compact EIA612/613, 50-pin connector, 0 to 52 Mb/s, DTE only. .Ed .It Sy LMC5245 T3, 2xBNC conns, 75 ohm .Bd -unfilled -compact C-Parity or M13 Framing, DSX-3 up to 910 ft. .Ed .It Sy LMC1000 SSI\[em]Synchronous Serial Interface, .Bd -unfilled -compact V.35, X.21, EIA449, EIA530(A), EIA232, 0 to 10 Mb/s, DTE or DCE. .Ed .It Sy LMC1200 T1/E1, RJ45 conn, 100 or 120 ohms, .Bd -unfilled -compact T1-B8ZS-ESF, T1-AMI-SF, E1-HDB3-many, DSX-1 up to 1500 ft; CSU up to 6 Kft. .Ed .El .Pp .Tn LMC 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" -offset indent .It Sy PCI The PCI interface is a .Tn "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 of 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 .Tn TranSwitch TXC-03401 framer chip. SSI cards use .Tn Linear Technology LTC1343 modem interface chips. T1 cards use a .Tn BrookTree/Conexant/Mindspeed Bt8370 framer and line interface chip. .El .Pp 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: .Bl -tag -width "GenericHDLC" -offset indent .if \n[fbsd] \{\ .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. ASCII configuration control messages are .Em not currently supported. \} .if \n[fbsd] \{\ .It Sy SPPP .Xr sppp 4 implements Synchronous-PPP, Cisco-HDLC and Frame-Relay in the kernel. \} .if (\n[nbsd] : \n[obsd]) \{\ .It Sy SPPP .Xr sppp 4 implements Synchronous-PPP and Cisco-HDLC in the kernel. \} .if \n[bsdi] \{\ .It Sy P2P .Xr p2p 4 implements Synchronous-PPP, Cisco-HDLC and Frame-Relay in the kernel. \} .if \n[linux] \{\ .It Sy GenericHDLC implements Synchronous-PPP, Cisco-HDLC, Frame-Relay, Ether-in-HDLC, IPv4-in-HDLC, and X.25 in the kernel. .It Sy SyncPPP implements Synchronous-PPP and Cisco-HDLC in the kernel. GenericHDLC uses SyncPPP as it's in-kernel PPP implementation. \} .It Sy 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. .El .\" .Sh EXAMPLES .\" .Ss ifconfig and lmcconfig .\" The program .Xr lmcconfig 8 manipulates interface parameters beyond the scope of .Xr ifconfig 8 . .Ic lmcconfig has many flags and options, but in normal operation only a few are needed. .Bd -unfilled -offset indent .Ic lmcconfig lmc0 .Ed displays interface configuration and status. .Bd -unfilled -offset indent .Ic lmcconfig lmc0 -X 1 .Ed selects the built-in RawIP line protocol stack. .if (\n[fbsd] : \n[nbsd] : \n[obsd]) \{\ .Bd -unfilled -offset indent .Ic lmcconfig lmc0 -X 2 -x 2 .Ed selects the SPPP stack and the PPP protocol. \} .if \n[bsdi] \{\ .Bd -unfilled -offset indent .Ic lmcconfig lmc0 -X 3 -x 2 .Ed selects the P2P stack and the PPP protocol. \} .if \n[linux] \{\ .Bd -unfilled -offset indent .Ic lmcconfig lmc0 -X 4 -x 2 .Ed selects the GenericHDLC stack and the PPP protocol. .Bd -unfilled -offset indent .Ic lmcconfig lmc0 -X 5 -x 2 .Ed selects the SyncPPP stack and the PPP protocol. \} .if (\n[fbsd] \{\ .Bd -unfilled -offset indent .Ic lmcconfig lmc0 -X 6 .Ed selects the Netgraph stack. \} .if (\n[fbsd] : \n[nbsd] : \n[obsd] : \n[bsdi]) \{\ .Pp Some configuration options are available through .Ic ifconfig as well as .Ic lmcconfig . .Bd -unfilled -offset indent -compact .Ic ifconfig -m lmc0 .Ed lists the available media options. .Pp .Bd -unfilled -offset indent .Ic ifconfig lmc0 mediaopt loopback .Ed loops the interface transmitter to the receiver for testing. This loopback uses a path present in every card type. .Ic lmcconfig can select card-specific loopbacks, such as outbound payload loopback. .Pp .if \n[obsd] \{\ .Bd -unfilled -offset indent .Ic ifconfig lmc0 media e1 timeslot all .Ed selects E1 format using all 32 timeslots. .Bd -unfilled -offset indent .Ic ifconfig lmc0 mediaopt ppp .Ed selects Point-to-Point Protocol. .Bd -unfilled -offset indent .Ic ifconfig lmc0 mediaopt master .Ed selects the on-board crystal oscillator as the transmitter clock. \} \} .Bd -unfilled -offset indent .Ic ifconfig lmc0 debug .Ed enables debugging output from the device driver and from the line protocol stack above it. .Bd -unfilled -offset indent .Ic lmcconfig lmc0 -D .Ed enables debugging output from the device driver. .Pp Debugging messages that appear on the console are also written to file .Pa /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. .\" .ie \n[allos] .Ss FreeBSD Operation .el .Ss Operation .\} .if \n[fbsd] \{\ Configure a PPP link using SPPP and Netgraph with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 6 .Ic ngctl mkpeer lmc0: sppp rawdata downstream .Ic ifconfig sppp0 10.0.0.1 10.0.0.2 .Ed .Pp Configure a PPP link using only SPPP with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 2 -x 2 .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ed .Pp Configure a Cisco-HDLC link using SPPP and Netgraph with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 6 .Ic ngctl mkpeer lmc0: sppp rawdata downstream .Ic ifconfig sppp0 10.0.0.1 10.0.0.2 link2 .Ed .Pp Configure a Cisco-HDLC link using only SPPP with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 2 -x 3 .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ed .Pp Configure a Cisco-HDLC link using only Netgraph with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 6 .Ic ngctl mkpeer lmc0: cisco rawdata downstream .Ic ngctl mkpeer lmc0:rawdata iface inet inet .Ic ifconfig ng0 10.0.0.1 10.0.0.2 .Ed .Pp Configure a Frame-Relay DTE link using SPPP with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 2 -x 4 .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ed SPPP implements the ANSI link management interface (LMI). .Pp Configure a Frame-Relay DTE link using Netgraph with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 6 .Ic ngctl mkpeer lmc0: frame_relay rawdata downstream .Ic ngctl mkpeer lmc0:rawdata lmi dlci0 auto0 .Ic ngctl connect lmc0:rawdata dlci0 dlci1023 auto1023 .Ic ngctl mkpeer lmc0:rawdata rfc1490 dlci500 downstream .Ic ngctl mkpeer lmc0:rawdata.dlci500 iface inet inet .Ic ifconfig ng0 10.0.0.1 10.0.0.2 .Ed Netgraph implements ANSI, ITU, and FRIF link management interfaces (LMIs). .Pp Configure a RAWIP link using only the driver with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 1 .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ed .Pp Configure a RAWIP link using Netgraph with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 6 .Ic ngctl mkpeer lmc0: iface rawdata inet .Ic ifconfig ng0 10.0.0.1 10.0.0.2 .Ed .\} \" FreeBSD operation .if \n[allos] .Ss NetBSD & OpenBSD Operation .if (\n[nbsd] : \n[obsd]) \{\ Configure a PPP link using SPPP with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 2 -x 2 .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ed .Pp Configure a Cisco-HDLC link using SPPP with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 2 -x 3 .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ed .Pp Configure a RAWIP link with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 1 .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ed .\} \" NetBSD & OpenBSD operation .if \n[allos] .Ss BSD/OS Operation .if \n[bsdi] \{\ Configure a PPP link using P2P by creating file .Pa /etc/ppp.sys containing .Bd -unfilled -offset indent -compact .Ic Plmc0: :device=lmc0: .Ic :local-addr=10.0.0.1: .Ic :remote-addr=10.0.0.2: .Ic :immediate:dialout:direct: .Ic :-pfc:-acfc:-tcpc: .Ed Then run .Xr ppp 8 : .Bd -unfilled -offset indent -compact .Ic ppp -bd Plmc0 .Ed Add .Ic -X debug-all to watch protocol events happen. .Pp Configure a Cisco-HDLC link by setting LINKTYPE with .Bd -unfilled -offset indent -compact .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 linktype chdlc .Ed .Pp Configure a Fame-Relay link with .Bd -unfilled -offset indent -compact .Ic ifconfig lmc0 linktype fr .Ic frconfig lmc0 lmi ansi [type dce] .Ic frconfig lmc0 dlci 500 10.0.0.2 .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ed Adding .Dq "type dce" after .Dq "ansi" configures it as a DCE (switch). P2P implements ANSI, ITU and FRIF link management interfaces (LMIs). .Pp Configure a RAWIP link with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 1 .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ed .\} \" BSD/OS operation .if \n[allos] .Ss Linux operation .if \n[linux] \{\ The .Ic sethdlc program configures the GenericHDLC code. .Bd -filled -offset indent -compact .Ic sethdlc hdlc0 (or .Ic pvc0 for frame relay) .Ed displays the current settings of a given device. Note that .Ic sethdlc must be run before .Ic ifconfig . .Ic Sethdlc and the GenericHDLC kernel code are documented in .Pa /usr/src/linux/Documentation/networking/generic-hdlc.txt and at .Pa http://www.kernel.org:/pub/linux/utils/net/hdlc .Pp Configure a PPP link using GenericHDLC with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 4 -x 2 .Ic sethdlc hdlc0 ppp .Ic ifconfig hdlc0 10.0.0.1 pointopoint 10.0.0.2 .Ed .Pp Configure a PPP link using SyncPPP with .Bd -unfilled -offset indent -compact .Ic lmcconfig hdlc0 -X 5 -x 2 .Ic ifconfig hdlc0 10.0.0.1 pointopoint 10.0.0.2 .Ed .Pp Configure a Cisco-HDLC link using GenericHDLC with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 4 .Ic sethdlc hdlc0 cisco .Ic ifconfig hdlc0 10.0.0.1 pointopoint 10.0.0.2 .Ed .Pp Configure a Cisco-HDLC link using SyncPPP with .Bd -unfilled -offset indent -compact .Ic lmcconfig hdlc0 -X 5 -x 3 .Ic ifconfig hdlc0 10.0.0.1 pointopoint 10.0.0.2 .Ed .Pp Configure a Frame-Relay DTE link using GenericHDLC with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 4 .Ic sethdlc hdlc0 fr lmi ansi [dce] .Ic sethdlc hdlc0 create 500 .Ic ifconfig hdlc0 up .Ic ifconfig pvc0 10.0.0.1 pointopoint 10.0.0.2 .Ed Adding .Dq dce after .Dq ansi configures it as a DCE (switch). GenericHDLC implements ANSI and ITU link management interfaces (LMIs). .Pp Configure a RAWIP link using GenericHDLC with .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -X 4 .Ic sethdlc hdlc0 hdlc .Ic ifconfig hdlc0 10.0.0.1 pointopoint 10.0.0.2 .Ed .Pp Configure a RAWIP link using only the driver with .Bd -unfilled -offset indent -compact .Ic lmcconfig hdlc0 -X 1 .Ic ifconfig hdlc0 10.0.0.1 pointopoint 10.0.0.2 .Ed .\} \" Linux Operation .\" .Sh TESTING .\" .if (\n[fbsd] : \n[nbsd] : \n[obsd] : \n[bsdi]) \{\ .\" .Ss 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. .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 Configure the card with .Bd -unfilled -offset indent -compact .Ic ifconfig lmc0 10.0.0.1 10.0.0.1 .Ed .Pp .Bl -tag -width "T1/E1" -offset indent .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 .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -a 2 .Ed .Dq Fl a Li 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 .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -E -f 10000000 .Ed .Bd -ragged -compact .Dq Fl E puts the card in DCE mode to source a transmit clock. .Dq Fl f Li 10000000 sets the internal clock source to 10 Mb/s. .Ed .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. .\} \" Testing with Loopbacks .\" .Ss 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. .Pp Configure the two cards with .Bd -unfilled -offset indent -compact .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ic ifconfig lmc1 10.0.0.2 10.0.0.1 .Ed .Pp .Bl -tag -width "T3/HSSI" -offset indent .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 and a T3 card. The coax cables between the card and the modem must .Dq "cross over" (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 and a T1 card. Use a T1 null modem cable (see below) between the external modem and the T1 card. .El .\" .Ss 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. .Pp Configure the two cards with .Bd -unfilled -offset indent -compact .Ic ifconfig lmc0 10.0.0.1 10.0.0.2 .Ic ifconfig lmc1 10.0.0.2 10.0.0.1 .Ed .Pp .Bl -tag -width "T1/E1" -offset indent .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 .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -a 2 .Ed .Dq Fl a Li 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\[em]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 .Bd -unfilled -offset indent -compact .Ic lmcconfig lmc0 -E -f 10000000 .Ed .Bd -ragged -compact .Dq Fl E puts the card in DCE mode to source a transmit clock. .Dq Fl f Li 10000000 sets the internal clock source to 10 Mb/s. .Ed .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 OPERATING NOTES .\" .Ss 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. .Bl -column "YELLOW" "upper-right" -offset indent -compact .It "RED\0" 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 .Pp 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! .Bl -column "YELLOW" "upper-right" -offset indent -compact .It "RED\0" 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 .Pp .Bl -column "YELLOW" -offset indent -compact .It "RED\0" Ta "blinks if an outward loopback is active." .It "GREEN" Ta "blinks if the device driver is alive." .It "BLUE" Ta "blinks if sending AIS, on solid if receiving AIS." .It "YELLOW" Ta "blinks if sending RAI, on solid if receiving RAI." .El .\" .Ss Packet Lengths .\" .Bd -unfilled -compact Maximum transmit and receive packet length is unlimited. Minimum transmit and receive packet length is one byte. .Ed .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 is not a problem since an IPv4 packet header is at least 20 bytes long. .Pp 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 .Bd -unfilled -offset indent -compact .Ic ifconfig lmc0 mtu 2000 .Ed .if (\n[fbsd] : \n[nbsd] : \n[obsd]) \{\ SPPP enforces an MTU of 1500 bytes for PPP and Cisco-HDLC. \} .if \n[bsdi] \{\ P2P enforces an MTU of 1500 bytes for PPP and Cisco-HDLC, and 4000 bytes for Frame Relay. \} .if \n[linux] \{\ GenericHDLC enforces an MTU range of (68..1500) bytes. \} RAWIP sets the default MTU to 4032 bytes, but allows it to be changed to anything. .\" .if (\n[fbsd] : \n[nbsd] : \n[obsd]) \{\ .\" .Ss ALTQ: Alternate Output Queue Disciplines .\" The driver has hooks for .Xr 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. .Pp .if \n[allos] .Ss FreeBSD ALTQ example .if \n[fbsd] \{\ Enable .Xr pf 4 and add the following lines to .Pa /etc/pf.conf : .Bd -unfilled -offset indent -compact .Ic altq on lmc0 bandwidth 44Mb hfsc queue { a b c } .Ic queue a\0 on lmc0 bandwidth 48% .Ic pass in\0 on lmc0 queue a from 10.0.0.2 port 12345 to 10.0.0.1 .Ic pass out on lmc0 queue a from 10.0.0.1 to 10.0.0.2 port 12345 .Ic queue b\0 on lmc0 bandwidth 48% .Ic pass in\0 on lmc0 queue b from 10.0.0.2 port 12346 to 10.0.0.1 .Ic pass out on lmc0 queue b from 10.0.0.1 to 10.0.0.2 port 12346 .Ic queue c\0 on lmc0 bandwidth 4% hfsc(default) .Ic pass in\0 on lmc0 queue c from 10.0.0.2 port 12347 to 10.0.0.1 .Ic pass out on lmc0 queue c from 10.0.0.1 to 10.0.0.2 port 12347 .Ed .\} \" FreeBSD altq configuration .if \n[allos] .Ss NetBSD and OpenBSD ALTQ example .if (\n[nbsd] : \n[obsd]) \{\ Enable .Xr altqd 8 and add the following lines to .Pa /etc/altq.conf : .Bd -unfilled -offset indent -compact .Ic interface lmc0 bandwidth 44M hfsc .Ic class hfsc lmc0 a root pshare 48 .Ic filter lmc0 a 10.0.0.2 12345 10.0.0.1 0 6 .Ic filter lmc0 a 10.0.0.1 0 10.0.0.2 12345 6 .Ic class hfsc lmc0 b root pshare 48 .Ic filter lmc0 b 10.0.0.2 12346 10.0.0.1 0 6 .Ic filter lmc0 b 10.0.0.1 0 10.0.0.2 12346 6 .Ic class hfsc lmc0 c root pshare 4 default .Ic filter lmc0 c 10.0.0.2 12347 10.0.0.1 0 6 .Ic filter lmc0 c 10.0.0.1 0 10.0.0.2 12347 6 .Ed .\} \" NetBSD and OpenBSD altq configuration .Pp The example above requires .ie \n[fbsd] \{\ the Packet Filter .Xr pf 4 and \} the .Xr altq 4 Hierarchical Fair Service Curve queue discipline to be configured in .Pa conf/YOURKERNEL : .Bd -unfilled -offset indent -compact .if \n[fbsd] .Ic device pf .if \n[obsd] \{\ .Ic option ALTQ .Ic option ALTQ_HFSC . \} .if (\n[nbsd] : \n[fbsd]) \{\ .Ic options ALTQ .Ic options ALTQ_HFSC . \} .Ed .\} \" ALTQ .\" .if (\n[fbsd] : \n[nbsd] : \n[obsd] : \n[bsdi]) \{\ .\" .Ss BPF: Berkeley Packet Filter .\" The driver has hooks for .Xr bpf 4 , the Berkeley Packet Filter, a protocol-independent raw interface to data link layers. .Pp To test the BPF kernel interface, bring up a link between two machines, then run .Xr ping 8 and .Xr tcpdump 1 : .Bd -unfilled -offset indent -compact .Ic ping 10.0.0.1 .Ed and in a different window: .Bd -unfilled -offset indent -compact .Ic tcpdump -i lmc0 .Ed The output from tcpdump should look like this: .Bd -unfilled -offset indent -compact .Ic 03:54:35.979965 10.0.0.2 > 10.0.0.1: icmp: echo request .Ic 03:54:35.981423 10.0.0.1 > 10.0.0.2: icmp: echo reply .Ed Line protocol control packets may appear among the ping packets occasionally. .Pp The kernel must be configured with .Bd -unfilled -offset indent -compact .if \n[fbsd] .Ic device bpf .if \n[nbsd] .Ic options bpfilter .if \n[obsd] .Ic option bpfilter .if \n[bsdi] .Ic pseudo-device bpfilter .Ed .\} \" Berkeley Packet Filter .\" .if \n[linux] \{\ .\" .Ss Device Polling .\" A T3 receiver can generate over 100K interrupts per second, This can cause a system to .Dq live-lock : spend all of its time servicing interrupts. .Tn Linux Ns 's polling mechanism disables a card's interrupt when it interrupts, calls the card's interrupt service routine with kernel interrupts enabled, and then reenables the card's interrupt. The driver is permitted to process a limited number of packets each time it is called by the kernel. Card interrupts are left disabled if more packets arrive than are permitted to be processed, which in extreme cases will result in packets being dropped in hardware at no cost to software. .Pp Polling is enabled using .Ic menuconfig by selecting .Bd -unfilled -offset indent -compact .Ic LanMedia (and some SBE) WAN card support .Ic [*] Use NAPI to prevent livelock .Ed .\} \" Linux Device Polling .\" .if \n[fbsd] \{\ .\" .Ss Device Polling .\" A T3 receiver can generate over 100K interrupts per second, This can cause a system to .Dq live-lock : spend all of its time servicing interrupts. .Fx Ns 's .Xr polling 4 mechanism permanently disables interrupts from the card and instead the card's interrupt service routine is polled 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 each time it is called by the kernel. .Pp Polling is enabled with .Bd -unfilled -offset indent -compact .Ic ifconfig lmc0 polling .Ed The kernel must be configured with .Bd -unfilled -offset indent -compact .Ic options DEVICE_POLLING .Ed .\} \" FreeBSD Device Polling .\" .Ss 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: .Bl -tag -width "RFC-2233" -offset indent -compact .It RFC-2233 .%T Interfaces group .It RFC-2496 .%T DS3 interfaces .It RFC-2495 .%T DS1/E1 interfaces .It RFC-1659 .%T 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 .if \n[fbsd] \{\ Netgraph control messages or \} .Xr ioctl 2 system calls. User programs should poll .Va sc->cfg.ticks which increments once per second after the SNMP state has been updated. .\" .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 .\" .Bd -unfilled -compact 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. .Ed .\" .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. .if 0 \{\ .\" .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 minimal .Em skew relative to) TD. Thus, cable length does not affect data/clock timing. .\} .if 0 \{\ .\" .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 is not hard; after all it is only 1.5 Mb/s second! .\} .if 0 \{\ .\" .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. .\} .\" .Sh SEE ALSO .\" .if \n[fbsd] .Xr tcpdump 1 , .if \n[nbsd] .Xr tcpdump 1 , .if \n[obsd] .Xr tcpdump 1 , .if \n[bsdi] .Xr tcpdump 1 , .Xr ioctl 2 , .if \n[fbsd] .Xr bpf 4 , .if \n[nbsd] .Xr bpf 4 , .if \n[obsd] .Xr bpf 4 , .if \n[bsdi] .Xr bpf 4 , .if \n[fbsd] .Xr de 4 , .if \n[nbsd] .Xr de 4 , .if \n[obsd] .Xr de 4 , .if \n[bsdi] .Xr de 4 , .if \n[fbsd] .Xr kld 4 , .if \n[fbsd] .Xr netgraph 4 , .if \n[bsdi] .Xr p2p 4 , .if \n[fbsd] .Xr pf 4 , .if \n[fbsd] .Xr polling 4 , .if \n[fbsd] .Xr sppp 4 , .if \n[nbsd] .Xr sppp 4 , .if \n[obsd] .Xr sppp 4 , .if \n[nbsd] .Xr altq.conf 5 , .if \n[obsd] .Xr altq.conf 5 , .if \n[fbsd] .Xr loader.conf 5 , .if \n[fbsd] .Xr pf.conf 5 , .if \n[obsd] .Xr altqd 8 , .if \n[nbsd] .Xr altqd 8 , .if \n[bsdi] .Xr frconfig 8 , .Xr ifconfig 8 , .if \n[fbsd] .Xr init 8 , .if \n[nbsd] .Xr init 8 , .if \n[obsd] .Xr init 8 , .if \n[fbsd] .Xr kldload 8 , .if \n[nbsd] .Xr lkm 8 , .if \n[obsd] .Xr lkm 8 , .Xr lmcconfig 8 , .if \n[nbsd] .Xr modload 8 , .if \n[obsd] .Xr modload 8 , .if \n[linux] .Xr modprobe 8 , .if \n[fbsd] .Xr ngctl 8 , .Xr ping 8 , .if \n[bsdi] .Xr ppp 8 , .Xr tcpdump 8 , .if \n[fbsd] .Xr altq 9 , .if \n[nbsd] .Xr altq 9 , .if \n[obsd] .Xr altq 9 , .if \n[fbsd] .Xr ifnet 9 .if \n[nbsd] .Xr ifnet 9 .if \n[obsd] .Xr ifnet 9 .if \n[bsdi] .Xr ifnet 9 .Pp .Bd -unfilled .Pa http://www.sbei.net/ .if \n[linux] \{\ .Pa http://www.kernel.org:/pub/linux/utils/net/hdlc .Pa file://usr/src/linux/Documentation/networking/generic-hdlc.txt \} .Ed .\" .Sh HISTORY .\" .An 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. .An David Boggs designed the Ethernet-to-HDLC gate array and PC cards. We did this at our company, .Tn "LAN Media Corporation (LMC)" . .Tn "SBE Corporation" aquired .Tn LMC and continues to make the cards. .Pp Since the cards use Tulip Ethernet chips, we started with .An Matt Thomas Ns ' ubiquitous .Xr de 4 driver. .An Michael Graff stripped out the Ethernet stuff and added HSSI stuff. .An Basil Gunn ported it to .Tn Solaris (lost) and .An Rob Braun ported it to .Tn Linux . .An Andrew Stanley-Jones added support for three more cards. .An David Boggs rewrote everything and now feels responsible for it. .\" .Sh AUTHORS .\" .An David Boggs Aq boggs@boggs.palo-alto.ca.us