Linux WL24xx Driver Installation Guide v.2 -------------------------------------- **************************** * 1. Introduction * **************************** This document describes how to install PLANET WL24xx series Wireless LAN Card on your Linux 2.0x system. For PCMCIA versions, please skip this file and refer PCMCIA.TXT instead. In addition to this document, you may need some other documentations from Linux. In the following chapter, I'll point them out. **************************** * 2. Before starting * **************************** What you should prepare: 1. A well installed Linux system (version 1.3.44 or above), contains kernel source code, and compiler. 2. A (or some) WL24xx Wireless LAN card(s). 3. WL24xx Wireless LAN card's Use's Manual. 4. The utilities come with the card. You may need additional documents available from Linux packages: 1. /usr/src/linux/README 2. /usr/doc/faq/howto/mini/Multiple-Ethernet.gz 3. /usr/doc/faq/howto/Ethernet-HOWTO.gz 4. /usr/doc/faq/howto/BootPrompt-HOWTO.gz 5. lilo, lilo.conf man pages **************************** * 3. Hardware installation.* **************************** First of all, you should install your WL24xx card properly in your PC. I suggest you to read the User's Manual first, and make something clear. (e.g. What's Ad-Hoc and Infrastructure mode, what's radio channel, and if you use Roaming or not...) If you think you have made everything ok, try to boot MS-DOS and run WLU.EXE to check if peer PCs could communicate with each other (through Link Quality Test). Cannot you run WLU.EXE? Ok! Don't worry, maybe your PC doesn't support PnP BIOS. You should refer Chapter 3 Hardware Installation in User's Manual, and "6. PnP BIOS Supporting" in this document. Now, two PCs may communicate with each other, hardware installation is completed. Note that: Link Quality Test does not activate IRQ, so even it works fine, it cannot approve IRQ is set correctly. **************************** * 4. Software installation.* **************************** (In the following text, I use Slackware as examples) Due to the implementation of Linux kernel, if we would like to add a driver into the system, we must re-complie the kernel even if the driver support 'module' mode. So, I hope you have installed the kernel source code in your system. (Of course, you should have. After installing the Linux package such as Slackware or RedHat, the first thing is to re-complie the kernel to remove unnecessary drivers and make the kernel compact). If you hadn't installed the kernel source, try to find one, and read the document in /usr/src/linux/README. It describes the procedure of making a new kernel very clearly. Let's make a kernel NOT supporting WL24xx cards first. If success, run lilo to install the new kernel (or if you use other loaders then do it by your ways) and reboot to make sure the new kernel works fine. It is for insurance. From now one, we try to add the WL24xx driver into the original kernel. In fact, there are only 2 files need to be patched. In order to make the patch works in the future, I do not provide a patch file for you. Instead, I point out which and where need to be patched. 1. copy wl*.o into /usr/src/linux/drivers/net, e.g. mcopy a:wl*.o /usr/src/linux/drivers/net 2. edit /usr/src/linux/drivers/net/Space.c, you may see a lot of statements like this: ------------------------------------------------------------------- static int ethif_probe(struct device *dev) { u_long base_addr = dev->base_addr; if ((base_addr == 0xffe0) || (base_addr == 1)) return 1; /* ENXIO */ if (1 #ifdef CONFIG_DGRS && dgrs_probe(dev) #endif #if defined(CONFIG_VORTEX) && tc59x_probe(dev) #endif ... ------------------------------------------------------------------- add two lines as follows: ------------------------------------------------------------------- extern int WL_Probe(struct device *); /*** Add this line ***/ static int ethif_probe(struct device *dev) { u_long base_addr = dev->base_addr; if ((base_addr == 0xffe0) || (base_addr == 1)) return 1; /* ENXIO */ if (1 && WL_Probe(dev) /*** Add this line ****/ #ifdef CONFIG_DGRS && dgrs_probe(dev) #endif #if defined(CONFIG_VORTEX) && tc59x_probe(dev) #endif ... ------------------------------------------------------------------- ********************************************************************** FOR THOSE WHO HAVE MORE THAN ONE ETHERNET CARDS: The WL_Probe() is made for probeing the WL24xx Wireless LAN card. We place the WL_Probe() IN FRONT OF other network cards to prevent other cards' drivers from returning invalid value that causes WL_Probe() cannot be executed. You had better try this first and verify if the card works correctly. If you insist that your original Ethernet card should be eth0, and the new installed WL24xx shall be eth1, then you may try to move the WL_Probe() just behinds your original Ethernet drivers. For example, if you had already installed a 3Com 3c595 card and its device name is eth0. After installing a WL24xx card, you wish 3c595 is still eth0 and WL24xx will be eth1. Try to move WL_Probe() just behinds tc59x_probe(). e.g. #if defined(CONFIG_VORTEX) && tc59x_probe(dev) #endif && WL_Probe(dev) /* Move to here */ But, as I mentioned before, take your own risk!! ********************************************************************** 3. Edit /usr/src/linux/drivers/net/Makefile, add a line : e.g. ------------------------------------------------------------------- ifeq ($(CONFIG_DGRS),y) L_OBJS += dgrs.o else ifeq ($(CONFIG_DGRS),m) M_OBJS += dgrs.o endif endif include $(TOPDIR)/Rules.make ------------------------------------------------------------------- to be ------------------------------------------------------------------- ifeq ($(CONFIG_DGRS),y) L_OBJS += dgrs.o else ifeq ($(CONFIG_DGRS),m) M_OBJS += dgrs.o endif endif L_OBJS += wl24.o wlapi.o wlpnp.o wlioctl.o /* Add this line */ include $(TOPDIR)/Rules.make ------------------------------------------------------------------- 4. Recompile the kernel, but DO NOT 'make dep' and 'make clean' again. e.g.: cd /usr/src/linux make zImage 5. Copy the kernel to where you want, and set lilo up. I STRONGLY suggest you to preserve your original kernel and add a new entry for the new one. Thus, if the new one hangs up, you may use the old one to boot up. e.g. In /etc/lilo.conf boot = /dev/sda delay = 300 vga = normal # force sane state ramdisk = 0 # paranoia setting image = /vmlinuz.WL24 # The new kernel support WL24xx append = "ether=0,0,eth1" # IF YOUR ETHERNET CARD > 1 root = /dev/sda5 label = WL24 read-only image = /vmlinuz.Original # The original kernel root = /dev/sda5 label = Original read-only ******************************************************************* NOTICE: If you install more than one Ethernet cards in your PC, you must read /usr/doc/faq/howto/mini/Multiple-Ethernet.gz ******************************************************************* 6. Run lilo, reboot your PC, and check if the new kenel could probe the WL24xx cards. e.g. lilo shutdown -r now **************************** * 5. Debugging * **************************** 1. Check if the WL_Probe() had been executed... root@linux:/# dmesg | more ... PART 1 ... eth1: Trying to probe WL24xx PnP card... wlpnp.c: Found Data port = 0x20b, by resource data wlpnp.c: nPnPRdPort = 0x20b wlpnp.c: Total 2 CNS found wlpnp.c: Find an CSN ID :0e 8c 00 28 2b dc 15 00 42 wlpnp.c: Find an CSN ID :68 6d 24 20 b3 10 00 e7 01 eth1: WL24xx PnP card probe at 0x280, IRQ 11 eth1: WL24xx at 0x280, IRQ 11, MAC address in EEPROM: 00:60:b3:10:00:e7 ... ... PART 2 ... eth1: Initialize WL24xx firmware... eth1: Channel 2, Speed 2 Mb/s, Infrastructure Mode, ESS ID = 123456 eth1: device opened If you do not find something like part 1, then the WL_Probe() didn't been excuted. What you should check first: Space.c (WL_Probe() sequence) lilo.conf If you do not find something like part 2, then the device didn't been opened. What you should check first: Do you have run 'ifconfig' for the card? (ref: /etc/rc*) 2. Check if the card is beening driven correctly... root@linux:/# ifconfig -a lo Link encap:Local Loopback inet addr:127.0.0.1 Bcast:127.255.255.255 Mask:255.0.0.0 UP BROADCAST LOOPBACK RUNNING MTU:3584 Metric:1 RX packets:18 errors:0 dropped:0 overruns:0 frame:0 TX packets:18 errors:0 dropped:0 overruns:0 carrier:0 coll:0 eth0 Link encap:Ethernet HWaddr 00:20:AF:D4:28:2C inet addr:203.67.40.216 Bcast:203.67.40.255 Mask:255.255.255.0 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:5571 errors:0 dropped:0 overruns:0 frame:0 TX packets:89 errors:0 dropped:0 overruns:0 carrier:0 coll:1 Interrupt:9 Base address:0xe000 eth1 Link encap:Ethernet HWaddr 00:60:B3:10:00:E7 inet addr:192.168.1.254 Bcast:192.168.1.255 Mask:255.255.255.0 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:4 errors:0 dropped:0 overruns:0 carrier:0 coll:0 Interrupt:11 Base address:0x280 If RX packets is zero, check if routing table set correctly. Then, check if interrupt set correctly. What you should check first: routing setup (man route) Ethernet card configuration (man ifconfig) WL24xx card setup (WLU.EXE, PC BIOS Setup, PnP) 3. Refer Q-A.TXT, it lists some checklist and guides you step by step. **************************** * 6. PnP BIOS Supporting * **************************** (If your PC BIOS supports Plug and Play feature, you may skip this chapter) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The WL24xx series cards do support PnP feature, so if your PC equiped with PnP BIOS (most of recently Pentium CPU motherboards, and some of 486 mother- boards), you will never worry about hardware jumps, IRQ, or I/O addresses. The card's PnP feature will automatically set up all of them and the device driver will make use of them when probed the card. If your PC does not support PnP BIOS, it's a little difficult. You may use the utility - WLJMP.EXE to set the IRQ and I/O address manunally. Of course, you must boot with MS-DOS first. After setting the IRQ and I/O address, you may still boot Linux and it will use the setting. But, if you reboot your PC by cold restart (means pressing the 'Reset' button in the front pannel or turn off the power and turn on), the setting will be lost, and you must run WLJMP again. It seems boring. So, the device driver provides the function of WLJMP too. You may assign the IRQ and I/O address by yourself and the device driver will try to find out a non-initialed WL24xx card and configure it. e.g. In lilo.conf append = "ether=11,0x280,eth0" # assign IRQ 11 and Port 0x280 for eth0 Meanwhile, only irq 10,11,12 and port 0x280 and up in steps of 0x40 are supported by the card. Note that, to not mess up the PnP feature, the device driver ONLY configures the WL24xx card which doesn't been assigned any IRQ and I/O address. So, if you have already use WLJMP to configure a card, the device driver will not configure it again, and the setting remains the value set by WLJMP. On the other hand, if you COLD reset the PC, the PnP configuration in the card will be cleared and the device driver will configure the card then. Remember to run lilo after modifying lilo.conf! :-) **************************** * 7. For Linux Hackers * **************************** Design Issues: The driver had been carefully designed with the following approachs to provide high performance and low overload in parallel tasking environment. 1. Prevent using cli() and sti() functions to slove critical section problem as possible. 2. Not doing busy waiting. 3. Only block the corresponded card's interrupt instead of sti() in ISR and related routines. 4. Lock the SUTRO (O/S within card) as short as possible if necessary. 5. Fully utilize Rx/Tx queueing buffer in card. (Rx/Tx is about 12K/12K) 6. Avoid additional memcpy between O/S and card. The object files are compiled with the following arguments: gcc -D__KERNEL__ -I/usr/src/linux/include -Wall -Wstrict-prototypes -O2 \ -fomit-frame-pointer -fno-strength-reduce -pipe -m386 -DCPU=386 -c \ wl24.c It should work for almost all configurations even if you use 386 CPU. Specification: 1. Fully function driver, multicast and promiscuous filter supported. 2. Ad-hoc, infrastructure, and roaming algorithm supported. 3. Error recovery function supported. 4. Support both Plug'n'Play and Non-Plug'n'Play machines.