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, and to Andreas Kemnade
for their contributions 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 or 2.6 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

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.
    . Ad-Hoc mode works.
    . The card now resumes from hibernation (aka suspend to disk).

What doesn't works:
*******************
    . Not all firmware versions are supported. To my knowledge :
	version	    where?	works?
        5.00.01	    cisco	yes
	5.00.03	    cisco	yes
	5b00.08	    OEM ?	yes
	5.02.20	    cisco	no
	5.20.17	    cisco	no
	5.20.17	    cisco	no
	5b30.11	    OEM ?	no
	5.30.17	    cisco	no
      
      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. With these recent
      firmwares, the driver is successfully loaded, it accepts commands, its
      state can be queryied via the /proc filesystem, but for an unknown 
      reason, it doesn't associate to the access point in managed mode.

    . monitor mode doesn't work.

    . stability issue : this driver is not stable, I made my best to improve
      its robustness, but I didn't succeed yet. Maybe that's a buggy firmware
      issue, maybe that's a problem in the code of the driver, I don't know. 
      Anyway, I diagnosed two types of crashes :

        - type 1 : the card looses association with the access point, and
	reports a linkstat value of 0x8001. When this happens, you can safely
	restart the network interface (/sbin/ifdown eth1 ; rmmod airo_mpi ; 
	modprobe airo_mpi ; <config wireless params> ; <config ip
	parameters>), and the card should restart finely.

	- type 2 : the card timeouts on commands, and reports 'Could not 
	clear command register' in your log. When this happens, the only
	possibility to restart the network interface is to power the card
	off : do the following steps to avoid a reboot :
	      - ifconfig eth1 down
	      - rmmod airo_mpi
	      - suspend and resume the laptop (do not suspend it before 
	        unloading the driver)
	      - modprobe airo_mpi
	      - do a reconfiguration of the wireless/network parameters.
	
      After a huge amount of tests, it seems to me that the card becomes 
      more unstable when :
	    - it handles a large amount of traffic
	    - card RID are often requested (status, config, stats). 
      So if you want to improve stability of the driver, you can try to 
      decrease the RID accesses frequency, by shutting down the apps that 
      often query the card status (wireless monitor apps for example). I know
      this is a bad solution, because this driver implements the wireless
      extensions at the difference of the cisco driver, and I just encourage
      you not to use these extensions too much...

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).
    . airo_mpi-20031108.tar.gz
	- Peter Johanson improved the Makefile. It should now compile with
	  the 2.6 kernel too.
	- tested on Fedora Core 1 sucessfully.
    . airo_mpi-20031203.tar.gz
        - Merged airo.c changes (from kernel 2.4.23) : crypto API for MIC
	  (untested), airo_thread() new event.
	- Fixed locking problem reported by Andreas Kemnade.
	- Fixed a bug with FLAG_RADIO_MASK in enable_MAC(). Possible cause
	  of problem with Ad-Hoc mode. 
	- Removed debug code related to locks. too verbose.
	- Added profiling code.
	- Integrated back features from the Cisco driver :
	    - tx/rx counts are computed by the driver and not requested
	      from the card anymore (useless RID access avoided)
	    - MAC enable/disable : added a status variable
	    - issuecommand : imported code from the cisco driver. adapted
	      timings.
	- Fixed a race condition in airo_pci_resume(). Hibernation now 
	  seems to work.
	- Do not query wireless stats from airo_thread(), as it blocks the
	  thread from transmiting packets, while the card is queryied the RID
	  stats and RID status.
	- Disabled the flashcard related code
        - Be sure to compile with gcc32 (make CC=gcc32) on Fedora Core 1.

$Id: airo_mpi.HOWTO.txt,v 1.21 2003/12/04 10:45:36 bellet Exp $
