This commit was generated by cvs2svn to compensate for changes in r41980,

which included commits to RCS files with non-trunk default branches.

1 files changed, 181 insertions, 0 deletions

diff --git a/share/man/man4/man4.i386/rdp.4 b/share/man/man4/man4.i386/rdp.4
new file mode 100644
index 0000000..fb70f40
--- /dev/null
+++ b/share/man/man4/man4.i386/rdp.4
@@ -0,0 +1,181 @@
+.\"
+.\"
+.\" Copyright (c) 1997 Joerg Wunsch
+.\"
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $Id: rdp.4,v 1.1.1.1 1998/12/21 12:43:35 j Exp $
+.\"
+.\"
+.\" " (emacs disconfusion)
+.Dd December 21, 1998
+.Dt RDP 4 i386
+.Os
+.Sh NAME
+.Nm rdp
+.Nd Ethernet driver for RealTek RTL 8002 pocket ethernet
+.Sh SYNOPSIS
+.Cd "device rdp0 at isa? port 0x378 net irq 7"
+.Cd "device rdp0 at isa? port 0x378 net irq 7 flags 0x2"
+.Sh DESCRIPTION
+The
+.Nm
+device driver supports RealTek RTL 8002-based pocket ethernet adapters,
+connected to a standard parallel port.
+.Pp
+These adapters seem to belong to the cheaper choices among pocket
+ethernet adapters.  The RTL 8002 is the central part, containing an
+interface to BNC and UTP (10 Mbit/s) media, as well as a host
+interface that is designed to talk to standard parallel printer
+adapters.  For the full ethernet adapter to work, it is completed by
+an external RAM used as the Tx and Rx packet buffer (16 K x 4 for the
+RTL 8002), and an EEPROM to hold the assigned ethernet hardware
+address.  For the RTL 8002, the EEPROM can be either a standard 93C46
+serial EEPROM (which seems to be a common choice), or a 74S288
+parallel one.  The latter variant needs the device configuration flag
+0x1 in order to work.
+.Pp
+Since standard printer adapters seem to vary wildly among their timing
+requirements, there are currently two possible choices for the way
+data are being exchanged between the pocket ethernet adapter and the
+printer interface.  The default is the fastest mode the RTL 8002
+supports.  If the printer adapter to use is particularly slow (which
+can be noticed by watching the ethernet wire for crippled packets, or
+by not seeing correclty received packets), the configuration flag 0x2
+can be set in order to throttle down the
+.Nm
+driver.  Note that in fast mode, the data rate is assymetric, sending
+is a little faster (up to two times) than receiving.  Rates like 150
+KB/s for sending and 80 KB/s for receiving are common.  For slow mode,
+both rates are about the same, and in the range of 50 KB/s through 70
+KB/s.  As always, your mileage may vary.
+.Pp
+In case the adapter isn't recognized at boot-time, setting the
+.Em bootverbose
+flag
+.Pq Ql Fl v
+might help in diagnosing the reason.  Since the RTL 8002 requires
+the availability of a working interrupt for the printer adapter (unlike
+the
+.Xr lpt 4
+driver), the
+.Nm
+driver fails to attach if the ethernet adapter cannot assert an
+interrupt at probe time.
+.Pp
+The RTL 8002 doesn't support (hardware) multicast.
+.Pp
+The
+.Nm
+driver internally sets a flag so it gets probed very early.  This way,
+it is possible to configure both, an
+.Nm
+driver as well as an
+.Xr lpt 4
+driver into the same kernel.  If no RTL 8002 hardware is present, probing
+will eventually detect the printer driver.
+.Sh DIAGNOSTICS
+.Pp
+.Dl "rdp0: configured IRQ (7) cannot be asserted by device"
+.Pp
+The probe routine was unable to get the RTL 8002 asserting an interrupt
+request through the printer adapter.
+.Pp
+.Dl "rdp0: failed to find a valid hardware address in EEPROM"
+.Pp
+Since there doesn't seem to be a standard place for storing the hardware
+ethernet address within the EEPROM, the
+.Nm
+driver walks the entire (serial) EEPROM contents until it finds something
+that looks like a valid ethernet hardware address, based on the IEEE's
+OUI assignments.  This diagnostic tells the driver was unable to find
+one.  Note: it might as well be the current adapter is one of the rare
+examples with a 74S288 EEPROM, so
+.Ql flags 0x1
+should be tried.
+.Pp
+.Dl "rdp0: Device timeout"
+.Pp
+After initiating a packet transmission, the ethernet adapter didn't
+return a notification of the (successful or failed) transmission.  The
+hardware is likely to be wedged, and is being reset.
+.Pp
+.Sh SEE ALSO
+.Xr lpt 4 ,
+.Xr ifconfig 8
+.Sh AUTHORS
+This driver was written by
+.ie t J\(:org Wunsch,
+.el Joerg Wunsch,
+based on RealTek's packet driver for the RTL 8002, as well as on some
+description of the successor chip, RTL 8012, RealTek was gratefully
+providing.
+.Sh BUGS
+There are certainly many of them.
+.Pp
+Since the
+.Nm
+driver wants to probe its hardware at boot-time, the adapter needs
+to be present then in order to be detected.
+.Pp
+Only two out of the eight different speed modes RealTek's packet
+driver could handle are implemented.  Thus there might be hardware
+where even the current slow mode is too fast.
+.Pp
+There should be a DMA transfer test in the probe routine that figures
+out the usable mode automatically.
+.Pp
+Abusing a standard printer interface for data exchange is error-prone.
+Occasional stuck hardware shouldn't surprise too much, hopefully the
+timeout routine will catch these cases.  Flood-pinging is a good
+example of triggering this problem.  Likewise, albeit BPF is of course
+supported, it's certainly a bad idea attempting to watch a crowded
+ethernet wire using promiscuous mode.
+.Pp
+Since the RTL 8002 has only 4 KB of Rx buffer space (2 x 2 KB are used
+as Tx buffers), the usual NFS deadlock with large packets arriving too
+quickly could happen if a machine using the
+.Nm
+driver NFS-mounts some fast server with the standard NFS blocksize of
+8 KB.  (Since NFS can only retransmit entire NFS packets, the same
+packet will be retransmitted over and over again.)
+.Pp
+The heuristic to find out the ethernet hardware address from the
+EEPROM sucks, but seems to be the only sensible generic way that
+doesn't depend on the actual location in EEPROM.  RealTek's sample
+driver placed it directly at address 0, other vendors picked something
+like 15, with other junk in front of it that must not be confused with
+a valid ethernet address.
+.Pp
+The driver should support the successor chip RTL 8012, which seems to
+be available and used these days.  (The RTL 8002 is already somewhat
+aged, around 1992/93.)  The RTL 8012 offers support for advanced
+printer adapter hardware, like bidirectional SPP, or EPP, which could
+speed up the transfers substantially.  The RTL 8012 also supports
+hardware multicast, and has the ability to address 64 K x 4 packet
+buffer RAM.
+.Pp
+The driver should be layered upon the ppc driver, instead of working
+standalone, and should be available as a loadable module, so the
+device probing can be deferred until the pocket ethernet adapter has
+actually been attached.