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