share/man/man4/man4.i386/rdp.4

   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 $
  28 .\" $DragonFly: src/share/man/man4/man4.i386/rdp.4,v 1.4 2007/05/17 08:19:01 swildner Exp $
  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
  42 The
  43 .Nm
  44 device driver supports RealTek RTL 8002-based pocket ethernet adapters,
  45 connected to a standard parallel port.
  46 .Pp
  47 These adapters seem to belong to the cheaper choices among pocket
  48 ethernet adapters.  The RTL 8002 is the central part, containing an
  49 interface to BNC and UTP (10 Mbit/s) media, as well as a host
  50 interface that is designed to talk to standard parallel printer
  51 adapters.  For the full ethernet adapter to work, it is completed by
  52 an external RAM used as the Tx and Rx packet buffer (16 K x 4 for the
  53 RTL 8002), and an EEPROM to hold the assigned ethernet hardware
  54 address.  For the RTL 8002, the EEPROM can be either a standard 93C46
  55 serial EEPROM (which seems to be a common choice), or a 74S288
  56 parallel one.  The latter variant needs the device configuration flag
  57 0x1 in order to work.
  58 .Pp
  59 Since standard printer adapters seem to vary wildly among their timing
  60 requirements, there are currently two possible choices for the way
  61 data are being exchanged between the pocket ethernet adapter and the
  62 printer interface.  The default is the fastest mode the RTL 8002
  63 supports.  If the printer adapter to use is particularly slow (which
  64 can be noticed by watching the ethernet wire for crippled packets, or
  65 by not seeing correctly received packets), the configuration flag 0x2
  66 can be set in order to throttle down the
  67 .Nm
  68 driver.  Note that in fast mode, the data rate is asymmetric, sending
  69 is a little faster (up to two times) than receiving.  Rates like 150
  70 KB/s for sending and 80 KB/s for receiving are common.  For slow mode,
  71 both rates are about the same, and in the range of 50 KB/s through 70
  72 KB/s.  As always, your mileage may vary.
  73 .Pp
  74 In case the adapter isn't recognized at boot-time, setting the
  75 .Em bootverbose
  76 flag
  77 .Pq Ql \-v
  78 might help in diagnosing the reason.  Since the RTL 8002 requires
  79 the availability of a working interrupt for the printer adapter (unlike
  80 the
  81 .Xr ppc 4
  82 driver), the
  83 .Nm
  84 driver fails to attach if the ethernet adapter cannot assert an
  85 interrupt at probe time.
  86 .Pp
  87 The RTL 8002 doesn't support (hardware) multicast.
  88 .Pp
  89 The
  90 .Nm
  91 driver internally sets a flag so it gets probed very early.  This way,
  92 it is possible to configure both, an
  93 .Nm
  94 driver as well as a
  95 .Xr ppc 4
  96 driver into the same kernel.  If no RTL 8002 hardware is present, probing
  97 will eventually detect the printer driver.
  98 .Sh DIAGNOSTICS
  99 .Dl "rdp0: configured IRQ (7) cannot be asserted by device"
 100 .Pp
 101 The probe routine was unable to get the RTL 8002 asserting an interrupt
 102 request through the printer adapter.
 103 .Pp
 104 .Dl "rdp0: failed to find a valid hardware address in EEPROM"
 105 .Pp
 106 Since there doesn't seem to be a standard place for storing the hardware
 107 ethernet address within the EEPROM, the
 108 .Nm
 109 driver walks the entire (serial) EEPROM contents until it finds something
 110 that looks like a valid ethernet hardware address, based on the IEEE's
 111 OUI assignments.  This diagnostic tells the driver was unable to find
 112 one.  Note: it might as well be the current adapter is one of the rare
 113 examples with a 74S288 EEPROM, so
 114 .Ql flags 0x1
 115 should be tried.
 116 .Pp
 117 .Dl "rdp0: Device timeout"
 118 .Pp
 119 After initiating a packet transmission, the ethernet adapter didn't
 120 return a notification of the (successful or failed) transmission.  The
 121 hardware 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
 127 This driver was written by
 128 .An J\(:org Wunsch ,
 129 based on RealTek's packet driver for the RTL 8002, as well as on some
 130 description of the successor chip, RTL 8012, gracefully provided by
 131 RealTek.
 132 .Sh BUGS
 133 There are certainly many of them.
 134 .Pp
 135 Since the
 136 .Nm
 137 driver wants to probe its hardware at boot-time, the adapter needs
 138 to be present then in order to be detected.
 139 .Pp
 140 Only two out of the eight different speed modes RealTek's packet
 141 driver could handle are implemented.  Thus there might be hardware
 142 where even the current slow mode is too fast.
 143 .Pp
 144 There should be a DMA transfer test in the probe routine that figures
 145 out the usable mode automatically.
 146 .Pp
 147 Abusing a standard printer interface for data exchange is error-prone.
 148 Occasional stuck hardware shouldn't surprise too much, hopefully the
 149 timeout routine will catch these cases.  Flood-pinging is a good
 150 example of triggering this problem.  Likewise, albeit BPF is of course
 151 supported, it's certainly a bad idea attempting to watch a crowded
 152 ethernet wire using promiscuous mode.
 153 .Pp
 154 Since the RTL 8002 has only 4 KB of Rx buffer space (2 x 2 KB are used
 155 as Tx buffers), the usual NFS deadlock with large packets arriving too
 156 quickly could happen if a machine using the
 157 .Nm
 158 driver NFS-mounts some fast server with the standard NFS blocksize of
 159 8 KB.  (Since NFS can only retransmit entire NFS packets, the same
 160 packet will be retransmitted over and over again.)
 161 .Pp
 162 The heuristic to find out the ethernet hardware address from the
 163 EEPROM sucks, but seems to be the only sensible generic way that
 164 doesn't depend on the actual location in EEPROM.  RealTek's sample
 165 driver placed it directly at address 0, other vendors picked something
 166 like 15, with other junk in front of it that must not be confused with
 167 a valid ethernet address.
 168 .Pp
 169 The driver should support the successor chip RTL 8012, which seems to
 170 be available and used these days.  (The RTL 8002 is already somewhat
 171 aged, around 1992/93.)  The RTL 8012 offers support for advanced
 172 printer adapter hardware, like bidirectional SPP, or EPP, which could
 173 speed up the transfers substantially.  The RTL 8012 also supports
 174 hardware multicast, and has the ability to address 64 K x 4 packet
 175 buffer RAM.
 176 .Pp
 177 The driver should be layered upon the ppc driver, instead of working
 178 standalone, and should be available as a loadable module, so the
 179 device probing can be deferred until the pocket ethernet adapter has
 180 actually been attached.