Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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> |