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 .\" I forget these things:
  47 .\" groff -Tascii -mdoc lmc.4 > lmc.0
  48 .\" groff -Tps    -mdoc lmc.4 > lmc.ps
  49 .\" groff -Thtml  -mdoc lmc.4 > lmc.html (buggy)
  50 .\"
  51 .Dd June 2005
  52 .Dt LMC 4
  53 .Os \" sets \*(oS or \*[operating-system]
  54 .
  55 .\" substring works differently before minor version 19
  56 .ie (\n(.y < 19) .nr ssfix 1
  57 .el .nr ssfix 0
  58 .
  59 .ie "\*[operating-system]"" .ds aa \*(oS
  60 .el .ds aa \*[operating-system]
  61 .substring aa (0+\n[ssfix] (6+\n[ssfix])
  62 .ie "\*(aa"FreeBSD" .nr fbsd 1
  63 .el .nr fbsd 0
  64 .
  65 .ie "\*[operating-system]"" .ds aa \*(oS
  66 .el .ds aa \*[operating-system]
  67 .substring aa (0+\n[ssfix]) (5+\n[ssfix])
  68 .ie "\*(aa"NetBSD" .nr nbsd 1
  69 .el .nr nbsd 0
  70 .
  71 .ie "\*[operating-system]"" .ds aa \*(oS
  72 .el .ds aa \*[operating-system]
  73 .substring aa (0+\n[ssfix]) (7+\n[ssfix])
  74 .ie "\*(aa"OpenBSD" .nr obsd 1
  75 .el .nr obsd 0
  76 .
  77 .ie "\*[operating-system]"" .ds aa \*(oS
  78 .el .ds aa \*[operating-system]
  79 .substring aa (0+\n[ssfix]) (4+\n[ssfix])
  80 .ie "\*(aa"BSDI" .nr bsdi 1
  81 .el .nr bsdi 0
  82 .
  83 .ie "\*[operating-system]"" .ds aa \*(oS
  84 .el .ds aa \*[operating-system]
  85 .ie "\*(aa"BSD" .nr linux 1
  86 .el .nr linux 0
  87 .
  88 .\" if no operating system matched, select all OSs
  89 .if !(\n[fbsd] : \n[nbsd] : \n[obsd] : \n[bsdi] : \n[linux]) \{\
  90 .nr fbsd  1
  91 .nr nbsd  1
  92 .nr obsd  1
  93 .nr bsdi  1
  94 .nr linux 1 \}
  95 .
  96 .Sp
  97 .Sh NAME
  98 .Sp
  99 .Nm lmc
 100 .Nd device driver for
 101 .Tn LMC
 102 (now
 103 .Tn SBE )
 104 wide-area network interface cards.
 105 .Sp
 106 .Sh SYNOPSIS
 107 .Sp
 108 .if \n[fbsd] \{\
 109 .Cd "device lmc" \}
 110 .if (\n[nbsd] : \n[obsd] : \n[bsdi]) \{\
 111 .Cd "lmc* at pci?" \}
 112 .if \n[linux] \{\
 113 .Cd "CONFIG_LANMEDIA=m" \}
 114 .Sp
 115 .Sh DESCRIPTION
 116 .Sp
 117 This is an open-source Unix device driver for PCI-bus WAN interface cards.
 118 It sends and receives packets in HDLC frames over synchronous circuits.
 119 A generic PC plus Unix plus some
 120 .Tn "LMC" /
 121 .Tn "SBE"
 122 cards makes an
 123 .Em open
 124 router.
 125 This driver works with FreeBSD, NetBSD, OpenBSD, BSD/OS and Linux OSs.
 126 It has been tested on i386 (SMP 32-bit little-end), Sparc (64-bit big-end),
 127 and Alpha (64-bit little-end) architectures.
 128 .Pp
 129 The
 130 .Nm
 131 driver works with the following cards:
 132 .Bd -literal -offset 2m
 133 SBE wanADAPT-HSSI       High Speed Serial Interface,
 134     (LMC5200)           EIA612/613, 50-pin connector,
 135                         0 to 52 Mb/s, DTE only.
 136 SBE wanADAPT-T3         T3: two 75-ohm BNC connectors,
 137     (LMC5245)           C-Parity or M13 Framing,
 138                         44.736 Mb/s, up to 950 ft.
 139 SBE wanADAPT-SSI        Synchronous Serial Interface,
 140     (LMC1000)           V.35, X.21, EIA449, EIA530(A), EIA232,
 141                         0 to 10 Mb/s, DTE or DCE.
 142 SBE wanADAPT-T1E1       T1 or E1: RJ45 conn, 100 or 120 ohms,
 143     (LMC1200)           T1-ESF-B8ZS, T1-SF-AMI, E1-(many)-HDB3,
 144                         1.544 Mb/s or 2.048 Mb/s, up to 6 Kft.
 145 .Ed
 146 .Pp
 147 Cards contain a high-performance
 148 .Sy "PCI"
 149 interface, an
 150 .Sy "HDLC"
 151 function and
 152 either integrated
 153 .Sy "modems"
 154 (T1, T3) or
 155 .Sy "modem"
 156 interfaces (HSSI and SSI).
 157 .Bl -tag -width "Modem"
 158 .It Sy "PCI"
 159 The PCI interface is a DEC 21140A "Tulip" Fast Ethernet chip.
 160 This chip has an efficient PCI implementation with scatter/gather DMA,
 161 and can run at 100 Mb/s full duplex (twice as fast as needed here).
 162 .It Sy "HDLC"
 163 The HDLC functions (ISO-3309: flags, bit-stuffing, CRC) are implemented
 164 in a Field Programmable Gate Array (FPGA) which talks to the Ethernet
 165 chip through a Media Independent Interface (MII).
 166 The hardware in the FPGA translates between Ethernet packets and
 167 HDLC frames on-the-fly; think it as a WAN PHY chip for Ethernet.
 168 .It Sy "Modem"
 169 The modem chips are the main differences between cards.
 170 HSSI cards use ECL10K chips to implement the EIA-612/613 interface.
 171 T3 cards use a TranSwitch TXC-03401 framer chip.
 172 SSI cards use Linear Technology LTC1343 modem interface chips.
 173 T1 cards use a BrookTree/Conexant/Mindspeed Bt8370 framer
 174 and line interface chip.
 175 .El
 176 .Pp
 177 Line protocols exist above device drivers and below internet protocols.
 178 They typically encapsulate packets in HDLC frames and deal with
 179 higher-level issues like protocol multiplexing and security.
 180 This driver is compatible with several line protocol packages:
 181 .Bl -tag -width "Generic HDLC"
 182 .if (\n[fbsd] : \n[nbsd]) \{\
 183 .It Sy "Netgraph"
 184 .Xr Netgraph 4
 185 implements many basic packet-handling functions as kernel loadable modules.
 186 They can be interconnected in a graph to implement many protocols.
 187 Configuration is done from userland without rebuilding the kernel.
 188 Packets are sent and received through this interface if the driver's
 189 .Em rawdata
 190 hook is connected, otherwise the ifnet interface (SPPP and RawIP) is used.
 191 ASCII configuration control messages are
 192 .Em not
 193 currently supported. \}
 194 .if (\n[fbsd]) \{\
 195 .It Sy "SPPP"
 196 .Xr sppp 4
 197 implements Synchronous-PPP, Frame-Relay and Cisco-HDLC in the kernel. \}
 198 .if (\n[nbsd] : \n[obsd]) \{\
 199 .It Sy "SPPP"
 200 .Xr sppp 4
 201 implements Synchronous-PPP and Cisco-HDLC in the kernel. \}
 202 .if \n[bsdi] \{\
 203 .It Sy "P2P"
 204 .Xr p2p 4
 205 implements Synchronous-PPP, Frame-Relay and Cisco-HDLC in the kernel. \}
 206 .if \n[linux] \{\
 207 .It Sy "Generic HDLC"
 208 implements Synchronous-PPP, Frame-Relay, Cisco-HDLC,
 209 Ether-in-HDLC, and IP-in-HDLC (aka RAWIP) in the kernel. \}
 210 .It Sy "RawIP"
 211 This null line protocol, built into the driver, sends and receives
 212 raw IPv4 and IPv6 packets in HDLC frames (aka IP-in-HDLC) with
 213 no extra bytes of overhead and no state at the end points.
 214 .El
 215 .Sp
 216 .Sh EXAMPLES
 217 .Sp
 218 .Ss ifconfig and lmcconfig
 219 .Sp
 220 The program
 221 .Xr lmcconfig 8
 222 manipulates interface parameters beyond the scope of
 223 .Xr ifconfig 8 .
 224 In normal operation only a few arguments are needed:
 225 .Bl -inset -offset 4n -compact
 226 .It Sy "-X\0\0"
 227 selects the external
 228 .if (\n[fbsd] : \n[nbsd] : \n[obsd]) SPPP
 229 .if \n[bsdi] P2P
 230 .if \n[linus] Generic-HDLC
 231 line protocol package.
 232 .It Sy "-x\0\0"
 233 selects the built-in RawIP line protocol package.
 234 .if (\n[fbsd] : \n[nbsd] : \n[obsd]) \{\
 235 .It Sy "-Z\0\0"
 236 selects PPP line protocol.
 237 .It Sy "-z\0\0"
 238 selects Cisco-HDLC line protocol.
 239 .It Sy "-F\0\0"
 240 selects Frame-Relay line protocol.\}
 241 .El
 242 .Pp
 243 .Ic "lmcconfig lmc0"
 244 .br
 245 displays interface configuration and status.
 246 .if \n[obsd] \{\
 247 .Pp
 248 Some configuration options are available through
 249 .Ic "ifconfig"
 250 as well as
 251 .Ic "lmcconfig" .
 252 .Pp
 253 .Ic "ifconfig lmc0 media e1 timeslot all
 254 .br
 255 selects E1 format using all 32 timeslots.
 256 .br
 257 .Ic "ifconfig -m lmc0"
 258 .br
 259 lists the available media options.
 260 .Pp
 261 .Ic "ifconfig lmc0 -mediaopt hdlc-crc16"
 262 .br
 263 deselects 16-bit CRCs, thereby selecting 32-bit CRCs.
 264 .br
 265 .Ic "ifconfig lmc0 mediaopt loopback"
 266 .br
 267 loops the interface transmitter to the receiver for testing.
 268 Some cards have up to six loopback paths through the hardware.
 269 .Ic "ifconfig"
 270 selects a simple loopback present in every card type, but
 271 .Ic "lmcconfig"
 272 can select them all.\}
 273 .Pp
 274 .Ic "lmcconfig lmc0 -D"
 275 .br
 276 enables debugging output from the device driver only.
 277 .br
 278 .Ic "ifconfig lmc0 debug"
 279 .br
 280 enables debugging output from the device driver and from
 281 the line protocol module above it.
 282 Debugging messages that appear on the console are also
 283 written to file
 284 .Ic "/var/log/messages" .
 285 .Em Caution :
 286 when things go very wrong, a torrent of debugging messages
 287 can swamp the console and bring a machine to its knees.
 288 .if (\n[fbsd] : \n[nbsd] : \n[obsd] : \n[bsdi]) \{\
 289 .Sp
 290 .Ss Patching Ethernet Drivers
 291 .Sp
 292 Since these cards use DEC 21140A Tulip Ethernet chips,
 293 be aware that an Ethernet driver may mistake one for an
 294 Ethernet card and try to drive it.
 295 For some versions of some operating systems, it is
 296 sufficient to list the
 297 .Nm
 298 cards before any Ethernet cards in the kernel configuration.
 299 Another solution is to unplug all 21140-based Ethernet cards
 300 and remove their device drivers from the kernel configuration.
 301 Finally, one can patch the Ethernet drivers to ignore
 302 .Nm
 303 cards.
 304 In any case, you must make a custom kernel.
 305 .if \n[fbsd] \{\
 306 Chapter 9 of the FreeBSD Handbook \}
 307 .if \n[nbsd] \{\
 308 Chapter 6 of the NetBSD Guide \}
 309 .if \n[obsd] \{\
 310 Chapter 5 of the OpenBSD FAQ \}
 311 .if \n[bsdi] \{\
 312 "Rebuilding the Kernel" in the BSD/OS Administrator's Guide \}
 313 explains how to configure and build custom kernels.
 314 .Pp
 315 To patch an Ethernet device driver:
 316 .if \n[fbsd] \{\
 317 .br
 318 add this line to
 319 .Ic "tulip_pci_probe()"
 320 in
 321 .Ic "sys/pci/if_de.c" : \}
 322 .if (\n[nbsd] : \n[obsd]) \{\
 323 .br
 324 add this line to
 325 .Ic "tulip_pci_probe()"
 326 in
 327 .Ic "/sys/dev/pci/if_de.c" :
 328 .br
 329 add this line to
 330 .Ic "dc_pci_match()   "
 331 in
 332 .Ic "/sys/dev/pci/if_dc_pci.c" :
 333 .if \n[nbsd] \{\
 334 .br
 335 add this line to
 336 .Ic "tlp_pci_match()  "
 337 in
 338 .Ic "/sys/dev/pci/if_tlp_pci.c" : \} \}
 339 .if \n[bsdi] \{\
 340 .br
 341 add this line to
 342 .Ic "tulip_pci_match()"
 343 in
 344 .Ic "/sys/i386/pci/if_de.c" : \}
 345 .br
 346 .if \n[fbsd] \{\
 347 .Ic "if (pci_get_subvendor(dev)==0x1376)"
 348 .br
 349 .Ic "   return ENXIO;"
 350 .br
 351 This driver should already be patched. \}
 352 .if (\n[nbsd] : \n[obsd]) \{\
 353 .Ic "if ((pci_conf_read(pa->pa_pc, pa->pa_tag, 0x2C) & 0xFFFF)==0x1376)"
 354 .br
 355 .Ic "   return 0;"
 356 .br \}
 357 .if \n[bsdi] \{\
 358 .Ic "if ((pci_inl(pa, 0x2C) & 0xFFFF)==0x1376)"
 359 .br
 360 .Ic "   return 0;"
 361 .br \}
 362 Make sure you patch the correct routine: many Ethernet drivers
 363 contain probe/match routines for several operating systems inside
 364 .Ic "#ifdefs" .
 365 .Pp
 366 .Ic "/var/log/messages"
 367 should contain a boot message like this:
 368 .br
 369 .if \n[fbsd] \{\
 370 .Ic "freebsd-4: pci0: <unknown card> (vendor=0x1011, dev=0x0009) at 18.0 irq 9"
 371 .br
 372 .Ic "freebsd-5: pci0: <network, ethernet> at device 18.0 (no driver attached)" \}
 373 .if \n[nbsd] \{\
 374 .Ic "vendor 0x1011 product 0x0009 (ethernet network, revision 0x22)
 375 .br
 376 .Ic "at pci0 dev 18 function 0 not configured" \}
 377 .if \n[obsd] \{\
 378 .Ic "DEC 21140 rev 0x22 at pci0 dev 18 function 0 not configured" \}
 379 .if \n[bsdi] \{\
 380 .Ic "lmc0 at pci0 iobase 0xe880 irq 10 maddr 0xfebeff00-0xfebeff7f" \}
 381 .if (\n[nbsd] : \n[obsd] : \n[bsdi]) \{\
 382 .Pp
 383 If the boot message looks like this:
 384 .br
 385 .if \n[obsd] \{\
 386 .Ic "de1 at pci0 dev 18 function 0 DEC 21140 rev 0x22:"
 387 .br
 388 .Ic "de1: can't read ENET ROM (why=-4) (76130600000 ..."
 389 .br
 390 .Ic "de1: 21140A [10-100Mb/s] pass 2.2 address unknown"
 391 .br \}
 392 .if \n[nbsd] \{\
 393 .Ic "tlp0 at pci0 dev 18 function 0: DECchip 21140A Ethernet, pass 2.2"
 394 .br
 395 .Ic "tlp0: sorry, unable to handle your board"
 396 .br \}
 397 .if \n[bsdi] \{\
 398 .Ic "stray interrupt on irq 9"
 399 .br \}
 400 then the Ethernet driver needs patching. \} \}
 401 .if \n[fbsd] \{\
 402 .Sp
 403 .Ss FreeBSD Configuration
 404 .Sp
 405 Put the source files in
 406 .Ic "/sys/dev/lmc" .
 407 You may need to create the directory.
 408 .Pp
 409 Add the following line to
 410 .Ic "/sys/conf/files" :
 411 .br
 412 .Ic "dev/lmc/if_lmc.c   optional        lmc pci"
 413 .br
 414 Put it near other
 415 .Ic "dev/l*"
 416 entries.
 417 .br
 418 For FreeBSD-5, change
 419 .Ic optional
 420 to
 421 .Ic count
 422 in the entry for sppp:
 423 .br
 424 .Ic "net/if_spppsubr.c  count   sppp"
 425 .Pp
 426 To wire this driver into your kernel:
 427 Add the following line to
 428 .Ic "/sys/ARCH/conf/YOURKERNEL" :
 429 .br
 430 .Ic "device     lmc     # LMC/SBE WAN cards"
 431 .br
 432 Put this line near lines for other network devices.
 433 To load the driver into a running kernel, see KLD below.
 434 .Pp
 435 To wire a line protocol into your kernel, add:
 436 .br
 437 .Ic "options    netgraph        # wired into the kernel"
 438 .br
 439 .Ic "pseudo-device      sppp    # FreeBSD-4"
 440 .br
 441 .Ic "device             sppp    # FreeBSD-5"
 442 .br
 443 It is not necessary to wire line protocols into your kernel.
 444 This driver and line protocols can be loaded later with kldload(8).
 445 The driver can send and receive raw IP packets even if neither
 446 SPPP nor Netgraph are configured into the kernel.
 447 Netgraph and SPPP can both be enabled; netgraph will be used if the
 448 .Em "rawdata"
 449 hook is connected. \}
 450 .if \n[fbsd] \{\
 451 .Sp
 452 .Ss FreeBSD Kernel Loadable Modules ("KLD" mechanism)
 453 .Sp
 454 To make this driver into a standard kernel loadable module:
 455 .br
 456 Make a directory named
 457 .Ic "/sys/modules/lmc" .
 458 .br
 459 Copy
 460 .Ic "/sys/dev/lmc/Makefile"
 461 to
 462 .Ic "/sys/modules/lmc/Makefile" .
 463 .br
 464 Add
 465 .Ic "lmc"
 466 to
 467 .Ic "/sys/modules/Makefile"
 468 for your machine architecture.
 469 .Pp
 470 While standing in
 471 .Ic /sys/ARCH/compile/YOURKERNEL:
 472 .br
 473 .Ic "make modules-depend"
 474 generates all module dependencies.
 475 .br
 476 .Ic "make modules"
 477 creates all modules.
 478 .br
 479 .Ic "make modules-install"
 480 installs all modules.
 481 .Pp
 482 To make this driver into a kernel loadable module "by hand":
 483 .br
 484 While standing in
 485 .Ic "/sys/dev/lmc" :
 486 .br
 487 .Ic "make depend"
 488 generates lmc module dependencies.
 489 .br
 490 .Ic "make all"
 491 creates the lmc module.
 492 .br
 493 .Ic "make install"
 494 installs the lmc module.
 495 .br
 496 .Ic "make depend all install"
 497 does everything.
 498 .Pp
 499 While standing anywhere (as root):
 500 .br
 501 .Ic "kldload if_lmc"
 502 loads the driver and starts it.
 503 .br
 504 .Ic "kldunload if_lmc"
 505 stops the driver and unloads it.
 506 .br
 507 .Ic "kldstat"
 508 displays status of loaded modules.
 509 .Pp
 510 .Ic "securelevel"
 511 must be 0 to load modules; see
 512 .Xr init 8 .
 513 .Pp
 514 To load this module at boot time, add
 515 .br
 516 .Ic "if_lmc_load=""YES"""
 517 .br
 518 to
 519 .Ic "/boot/loader.conf"; see
 520 .Xr loader.conf 5 . \}
 521 .if \n[fbsd] \{\
 522 .Sp
 523 .Ss FreeBSD Operation
 524 .Sp
 525 Activate a PPP link using SPPP and Netgraph with:
 526 .br
 527 .Ic "ngctl mkpeer lmc0: sppp rawdata downstream"
 528 .br
 529 .Ic "ifconfig sppp0 10.0.0.1 10.0.0.2"
 530 .Pp
 531 Activate a PPP link using only SPPP with:
 532 .br
 533 .Ic "lmcconfig lmc0 -XYZ"
 534 .br
 535 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
 536 .Pp
 537 Activate a Cisco-HDLC link using SPPP and Netgraph with:
 538 .br
 539 .Ic "ngctl mkpeer lmc0: sppp rawdata downstream"
 540 .br
 541 .Ic "ifconfig sppp0 10.0.0.1 10.0.0.2 link2"
 542 .Pp
 543 Activate a Cisco-HDLC link using only SPPP with:
 544 .br
 545 .Ic "lmcconfig lmc0 -XYz"
 546 .br
 547 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
 548 .Pp
 549 Activate a Cisco-HDLC link using only Netgraph with:
 550 .br
 551 .Ic "ngctl mkpeer lmc0: cisco rawdata downstream"
 552 .br
 553 .Ic "ngctl mkpeer lmc0:rawdata iface inet inet"
 554 .br
 555 .Ic "ifconfig ng0 10.0.0.1 10.0.0.2"
 556 .Pp
 557 Activate a Frame-Relay DTE link using SPPP with:
 558 .br
 559 .Ic "lmcconfig lmc0 -XYF"
 560 .br
 561 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
 562 .br
 563 SPPP implements the ANSI T1.617 annex D LMI.
 564 .Pp
 565 Activate a Frame-Relay DTE link using Netgraph with:
 566 .br
 567 .Ic "ngctl mkpeer  lmc0: frame_relay rawdata downstream"
 568 .br
 569 .Ic "ngctl mkpeer  lmc0:rawdata lmi dlci0 auto0"
 570 .br
 571 .Ic "ngctl connect lmc0:rawdata dlci0 dlci1023 auto1023"
 572 .br
 573 .Ic "ngctl mkpeer  lmc0:rawdata rfc1490 dlci500 downstream"
 574 .br
 575 .Ic "ngctl mkpeer  lmc0:rawdata.dlci500 iface inet inet"
 576 .br
 577 .Ic "ifconfig ng0 10.0.0.1 10.0.0.2"
 578 .br
 579 This is
 580 .Em "ONE"
 581 possible Frame Relay configuration; there are many.
 582 .Pp
 583 Activate a RAWIP link using only the driver with:
 584 .br
 585 .Ic "lmcconfig lmc0 -x"
 586 .br
 587 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
 588 .Pp
 589 Activate a RAWIP link using Netgraph with:
 590 .br
 591 .Ic "ngctl mkpeer lmc0: iface rawdata inet"
 592 .br
 593 .Ic "ifconfig ng0 10.0.0.1 10.0.0.2"
 594 .br
 595 If the driver is kldunloaded and then kldloaded, reconnect hooks by:
 596 .br
 597 .Ic "ngctl connect lmc0: ng0: rawdata inet" \}
 598 .if (\n[nbsd] : \n[obsd]) \{\
 599 .Sp
 600 .if \n[nbsd] .Ss NetBSD Configuration
 601 .if \n[obsd] .Ss OpenBSD Configuration
 602 .Sp
 603 Put the source files in
 604 .Ic "/sys/dev/pci/" .
 605 .Pp
 606 Add the following lines to
 607 .Ic "/sys/dev/pci/files.pci" :
 608 .br
 609 .Ic "device   lmc: ifnet, sppp"
 610 .if \n[obsd] .Ic ", ifmedia"
 611 .br
 612 .Ic "attach   lmc at pci"
 613 .br
 614 .Ic "file     dev/pci/if_lmc.c   lmc"
 615 .br
 616 Put them near other
 617 .Ic "dev/pci/if_*.c"
 618 entries.
 619 .Pp
 620 In file
 621 .Ic "/sys/conf/files" ,
 622 append
 623 .Ic "needs-count"
 624 to the end of this line:
 625 .br
 626 .Ic "file   net/if_spppsubr.c   sppp   needs-count"
 627 .Pp
 628 To wire this driver into your kernel,
 629 add the following line to
 630 .Ic "/sys/arch/ARCH/conf/YOURKERNEL" :
 631 .br
 632 .Ic "lmc* at pci?   # LMC/SBE WAN cards"
 633 .br
 634 Put this line near lines for other network devices.
 635 To load the driver into a running kernel, see LKM below.
 636 .Pp
 637 To wire SPPP into your kernel:
 638 .br
 639 .Ic "pseudo-device sppp   1   # wired into the kernel"
 640 .br
 641 The driver can send and receive raw IP packets even if
 642 SPPP is not configured into the kernel. \}
 643 .if (\n[nbsd] : \n[obsd]) \{\
 644 .Sp
 645 .if \n[nbsd] .Ss NetBSD Loadable Kernel Modules ("LKM" mechanism)
 646 .if \n[obsd] .Ss OpenBSD Loadable Kernel Modules ("LKM" mechanism)
 647 .Sp
 648 Add the following line to
 649 .Ic "/sys/arch/ARCH/conf/YOURKERNEL" :
 650 .br
 651 .Ic "options   LKM   # loadable kernel modules"
 652 .Pp
 653 Install symbolic links from the kernel compilation directory
 654 to the source directory:
 655 .br
 656 .Ic "ln -s /sys/dev/pci/if_lmc.c"
 657 .br
 658 .Ic "ln -s /sys/dev/pci/if_lmc.h"
 659 .Pp
 660 While standing in
 661 .Ic "/sys/arch/ARCH/compile/YOURKENEL" :
 662 .br
 663 .Ic "make if_lmc.o"
 664 compiles the driver module.
 665 .br
 666 .Ic "modload if_lmc.o"
 667 loads the driver and starts it.
 668 .Pp
 669 while standing anywhere (as root):
 670 .br
 671 .Ic "modunload -n if_lmc.o"
 672 stops the driver and unloads it.
 673 .br
 674 .Ic "modstat"
 675 displays status of loaded modules.
 676 .Pp
 677 When the driver module is loaded, if you get a message like this:
 678 .br
 679 .Ic lmc1: bus_space_map failed; error 35
 680 .br
 681 then the Ethernet device driver needs patching.
 682 .Pp
 683 .Ic "securelevel"
 684 must be 0 to load modules; see
 685 .Xr init 8 .
 686 .br
 687 One way is to include in
 688 .Ic "/sys/arch/ARCH/conf/YOURKERNEL" :
 689 .br
 690 .Ic "options INSECURE   # disable kernel security levels"
 691 .if \n[obsd] \{\
 692 .Pp
 693 LKM only works for PCI bus 0 on an i386 machine. \} \}
 694 .Sp
 695 .if \n[nbsd] .Ss NetBSD Operation
 696 .if \n[obsd] .Ss OpenBSD Operation
 697 .Sp
 698 .if (\n[nbsd] : \n[obsd]) \{\
 699 Activate a PPP link using SPPP with:
 700 .br
 701 .Ic "lmcconfig lmc0 -XYZ"
 702 .br
 703 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
 704 .Pp
 705 Activate a Cisco-HDLC link using SPPP with:
 706 .br
 707 .Ic "lmcconfig lmc0 -XYz"
 708 .br
 709 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
 710 .Pp
 711 Activate a RAWIP link with:
 712 .br
 713 .Ic "lmcconfig lmc0 -x"
 714 .br
 715 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2" \}
 716 .if \n[bsdi] \{\
 717 .Sp
 718 .Ss BSD/OS Configuration
 719 .Sp
 720 Put the source files in
 721 .Ic "/sys/i386/pci/" .
 722 .Pp
 723 Add the following lines to
 724 .Ic "/sys/i386/conf/files.i386" :
 725 .br
 726 .Ic "device     lmc at pci: pcisubr, p2p"
 727 .br
 728 .Ic "file               i386/pci/if_lmc.c       lmc     device-driver"
 729 .br
 730 Put them near other
 731 .Ic "i386/pci/if_*.c entries" .
 732 .Pp
 733 Add the following lines to
 734 .Ic "/sys/i386/conf/YOURKERNEL" :
 735 .br
 736 .Ic "lmc*               at pci? # LMC/SBE WAN cards"
 737 .br
 738 Put the above line before any Ethernet devices.
 739 .br
 740 .Ic "options    PPP             # include PPP code"
 741 .br
 742 .Ic "options    FR              # include Frame-Relay code"
 743 .br
 744 .Ic "options    CISCO_HDLC      # include Cisco-HDLC code"
 745 .br \}
 746 .if \n[bsdi] \{\
 747 .Sp
 748 .Ss BSD/OS Operation
 749 .Sp
 750 To activate a PPP link, create file
 751 .Ic "/etc/ppp.sys"
 752 containing:
 753 .br
 754 .Ic "Plmc0:     :device=lmc0:\e"
 755 .br
 756 .Ic "           :local-addr=10.0.0.1:\e"
 757 .br
 758 .Ic "           :remote-addr=10.0.0.2:\e"
 759 .br
 760 .Ic "           :immediate:dialout:direct:\e"
 761 .br
 762 .Ic "           :-pfc:-acfc:-tcpc:"
 763 .br
 764 Then run
 765 .Xr ppp 8 :
 766 .Ic "ppp -bd Plmc0" .
 767 .br
 768 Add
 769 .Ic "-X debug-all"
 770 to watch protocol events happen.
 771 .Pp
 772 Activate a Cisco-HDLC link by setting LINKTYPE with ifconfig:
 773 .br
 774 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2 linktype chdlc"
 775 .Pp
 776 Activate a Fame-Relay link with:
 777 .br
 778 .Ic "ifconfig lmc0 linktype fr"
 779 .br
 780 By default the port is a DTE; add the next line to make it a DCE:
 781 .br
 782 .Ic "frconfig lmc0 type dce"
 783 .br
 784 .Ic "frconfig lmc0 lmi ansi"
 785 .br
 786 .Ic "frconfig lmc0 dlci 500 10.0.0.2"
 787 .br
 788 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
 789 .Pp
 790 Activate a RAWIP link with:
 791 .br
 792 .Ic "ifconfig lmc0 down -remove"
 793 .br
 794 .Ic "lmcconfig lmc0 -x"
 795 .br
 796 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.2"
 797 .br \}
 798 .if \n[linux] \{\
 799 .Sp
 800 .Ss Linux Configuration
 801 .Sp
 802 The source files are in
 803 .Ic "/usr/src/linux/drivers/net/wan/lmc/" .
 804 .Pp
 805 Configure the driver and line protocol into your kernel with
 806 .Ic make menuconfig ,
 807 navigating through the menus, select this device driver and the
 808 generic HDLC layer as loadable kernel modules or wired into the kernel:
 809 .br
 810 .Ic "Device Drivers --->"
 811 .br
 812 .Ic "Networking Support --->"
 813 .br
 814 .Ic "Wan interfaces --->"
 815 .br
 816 .Ic "<M> SBE Inc. LMC1000/1200/5200/5245 support"
 817 .br
 818 .Ic "<M> Generic HDLC layer"
 819 .br
 820 .Ic "<M>\|"
 821 configures code as a module and
 822 .Ic "<*>"
 823 wires it into the kernel.
 824 .Pp
 825 Selecting the Generic HDLC layer selects all available protocols.
 826 Raw, Cisco and Frame-Relay are in the generic-hdlc module;
 827 PPP is a separate module.
 828 .br
 829 .Ic "[*]  Raw HDLC support"
 830 .br
 831 .Ic "[*]  Raw HDLC Ethernet device support"
 832 .br
 833 .Ic "[*]  Cisco HDLC support"
 834 .br
 835 .Ic "[*]  Frame Relay support"
 836 .br
 837 .Ic "[*]  Synchronous Point-to-Point Protocol (PPP) support"
 838 .br
 839 .Ic "[*]\|"
 840 includes support for a protocol and
 841 .Ic "[\0]"
 842 excludes it.
 843 .Pp
 844 The driver can send and receive raw IP packets even if
 845 Generic-HDLC is not configured into the kernel.
 846 The device name will be
 847 .Ic "hdlc<n>"
 848 if the generic HDLC code is used, or
 849 .Ic "lmc<n>"
 850 otherwise. \}
 851 .if \n[linux] \{\
 852 .Sp
 853 .Ss Linux Loadable Kernel Modules
 854 .Sp
 855 If configured as above, the kernel will recognize an LMC/SBE card
 856 when it boots and load this driver and the Generic-HDLC code.
 857 Messages similar to the following will appear in /var/log/messages:
 858 .br
 859 .Ic "Cronyx Ltd, Synchronous PPP and CISCO HDLC (c) 1994"
 860 .br
 861 .Ic "Linux port (c) 1998 Building Number Three Ltd & Jan 'Yenya' Kasprzak."
 862 .br
 863 .Ic "HDLC support module revision 1.16"
 864 .br
 865 .Ic "hdlc0: <SBE/LMC T3 Card> io 0xe880/9 mem 0xfebeff00/25"
 866 .Ic "rom 0xfeb40000/14 irq 11 pci 0000:00:13.0"
 867 .br
 868 The driver registers itself under the name
 869 .Ic "hdlc<n>"
 870 rather than
 871 .Ic "lmc<n>"
 872 because the generic-HDLC code requires it.
 873 .Pp
 874 When the card and line protocol are configured these messages will appear:
 875 .br
 876 .Ic "hdlc0: PCI rev 2.2, MII rev 3.5,
 877 .Ic "IEEE addr 00:60:99:00:13:c4, TXC03401 rev B"
 878 .br
 879 .Ic "hdlc0: Driver rev 2004.6.17, Options IO_CSR LITTLE_END"
 880 .br
 881 .Ic "hdlc0: protocol up"
 882 .Pp
 883 While standing in /usr/src/linux/drivers/net/wan/lmc:
 884 .br
 885 .Ic "make -C /usr/src/linux SUBDIRS=/usr/src/linux/drivers/net/wan/lmc \e"
 886 .br
 887 .Ic "  modules modules-install "
 888 compiles and installs the driver.
 889 .br
 890 .Ic "modprobe if_lmc "
 891 loads the module into the kernel.
 892 .br
 893 .Ic "modprobe -r if_lmc "
 894 removes the module from the kernel.
 895 .br
 896 .Ic "lsmod "
 897 displays status of loaded modules.
 898 .br \}
 899 .if \n[linux] \{\
 900 .Sp
 901 .Ss Linux Operation
 902 .Sp
 903 The program
 904 .Ic "sethdlc"
 905 configures the generic-HDLC code.
 906 .br
 907 .Ic "sethdlc hdlc0 (or pvc0 for frame relay)"
 908 .br
 909 displays the current settings of a given device.
 910 Note that
 911 .Ic "sethdlc"
 912 must be run before
 913 .Ic "ifconfig" .
 914 .Ic "Sethdlc"
 915 and the generic-hdlc kernel code are documented in
 916 .Ic "/usr/src/linux/Documentation/networking/generic-hdlc.txt"
 917 and at
 918 .Ic "http://hq.pm.waw.pl/hdlc"
 919 .Pp
 920 Activate a PPP link with:
 921 .br
 922 .Ic "sethdlc hdlc0 ppp"
 923 .br
 924 .Ic "ifconfig hdlc0 10.0.0.1 pointopoint 10.0.0.2"
 925 .Pp
 926 Activate a Cisco-HDLC link with:
 927 .br
 928 .Ic "sethdlc hdlc0 cisco"
 929 .br
 930 .Ic "ifconfig hdlc0 10.0.0.1 pointopoint 10.0.0.2"
 931 .Pp
 932 Activate a Frame-Relay DTE link with:
 933 .br
 934 .Ic "sethdlc hdlc0 fr lmi ansi [dce]"
 935 .br
 936 .Ic "sethdlc hdlc0 create 500"
 937 .br
 938 .Ic "ifconfig hdlc0 up"
 939 .br
 940 .Ic "ifconfig pvc0 10.0.0.1 pointopoint 10.0.0.2"
 941 .br
 942 This is
 943 .Em "ONE"
 944 possible Frame Relay configuration; there are many.
 945 Adding "dce" after "ansi" configures it as a DCE (switch).
 946 .Pp
 947 Activate a RAWIP link with:
 948 .br
 949 .Ic "sethdlc hdlc0 hdlc"
 950 .br
 951 .Ic "ifconfig hdlc0 10.0.0.1 pointopoint 10.0.0.2"
 952 .br \}
 953 .Sp
 954 .Sh TESTING
 955 .Sp
 956 .Ss Testing with Loopbacks
 957 .Sp
 958 Testing with loopbacks requires only one card.
 959 Packets can be looped back at many points: in the PCI chip,
 960 in the modem chips, through a loopback plug, in the
 961 local external equipment, or at the far end of a circuit.
 962 .if \n[linux] \{\
 963 Testing with loopbacks does not work on Linux because the
 964 kernel detects that an outgoing packet is destined for "self"
 965 and loops it back without ever giving it to the hardware. \}
 966 .Pp
 967 Activate the card with ifconfig:
 968 .br
 969 .Ic "ifconfig lmc0 10.0.0.1 10.0.0.1"
 970 .Pp
 971 All cards can be looped through the PCI chip.
 972 Cards with internal modems can be looped through
 973 the modem framer and the modem line interface.
 974 Cards for external modems can be looped through
 975 the driver/receiver chips.
 976 See
 977 .Xr lmcconfig 8
 978 for details.
 979 .Pp
 980 Loopback plugs test everything on the card.
 981 .Bl -tag -width "T1/E1" -offset 2m -compact
 982 .It Sy "HSSI"
 983 Loopback plugs can be ordered from SBE (and others).
 984 Transmit clock is normally supplied by the external modem.
 985 When an HSSI card is operated with a loopback plug, the PCI bus
 986 clock must be used as the transmit clock, typically 33 MHz.
 987 When testing an HSSI card with a loopback plug,
 988 configure it with lmcconfig:
 989 .br
 990 .Ic "lmcconfig lmc0 -a 2
 991 .br
 992 .Ic "-a 2  "
 993 selects the PCI bus clock as the transmit clock.
 994 .It Sy "T3"
 995 Connect the two BNC jacks with a short coax cable.
 996 .It Sy "SSI"
 997 Loopback plugs can be ordered from SBE (only).
 998 Transmit clock is normally supplied by the external modem.
 999 When an SSI card is operated with a loopback plug,
1000 the on-board clock synthesizer must be used.
1001 When testing an SSI card with a loopback plug,
1002 configure it with lmcconfig:
1003 .br
1004 .Ic "lmcconfig lmc0 -E -f 10000000"
1005 .br
1006 .Ic "-E  "
1007 puts the card in DCE mode to source a transmit clock.
1008 .br
1009 .Ic "-f 10000000  "
1010 sets the internal clock source to 10 Mb/s.
1011 .br
1012 .It Sy "T1/E1"
1013 A loopback plug is a modular plug with two wires
1014 connecting pin 1 to pin 4 and pin 2 to pin 5.
1015 .El
1016 .Pp
1017 One can also test by connecting to a local modem (HSSI and SSI)
1018 or NI (T1 and T3) configured to loop back.
1019 Cards can generate signals to loopback remote equipment
1020 so that complete circuits can be tested; see
1021 .Xr lmcconfig 8
1022 for details.
1023 .Sp
1024 .Ss Testing with a Modem
1025 .Sp
1026 Testing with a modem requires two cards of different types.
1027 .Bl -tag -width "T3/HSSI"
1028 .It Sy "T3/HSSI"
1029 If you have a T3 modem with an HSSI interface
1030 (made by Digital Link, Larscom, Kentrox etc.)
1031 then use an HSSI card in one machine and a T3 card in the other machine.
1032 The T3 coax cables must use the null modem configuration (see below).
1033 .It Sy "T1/V.35"
1034 If you have a T1 (or E1) modem with a V.35, X.21 or EIA530 interface,
1035 then use an SSI card in one machine and a T1 card in the other machine.
1036 Use a T1 null modem cable (see below).
1037 .El
1038 .Sp
1039 .Ss Testing with a Null Modem Cable
1040 .Sp
1041 Testing with a null modem cable requires two cards of the same type.
1042 .Bl -tag -width "T1/E1"
1043 .It Sy "HSSI"
1044 Three-meter HSSI null-modem cables can be ordered from SBE.
1045 In a pinch, a 50-pin SCSI-II cable up to a few meters will
1046 work as a straight HSSI cable (not a null modem cable).
1047 Longer cables should be purpose-built HSSI cables because
1048 the cable impedance is different.
1049 Transmit clock is normally supplied by the external modem.
1050 When an HSSI card is connected by a null modem cable, the PCI bus
1051 clock can be used as the transmit clock, typically 33 MHz.
1052 When testing an HSSI card with a null modem cable, configure it
1053 with lmcconfig:
1054 .br
1055 .Ic "lmcconfig lmc0 -a 2
1056 .br
1057 .Ic "-a 2  "
1058 selects the PCI bus clock as the transmit clock.
1059 .It Sy "T3"
1060 T3 null modem cables are just 75-ohm coax cables with BNC connectors.
1061 TX OUT on one card should be connected to RX IN on the other card.
1062 In a pinch, 50-ohm thin Ethernet cables
1063 .Em usually
1064 work up to a few meters, but they will
1065 .Em not
1066 work for longer runs -- 75-ohm coax is
1067 .Em required .
1068 .It Sy "SSI"
1069 Three-meter SSI null modem cables can be ordered from SBE.
1070 An SSI null modem cable reports a cable type of V.36/EIA449.
1071 Transmit clock is normally supplied by the external modem.
1072 When an SSI card is connected by a null modem cable,
1073 an on-board clock synthesizer is used.
1074 When testing an SSI card with a null modem cable, configure it
1075 with lmcconfig:
1076 .br
1077 .Ic "lmcconfig lmc0 -E -f 10000000"
1078 .br
1079 .Ic "-E  "
1080 puts the card in DCE mode to source a transmit clock.
1081 .br
1082 .Ic "-f 10000000  "
1083 sets the internal clock source to 10 Mb/s.
1084 .br
1085 .Pp
1086 .It Sy "T1/E1"
1087 A T1 null modem cable has two twisted pairs that connect
1088 pins 1 and 2 on one plug to pins 4 and 5 on the other plug.
1089 Looking into the cable entry hole of a plug,
1090 with the locking tab oriented down,
1091 pin 1 is on the left.
1092 A twisted pair Ethernet cable makes an excellent straight T1 cable.
1093 Alas, Ethernet cross-over cables do not work as T1 null modem cables.
1094 .El
1095 .Sp
1096 .Sh OPERATION NOTES
1097 .Sp
1098 .Ss Packet Lengths
1099 Maximum transmit and receive packet length is unlimited.
1100 .br
1101 Minimum transmit and receive packet length is one byte.
1102 .Pp
1103 Cleaning up after one packet and setting up for the next
1104 packet involves making several DMA references.
1105 This can take longer than the duration of a short packet,
1106 causing the adapter to fall behind.
1107 For typical PCI bus traffic levels and memory system latencies,
1108 back-to-back packets longer than about 20 bytes will always
1109 work (53 byte cells work), but a burst of several hundred
1110 back-to-back packets shorter than 20 bytes will cause packets
1111 to be dropped.
1112 This usually isn't a problem since an IPv4 packet header is
1113 at least 20 bytes long.
1114 .Pp
1115 This device driver imposes no constraints on packet size.
1116 Most operating systems set the default Maximum Transmission
1117 Unit (MTU) to 1500 bytes; the legal range is usually (72..65535).
1118 This can be changed with
1119 .br
1120 .Ic "ifconfig lmc0 mtu 2000" .
1121 .br
1122 .if (\n[fbsd] : \n[nbsd] : \n[obsd]) \{\
1123 SPPP enforces an MTU of (128..far-end-MRU) for PPP
1124 and 1500 bytes for Cisco-HDLC. \}
1125 .if \n[bsdi] \{\
1126 P2P enforces an MTU of 1500 bytes for PPP and Cisco-HDLC
1127 and 4000 bytes for Frame Relay. \}
1128 .if \n[linux] \{\
1129 Generic-HDLC enforces an MTU range of (68..1500) bytes. \}
1130 RAWIP sets the default MTU to 4032 bytes,
1131 but it can be changed to anything.
1132 .if (\n[fbsd] : \n[nbsd] : \n[obsd]) \{\
1133 .Sp
1134 .Ss ALTQ - Alternate Output Queue Disciplines
1135 .Sp
1136 This driver has hooks for
1137 .Xr altq 4 ,
1138 the Alternate Queueing package.
1139 To see Altq in action, use your favorite traffic generation
1140 program to generate three flows sending down one T3 circuit.
1141 Without Altq, the speeds of the three connections will vary chaotically.
1142 Turn on Altq and two of the connections will run at 21 Mb/s and
1143 the third will run at 1.5 Mb/s.
1144 .Pp
1145 To include ALTQ in your kernel,
1146 add the following line to
1147 .Ic "conf/YOURKERNEL" :
1148 .br
1149 .Ic "options ALTQ        # ALTQ enabled"
1150 .br
1151 The example below requires the Hierarchical
1152 Fair Service Curve (HSFC) queue discipline:
1153 .br
1154 .Ic "options ALTQ_HFSC   # queue discipline"
1155 .Pp
1156 Enable
1157 .Xr altqd 8
1158 and create file
1159 .Ic "/etc/altq.conf"
1160 containing:
1161 .br
1162 .Bd -literal -offset 2m -compact
1163 .Ic "interface lmc0 bandwidth 44M hfsc"
1164 .br
1165 .Ic "class hfsc lmc0 a root pshare 49"
1166 .br
1167 .Ic "filter lmc0 a 10.0.0.2 12345 10.0.0.1 0 6"
1168 .br
1169 .Ic "filter lmc0 a 10.0.0.1 0 10.0.0.2 12345 6"
1170 .br
1171 .Ic "class hfsc lmc0 b root pshare 49"
1172 .br
1173 .Ic "filter lmc0 b 10.0.0.2 12346 10.0.0.1 0 6"
1174 .br
1175 .Ic "filter lmc0 b 10.0.0.1 0 10.0.0.2 12346 6"
1176 .br
1177 .Ic "class hfsc lmc0 c root pshare 2 default"
1178 .br
1179 .Ic "filter lmc0 c 10.0.0.2 12347 10.0.0.1 0 6"
1180 .br
1181 .Ic "filter lmc0 c 10.0.0.1 0 10.0.0.2 12347 6"
1182 .br
1183 .Ed \}
1184 .if (\n[fbsd] : \n[nbsd] : \n[obsd] : \n[bsdi]) \{\
1185 .Sp
1186 .Ss BPF - Berkeley Packet Filter
1187 .Sp
1188 This driver has hooks for
1189 .Xr bpf 4 ,
1190 the Berkeley Packet Filter.
1191 The line protocol header length reported to BPF is four bytes
1192 for SPPP and P2P line protocols and zero bytes for RawIP.
1193 .Pp
1194 To include BPF for ifnet in your kernel,
1195 add the following line to
1196 .Ic "conf/YOURKERNEL" :
1197 .br
1198 .Ic "pseudo-device      bpf     # FreeBSD-4, NetBSD, OpenBSD, BSD/OS"
1199 .br
1200 .Ic "device             bpf     # FreeBSD-5"
1201 .Pp
1202 To test the BPF kernel interface,
1203 bring up a link between two machines, then run
1204 .Xr ping 8
1205 and
1206 .Xr tcpdump 1 :
1207 .br
1208 .Ic "ping 10.0.0.1"
1209 .br
1210 and in a different window:
1211 .br
1212 .Ic "tcpdump -i lmc0"
1213 .br
1214 The output from tcpdump should look like this:
1215 .br
1216 .Ic "03:54:35.979965 10.0.0.2 > 10.0.0.1: icmp: echo request"
1217 .br
1218 .Ic "03:54:35.981423 10.0.0.1 > 10.0.0.2: icmp: echo reply"
1219 .br
1220 Line protocol control packets will appear among the
1221 ping packets occasionally. \}
1222 .if (\n[fbsd] : \n[linux]) \{\
1223 .Sp
1224 .Ss Device Polling
1225 .Sp
1226 A T3 receiver can generate over 100K interrupts per second,
1227 This can cause a system to "live-lock": spend all of its
1228 time servicing interrupts.
1229 Linux and FreeBSD have polling mechanisms to prevent live-lock.
1230 .if \n[linux] \{\
1231 .Pp
1232 Linux's mechanism disables a card's interrupt when it interrupts,
1233 calls the card's interrupt service routine with kernel interrupts
1234 enabled, and then reenables the card's interrupt.
1235 The driver is permitted to process a limited number of packets each
1236 time it is called by the kernel.
1237 Card interrupts are left disabled if more packets arrive than are
1238 permitted to be processed, which in extreme cases will result in
1239 packets being dropped in hardware at no cost to software. \}
1240 .if \n[fbsd] \{\
1241 .Pp
1242 FreeBSD's mechanism permanently disables interrupts from the card
1243 and instead the card's interrupt service routine is called each
1244 time the kernel is entered (syscall, timer interrupt, etc) and
1245 from the kernel idle loop; this adds some latency.
1246 The driver is permitted to process a limited number of packets.
1247 The percentage of the CPU that can be consumed this way is settable.
1248 .Pp
1249 FreeBSD's
1250 .Xr polling 4
1251 mechanism is enabled with:
1252 .br
1253 .Ic "sysctl kern.polling.enable=1"
1254 .br
1255 The kernel must be built with polling enabled:
1256 .br
1257 .Ic "options DEVICE_POLLING"
1258 .br
1259 .Ic "options HZ=1000" \} \}
1260 .Sp
1261 .Ss SNMP: Simple Network Management Protocol
1262 .Sp
1263 This driver is aware of what is required to be a Network Interface
1264 Object managed by an Agent of the Simple Network Management Protocol.
1265 The driver exports SNMP-formatted configuration and status
1266 information sufficient for an SNMP Agent to create MIBs for:
1267 .Bl -inset -compact -offset 2m
1268 .It RFC-2233: Interfaces group,
1269 .It RFC-2496: DS3 interfaces,
1270 .It RFC-2495: DS1/E1 interfaces,
1271 .It RFC-1659: RS232-like interfaces.
1272 .El
1273 .Pp
1274 An SNMP Agent is a user program, not a kernel function.
1275 Agents can retrieve configuration and status information
1276 by using
1277 .if \n[fbsd] \{\
1278 Netgraph control messages or \}
1279 .Xr ioctl 2
1280 system calls.
1281 User programs should poll
1282 .Ic sc->cfg.ticks
1283 which increments once per second after the SNMP state has been updated.
1284 .Sp
1285 .Ss HSSI and SSI LEDs
1286 .Sp
1287 The card should be operational if all three green LEDs are on
1288 (the upper-left one should be blinking) and the red LED is off.
1289 All four LEDs turn on at power-on and module-unload.
1290 .Bl -column -compact -offset 2m "YELLOW" "upper-right" "Software"
1291 .It "RED"   Ta "upper-right" Ta "No Transmit clock"
1292 .It "GREEN" Ta "upper-left"  Ta "Device driver is alive if blinking"
1293 .It "GREEN" Ta "lower-right" Ta "Modem signals are good"
1294 .It "GREEN" Ta "lower-left"  Ta "Cable is plugged in (SSI only)"
1295 .El
1296 .Sp
1297 .Ss T1E1 and T3 LEDs
1298 .Sp
1299 The card should be operational if the upper-left green LED is blinking
1300 and all other LEDs are off.  For the T3 card, if other LEDs are on or
1301 blinking, try swapping the coax cables!
1302 All four LEDs turn on at power-on and module-unload.
1303 .Bl -column -compact -offset 2m "YELLOW" "upper-right" "Received"
1304 .It "RED"    Ta "upper-right" Ta "Received signal is wrong"
1305 .It "GREEN"  Ta "upper-left"  Ta "Device driver is alive if blinking"
1306 .It "BLUE"   Ta "lower-right" Ta "Alarm Information Signal (AIS)"
1307 .It "YELLOW" Ta "lower-left"  Ta "Remote Alarm Indication (RAI)"
1308 .El \" YELLOW
1309 .Bl -column -compact "The yellow" "LED"
1310 .It "The green"  Ta "LED blinks if the device driver is alive."
1311 .It "The red"    Ta "LED blinks if an outward loopback is active."
1312 .It "The blue"   Ta "LED blinks if sending AIS, on solid if receiving AIS."
1313 .It "The yellow" Ta "LED blinks if sending RAI, on solid if receiving RAI."
1314 .El \" LED
1315 .Sp
1316 .Ss E1 Framing
1317 .Sp
1318 Phone companies usually insist that customers put a
1319 .Em Frame Alignment Signal
1320 (FAS) in time slot 0.
1321 A Cyclic Redundancy Checksum (CRC) can also ride in time slot 0.
1322 .Em Channel Associated Signalling
1323 (CAS) uses Time Slot 16.
1324 In telco-speak
1325 .Em signalling
1326 is on/off hook, ringing, busy, etc.
1327 Signalling is not needed here and consumes 64 Kb/s.
1328 Only use E1-CAS formats if the other end insists on it!
1329 Use E1-FAS+CRC framing format on a public circuit.
1330 Depending on the equipment installed in a private circuit,
1331 it may be possible to use all 32 time slots for data (E1-NONE).
1332 .Sp
1333 .Ss T3 Framing
1334 .Sp
1335 M13 is a technique for multiplexing 28 T1s into a T3.
1336 Muxes use the C-bits for speed-matching the tributaries.
1337 Muxing is not needed here and usurps the FEBE and FEAC bits.
1338 Only use T3-M13 format if the other end insists on it!
1339 Use T3-CParity framing format if possible.
1340 Loop Timing, Fractional T3, and HDLC packets in
1341 the Facility Data Link are
1342 .Em not
1343 supported.
1344 .Sp
1345 .Ss T1 & T3 Frame Overhead Functions
1346 .Sp
1347 Performance Report Messages (PRMs) are enabled in T1-ESF.
1348 .br
1349 Bit Oriented Protocol (BOP) messages are enabled in T1-ESF.
1350 .br
1351 In-band loopback control (framed or not) is enabled in T1-SF.
1352 .br
1353 Far End Alarm and Control (FEAC) msgs are enabled in T3-CPar.
1354 .br
1355 Far End Block Error (FEBE) reports are enabled in T3-CPar.
1356 .br
1357 Remote Alarm Indication (RAI) is enabled in T3-Any.
1358 .br
1359 Loopbacks initiated remotely time out after 300 seconds.
1360 .Sp
1361 .Ss T1/E1 'Fractional' 64 kb/s Time Slots
1362 .Sp
1363 T1 uses time slots 24..1; E1 uses time slots 31..0.
1364 E1 uses TS0 for FAS overhead and TS16 for CAS overhead.
1365 E1-NONE has
1366 .Em no
1367 overhead, so all 32 TSs are available for data.
1368 Enable/disable time slots by setting 32 1s/0s in a config param.
1369 Enabling an E1 overhead time slot,
1370 or enabling TS0 or TS25-TS31 for T1,
1371 is ignored by the driver, which knows better.
1372 The default TS param, 0xFFFFFFFF, enables the maximum number
1373 of time slots for whatever frame format is selected.
1374 56 Kb/s time slots are
1375 .Em not
1376 supported.
1377 .Sp
1378 .Ss T1 Raw Mode
1379 .Sp
1380 Special gate array microcode exists for the T1/E1 card.
1381 Each T1 frame of 24 bytes is treated as a packet.
1382 A raw T1 byte stream can be delivered to main memory
1383 and transmitted from main memory.
1384 The T1 card adds or deletes framing bits but does not
1385 touch the data.
1386 ATM cells can be transmitted and received this way, with
1387 the software doing all the work.
1388 But that's not hard; after all it's only 1.5 Mb/s second!
1389 .Sp
1390 .Ss T3 Circuit Emulation Mode
1391 .Sp
1392 Special gate array microcode exists for the T3 card.
1393 Each T3 frame of 595 bytes is treated as a packet.
1394 A raw T3 signal can be
1395 .Em packetized ,
1396 transported through a
1397 packet network (using some protocol) and then
1398 .Em reconstituted
1399 as a T3 signal at the far end.  The output transmitter's
1400 bit rate can be controlled from software so that it can be
1401 .Em frequency locked
1402 to the distant input signal.
1403 .Sp
1404 .Ss HSSI and SSI Transmit Clocks
1405 .Sp
1406 Synchronous interfaces use two transmit clocks to eliminate
1407 .Em skew
1408 caused by speed-of-light delays in the modem cable.
1409 DCEs (modems) drive ST, Send Timing. the first transmit clock.
1410 DTEs (hosts) receive ST and use it to clock transmit data, TD,
1411 onto the modem cable.
1412 DTEs also drive a copy of ST back towards the DCE and call it TT,
1413 Transmit Timing. the second trasmit clock.
1414 DCEs receive TT and TD and use TT to clock TD into a flip flop.
1415 TT experiences the same delay as (and has no
1416 .Em skew
1417 relative to) TD.
1418 Thus, cable length does not affect data/clock timing.
1419 .Sp
1420 .Sh SEE ALSO
1421 .Sp
1422 .Xr tcpdump 1 ,
1423 .Xr ioctl 2 ,
1424 .if (\n[fbsd] : \n[nbsd] : \n[obsd]) \{\
1425 .Xr altq 4 , \}
1426 .if (\n[fbsd] : \n[nbsd] : \n[obsd] : \n[bsdi]) \{\
1427 .Xr bpf 4 , \}
1428 .if \n[fbsd] \{\
1429 .Xr kld 4 ,
1430 .Xr loader.conf 5 ,
1431 .Xr netgraph 4 , \}
1432 .if \n[bsdi] \{\
1433 .Xr p2p 4 , \}
1434 .if \n[fbsd] \{\
1435 .Xr polling 4 , \}
1436 .if (\n[fbsd] : \n[nbsd] : \n[obsd]) \{\
1437 .Xr sppp 4 ,
1438 .Xr altqd 8 , \}
1439 .if \n[bsdi] \{\
1440 .Xr frconfig 8 , \}
1441 .Xr ifconfig 8 ,
1442 .if (\n[fbsd] : \n[nbsd] : \n[obsd]) \{\
1443 .Xr init 8 , \}
1444 .if (\n[nbsd] : \n[obsd]) \{\
1445 .Xr lkm 8 , \}
1446 .if \n[fbsd] \{\
1447 .Xr mpd 8 ,
1448 .Xr ngctl 8 , \}
1449 .Xr ping 8 ,
1450 .if \n[bsdi] \{\
1451 .Xr ppp 8 , \}
1452 .Xr lmcconfig 8 ,
1453 .if (\n[fbsd] : \n[nbsd] : \n[obsd] : \n[bsdi]) \{\
1454 .Xr ifnet 9 . \}
1455 .if \n[fbsd] \{\
1456 .Pp
1457 .Pa /usr/ports/net/mpd . \}
1458 .if \n[linux] \{\
1459 .Pp
1460 .Pa http://hq.pm.waw.pl/hdlc . \}
1461 .Pp
1462 .Pa http://www.sbei.com .
1463 .Sp
1464 .Sh HISTORY
1465 .Sp
1466 Ron Crane had the idea to use a Fast Ethernet chip as a PCI interface
1467 and add an Ethernet-to-HDLC gate array to make a WAN card.
1468 David Boggs designed the Ethernet-to-HDLC gate array and PC cards.
1469 We did this at our company, LAN Media Corporation
1470 .Tn (LMC) .
1471 .Tn SBE
1472 Corp aquired
1473 .Tn LMC
1474 and continues to make the cards.
1475 .Pp
1476 Since the cards use Tulip Ethernet chips, we started with Matt Thomas'
1477 ubiquitous "de" driver.  Michael Graff stripped out the Ethernet stuff
1478 and added HSSI stuff.  Basil Gunn ported it to Solaris (lost) and
1479 Rob Braun ported it to Linux.  Andrew Stanley-Jones added support
1480 for three more cards and wrote the first version of lmcconfig.
1481 David Boggs rewrote everything and now feels responsible for it.
1482 .Sp
1483 .Sh AUTHOR
1484 .Sp
1485 .An "David Boggs" Aq boggs@boggs.palo-alto.ca.us .