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 19I 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 41II 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 85III 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 223IV 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 287Addendum by Jorge L. deLyra <delyra@latt.if.usp.br>, 22Nov2000 re 288working around the 3C905 hardware bug mentioned above: 289 290Use this floppy to fix any 3COM model 3C905B PCI 10/100 Ethernet cards 291that fail to load and run the boot program the first time around. If 292they have a "Lucent" rather than a "Broadcom" chipset these cards have 293a configuration bug that causes a hang when trying to load the boot 294program from the PROM, if you try to use them right out of the box. 295 296The boot program in this floppy is the file named 3c905b-tpo100.rom 297from Etherboot version 4.6.10, compiled with the bugfix parameter 298 299 CFG_3C90X_BOOTROM_FIX 300 301You have to take the chip off the card and boot the system once using 302this floppy. Once loaded from the floppy, the boot program will access 303the card and change some setting in it, correcting the problem. After 304that you may use either this boot program or the normal one, compiled 305without 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.] 308