| |
| Instructions for use of the 3C90X driver for EtherBoot |
| |
| Original 3C905B support by: |
| Greg Beeley (Greg.Beeley@LightSys.org), |
| LightSys Technology Services, Inc. |
| February 11, 1999 |
| |
| Updates for 3C90X family by: |
| Steve Smith (steve.smith@juno.com) |
| October 1, 1999 |
| |
| ------------------------------------------------------------------------------- |
| |
| I OVERVIEW |
| |
| The 3c90X series ethernet cards are a group of high-performance busmaster |
| DMA cards from 3Com. This particular driver supports both the 3c90x and |
| the 3c90xB revision cards. 3C90xC family support is not yet available. |
| |
| Here's the licensing information: |
| |
| This program Copyright (C) 1999 LightSys Technology Services, Inc. |
| Portions Copyright (C) 1999 Steve Smith. |
| |
| This program may be re-distributed in source or binary form, modified, |
| sold, or copied for any purpose, provided that the above copyright message |
| and this text are included with all source copies or derivative works, and |
| provided that the above copyright message and this text are included in the |
| documentation of any binary-only distributions. This program is distributed |
| WITHOUT ANY WARRANTY, without even the warranty of FITNESS FOR A PARTICULAR |
| PURPOSE or MERCHANTABILITY. Please read the associated documentation |
| "3c90x.txt" before compiling and using this driver. |
| |
| |
| II FLASH PROMS |
| |
| The 3c90xB cards, according to the 3Com documentation, only accept the |
| following flash memory chips: |
| |
| Atmel AT29C512 (64 kilobyte) |
| Atmel AT29C010 (128 kilobyte) |
| |
| The 3c90x cards, according to the 3Com documentation, accept the |
| following flash memory chips capacities: |
| |
| 64 kb (8 kB) |
| 128 kb (16 kB) |
| 256 kb (32 kB) and |
| 512 kb (64 kB) |
| |
| Atmel AT29C512 (64 kilobyte) chips are specifically listed for both |
| adapters, but flashing on the 3c905b cards would only be supported |
| through the Atmel parts. Any device, of the supported size, should |
| be supported when programmed by a dedicated PROM programmer (e.g. |
| not the card). |
| |
| To use this driver in such a PROM, visit Atmel's web site and download their |
| .PDF file containing a list of their distributors. Contact the distributors |
| for pricing information. The prices are quite reasonable (about $3 US each |
| for the 64 kB part), and are comparable to what one would expect for |
| similarly sized standard EPROMs. And, the flash chips are much easier to |
| work with, as they don't need to be UV-erased to be reprogrammed. The |
| 3C905B card actually provides a method to program the flash memory while |
| it is resident on board the card itself; if someone would like to write a |
| small DOS program to do the programming, I can provide the information |
| about the registers and so forth. |
| |
| Better yet, for those using Linux it might be even better if the programming |
| could be done while Linux is running, either via a modification to the 3c59x |
| driver or via some other program/driver. That way, a system administrator |
| on a private network could update all the NC flash images from a centrally |
| managed location. |
| |
| |
| III GENERAL USE |
| |
| Normally, the basic procedure for using this driver is as follows: |
| |
| 1. Run the 3c90xcfg program on the driver diskette to enable the |
| boot PROM and set it to 64k or 128k, as appropriate. |
| 2. Edit Config (in the src-32 directory) and define the |
| 90X_SIGNATURE for your particular adapter (model numbers and |
| corresponding values are listed in the file) |
| 3. Build the 3c90x.fd0 floppy image with possibly the value |
| CFG_3C90X_XCVR defined to the transceiver type that you want |
| to use (i.e., 10/100 rj45, AUI, coax, MII, etc.) |
| 4. Run the floppy image on the PC to be network booted, to get |
| it configured, and to verify that it will boot properly. |
| 5. Build the 3c90x.rom or 3c90x.lzrom PROM image and program |
| it into the flash memory chip. |
| 6. Put the PROM in the ethernet card, boot and enable 'boot from |
| network first' in the system BIOS, save and reboot. |
| |
| Here are some issues to be aware of: |
| |
| 1. A picky BIOS that may work better with NO_PNP_PCI_HEADER |
| defined to boot the prom image. |
| 2. The possible need to manually set the CFG_3C90X_XCVR value to |
| configure the transceiver type. Values are listed below. |
| 3. The possible need to define CFG_3C90X_PRESERVE_XCVR for use in |
| operating systems that don't intelligently determine the |
| transceiver type. |
| |
| Some things that are on the 'To-Do' list, perhaps for me, but perhaps |
| for any other volunteers out there: |
| |
| 1. Write a DOS- or Linux- based flash programmer for the 3c905b |
| card, so PROM users don't have to buy a $200 programmer.... |
| 2. Extend the driver to fully implement the auto-select |
| algorithm if the card has multiple media ports. |
| 3. Fix any bugs in the code <grin>.... |
| 4. Extend the driver to support the 3c905c revision cards |
| |
| Now for the details.... |
| |
| This driver has been tested on roughly 300 systems. The main two |
| configuration issues to contend with are: |
| 1. Ensure that PCI Busmastering is enabled for the adapter |
| (configured in the CMOS setup) |
| 2. Some systems don't work properly with the adapter when |
| plug and play OS is enabled; I always set it to "No" or |
| "Disabled" -- this makes it easier and really doesn't |
| adversely affect anything. |
| Roughly 95% of the systems worked when configured properly. A few |
| have issues with booting locally once the boot PROM has been installed |
| (this number has been less than 2%). Other configuration issues that |
| to check: |
| 1. Newer BIOS's actually work correctly with the network boot |
| order. Set the network adapter first. Most older BIOS's |
| automatically go to the network boot PROM first. |
| 2. For systems where the adapter was already installed and is |
| just having the PROM installed, try setting the "reset |
| configuration data" to yes in the CMOS setup if the BIOS isn't |
| seen at first. If your BIOS doesn't have this option, remove |
| the card, start the system, shut down, install the card and |
| restart (or switch to a different PCI slot). |
| 3. Make sure the CMOS security settings aren't preventing a boot. |
| |
| The 3c905B cards have a significant 'bug' that relates to the flash prom: |
| unless the card is set internally to the MII transceiver, it will only |
| read the first 8k of the PROM image. Don't ask why -- it seems really |
| obscure, but it has to do with the way they mux'd the address lines |
| from the PCI bus to the ROM. Unfortunately, most of us are not using |
| MII transceivers, and even the .lzrom image ends up being just a little |
| bit larger than 8k. |
| |
| So, the solution that I've used is to internally set the card's nvram |
| configuration to use MII when it boots. The 3c905b driver does this |
| automatically. This way, the 16k prom image can be loaded into memory, |
| and then the 3c905b driver can set the temporary configuration of the |
| card to an appropriate value, either configurable by the user or chosen |
| by the driver. |
| |
| The driver should choose an appropriate transceiver on the card. However, |
| if it doesn't on your card or if you need to, for instance, set your |
| card to 10mbps when connected to an unmanaged 10/100 hub, you can specify |
| which transceiver you want to use. To do this, build the 3c905b.fd0 |
| image with -DCFG_3C905B_XCVR=x, where 'x' is one of the following |
| values: |
| |
| 0 10Base-T |
| 1 10mbps AUI |
| 3 10Base-2 (thinnet/coax) |
| 4 100Base-TX |
| 5 100Base-FX |
| 6 MII |
| 8 Auto-negotiation 10Base-T / 100Base-TX (usually the default) |
| 9 MII External MAC Mode |
| 255 Allow driver to choose an 'appropriate' media port. |
| |
| Then proceed from step 2 in the above 'general use' instructions. The |
| .rom image can be built with CFG_3C90X_XCVR set to a value, but you |
| normally don't want to do this, since it is easier to change the |
| transceiver type by rebuilding a new floppy, changing the BIOS to floppy |
| boot, booting, and then changing the BIOS back to network boot. If |
| CFG_3C90X_XCVR is not set in a particular build, it just uses the |
| current configuration (either its 'best guess' or whatever the stored |
| CFG_3C90X_XCVR value was from the last time it was set). |
| |
| [[ Note for the more technically inclined: The CFG_3C90X_XCVR value is |
| programmed into a register in the card's NVRAM that was reserved for |
| LanWorks PROM images to use. When the driver boots, the card comes |
| up in MII mode, and the driver checks the LanWorks register to find |
| out if the user specified a transceiver type. If it finds that |
| information, it uses that, otherwise it picks a transceiver that the |
| card has based on the 3c905b's MediaOptions register. This driver isn't |
| quite smart enough to always determine which media port is actually |
| _connected_; maybe someone else would like to take on that task (it |
| actually involves sending a self-directed packet and seeing if it |
| comes back. IF it does, that port is connected). ]] |
| |
| Another issue to keep in mind is that it is possible that some OS'es |
| might not be happy with the way I've handled the PROM-image hack with |
| setting MII mode on bootup. Linux 2.0.35 does not have this problem. |
| I haven't tested anything else. The 3com documentation specifically |
| says that, at least with the card that I have, the device driver in the |
| OS should auto-select the media port, so other drivers should work fine |
| with this 'hack'. However, if yours doesn't seem to, you can try defining |
| CFG_3C90X_PRESERVE_XCVR when building to cause Etherboot to keep the |
| working setting (that allowed the bootp/tftp process) across the eth_reset |
| operation. |
| |
| |
| IV FOR DEVELOPERS.... |
| |
| If you would like to fix/extend/etc. this driver, feel free to do so; just |
| be sure you can test the modified version on the 3c905B-TX cards that the |
| driver was originally designed for. This section of this document gives |
| some information that might be relevant to a programmer. |
| |
| A. Main Entry Point |
| |
| a3c90x_probe is the main entry point for this driver. It is referred |
| to in an array in 'config.c'. |
| |
| B. Other Exported Functions |
| |
| The functions a3c90x_transmit, a3c90x_poll, a3c90x_reset, and |
| a3c90x_disable are exported functions that EtherBoot finds out about |
| as a result of a3c90x_probe setting entries in the nic structure |
| for them. The EtherBoot framework does not use interrupts. It is |
| polled. All transmit and receive operations are initiated by the |
| etherboot framework, not by an interrupt or by the driver. |
| |
| C. Internal Functions |
| |
| The following functions are internal to the driver: |
| |
| a3c90x_internal_IssueCommand - sends a command to the 3c905b card. |
| a3c90x_internal_SetWindow - shifts between one of eight register |
| windows onboard the 3c90x. The bottom 16 bytes of the card's |
| I/O space are multiplexed among 128 bytes, only 16 of which are |
| visible at any one time. This SetWindow function selects one of |
| the eight sets. |
| a3c90x_internal_ReadEeprom - reads a word (16 bits) from the |
| card's onboard nvram. This is NOT the BIOS boot rom. This is |
| where the card stores such things as its hardware address. |
| a3c90x_internal_WriteEeprom - writes a word (16 bits) to the |
| card's nvram, and recomputes the eeprom checksum. |
| a3c90x_internal_WriteEepromWord - writes a word (16 bits) to the |
| card's nvram. Used by the above routine. |
| a3c90x_internal_WriteEepromWord - writes a word (16 bits) to the |
| card's nvram. Used by the above routine. |
| |
| D. Globals |
| |
| All global variables are inside a global structure named INF_3C90X. |
| So, wherever you see that structure referenced, you know the variable |
| is a global. Just keeps things a little neater. |
| |
| E. Enumerations |
| |
| There are quite a few enumerated type definitions for registers and |
| so forth, many for registers that I didn't even touch in the driver. |
| Register types start with 'reg', window numbers (for SetWindow) |
| start with 'win', and commands (for IssueCommand) start with 'cmd'. |
| Register offsets also include an indication in the name as to the |
| size of the register (_b = byte, _w = word, _l = long), and which |
| window the register is in, if it is windowed (0-7). |
| |
| F. Why the 'a3c90x' name? |
| |
| I had to come up with a letter at the beginning of all of the |
| identifiers, since 3com so conveniently had their name start with a |
| number. Another driver used 't' (for 'three'?); I chose 'a' for |
| no reason at all. |
| |