gold: Fix hardcoded library search path
[dragonfly.git] / share / man / man4 / man4.i386 / rdp.4
CommitLineData
984263bc
MD
1.\"
2.\"
3.\" Copyright (c) 1997 Joerg Wunsch
4.\"
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26.\"
27.\" $FreeBSD: src/share/man/man4/man4.i386/rdp.4,v 1.5.2.4 2001/08/17 13:08:46 ru Exp $
3f5e28f4 28.\" $DragonFly: src/share/man/man4/man4.i386/rdp.4,v 1.4 2007/05/17 08:19:01 swildner Exp $
984263bc
MD
29.\"
30.\"
31.\" " (emacs disconfusion)
32.Dd December 21, 1998
33.Dt RDP 4 i386
34.Os
35.Sh NAME
36.Nm rdp
37.Nd Ethernet driver for RealTek RTL 8002 pocket ethernet
38.Sh SYNOPSIS
39.Cd "device rdp0 at isa? port 0x378 irq 7"
40.Cd "device rdp0 at isa? port 0x378 irq 7 flags 0x2"
41.Sh DESCRIPTION
42The
43.Nm
44device driver supports RealTek RTL 8002-based pocket ethernet adapters,
45connected to a standard parallel port.
46.Pp
47These adapters seem to belong to the cheaper choices among pocket
48ethernet adapters. The RTL 8002 is the central part, containing an
49interface to BNC and UTP (10 Mbit/s) media, as well as a host
50interface that is designed to talk to standard parallel printer
51adapters. For the full ethernet adapter to work, it is completed by
52an external RAM used as the Tx and Rx packet buffer (16 K x 4 for the
53RTL 8002), and an EEPROM to hold the assigned ethernet hardware
54address. For the RTL 8002, the EEPROM can be either a standard 93C46
55serial EEPROM (which seems to be a common choice), or a 74S288
56parallel one. The latter variant needs the device configuration flag
570x1 in order to work.
58.Pp
59Since standard printer adapters seem to vary wildly among their timing
60requirements, there are currently two possible choices for the way
61data are being exchanged between the pocket ethernet adapter and the
62printer interface. The default is the fastest mode the RTL 8002
63supports. If the printer adapter to use is particularly slow (which
64can be noticed by watching the ethernet wire for crippled packets, or
3f5e28f4 65by not seeing correctly received packets), the configuration flag 0x2
984263bc
MD
66can be set in order to throttle down the
67.Nm
3f5e28f4 68driver. Note that in fast mode, the data rate is asymmetric, sending
984263bc
MD
69is a little faster (up to two times) than receiving. Rates like 150
70KB/s for sending and 80 KB/s for receiving are common. For slow mode,
71both rates are about the same, and in the range of 50 KB/s through 70
72KB/s. As always, your mileage may vary.
73.Pp
74In case the adapter isn't recognized at boot-time, setting the
75.Em bootverbose
76flag
d86d12ac 77.Pq Ql \-v
984263bc
MD
78might help in diagnosing the reason. Since the RTL 8002 requires
79the availability of a working interrupt for the printer adapter (unlike
80the
81.Xr ppc 4
82driver), the
83.Nm
84driver fails to attach if the ethernet adapter cannot assert an
85interrupt at probe time.
86.Pp
87The RTL 8002 doesn't support (hardware) multicast.
88.Pp
89The
90.Nm
91driver internally sets a flag so it gets probed very early. This way,
92it is possible to configure both, an
93.Nm
94driver as well as a
95.Xr ppc 4
96driver into the same kernel. If no RTL 8002 hardware is present, probing
97will eventually detect the printer driver.
98.Sh DIAGNOSTICS
99.Dl "rdp0: configured IRQ (7) cannot be asserted by device"
100.Pp
101The probe routine was unable to get the RTL 8002 asserting an interrupt
102request through the printer adapter.
103.Pp
104.Dl "rdp0: failed to find a valid hardware address in EEPROM"
105.Pp
106Since there doesn't seem to be a standard place for storing the hardware
107ethernet address within the EEPROM, the
108.Nm
109driver walks the entire (serial) EEPROM contents until it finds something
110that looks like a valid ethernet hardware address, based on the IEEE's
111OUI assignments. This diagnostic tells the driver was unable to find
112one. Note: it might as well be the current adapter is one of the rare
113examples with a 74S288 EEPROM, so
114.Ql flags 0x1
115should be tried.
116.Pp
117.Dl "rdp0: Device timeout"
118.Pp
119After initiating a packet transmission, the ethernet adapter didn't
120return a notification of the (successful or failed) transmission. The
121hardware is likely to be wedged, and is being reset.
122.Sh SEE ALSO
123.Xr ng_ether 4 ,
124.Xr ppc 4 ,
125.Xr ifconfig 8
126.Sh AUTHORS
127This driver was written by
128.An J\(:org Wunsch ,
129based on RealTek's packet driver for the RTL 8002, as well as on some
130description of the successor chip, RTL 8012, gracefully provided by
131RealTek.
132.Sh BUGS
133There are certainly many of them.
134.Pp
135Since the
136.Nm
137driver wants to probe its hardware at boot-time, the adapter needs
138to be present then in order to be detected.
139.Pp
140Only two out of the eight different speed modes RealTek's packet
141driver could handle are implemented. Thus there might be hardware
142where even the current slow mode is too fast.
143.Pp
144There should be a DMA transfer test in the probe routine that figures
145out the usable mode automatically.
146.Pp
147Abusing a standard printer interface for data exchange is error-prone.
148Occasional stuck hardware shouldn't surprise too much, hopefully the
149timeout routine will catch these cases. Flood-pinging is a good
150example of triggering this problem. Likewise, albeit BPF is of course
151supported, it's certainly a bad idea attempting to watch a crowded
152ethernet wire using promiscuous mode.
153.Pp
154Since the RTL 8002 has only 4 KB of Rx buffer space (2 x 2 KB are used
155as Tx buffers), the usual NFS deadlock with large packets arriving too
156quickly could happen if a machine using the
157.Nm
158driver NFS-mounts some fast server with the standard NFS blocksize of
1598 KB. (Since NFS can only retransmit entire NFS packets, the same
160packet will be retransmitted over and over again.)
161.Pp
162The heuristic to find out the ethernet hardware address from the
163EEPROM sucks, but seems to be the only sensible generic way that
164doesn't depend on the actual location in EEPROM. RealTek's sample
165driver placed it directly at address 0, other vendors picked something
166like 15, with other junk in front of it that must not be confused with
167a valid ethernet address.
168.Pp
169The driver should support the successor chip RTL 8012, which seems to
170be available and used these days. (The RTL 8002 is already somewhat
171aged, around 1992/93.) The RTL 8012 offers support for advanced
172printer adapter hardware, like bidirectional SPP, or EPP, which could
173speed up the transfers substantially. The RTL 8012 also supports
174hardware multicast, and has the ability to address 64 K x 4 packet
175buffer RAM.
176.Pp
177The driver should be layered upon the ppc driver, instead of working
178standalone, and should be available as a loadable module, so the
179device probing can be deferred until the pocket ethernet adapter has
180actually been attached.