Documentation/DocBook/tulip-user.tmpl

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
   4
   5 <book id="TulipUserGuide">
   6  <bookinfo>
   7   <title>Tulip Driver User's Guide</title>
   8
   9   <authorgroup>
  10    <author>
  11     <firstname>Jeff</firstname>
  12     <surname>Garzik</surname>
  13     <affiliation>
  14      <address>
  15       <email>jgarzik@pobox.com</email>
  16      </address>
  17     </affiliation>
  18    </author>
  19   </authorgroup>
  20
  21   <copyright>
  22    <year>2001</year>
  23    <holder>Jeff Garzik</holder>
  24   </copyright>
  25
  26   <legalnotice>
  27    <para>
  28      This documentation is free software; you can redistribute
  29      it and/or modify it under the terms of the GNU General Public
  30      License as published by the Free Software Foundation; either
  31      version 2 of the License, or (at your option) any later
  32      version.
  33    </para>
  34
  35    <para>
  36      This program is distributed in the hope that it will be
  37      useful, but WITHOUT ANY WARRANTY; without even the implied
  38      warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  39      See the GNU General Public License for more details.
  40    </para>
  41
  42    <para>
  43      You should have received a copy of the GNU General Public
  44      License along with this program; if not, write to the Free
  45      Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  46      MA 02111-1307 USA
  47    </para>
  48
  49    <para>
  50      For more details see the file COPYING in the source
  51      distribution of Linux.
  52    </para>
  53   </legalnotice>
  54  </bookinfo>
  55
  56  <toc></toc>
  57
  58   <chapter id="intro">
  59     <title>Introduction</title>
  60 <para>
  61 The Tulip Ethernet Card Driver
  62 is maintained by Jeff Garzik (<email>jgarzik@pobox.com</email>).
  63 </para>
  64
  65 <para>
  66 The Tulip driver was developed by Donald Becker and changed by
  67 Jeff Garzik, Takashi Manabe and a cast of thousands.
  68 </para>
  69
  70 <para>
  71 For 2.4.x and later kernels, the Linux Tulip driver is available at
  72 <ulink url="http://sourceforge.net/projects/tulip/">http://sourceforge.net/projects/tulip/</ulink>
  73 </para>
  74
  75 <para>
  76         This driver is for the Digital "Tulip" Ethernet adapter interface.
  77         It should work with most DEC 21*4*-based chips/ethercards, as well as
  78         with work-alike chips from Lite-On (PNIC) and Macronix (MXIC) and ASIX.
  79 </para>
  80
  81 <para>
  82         The original author may be reached as becker@scyld.com, or C/O
  83         Scyld Computing Corporation,
  84         410 Severn Ave., Suite 210,
  85         Annapolis MD 21403
  86 </para>
  87
  88 <para>
  89         Additional information on Donald Becker's tulip.c
  90         is available at <ulink url="http://www.scyld.com/network/tulip.html">http://www.scyld.com/network/tulip.html</ulink>
  91 </para>
  92
  93   </chapter>
  94
  95   <chapter id="drvr-compat">
  96     <title>Driver Compatibility</title>
  97
  98 <para>
  99 This device driver is designed for the DECchip "Tulip", Digital's
 100 single-chip ethernet controllers for PCI (now owned by Intel).
 101 Supported members of the family
 102 are the 21040, 21041, 21140, 21140A, 21142, and 21143.  Similar work-alike
 103 chips from Lite-On, Macronics, ASIX, Compex and other listed below are also
 104 supported.
 105 </para>
 106
 107 <para>
 108 These chips are used on at least 140 unique PCI board designs.  The great
 109 number of chips and board designs supported is the reason for the
 110 driver size and complexity.  Almost of the increasing complexity is in the
 111 board configuration and media selection code.  There is very little
 112 increasing in the operational critical path length.
 113 </para>
 114   </chapter>
 115
 116   <chapter id="board-settings">
 117     <title>Board-specific Settings</title>
 118
 119 <para>
 120 PCI bus devices are configured by the system at boot time, so no jumpers
 121 need to be set on the board.  The system BIOS preferably should assign the
 122 PCI INTA signal to an otherwise unused system IRQ line.
 123 </para>
 124
 125 <para>
 126 Some boards have EEPROMs tables with default media entry.  The factory default
 127 is usually "autoselect".  This should only be overridden when using
 128 transceiver connections without link beat e.g. 10base2 or AUI, or (rarely!)
 129 for forcing full-duplex when used with old link partners that do not do
 130 autonegotiation.
 131 </para>
 132   </chapter>
 133
 134   <chapter id="driver-operation">
 135     <title>Driver Operation</title>
 136
 137 <sect1><title>Ring buffers</title>
 138
 139 <para>
 140 The Tulip can use either ring buffers or lists of Tx and Rx descriptors.
 141 This driver uses statically allocated rings of Rx and Tx descriptors, set at
 142 compile time by RX/TX_RING_SIZE.  This version of the driver allocates skbuffs
 143 for the Rx ring buffers at open() time and passes the skb->data field to the
 144 Tulip as receive data buffers.  When an incoming frame is less than
 145 RX_COPYBREAK bytes long, a fresh skbuff is allocated and the frame is
 146 copied to the new skbuff.  When the incoming frame is larger, the skbuff is
 147 passed directly up the protocol stack and replaced by a newly allocated
 148 skbuff.
 149 </para>
 150
 151 <para>
 152 The RX_COPYBREAK value is chosen to trade-off the memory wasted by
 153 using a full-sized skbuff for small frames vs. the copying costs of larger
 154 frames.  For small frames the copying cost is negligible (esp. considering
 155 that we are pre-loading the cache with immediately useful header
 156 information).  For large frames the copying cost is non-trivial, and the
 157 larger copy might flush the cache of useful data.  A subtle aspect of this
 158 choice is that the Tulip only receives into longword aligned buffers, thus
 159 the IP header at offset 14 isn't longword aligned for further processing.
 160 Copied frames are put into the new skbuff at an offset of "+2", thus copying
 161 has the beneficial effect of aligning the IP header and preloading the
 162 cache.
 163 </para>
 164
 165 </sect1>
 166
 167 <sect1><title>Synchronization</title>
 168 <para>
 169 The driver runs as two independent, single-threaded flows of control.  One
 170 is the send-packet routine, which enforces single-threaded use by the
 171 dev->tbusy flag.  The other thread is the interrupt handler, which is single
 172 threaded by the hardware and other software.
 173 </para>
 174
 175 <para>
 176 The send packet thread has partial control over the Tx ring and 'dev->tbusy'
 177 flag.  It sets the tbusy flag whenever it's queuing a Tx packet. If the next
 178 queue slot is empty, it clears the tbusy flag when finished otherwise it sets
 179 the 'tp->tx_full' flag.
 180 </para>
 181
 182 <para>
 183 The interrupt handler has exclusive control over the Rx ring and records stats
 184 from the Tx ring.  (The Tx-done interrupt can't be selectively turned off, so
 185 we can't avoid the interrupt overhead by having the Tx routine reap the Tx
 186 stats.)  After reaping the stats, it marks the queue entry as empty by setting
 187 the 'base' to zero.      Iff the 'tp->tx_full' flag is set, it clears both the
 188 tx_full and tbusy flags.
 189 </para>
 190
 191 </sect1>
 192
 193   </chapter>
 194
 195   <chapter id="errata">
 196     <title>Errata</title>
 197
 198 <para>
 199 The old DEC databooks were light on details.
 200 The 21040 databook claims that CSR13, CSR14, and CSR15 should each be the last
 201 register of the set CSR12-15 written.  Hmmm, now how is that possible?
 202 </para>
 203
 204 <para>
 205 The DEC SROM format is very badly designed not precisely defined, leading to
 206 part of the media selection junkheap below.  Some boards do not have EEPROM
 207 media tables and need to be patched up.  Worse, other boards use the DEC
 208 design kit media table when it isn't correct for their board.
 209 </para>
 210
 211 <para>
 212 We cannot use MII interrupts because there is no defined GPIO pin to attach
 213 them.  The MII transceiver status is polled using an kernel timer.
 214 </para>
 215   </chapter>
 216
 217   <chapter id="changelog">
 218     <title>Driver Change History</title>
 219
 220     <sect1><title>Version 0.9.14 (February 20, 2001)</title>
 221     <itemizedlist>
 222     <listitem><para>Fix PNIC problems (Manfred Spraul)</para></listitem>
 223     <listitem><para>Add new PCI id for Accton comet</para></listitem>
 224     <listitem><para>Support Davicom tulips</para></listitem>
 225     <listitem><para>Fix oops in eeprom parsing</para></listitem>
 226     <listitem><para>Enable workarounds for early PCI chipsets</para></listitem>
 227     <listitem><para>IA64, hppa csr0 support</para></listitem>
 228     <listitem><para>Support media types 5, 6</para></listitem>
 229     <listitem><para>Interpret a bit more of the 21142 SROM extended media type 3</para></listitem>
 230     <listitem><para>Add missing delay in eeprom reading</para></listitem>
 231     </itemizedlist>
 232     </sect1>
 233
 234     <sect1><title>Version 0.9.11 (November 3, 2000)</title>
 235     <itemizedlist>
 236     <listitem><para>Eliminate extra bus accesses when sharing interrupts (prumpf)</para></listitem>
 237     <listitem><para>Barrier following ownership descriptor bit flip (prumpf)</para></listitem>
 238     <listitem><para>Endianness fixes for >14 addresses in setup frames (prumpf)</para></listitem>
 239     <listitem><para>Report link beat to kernel/userspace via netif_carrier_*. (kuznet)</para></listitem>
 240     <listitem><para>Better spinlocking in set_rx_mode.</para></listitem>
 241     <listitem><para>Fix I/O resource request failure error messages (DaveM catch)</para></listitem>
 242     <listitem><para>Handle DMA allocation failure.</para></listitem>
 243     </itemizedlist>
 244     </sect1>
 245
 246     <sect1><title>Version 0.9.10 (September 6, 2000)</title>
 247     <itemizedlist>
 248     <listitem><para>Simple interrupt mitigation (via jamal)</para></listitem>
 249     <listitem><para>More PCI ids</para></listitem>
 250     </itemizedlist>
 251     </sect1>
 252
 253     <sect1><title>Version 0.9.9 (August 11, 2000)</title>
 254     <itemizedlist>
 255     <listitem><para>More PCI ids</para></listitem>
 256     </itemizedlist>
 257     </sect1>
 258
 259     <sect1><title>Version 0.9.8 (July 13, 2000)</title>
 260     <itemizedlist>
 261     <listitem><para>Correct signed/unsigned comparison for dummy frame index</para></listitem>
 262     <listitem><para>Remove outdated references to struct enet_statistics</para></listitem>
 263     </itemizedlist>
 264     </sect1>
 265
 266     <sect1><title>Version 0.9.7 (June 17, 2000)</title>
 267     <itemizedlist>
 268     <listitem><para>Timer cleanups (Andrew Morton)</para></listitem>
 269     <listitem><para>Alpha compile fix (somebody?)</para></listitem>
 270     </itemizedlist>
 271     </sect1>
 272
 273     <sect1><title>Version 0.9.6 (May 31, 2000)</title>
 274     <itemizedlist>
 275     <listitem><para>Revert 21143-related support flag patch</para></listitem>
 276     <listitem><para>Add HPPA/media-table debugging printk</para></listitem>
 277     </itemizedlist>
 278     </sect1>
 279
 280     <sect1><title>Version 0.9.5 (May 30, 2000)</title>
 281     <itemizedlist>
 282     <listitem><para>HPPA support (willy@puffingroup)</para></listitem>
 283     <listitem><para>CSR6 bits and tulip.h cleanup (Chris Smith)</para></listitem>
 284     <listitem><para>Improve debugging messages a bit</para></listitem>
 285     <listitem><para>Add delay after CSR13 write in t21142_start_nway</para></listitem>
 286     <listitem><para>Remove unused ETHER_STATS code</para></listitem>
 287     <listitem><para>Convert 'extern inline' to 'static inline' in tulip.h (Chris Smith)</para></listitem>
 288     <listitem><para>Update DS21143 support flags in tulip_chip_info[]</para></listitem>
 289     <listitem><para>Use spin_lock_irq, not _irqsave/restore, in tulip_start_xmit()</para></listitem>
 290     <listitem><para>Add locking to set_rx_mode()</para></listitem>
 291     <listitem><para>Fix race with chip setting DescOwned bit (Hal Murray)</para></listitem>
 292     <listitem><para>Request 100% of PIO and MMIO resource space assigned to card</para></listitem>
 293     <listitem><para>Remove error message from pci_enable_device failure</para></listitem>
 294     </itemizedlist>
 295     </sect1>
 296
 297     <sect1><title>Version 0.9.4.3 (April 14, 2000)</title>
 298     <itemizedlist>
 299     <listitem><para>mod_timer fix (Hal Murray)</para></listitem>
 300     <listitem><para>PNIC2 resuscitation (Chris Smith)</para></listitem>
 301     </itemizedlist>
 302     </sect1>
 303
 304     <sect1><title>Version 0.9.4.2 (March 21, 2000)</title>
 305     <itemizedlist>
 306     <listitem><para>Fix 21041 CSR7, CSR13/14/15 handling</para></listitem>
 307     <listitem><para>Merge some PCI ids from tulip 0.91x</para></listitem>
 308     <listitem><para>Merge some HAS_xxx flags and flag settings from tulip 0.91x</para></listitem>
 309     <listitem><para>asm/io.h fix (submitted by many) and cleanup</para></listitem>
 310     <listitem><para>s/HAS_NWAY143/HAS_NWAY/</para></listitem>
 311     <listitem><para>Cleanup 21041 mode reporting</para></listitem>
 312     <listitem><para>Small code cleanups</para></listitem>
 313     </itemizedlist>
 314     </sect1>
 315
 316     <sect1><title>Version 0.9.4.1 (March 18, 2000)</title>
 317     <itemizedlist>
 318     <listitem><para>Finish PCI DMA conversion (davem)</para></listitem>
 319     <listitem><para>Do not netif_start_queue() at end of tulip_tx_timeout() (kuznet)</para></listitem>
 320     <listitem><para>PCI DMA fix (kuznet)</para></listitem>
 321     <listitem><para>eeprom.c code cleanup</para></listitem>
 322     <listitem><para>Remove Xircom Tulip crud</para></listitem>
 323     </itemizedlist>
 324     </sect1>
 325   </chapter>
 326
 327 </book>