share/man/man4/lmc.4

   1 .\"
   2 .\" $FreeBSD$
   3 .\"
   4 .\" Copyright (c) 2002-2005 David Boggs. (boggs@boggs.palo-alto.ca.us)
   5 .\" All rights reserved.
   6 .\"
   7 .\" BSD License:
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" GNU General Public License:
  31 .\"
  32 .\" This program is free software; you can redistribute it and/or modify it
  33 .\" under the terms of the GNU General Public License as published by the Free
  34 .\" Software Foundation; either version 2 of the License, or (at your option)
  35 .\" any later version.
  36 .\"
  37 .\" This program is distributed in the hope that it will be useful, but WITHOUT
  38 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  39 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  40 .\" more details.
  41 .\"
  42 .\" You should have received a copy of the GNU General Public License along with
  43 .\" this program; if not, write to the Free Software Foundation, Inc., 59
  44 .\" Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  45 .\"
  46 .Dd February 8, 2012
  47 .Dt LMC 4
  48 .Os
  49 .\"
  50 .Sh NAME
  51 .\"
  52 .Nm lmc
  53 .Nd device driver for
  54 .Tn LMC
  55 (now
  56 .Tn SBE )
  57 wide-area network interface cards
  58 .\"
  59 .Sh SYNOPSIS
  60 .\"
  61 To wire this driver into your kernel,
  62 add the following line to your kernel configuration file:
  63 .Bd -ragged -offset indent
  64 .Cd "device lmc"
  65 .Ed
  66 .Pp
  67 Alternatively, to load this module at boot time, add
  68 .Bd -literal -offset indent
  69 if_lmc_load="YES"
  70 .Ed
  71 .Pp
  72 to
  73 .Pa /boot/loader.conf ;
  74 see
  75 .Xr loader.conf 5 .
  76 .Pp
  77 To wire a line protocol into your kernel, add:
  78 .Bd -ragged -offset indent
  79 .Cd "options NETGRAPH"
  80 .Cd "device sppp"
  81 .Ed
  82 .Pp
  83 It is not necessary to wire line protocols into your kernel,
  84 they can be loaded later with
  85 .Xr kldload 8 .
  86 The driver can send and receive raw IP packets even if neither
  87 SPPP nor Netgraph are configured into the kernel.
  88 Netgraph and SPPP can both be enabled; Netgraph will be used if the
  89 .Va rawdata
  90 hook is connected.
  91 .\"
  92 .Sh DESCRIPTION
  93 .\"
  94 This is an open-source
  95 .Ux
  96 device driver for PCI-bus WAN interface cards.
  97 It sends and receives packets in HDLC frames over synchronous circuits.
  98 A generic PC plus
  99 .Ux
 100 plus some
 101 .Tn LMC / SBE
 102 cards makes an
 103 .Em open
 104 router.
 105 This driver works with
 106 .Fx ,
 107 .Nx ,
 108 .Ox ,
 109 .Bsx
 110 and
 111 .Tn Linux
 112 OSs.
 113 It has been tested on i386 (SMP 32-bit little-endian) and Sparc (64-bit big-endian)
 114 architectures.
 115 .Pp
 116 The
 117 .Nm
 118 driver works with the following cards:
 119 .Bl -bullet
 120 .It
 121 SBE wanADAPT-HSSI (LMC5200)
 122 .Pp
 123 High Speed Serial Interface,
 124 EIA612/613, 50-pin connector,
 125 0 to 52 Mb/s, DTE only.
 126 .It
 127 SBE wanADAPT-T3 (LMC5245)
 128 .Pp
 129 T3: two 75-ohm BNC connectors,
 130 C-Parity or M13 Framing,
 131 44.736 Mb/s, up to 950 ft.
 132 .It
 133 SBE wanADAPT-SSI (LMC1000)
 134 .Pp
 135 Synchronous Serial Interface,
 136 V.35, X.21, EIA449, EIA530(A), EIA232,
 137 0 to 10 Mb/s, DTE or DCE.
 138 .It
 139 SBE wanADAPT-T1E1 (LMC1200)
 140 .Pp
 141 T1 or E1: RJ45 conn, 100 or 120 ohms,
 142 T1-ESF-B8ZS, T1-SF-AMI, E1-(many)-HDB3,
 143 1.544 Mb/s or 2.048 Mb/s, up to 6 Kft.
 144 .El
 145 .Pp
 146 Cards contain a high-performance
 147 .Sy "PCI"
 148 interface, an
 149 .Sy "HDLC"
 150 function and
 151 either integrated
 152 .Sy "modems"
 153 (T1, T3) or
 154 .Sy "modem"
 155 interfaces (HSSI and SSI).
 156 .Bl -tag -width "Modem"
 157 .It Sy "PCI"
 158 The PCI interface is a DEC 21140A "Tulip" Fast Ethernet chip.
 159 This chip has an efficient PCI implementation with scatter/gather DMA,
 160 and can run at 100 Mb/s full duplex (twice as fast as needed here).
 161 .It Sy "HDLC"
 162 The HDLC functions (ISO-3309: flags, bit-stuffing, CRC) are implemented
 163 in a Field Programmable Gate Array (FPGA) which talks to the Ethernet
 164 chip through a Media Independent Interface (MII).
 165 The hardware in the FPGA translates between Ethernet packets and
 166 HDLC frames on-the-fly; think it as a WAN PHY chip for Ethernet.
 167 .It Sy "Modem"
 168 The modem chips are the main differences between cards.
 169 HSSI cards use ECL10K chips to implement the EIA-612/613 interface.
 170 T3 cards use a TranSwitch TXC-03401 framer chip.
 171 SSI cards use Linear Technology LTC1343 modem interface chips.
 172 T1 cards use a BrookTree/Conexant/Mindspeed Bt8370 framer
 173 and line interface chip.
 174 .El
 175 .Pp
 176 Line protocols exist above device drivers and below internet protocols.
 177 They typically encapsulate packets in HDLC frames and deal with
 178 higher-level issues like protocol multiplexing and security.
 179 This driver is compatible with several line protocol packages:
 180 .Bl -tag -width "Generic HDLC"
 181 .It Sy "Netgraph"
 182 .Xr netgraph 4
 183 implements many basic packet-handling functions as kernel loadable modules.
 184 They can be interconnected in a graph to implement many protocols.
 185 Configuration is done from userland without rebuilding the kernel.
 186 Packets are sent and received through this interface if the driver's
 187 .Em rawdata
 188 hook is connected, otherwise the ifnet interface (SPPP and RawIP) is used.
 189 ASCII configuration control messages are
 190 .Em not
 191 currently supported.
 192 .It Sy "SPPP"
 193 .Xr sppp 4
 194 implements Synchronous-PPP, Frame-Relay and Cisco-HDLC in the kernel.
 195 .It Sy "RawIP"
 196 This null line protocol, built into the driver, sends and receives
 197 raw IPv4 and IPv6 packets in HDLC frames (aka IP-in-HDLC) with
 198 no extra bytes of overhead and no state at the end points.
 199 .El
 200 .\"
 201 .Sh EXAMPLES
 202 .\"
 203 .Ss "ifconfig and lmcconfig"
 204 .\"
 205 The program
 206 .Xr lmcconfig 8
 207 manipulates interface parameters beyond the scope of
 208 .Xr ifconfig 8 .
 209 In normal operation only a few arguments are needed:
 210 .Pp
 211 .Bl -tag -width ".Fl X" -offset indent -compact
 212 .It Fl X
 213 selects the external
 214 SPPP
 215 line protocol package.
 216 .It Fl x
 217 selects the built-in RawIP line protocol package.
 218 .It Fl Z
 219 selects PPP line protocol.
 220 .It Fl z
 221 selects Cisco-HDLC line protocol.
 222 .It Fl F
 223 selects Frame-Relay line protocol.
 224 .El
 225 .Bl -tag -width indent
 226 .It Li "lmcconfig lmc0"
 227 displays interface configuration and status.
 228 .It Li "lmcconfig lmc0 -D"
 229 enables debugging output from the device driver only.
 230 .It Li "ifconfig lmc0 debug"
 231 enables debugging output from the device driver and from
 232 the line protocol module above it.
 233 Debugging messages that appear on the console are also
 234 written to file
 235 .Pa "/var/log/messages" .
 236 .Em Caution :
 237 when things go very wrong, a torrent of debugging messages
 238 can swamp the console and bring a machine to its knees.
 239 .El
 240 .\"
 241 .Ss Operation
 242 .\"
 243 Activate a PPP link using SPPP and Netgraph with:
 244 .Bd -literal -offset indent
 245 ngctl mkpeer lmc0: sppp rawdata downstream
 246 ifconfig sppp0 10.0.0.1 10.0.0.2
 247 .Ed
 248 .Pp
 249 Activate a PPP link using only SPPP with:
 250 .Bd -literal -offset indent
 251 lmcconfig lmc0 -XYZ
 252 ifconfig lmc0 10.0.0.1 10.0.0.2
 253 .Ed
 254 .Pp
 255 Activate a Cisco-HDLC link using SPPP and Netgraph with:
 256 .Bd -literal -offset indent
 257 ngctl mkpeer lmc0: sppp rawdata downstream
 258 ifconfig sppp0 10.0.0.1 10.0.0.2 link2
 259 .Ed
 260 .Pp
 261 Activate a Cisco-HDLC link using only SPPP with:
 262 .Bd -literal -offset indent
 263 lmcconfig lmc0 -XYz
 264 ifconfig lmc0 10.0.0.1 10.0.0.2
 265 .Ed
 266 .Pp
 267 Activate a Cisco-HDLC link using only Netgraph with:
 268 .Bd -literal -offset indent
 269 ngctl mkpeer lmc0: cisco rawdata downstream
 270 ngctl mkpeer lmc0:rawdata iface inet inet
 271 ifconfig ng0 10.0.0.1 10.0.0.2
 272 .Ed
 273 .Pp
 274 Activate a Frame-Relay DTE link using SPPP with:
 275 .Bd -literal -offset indent
 276 lmcconfig lmc0 -XYF
 277 ifconfig lmc0 10.0.0.1 10.0.0.2
 278 .Ed
 279 .Pp
 280 (SPPP implements the ANSI T1.617 annex D LMI.)
 281 .Pp
 282 Activate a Frame-Relay DTE link using Netgraph with:
 283 .Bd -literal -offset indent
 284 ngctl mkpeer  lmc0: frame_relay rawdata downstream
 285 ngctl mkpeer  lmc0:rawdata lmi dlci0 auto0
 286 ngctl connect lmc0:rawdata dlci0 dlci1023 auto1023
 287 ngctl mkpeer  lmc0:rawdata rfc1490 dlci500 downstream
 288 ngctl mkpeer  lmc0:rawdata.dlci500 iface inet inet
 289 ifconfig ng0 10.0.0.1 10.0.0.2
 290 .Ed
 291 This is
 292 .Em ONE
 293 possible Frame Relay configuration; there are many.
 294 .Pp
 295 Activate a RAWIP link using only the driver with:
 296 .Bd -literal -offset indent
 297 lmcconfig lmc0 -x
 298 ifconfig lmc0 10.0.0.1 10.0.0.2
 299 .Ed
 300 .Pp
 301 Activate a RAWIP link using Netgraph with:
 302 .Bd -literal -offset indent
 303 ngctl mkpeer lmc0: iface rawdata inet
 304 ifconfig ng0 10.0.0.1 10.0.0.2
 305 .Ed
 306 .Pp
 307 If the driver is unloaded and then loaded, reconnect hooks by:
 308 .Pp
 309 .Dl "ngctl connect lmc0: ng0: rawdata inet"
 310 .\"
 311 .Sh TESTING
 312 .\"
 313 .Ss Testing with Loopbacks
 314 .\"
 315 Testing with loopbacks requires only one card.
 316 Packets can be looped back at many points: in the PCI chip,
 317 in the modem chips, through a loopback plug, in the
 318 local external equipment, or at the far end of a circuit.
 319 .Pp
 320 Activate the card with
 321 .Xr ifconfig 8 :
 322 .Pp
 323 .Dl "ifconfig lmc0 10.0.0.1 10.0.0.1"
 324 .Pp
 325 All cards can be looped through the PCI chip.
 326 Cards with internal modems can be looped through
 327 the modem framer and the modem line interface.
 328 Cards for external modems can be looped through
 329 the driver/receiver chips.
 330 See
 331 .Xr lmcconfig 8
 332 for details.
 333 .Pp
 334 Loopback plugs test everything on the card.
 335 .Bl -tag -width ".Sy T1/E1"
 336 .It Sy HSSI
 337 Loopback plugs can be ordered from SBE (and others).
 338 Transmit clock is normally supplied by the external modem.
 339 When an HSSI card is operated with a loopback plug, the PCI bus
 340 clock must be used as the transmit clock, typically 33 MHz.
 341 When testing an HSSI card with a loopback plug,
 342 configure it with
 343 .Xr lmcconfig 8 :
 344 .Pp
 345 .Dl "lmcconfig lmc0 -a 2"
 346 .Pp
 347 .Dq Fl a Li 2
 348 selects the PCI bus clock as the transmit clock.
 349 .It Sy T3
 350 Connect the two BNC jacks with a short coax cable.
 351 .It Sy SSI
 352 Loopback plugs can be ordered from SBE (only).
 353 Transmit clock is normally supplied by the external modem.
 354 When an SSI card is operated with a loopback plug,
 355 the on-board clock synthesizer must be used.
 356 When testing an SSI card with a loopback plug,
 357 configure it with
 358 .Xr lmcconfig 8 :
 359 .Pp
 360 .Dl "lmcconfig lmc0 -E -f 10000000"
 361 .Pp
 362 .Fl E
 363 puts the card in DCE mode to source a transmit clock.
 364 .Dq Fl f Li 10000000
 365 sets the internal clock source to 10 Mb/s.
 366 .It Sy T1/E1
 367 A loopback plug is a modular plug with two wires
 368 connecting pin 1 to pin 4 and pin 2 to pin 5.
 369 .El
 370 .Pp
 371 One can also test by connecting to a local modem (HSSI and SSI)
 372 or NI (T1 and T3) configured to loop back.
 373 Cards can generate signals to loopback remote equipment
 374 so that complete circuits can be tested; see
 375 .Xr lmcconfig 8
 376 for details.
 377 .\"
 378 .Ss Testing with a Modem
 379 .\"
 380 Testing with a modem requires two cards of different types.
 381 .Bl -tag -width ".Sy T3/HSSI"
 382 .It Sy T3/HSSI
 383 If you have a T3 modem with an HSSI interface
 384 (made by Digital Link, Larscom, Kentrox etc.\&)
 385 then use an HSSI card in one machine and a T3 card in the other machine.
 386 The T3 coax cables must use the null modem configuration (see below).
 387 .It Sy T1/V.35
 388 If you have a T1 (or E1) modem with a V.35, X.21 or EIA530 interface,
 389 then use an SSI card in one machine and a T1 card in the other machine.
 390 Use a T1 null modem cable (see below).
 391 .El
 392 .\"
 393 .Ss Testing with a Null Modem Cable
 394 .\"
 395 Testing with a null modem cable requires two cards of the same type.
 396 .Bl -tag -width ".Sy T1/E1"
 397 .It Sy HSSI
 398 Three-meter HSSI null-modem cables can be ordered from SBE.
 399 In a pinch, a 50-pin SCSI-II cable up to a few meters will
 400 work as a straight HSSI cable (not a null modem cable).
 401 Longer cables should be purpose-built HSSI cables because
 402 the cable impedance is different.
 403 Transmit clock is normally supplied by the external modem.
 404 When an HSSI card is connected by a null modem cable, the PCI bus
 405 clock can be used as the transmit clock, typically 33 MHz.
 406 When testing an HSSI card with a null modem cable, configure it
 407 with
 408 .Xr lmcconfig 8 :
 409 .Pp
 410 .Dl "lmcconfig lmc0 -a 2
 411 .Pp
 412 .Dq Fl a Li 2
 413 selects the PCI bus clock as the transmit clock.
 414 .It Sy T3
 415 T3 null modem cables are just 75-ohm coax cables with BNC connectors.
 416 TX OUT on one card should be connected to RX IN on the other card.
 417 In a pinch, 50-ohm thin Ethernet cables
 418 .Em usually
 419 work up to a few meters, but they will
 420 .Em not
 421 work for longer runs \[em] 75-ohm coax is
 422 .Em required .
 423 .It Sy SSI
 424 Three-meter SSI null modem cables can be ordered from SBE.
 425 An SSI null modem cable reports a cable type of V.36/EIA449.
 426 Transmit clock is normally supplied by the external modem.
 427 When an SSI card is connected by a null modem cable,
 428 an on-board clock synthesizer is used.
 429 When testing an SSI card with a null modem cable, configure it
 430 with
 431 .Xr lmcconfig 8 :
 432 .Pp
 433 .Dl "lmcconfig lmc0 -E -f 10000000"
 434 .Pp
 435 .Fl E
 436 puts the card in DCE mode to source a transmit clock.
 437 .Dq Fl f Li 10000000
 438 sets the internal clock source to 10 Mb/s.
 439 .It Sy T1/E1
 440 A T1 null modem cable has two twisted pairs that connect
 441 pins 1 and 2 on one plug to pins 4 and 5 on the other plug.
 442 Looking into the cable entry hole of a plug,
 443 with the locking tab oriented down,
 444 pin 1 is on the left.
 445 A twisted pair Ethernet cable makes an excellent straight T1 cable.
 446 Alas, Ethernet cross-over cables do not work as T1 null modem cables.
 447 .El
 448 .\"
 449 .Sh OPERATION NOTES
 450 .\"
 451 .Ss Packet Lengths
 452 Maximum transmit and receive packet length is unlimited.
 453 Minimum transmit and receive packet length is one byte.
 454 .Pp
 455 Cleaning up after one packet and setting up for the next
 456 packet involves making several DMA references.
 457 This can take longer than the duration of a short packet,
 458 causing the adapter to fall behind.
 459 For typical PCI bus traffic levels and memory system latencies,
 460 back-to-back packets longer than about 20 bytes will always
 461 work (53 byte cells work), but a burst of several hundred
 462 back-to-back packets shorter than 20 bytes will cause packets
 463 to be dropped.
 464 This usually is not a problem since an IPv4 packet header is
 465 at least 20 bytes long.
 466 .Pp
 467 This device driver imposes no constraints on packet size.
 468 Most operating systems set the default Maximum Transmission
 469 Unit (MTU) to 1500 bytes; the legal range is usually (72..65535).
 470 This can be changed with
 471 .Pp
 472 .Dl "ifconfig lmc0 mtu 2000"
 473 .Pp
 474 SPPP enforces an MTU of (128..far-end-MRU) for PPP
 475 and 1500 bytes for Cisco-HDLC.
 476 RAWIP sets the default MTU to 4032 bytes,
 477 but it can be changed to anything.
 478 .\"
 479 .Ss BPF - Berkeley Packet Filter
 480 .\"
 481 This driver has hooks for
 482 .Xr bpf 4 ,
 483 the Berkeley Packet Filter.
 484 The line protocol header length reported to BPF is four bytes
 485 for SPPP and P2P line protocols and zero bytes for RawIP.
 486 .Pp
 487 To include BPF support into your kernel,
 488 add the following line to
 489 .Pa conf/YOURKERNEL :
 490 .Pp
 491 .Dl "device bpf"
 492 .Pp
 493 To test the BPF kernel interface,
 494 bring up a link between two machines, then run
 495 .Xr ping 8
 496 and
 497 .Xr tcpdump 1 :
 498 .Pp
 499 .Dl "ping 10.0.0.1"
 500 .Pp
 501 and in a different window:
 502 .Pp
 503 .Dl "tcpdump -i lmc0"
 504 .Pp
 505 The output from
 506 .Xr tcpdump 1
 507 should look like this:
 508 .Bd -literal -offset indent
 509 03:54:35.979965 10.0.0.2 > 10.0.0.1: icmp: echo request
 510 03:54:35.981423 10.0.0.1 > 10.0.0.2: icmp: echo reply
 511 .Ed
 512 .Pp
 513 Line protocol control packets will appear among the
 514 .Xr ping 8
 515 packets occasionally.
 516 .\"
 517 .Ss Device Polling
 518 .\"
 519 A T3 receiver can generate over 100K interrupts per second,
 520 this can cause a system to
 521 .Dq live-lock :
 522 spend all of its
 523 time servicing interrupts.
 524 .Fx
 525 has a polling mechanism to prevent live-lock.
 526 .Pp
 527 .Fx Ns 's
 528 mechanism permanently disables interrupts from the card
 529 and instead the card's interrupt service routine is called each
 530 time the kernel is entered (syscall, timer interrupt, etc.\&) and
 531 from the kernel idle loop; this adds some latency.
 532 The driver is permitted to process a limited number of packets.
 533 The percentage of the CPU that can be consumed this way is settable.
 534 .Pp
 535 See the
 536 .Xr polling 4
 537 manpage for details on how to enable the polling mode.
 538 .\"
 539 .Ss SNMP: Simple Network Management Protocol
 540 .\"
 541 This driver is aware of what is required to be a Network Interface
 542 Object managed by an Agent of the Simple Network Management Protocol.
 543 The driver exports SNMP-formatted configuration and status
 544 information sufficient for an SNMP Agent to create MIBs for:
 545 .Pp
 546 .Bl -item -offset indent -compact
 547 .It
 548 .%T "RFC-2233: Interfaces group" ,
 549 .It
 550 .%T "RFC-2496: DS3 interfaces" ,
 551 .It
 552 .%T "RFC-2495: DS1/E1 interfaces" ,
 553 .It
 554 .%T "RFC-1659: RS232-like interfaces" .
 555 .El
 556 .Pp
 557 An SNMP Agent is a user program, not a kernel function.
 558 Agents can retrieve configuration and status information
 559 by using
 560 Netgraph control messages or
 561 .Xr ioctl 2
 562 system calls.
 563 User programs should poll
 564 .Va sc->cfg.ticks
 565 which increments once per second after the SNMP state has been updated.
 566 .\"
 567 .Ss HSSI and SSI LEDs
 568 .\"
 569 The card should be operational if all three green LEDs are on
 570 (the upper-left one should be blinking) and the red LED is off.
 571 All four LEDs turn on at power-on and module unload.
 572 .Pp
 573 .Bl -column -compact -offset indent "YELLOW" "upper-right" "Software"
 574 .It "RED"   Ta "upper-right" Ta "No Transmit clock"
 575 .It "GREEN" Ta "upper-left"  Ta "Device driver is alive if blinking"
 576 .It "GREEN" Ta "lower-right" Ta "Modem signals are good"
 577 .It "GREEN" Ta "lower-left"  Ta "Cable is plugged in (SSI only)"
 578 .El
 579 .\"
 580 .Ss T1E1 and T3 LEDs
 581 .\"
 582 The card should be operational if the upper-left green LED is blinking
 583 and all other LEDs are off.
 584 For the T3 card, if other LEDs are on or
 585 blinking, try swapping the coax cables!
 586 All four LEDs turn on at power-on and module unload.
 587 .Pp
 588 .Bl -column -compact -offset indent "YELLOW" "upper-right" "Received"
 589 .It "RED"    Ta "upper-right" Ta "Received signal is wrong"
 590 .It "GREEN"  Ta "upper-left"  Ta "Device driver is alive if blinking"
 591 .It "BLUE"   Ta "lower-right" Ta "Alarm Information Signal (AIS)"
 592 .It "YELLOW" Ta "lower-left"  Ta "Remote Alarm Indication (RAI)"
 593 .El \" YELLOW
 594 .Pp
 595 .Bl -column -compact "The yellow" "LED"
 596 .It "The green"  Ta "LED blinks if the device driver is alive."
 597 .It "The red"    Ta "LED blinks if an outward loopback is active."
 598 .It "The blue"   Ta "LED blinks if sending AIS, on solid if receiving AIS."
 599 .It "The yellow" Ta "LED blinks if sending RAI, on solid if receiving RAI."
 600 .El \" LED
 601 .\"
 602 .Ss E1 Framing
 603 .\"
 604 Phone companies usually insist that customers put a
 605 .Em Frame Alignment Signal
 606 (FAS) in time slot 0.
 607 A Cyclic Redundancy Checksum (CRC) can also ride in time slot 0.
 608 .Em Channel Associated Signalling
 609 (CAS) uses Time Slot 16.
 610 In telco-speak
 611 .Em signalling
 612 is on/off hook, ringing, busy, etc.
 613 Signalling is not needed here and consumes 64 Kb/s.
 614 Only use E1-CAS formats if the other end insists on it!
 615 Use E1-FAS+CRC framing format on a public circuit.
 616 Depending on the equipment installed in a private circuit,
 617 it may be possible to use all 32 time slots for data (E1-NONE).
 618 .\"
 619 .Ss T3 Framing
 620 .\"
 621 M13 is a technique for multiplexing 28 T1s into a T3.
 622 Muxes use the C-bits for speed-matching the tributaries.
 623 Muxing is not needed here and usurps the FEBE and FEAC bits.
 624 Only use T3-M13 format if the other end insists on it!
 625 Use T3-CParity framing format if possible.
 626 Loop Timing, Fractional T3, and HDLC packets in
 627 the Facility Data Link are
 628 .Em not
 629 supported.
 630 .\"
 631 .Ss T1 & T3 Frame Overhead Functions
 632 .\"
 633 .Bl -item -compact
 634 .It
 635 Performance Report Messages (PRMs) are enabled in T1-ESF.
 636 .It
 637 Bit Oriented Protocol (BOP) messages are enabled in T1-ESF.
 638 .It
 639 In-band loopback control (framed or not) is enabled in T1-SF.
 640 .It
 641 Far End Alarm and Control (FEAC) msgs are enabled in T3-CPar.
 642 .It
 643 Far End Block Error (FEBE) reports are enabled in T3-CPar.
 644 .It
 645 Remote Alarm Indication (RAI) is enabled in T3-Any.
 646 .It
 647 Loopbacks initiated remotely time out after 300 seconds.
 648 .El
 649 .\"
 650 .Ss T1/E1 'Fractional' 64 kb/s Time Slots
 651 .\"
 652 T1 uses time slots 24..1; E1 uses time slots 31..0.
 653 E1 uses TS0 for FAS overhead and TS16 for CAS overhead.
 654 E1-NONE has
 655 .Em no
 656 overhead, so all 32 TSs are available for data.
 657 Enable/disable time slots by setting 32 1s/0s in a config param.
 658 Enabling an E1 overhead time slot,
 659 or enabling TS0 or TS25-TS31 for T1,
 660 is ignored by the driver, which knows better.
 661 The default TS param, 0xFFFFFFFF, enables the maximum number
 662 of time slots for whatever frame format is selected.
 663 56 Kb/s time slots are
 664 .Em not
 665 supported.
 666 .\"
 667 .Ss T1 Raw Mode
 668 .\"
 669 Special gate array microcode exists for the T1/E1 card.
 670 Each T1 frame of 24 bytes is treated as a packet.
 671 A raw T1 byte stream can be delivered to main memory
 672 and transmitted from main memory.
 673 The T1 card adds or deletes framing bits but does not
 674 touch the data.
 675 ATM cells can be transmitted and received this way, with
 676 the software doing all the work.
 677 But that is not hard; after all it is only 1.5 Mb/s second!
 678 .\"
 679 .Ss T3 Circuit Emulation Mode
 680 .\"
 681 Special gate array microcode exists for the T3 card.
 682 Each T3 frame of 595 bytes is treated as a packet.
 683 A raw T3 signal can be
 684 .Em packetized ,
 685 transported through a
 686 packet network (using some protocol) and then
 687 .Em reconstituted
 688 as a T3 signal at the far end.
 689 The output transmitter's
 690 bit rate can be controlled from software so that it can be
 691 .Em frequency locked
 692 to the distant input signal.
 693 .\"
 694 .Ss HSSI and SSI Transmit Clocks
 695 .\"
 696 Synchronous interfaces use two transmit clocks to eliminate
 697 .Em skew
 698 caused by speed-of-light delays in the modem cable.
 699 DCEs (modems) drive ST, Send Timing, the first transmit clock.
 700 DTEs (hosts) receive ST and use it to clock transmit data, TD,
 701 onto the modem cable.
 702 DTEs also drive a copy of ST back towards the DCE and call it TT,
 703 Transmit Timing, the second transmit clock.
 704 DCEs receive TT and TD and use TT to clock TD into a flip flop.
 705 TT experiences the same delay as (and has no
 706 .Em skew
 707 relative to) TD.
 708 Thus, cable length does not affect data/clock timing.
 709 .\"
 710 .Sh SEE ALSO
 711 .\"
 712 .Xr tcpdump 1 ,
 713 .Xr ioctl 2 ,
 714 .Xr bpf 4 ,
 715 .Xr kld 4 ,
 716 .Xr netgraph 4 ,
 717 .Xr polling 4 ,
 718 .Xr sppp 4 ,
 719 .Xr loader.conf 5 ,
 720 .Xr ifconfig 8 ,
 721 .Xr lmcconfig 8 ,
 722 .Xr mpd 8 Pq Pa ports/net/mpd ,
 723 .Xr ngctl 8 ,
 724 .Xr ping 8 ,
 725 .Xr ifnet 9
 726 .\"
 727 .Sh HISTORY
 728 .\"
 729 .An Ron Crane
 730 had the idea to use a Fast Ethernet chip as a PCI interface
 731 and add an Ethernet-to-HDLC gate array to make a WAN card.
 732 .An David Boggs
 733 designed the Ethernet-to-HDLC gate array and PC cards.
 734 We did this at our company, LAN Media Corporation
 735 .Tn (LMC) .
 736 .Tn SBE
 737 Corp.\& acquired
 738 .Tn LMC
 739 and continues to make the cards.
 740 .Pp
 741 Since the cards use Tulip Ethernet chips, we started with
 742 .An Matt Thomas Ns '
 743 ubiquitous
 744 .Xr de 4
 745 driver.
 746 .An Michael Graff
 747 stripped out the Ethernet stuff and added HSSI stuff.
 748 .An Basil Gunn
 749 ported it to
 750 .Tn Solaris
 751 (lost) and
 752 .Tn Rob Braun
 753 ported it to
 754 .Tn Linux .
 755 .An Andrew Stanley-Jones
 756 added support
 757 for three more cards and wrote the first version of
 758 .Xr lmcconfig 8 .
 759 .An David Boggs
 760 rewrote everything and now feels responsible for it.
 761 .\"
 762 .Sh AUTHORS
 763 .\"
 764 .An "David Boggs" Aq boggs@boggs.palo-alto.ca.us