[3c90x] 3c90x driver rewrite using gPXE API
[people/mcb30/gpxe.git] / src / drivers / net / 3c90x.txt
1
2         Instructions for use of the 3C90X driver for EtherBoot
3
4                 Original 3C905B support by:
5                         Greg Beeley (Greg.Beeley@LightSys.org),
6                         LightSys Technology Services, Inc.
7                         February 11, 1999
8
9                 Updates for 3C90X family by:
10                         Steve Smith (steve.smith@juno.com)
11                         October 1, 1999
12
13                 Minor documentation updates by
14                         Greg Beeley (Greg.Beeley@LightSys.org)
15                         March 29, 2000
16
17 -------------------------------------------------------------------------------
18
19 I   OVERVIEW
20
21     The 3c90X series ethernet cards are a group of high-performance busmaster
22     DMA cards from 3Com.  This particular driver supports both the 3c90x and
23     the 3c90xB revision cards.  3C90xC family support has been tested to some
24     degree but not extensively.
25
26     Here's the licensing information:
27
28     This program Copyright (C) 1999 LightSys Technology Services, Inc.
29     Portions Copyright (C) 1999 Steve Smith.
30
31     This program may be re-distributed in source or binary form, modified,
32     sold, or copied for any purpose, provided that the above copyright message
33     and this text are included with all source copies or derivative works, and
34     provided that the above copyright message and this text are included in the
35     documentation of any binary-only distributions.  This program is
36     distributed WITHOUT ANY WARRANTY, without even the warranty of FITNESS FOR
37     A PARTICULAR PURPOSE or MERCHANTABILITY.  Please read the associated
38     documentation "3c90x.txt" before compiling and using this driver.
39
40
41 II  FLASH PROMS
42
43     The 3c90xB cards, according to the 3Com documentation, only accept the
44     following flash memory chips:
45
46         Atmel AT29C512 (64 kilobyte)
47         Atmel AT29C010 (128 kilobyte)
48
49     The 3c90x cards, according to the 3Com documentation, accept the
50     following flash memory chips capacities:
51
52         64  kb (8 kB)
53         128 kb (16 kB)
54         256 kb (32 kB) and
55         512 kb (64 kB)
56
57     Atmel AT29C512 (64 kilobyte) chips are specifically listed for both
58     adapters, but flashing on the 3c905b cards would only be supported
59     through the Atmel parts.  Any device, of the supported size, should
60     be supported when programmed by a dedicated PROM programmer (e.g.
61     not the card).
62
63     To use this driver in such a PROM, visit Atmel's web site and download
64     their .PDF file containing a list of their distributors.  Contact the
65     distributors for pricing information.  The prices are quite reasonable
66     (about $3 US each for the 64 kB part), and are comparable to what one would
67     expect for similarly sized standard EPROMs.  And, the flash chips are much
68     easier to work with, as they don't need to be UV-erased to be reprogrammed.
69     The 3C905B card actually provides a method to program the flash memory
70     while it is resident on board the card itself; if someone would like to
71     write a small DOS program to do the programming, I can provide the
72     information about the registers and so forth.
73
74     A utility program, 3c90xutil, is provided with Etherboot in the 'contrib'
75     directory that allows for the on-board flashing of the ROM while Linux
76     is running.  The program has been successfully used under Linux, but I
77     have heard problem reports of its use under FreeBSD.  Anyone willing to
78     make it work under FreeBSD is more than welcome to do so!
79
80     You also have the option of using EPROM chips - the 3C905B-TX-NM has been
81     successfully tested with 27C256 (32kB) and 27C512 (64kB) chips with a
82     specified access time of 100ns and faster.
83
84
85 III GENERAL USE
86
87     Normally, the basic procedure for using this driver is as follows:
88
89         1.  Run the 3c90xcfg program on the driver diskette to enable the
90         boot PROM and set it to 64k or 128k, as appropriate.
91         2.  Build the appropriate 3c90x.fd0 or 3c90x.fd0 floppy image with
92         possibly the value CFG_3C90X_XCVR defined to the transceiver type that
93         you want to use (i.e., 10/100 rj45, AUI, coax, MII).
94         3.  Run the floppy image on the PC to be network booted, to get
95         it configured, and to verify that it will boot properly.
96         4.  Build the 3c90x.rom or 3c90x.lzrom PROM image and program
97         it into the flash or EPROM memory chip.
98         5.  Put the PROM in the ethernet card, boot and enable 'boot from
99         network first' in the system BIOS, save and reboot.
100
101     Here are some issues to be aware of:
102
103         1.  If you experience crashes or different behaviour when using the
104         boot PROM, add the setting CFG_3C90X_BOOTROM_FIX and go through the
105         steps 2-5 above.  This works around a bug in some 3c905B cards (see
106         below), but has some side-effects which may not be desirable.
107         Please note that you have to boot off a floppy (not PROM!) once for
108         this fix to take effect.
109         2.  The possible need to manually set the CFG_3C90X_XCVR value to
110         configure the transceiver type.  Values are listed below.
111         3.  The possible need to define CFG_3C90X_PRESERVE_XCVR for use in
112         operating systems that don't intelligently determine the
113         transceiver type.
114
115     Some things that are on the 'To-Do' list, perhaps for me, but perhaps
116     for any other volunteers out there:
117
118         1.  Extend the driver to fully implement the auto-select
119         algorithm if the card has multiple media ports.
120         2.  Fix any bugs in the code <grin>....
121         3.  Extend the driver to support the 3c905c revision cards
122         "officially".  Right now, the support has been primarily empirical
123         and not based on 3c905C documentation.
124
125     Now for the details....
126
127     This driver has been tested on roughly 300 systems.  The main two
128     configuration issues to contend with are:
129
130         1.  Ensure that PCI Busmastering is enabled for the adapter (configured
131         in the CMOS setup)
132         2.  Some systems don't work properly with the adapter when plug and
133         play OS is enabled; I always set it to "No" or "Disabled" -- this makes
134         it easier and really doesn't adversely affect anything.
135
136     Roughly 95% of the systems worked when configured properly.  A few
137     have issues with booting locally once the boot PROM has been installed
138     (this number has been less than 2%).  Other configuration issues that
139     to check:
140
141         1.  Newer BIOS's actually work correctly with the network boot order.
142         Set the network adapter first.  Most older BIOS's automatically go to
143         the network boot PROM first.
144         2.  For systems where the adapter was already installed and is just
145         having the PROM installed, try setting the "reset configuration data"
146         to yes in the CMOS setup if the BIOS isn't seen at first.  If your BIOS
147         doesn't have this option, remove the card, start the system, shut down,
148         install the card and restart (or switch to a different PCI slot).
149         3.  Make sure the CMOS security settings aren't preventing a boot.
150
151     The 3c905B cards have a significant 'bug' that relates to the flash prom:
152     unless the card is set internally to the MII transceiver, it will only
153     read the first 8k of the PROM image.  Don't ask why -- it seems really
154     obscure, but it has to do with the way they mux'd the address lines
155     from the PCI bus to the ROM.  Unfortunately, most of us are not using
156     MII transceivers, and even the .lzrom image ends up being just a little
157     bit larger than 8k.  Note that the workaround for this is disabled by
158     default, because the Windows NT 4.0 driver does not like it (no packets
159     are transmitted).
160
161     So, the solution that I've used is to internally set the card's nvram
162     configuration to use MII when it boots.  The 3c905b driver does this
163     automatically.  This way, the 16k prom image can be loaded into memory,
164     and then the 3c905b driver can set the temporary configuration of the
165     card to an appropriate value, either configurable by the user or chosen
166     by the driver.
167
168     To enable the 3c905B bugfix, which is necessary for these cards when 
169     booting from the Flash ROM, define -DCFG_3C90X_BOOTROM_FIX when building,
170     create a floppy image and boot it once.
171     Thereafter, the card should accept the larger prom image.
172
173     The driver should choose an appropriate transceiver on the card.  However,
174     if it doesn't on your card or if you need to, for instance, set your
175     card to 10mbps when connected to an unmanaged 10/100 hub, you can specify
176     which transceiver you want to use.  To do this, build the 3c905b.fd0
177     image with -DCFG_3C90X_XCVR=x, where 'x' is one of the following
178     values:
179
180         0       10Base-T
181         1       10mbps AUI
182         3       10Base-2 (thinnet/coax)
183         4       100Base-TX
184         5       100Base-FX
185         6       MII
186         8       Auto-negotiation 10Base-T / 100Base-TX (usually the default)
187         9       MII External MAC Mode
188         255     Allow driver to choose an 'appropriate' media port.
189
190     Then proceed from step 2 in the above 'general use' instructions.  The
191     .rom image can be built with CFG_3C90X_XCVR set to a value, but you
192     normally don't want to do this, since it is easier to change the
193     transceiver type by rebuilding a new floppy, changing the BIOS to floppy
194     boot, booting, and then changing the BIOS back to network boot.  If
195     CFG_3C90X_XCVR is not set in a particular build, it just uses the
196     current configuration (either its 'best guess' or whatever the stored
197     CFG_3C90X_XCVR value was from the last time it was set).
198
199     [[ Note for the more technically inclined:  The CFG_3C90X_XCVR value is
200     programmed into a register in the card's NVRAM that was reserved for
201     LanWorks PROM images to use.  When the driver boots, the card comes
202     up in MII mode, and the driver checks the LanWorks register to find
203     out if the user specified a transceiver type.  If it finds that
204     information, it uses that, otherwise it picks a transceiver that the
205     card has based on the 3c905b's MediaOptions register.  This driver isn't
206     quite smart enough to always determine which media port is actually
207     _connected_; maybe someone else would like to take on that task (it
208     actually involves sending a self-directed packet and seeing if it
209     comes back.  IF it does, that port is connected). ]]
210
211     Another issue to keep in mind is that it is possible that some OS'es
212     might not be happy with the way I've handled the PROM-image hack with
213     setting MII mode on bootup.  Linux 2.0.35 does not have this problem.
214     Behavior of other systems may vary.  The 3com documentation specifically
215     says that, at least with the card that I have, the device driver in the
216     OS should auto-select the media port, so other drivers should work fine
217     with this 'hack'.  However, if yours doesn't seem to, you can try defining
218     CFG_3C90X_PRESERVE_XCVR when building to cause Etherboot to keep the
219     working setting (that allowed the bootp/tftp process) across the eth_reset
220     operation.
221
222
223 IV  FOR DEVELOPERS....
224
225     If you would like to fix/extend/etc. this driver, feel free to do so; just
226     be sure you can test the modified version on the 3c905B-TX cards that the
227     driver was originally designed for.  This section of this document gives
228     some information that might be relevant to a programmer.
229
230     A.  Main Entry Point
231
232         a3c90x_probe is the main entry point for this driver.  It is referred
233         to in an array in 'config.c'.
234
235     B.  Other Important Functions
236
237         The functions a3c90x_transmit, a3c90x_poll, a3c90x_reset, and
238         a3c90x_disable are static functions that EtherBoot finds out about
239         as a  result of a3c90x_probe setting entries in the nic structure
240         for them.  The EtherBoot framework does not use interrupts.  It is
241         polled.  All transmit and receive operations are initiated by the
242         etherboot framework, not by an interrupt or by the driver.
243
244     C.  Internal Functions
245
246         The following functions are internal to the driver:
247
248         a3c90x_internal_IssueCommand - sends a command to the 3c905b card.
249         a3c90x_internal_SetWindow - shifts between one of eight register
250         windows onboard the 3c90x.  The bottom 16 bytes of the card's
251         I/O space are multiplexed among 128 bytes, only 16 of which are
252         visible at any one time.  This SetWindow function selects one of
253         the eight sets.
254         a3c90x_internal_ReadEeprom - reads a word (16 bits) from the
255         card's onboard nvram.  This is NOT the BIOS boot rom.  This is
256         where the card stores such things as its hardware address.
257         a3c90x_internal_WriteEeprom - writes a word (16 bits) to the
258         card's nvram, and recomputes the eeprom checksum.
259         a3c90x_internal_WriteEepromWord - writes a word (16 bits) to the
260         card's nvram.  Used by the above routine.
261         a3c90x_internal_WriteEepromWord - writes a word (16 bits) to the
262         card's nvram.  Used by the above routine.
263
264     D.  Globals
265
266         All global variables are inside a global structure named INF_3C90X.
267         So, wherever you see that structure referenced, you know the variable
268         is a global.  Just keeps things a little neater.
269
270     E.  Enumerations
271
272         There are quite a few enumerated type definitions for registers and
273         so forth, many for registers that I didn't even touch in the driver.
274         Register types start with 'reg', window numbers (for SetWindow)
275         start with 'win', and commands (for IssueCommand) start with 'cmd'.
276         Register offsets also include an indication in the name as to the
277         size of the register (_b = byte, _w = word, _l = long), and which
278         window the register is in, if it is windowed (0-7).
279
280     F.  Why the 'a3c90x' name?
281
282         I had to come up with a letter at the beginning of all of the
283         identifiers, since 3com so conveniently had their name start with a
284         number.  Another driver used 't' (for 'three'?); I chose 'a' for
285         no reason at all.
286
287 Addendum by Jorge L. deLyra <delyra@latt.if.usp.br>, 22Nov2000 re
288 working around the 3C905 hardware bug mentioned above:
289
290 Use this floppy to fix any 3COM model 3C905B PCI 10/100 Ethernet cards
291 that fail to load and run the boot program the first time around. If
292 they have a "Lucent" rather than a "Broadcom" chipset these cards have
293 a configuration bug that causes a hang when trying to load the boot
294 program from the PROM, if you try to use them right out of the box.
295
296 The boot program in this floppy is the file named 3c905b-tpo100.rom
297 from Etherboot version 4.6.10, compiled with the bugfix parameter
298
299                         CFG_3C90X_BOOTROM_FIX
300
301 You have to take the chip off the card and boot the system once using
302 this floppy. Once loaded from the floppy, the boot program will access
303 the card and change some setting in it, correcting the problem. After
304 that you may use either this boot program or the normal one, compiled
305 without this bugfix parameter, to boot the machine from the PROM chip.
306
307 [Any recent Etherboot version should do, not just 4.6.10 - Ed.]