This directory contains device drivers for the 3Com 3c900, 3c905 and 3c905B Etherlink XL and Fast Etherlink XL ethernet adapters. There are separate drivers for FreeBSD 3.0-current and FreeBSD 2.2.x (should work with 2.2.5, 2.2.6 and 2.2.7). Both versions support the same devices and offer the same performance. Note that this driver has been integrated into the FreeBSD-current (3.0) and FreeBSD 2.2.x and is now standard. It should appear in all the latest snapshots and will be in 2.2.8 and later releases. I will continue to keep the copies of the drivers in this directory up to date as a convenience to users with older releases who still want 3c905B support. The rcsids in the drivers here should sync up with those in the CVS repository at some point. Here are instructions on how to add the XL driver to an existing FreeBSD system: - Download the version of if_xl.c and if_xlreg.h that goes with your version of FreeBSD. The 3.0 directory contains code for FreeBSD 3.0. The 2.2 directory is for FreeBSD 2.2.5, 2.2.6 and 2.2.7. - Make sure you have the kernel source unpacked under /usr/src. - Copy if_xl.c and if_xlreg.h to /sys/pci. - Edit /sys/conf/files and add a line that says: pci/if_xl.c optional xl device-driver - Edit your kernel config file (e.g. /sys/i386/conf/GENERIC) and add a line that says: device xl0 - The xl driver supports some of the same NICs that the vortex driver (if_vx) does, namely the 3c900 and 3c905 NICs. However, the vx driver supports 3c59x NICs that the xl driver does not. If you want to use the xl driver _instead_ _of_ the vx driver, then remove the line that says: device vx0 from your config file. If you need the vortex driver for a 3c59x adapter and want to use the vortex driver _in_ _addition_ _to_ the xl driver, then edit /sys/pci/if_vx_pci.c and comment out the portions of the probe routine that check for the Fast Etherlink XL PCI device IDs. If you're not using the vortex driver now and don't intend to, then just forget this step. - config and compile a new kernel - copy the kernel to the root directory, then reboot. Interfaces should be detected as xl0, xl1, etc... You should edit /etc/rc.conf to have the interface brought up automatically when the system boots. If you experience problems with the driver, please send mail to wpaul@skynet.ctr.columbia.edu with the following information: - The version of FreeBSD you're using - The rcsid string from the version of if_xl.c you're using - The type of system you have (CPU type and speed) - The exact type of NIC you have - Whether you have an add-in PCI card or if the NIC is built into your system somehow (integrated on motherboard or docking station) - A copy of the dmesg output for your system showing the messages where your card is probed - A complete description of the problem, with error messages if any. - Optionally, boot your system with the -v flag to obtain verbose boot messages and include all the messages related to the xl device. The copies of the code here may be updated to add fixes. Notices of new versions will be posted to hackers@freebsd.org. Questions which may be frequently asked: Q: "I have a dual-boot machine with Win95/98/NT and a 3c905B adapter; whenever I shut down Windows and warm boot (i.e. reboot without powering off) to load FreeBSD, my 3c905B isn't detected properly, and there's this message about some D3 power mode. What's going on?" A: The 3c905B supports power management, which means it can be placed in a low power mode. In this mode (called the D3(hot) mode), the 3c905B loses all its PCI configuration data, except the state of its power state register. A PCI BIOS that supports power management is supposed to put the 3c905B back into the full power (D0) state before trying to configure the card, but some BIOSes don't. When Lose95/98/NT shut down, they place the 3c905B in the D3(hot) low power mode. If your BIOS doesn't bring it out of this mode, it won't be able to configure it properly. FreeBSD depends on the PCI BIOS to configure PCI devices correctly and can't do anything with the adapter when it's in this state, other than try to switch it back to D0 mode. But once it does that, it can't reconfigure the card. There are a few things you can do: - After Lose95/98/NT shuts down, power off your system and then turn it back on. This should cause the 3c905B to be reset correctly. - After FreeBSD complains about the card being in the D3 state and sets it to the D0 state, warm boot the system and load FreeBSD one more time. This time, it should be configured and detected correctly. - Remove Lose95/98/NT from your system and use only FreeBSD. This is the recommended solution. :) Q: "But when I reboot with Windows, the card works fine! Can't you fix it? Waaaah!" A: I have added code to attempt to fix this problem, however I can't easily confirm that it works because the PCI BIOS in my test machines seems to reset the NICs back to full power mode at startup, and since the chips are built onto the motherboard, I can't move the adapter to another machine. The driver will now attempt to preserve the PCI settings during the attach phase and properly reprogram the NIC after setting it back to full power mode. This should work provided I'm reading the manual correctly: I _think_ that the PCI configuration information is lost during the transition from the D3(hot) state back to D0, but the register contents are still valid prior to switching modes. This means that it should be possible to save the configuration right before resetting the power state and then write it back afterwards. You'll still see the warning about switching modes, but the card should work. If anyone can confirm whether this works or not, please let me know. Q: "When I boot FreeBSD with my 3c900 card, it selects the wrong media type. How can I fix it?" A: The driver probes the transceiver selection from the EEPROM and uses that as the default media. For 3c900-TP cards, the only possible media is 10baseT/UTP, so it can't get it wrong there. But for the 3c900-COMBO cards, it may be one of TP, BNC or AUI. The 3c900 NICs don't really have a built-in autoselection mechanism like the 3c905B or 3c905-TX, which means it's up to the driver to figure out what media to use by checking link states and transmitting test packets. This is akward to do inside the kernel, so the driver just settles for the transceiver type specified in the EEPROM and ignores the 'autoselect' setting. However, the EEPROM setting may not be the one you want. If you want to have the driver switch the card to a different media, you can use the following commands (note that you must be root): # ifconfig xl0 media 10baseT/UTP # ifconfig xl0 media 10base2/BNC # ifconfig xl0 media 10base5/AUI You can put the media selection options in the 'interfaces' section of your rc.conf file, or specify it as an ifconfig option to the FreeBSD installation program (sysinstall). Q: "What kind of performance can I expect from the 3c905B?" A: Well, "unfortunately," the only test systems I have with 3c905B adapters are two Dell Optiplex GX1 systems with 400Mhz PII CPUs. (The 3c905B chips are integrated onto the motherboard.) These are very fast machines, which means I tend to see very fast performance. The two machines are linked together through an Intel 550 routing switch. At 100Mbps in full duplex mode, I can get TCP transfers of up to 11.3MB/sec using the ttcp program. The netperf utility reports throughput of about 93 Mbps (megabits per second). This is with a FreeBSD 3.0 CAM snapshot. Performace with the 3c905-TX, which uses an external NS 83840A PHY, should be comparable, if maybe a tiny bit slower. Q: "What's the difference between the xl driver and the vx (vortex) driver?" A: The vortex driver was written for the 3c59x "vortex" chips (which I think are on the Fast Etherlink III adapters). The vortex chips work very much like the 3c509 Etherlink III adapters in that they support a programmed I/O (PIO) mechanism for transfering packets to and from the NIC's memory. The PIO mechanism is fairly slow: to read a received packet for example, you have to read the packet 32-bits at a time from a FIFO register. Even a well written driver would have trouble getting decent performance at anything other than 10Mbps data rates. After the 3c59x chips were released, 3Com introduced a new series called the 3c90x, which started with the 3c900 and 3c905 NICs. These are known as the "boomerang" NICs. The 3c90x chips also have a PIO interface that works just like the vortex interface, which allows the old vortex driver to support these boards. However the vortex driver works poorly with adapters like the 3c905-TX which supports 100Mbps data rates. The 3c90x adapters also support a bus master DMA packet transfer mechanism in addition to the PIO mechanism which is much more efficient. With the DMA mechanism, the adapter copies packets into and out of the host's memory without requiring the host CPU to do any work. (In effect, the chip does the packet copying for the host, which saves the host from having to do tedious bcopy()s.) Later, 3Com introduced a new revision of the 3c905 called the 3c905B or "cyclone." The 3c905B no longer supports the PIO packet transfer mechanism. Consequently, the vortex driver won't work with these NICs. It can detect the NIC and even initialize it, but it can't do any sending or receiving. The xl driver uses the bus master DMA packet transfer mechanism available with the 3c900 and later NICs. Because the 3c900, 3c905 and 3c905B NICs support the same mechanism, the driver works with all three adapters, with only a couple of board-specific tweaks. Note what while the vortex driver will work with the 3c905 series of adapters, it doesn't know anything about switching the card into full-duplex mode or performing autonegotiation. I haven't tested it extensively, however I doubt that it works well (if at all) at 100Mbps. Q: "I have a Dell Latitude laptop with a docking station that has a 3c905-TX adapter built-in, and when I boot FreeBSD, the xl driver complains loudly that the media options bits aren't set. What does this mean?" A: The 3c90x adapters have a media options register that's supposed to tell you what kind of media is available on the card. This includes things like 10Mbps support, 100Mbps support, 100baseT4 support, externally-attached MII devices, etc. For the 3c905B, this register is loaded from the EEPROM. For the 3c905, the media options bits are hard-wired depending on how some of the chip's pins are connected when the adapter is manufactured. With the Dell Latitude docking station, the integrated 3c905's media options bits are all 0, which, according to the 3Com 3c90x technical manual, isn't supposed to happen. I'm not sure why it's set up like this. My best guess is that it's a manufacturing defect on Dell's part. When faced with this situation, the driver attempts to guess the media types based on the adapter type, according to its PCI device ID. Because I consider this to be a serious kludge, I added noisy warning messages to announce what's going on. If the messages bother you, you can always edit them out.