This is a minimalist documentation to help you to get your Cisco
mini-PCI wireless card working with the airo-linux driver. Thanks to Dan
Borello, Alexis de Lattre, Eric Covener and to Mike Hudson for their
contributions to this howto. Thanks to Peter Johanson for his contribution
to the code.

Background:
***********
Benjamin Reed and Javier Achirica are developping a driver for the
Aironet/Cisco cards at airo-linux.sourceforge.net. Recently, Benjamin
started to adapt the airo.c driver for the Cisco 350 miniPCI series,
using a GPL driver developped by Cisco. This new driver is called
airo_mpi.c. The Cisco driver doesn't implement the wireless extensions,
and uses instead an user-unfriendly proprietary GUI to setup the card,
which explain why airo_mpi.c was born. airo.c is merged into the
standard Linux kernel. But airo_mpi.c only lives in the sourceforge CVS
repository.

I improved the airo_mpi.c driver, but my modifications have not been
integrated yet. I will explain here how to install this modified
driver. 

Steps:
******
1.  Download the latest package airo_mpi-YYYMMDD.tar.gz (where YYMMDD 
    is the date of the release from http://bellet.info/~bellet/laptop/
    and unpack it. This tarball contains various files from the airo-linux
    driver project from Sourceforge CVS 
    http://sourceforge.net/projects/airo-linux

2.  According to your kernel version, I basically tested the following 
    situations :

    2.1. If you're running a RedHat 2.4 kernel:
         
	 - check that the kernel-source package RPM is installed, and
	   ideally not altered by a previous custom kernel compilation.
	   (use "rpm -V kernel-source" to verify it)
	 - compile and install the airo mpi driver with the usual :
	    cd airo_mpi-YYYMMDD
	    make && make install

    2.2. If you're running a vanilla 2.4 kernel, or a custom kernel :

	 - I suppose that you have enabled "Wireless LAN" in the kernel
	   configuration.
	 - just compile and install the driver with :
	    cd airo_mpi-YYYMMDD
	    make && make install

    2.3. If you're running a custom 2.6 kernel :

         - I suppose that your kernel tree is in /usr/src/linux
	 - I suppose that you have enabled "Wireless LAN" in the kernel
	   configuration.
	 - copy the airo_mpi.c file to /usr/src/linux/driver/net/wireless
	 - edit /usr/src/linux/drivers/net/wireless/Makefile and add this 
	   line :

	     obj-m += airo_mpi.o

	   (airo_mpi will be unconditionnaly built as a module)

	 - cd /usr/src/linux && make && make modules_install

3.  modprobe airo_mpi

4.  Enjoy your wireless card with wireless extensions. The wireless
    extensions is a set of configuration functions common to all wireless card
    drivers, and accessible via userland programs in the wireless-tools package.

What works:
***********
    . Cisco tools (ACU and bcard) are supported, but I firmly suggest you
      to stay away from the flashing utility. If you really want to flash
      your firmware on Linux, please use the original mpi350 driver from
      Cisco, and eventually report flashing problems to Cisco directly.
    . Supplementary information is available in /proc/driver/aironet/eth1/
    . scanning with "iwlist eth1 scan", setting ESSID, WEP encryption with 
      iwconfig.
    . Eric Covener reported that he's been able to associate to a 
      LEAP-enabled AP using the Cisco leapscript binary.
    . power management callbacks both with a 2.4 and a 2.6 kernel (acpi and
      apm). The configuration of the card is preserved, including wifi
      settings.

What doesn't works:
*******************
    . Not all firmware versions are supported. I have been told 5.x doesn't
      work as a whole. Mine is 5b00.08, and it works, YMMW. I've also read
      that version 5.00.03 and 5.00.01 work too, but I cannot confirm. The 
      particularity of version 5b00.08 is that --to my knowledge-- it's NOT 
      available for download, so if you choose to flash your firmware to
      anything else, you won't be able to revert this action in case of 
      problem.  
      
      There's currently no possibility to adapt the driver to these new 
      firmwares, because I have no documentation, and even the Cisco linux
      driver doesn't support these new firmwares too.

      Note : Under linux, you can determine the firmware version of your card
      by reading the pseudo file /proc/driver/aironet/eth1/Status. This
      requires that the driver successfully loaded to have access to this
      pseudo file. If your firmware version is not compatible with the driver,
      you'll just experience a kernel freeze/crash when you try to load the
      driver via modprobe (at step 6), or the impossibily to turn radio on
      according to other source. 

    . monitor mode doesn't work.

    . in some cases, the card silently stops working. When this occurs, it
      might be sufficient to rmmod the driver and to insmod it again. In other
      situations, the card reset occuring at insmod time can fail too.  Two 
      possibilities then : 1/ to issue a second reset command, with another 
      insmod or 2/ to suspend the laptop (apm --suspend), causing the card 
      to be powered off, and to try another modprobe when the laptop wakes 
      up.

What's untested:
****************
    . MICSUPPORT

Changes :
*********
    . airo_mpi.c-20030719 has been successfully tested be several persons,
      and is reported to work reasonably well.
    . airo_mpi.c-20030802
	- cosmetics changes to come back closer to the original airo.c file.
	- reenabled MICSUPPORT. 
	- backported changes from Javier Achirica in airo.c (late July on
	  LKML, and now in airo-linux CVS) [RFMON, noise report]
	- fixed an int overflow in statistics report in /proc.
	- fixed the way the signal quality is reported. It seems that the
	  meaning of the signal quality value in the status rid changed in
	  the mini-PCI card. I experienced the best sig quality when this 
	  value is small, and greater values represents a degradation of 
	  the signal.  So I decided to set up a linear transform between to 
	  arbitrary extrem values [10 .. 90] --> [0% .. 100%].
    . airo_mpi.c-20030926
	- backported modifications from Javier Achirica in airo.c (in 
	  airo-linux CVS) [the driver now uses a kernel thread to handle 
	  concurrency, and other small fixes]
	- cosmetics debug changes.
	- added spinlocks back again to protect airo_transmit(),
	  airo_interrupt(), issuecommand() and airo_ioctl() from
	  being interrupted. This later modification seems to solve the
	  stability issue experienced with previous versions of the driver. 
	  This one worked fine fore more than 15 hours, with a high bandwidth
	  sustained traffic.
    . airo_mpi.c-20031011
        - removed the supplementary wifi0 interface (for monitor mode). This 
	  one is currently useless, as monitor doesn't work (yet).
	- implemented suspend/resume callbacks, so the card can now hopefully
	  survive to an APM suspend to RAM event.
    . airo_mpi-20031023.tar.gz
	- packaged the various required files in the single tarball.
	- wrote a simple Makefile that should work with most 2.4 kernels. 
	  Added some magic to autodetect backported patches from the RedHat 
	  kernel.
	- Merged Peter Johanson's patch for kernel 2.6.
	- suspend/resume now works on kernel 2.6 (both with acpi and apm).

$Id: airo_mpi.HOWTO.txt,v 1.17 2003/10/23 15:57:25 bellet Exp $
