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).
    . stable, at last ?

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.

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-20031204.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.
    . airo_mpi-20031216.tar.gz
        - applied a patch from Christophe Saout.
	- applied a patch from Andreas Kemnade.
	- removed txreclaim(), airo_kick(), and airo_clear(). txreclaim seems
	  to be the function that caused the instability of the card. The
	  anticipated access to the card TX descriptor before putting the
	  data into the transmit buffer was not required, and moreover, under
	  some circumstances caused a complete corruption of the registers
	  of the card. 
	- added some more conditionnal code for debugging purpose.
	- shortened the timeout when resetting the card (used the same
	  value than the airo.c driver).
	- do not ack the EV_CMD interrupt in the interrupt handler. This
	  interrupt is acked in the issuecommand() function already.
	- do not mask interrupts in the interrupt handler.
	- cleaned the issuecommand() function (code mostly taken 
	  from airo.c):
	    - removed the "wait for no busy" stuff.
	    - removed the kick and clear function. 
	    - removed the spinlock protecting this function.
	    - added a call to schedule(), to not slow down the interrupt
	      processing, while we're issuing a command. The card can
	      handle both in parallel.
	- fixed the problem in the apm resume callback, when the
	  interface is not closed before suspend. The call to enable_MAC
	  and disable_MAC depends on the status of the mac.
	- airo_transmit isn't handled by the thread, because packet 
	  transmit and other thread activities can be processed in parallel.
	  For example, the time comsuming stats RID query shouldn't block
	  the transmission of the packet to the card.
    . airo_mpi-20031217.tar.gz
	- fixed the installation location
	- clear the EV_CMD flag before issueing a new command.
    . airo_mpi-20031220.tar.gz
	- the driver no longer taints the 2.6 kernel.
	- removed the spinlock in airo_ioctl()
	- removed the call to schedule() in issuecommand() for 2.6
	- merged a small patch from airo.c in the 2.6 tree.

$Id: airo_mpi.HOWTO.txt,v 1.25 2003/12/20 09:18:21 bellet Exp $
