Linux WLAN package
version 0.3.2
Mon Oct 25 01:41:55 EDT 1999

INTRODUCTION
This package contains a device driver and support utility for GNU/Linux
supporting the Harris Semiconductor reference design PRISM Direct Sequence 
Spread Spectrum (DSSS) Wireless LAN (WLAN) Adapters (PRISM cards for short).
This design uses the PCMCIA interface and form factor.

The PRISM card is an IEEE 802.11 compliant 2.4 GHz DSSS WLAN network 
interface card that uses the Harris PRISM chipset for it's radio functions
and the AMD PCNet-Mobile chip (AM79C930) for its Media Access Controller (MAC)
function.

CONTRIBUTORS
A couple of folks have contributed code, documentation, test results, and
kind words to this project.  Here's a short list:

   Robert Coie <irac@intrigue.com>
      Fixed 2.2.x kernel compatibility, my incorrect memory mapped i/o, and
	  identified a problem with a particular TI cardbus controller.
   Geoff Hibble <ghibble@adevice.com>
      Provided some script fixes and some truly useful test results.
   Yoshimura Haba <haba@melcoinc.co.jp>
      Identified the 'stale scan results' problem and tested with Japanese 
	  firmware.

HARDWARE
This driver has been tested to work with Harris part no. PRISM1BRD.  There
are a number of network hardware vendors who are shipping cards using a design
that is virtually identical to the Harris Card.  For a list of vendors and
their compatibility status with this driver, see
http://www.absoval.com/linux-wlan .

Stay tuned for test notes about various cards.

FIRMWARE
The AMD PCNet Mobile chip is contains a microcontroller core (an 80188) that
runs firmware stored in Flash memory on the card.  The firmware is field 
upgradeable and AMD publishes new versions on their web site 
http://www.amd.com .

This version of the driver was developed against the version 2.0 firmware
available from the AMD web site.  

To determine what firmware you have:
	- install the driver per the instructions below
	- insert your card
	- there should be a message printed on your console that looks something
	  like this:
	    Firmware Banner: PCnetMobile:v2.00 033098 API004
	- if you don't see the "v2.00" then you'll need to upgrade your firmware
	- download the firmware from AMD (or your card vendor) and follow the 
	  instructions
	  (if pressed, I'll put together a condensed set of instructions)

SOFTWARE VERSIONS
This version of the driver was tested using the following software:
   - Linux kernel version 2.0.36
   - Linux kernel version 2.2.3
   - pcmcia-cs version 3.0.9

PACKAGE CONTENTS
Enclosed in this package is the code for a PCMCIA device driver module 
(am930_cs.o), a control utility (wlanctl), a man page for the 
utility (wlanctl.8), and some samples to help you set up your PCMCIA 
configuration files.  NOTE: Depending on the distribution of Linux you're
using, some of the following example commands may not work.  However,
you simply modify the example for the distribution you're using.

GETTING STARTED
1) Make sure you're running one of the tested kernels or later.
2) Make sure you're running the tested PCMCIA package or later.
3) untar the wlan package into your /usr/src directory using the following 
	commands.

		cd /usr/src
		tar zxvf linux-wlan-0.3.2.tar.gz

4) This will create a linux-wlan-0.3.2 subdirectory under /usr/src. I usually
	make a symbolic link to this directory called wlan, just for
	convenience:

		ln -s linux-wlan-0.3.2 wlan

5) Change to the wlan directory:

		cd linux-wlan-0.3.2

			-OR- (if you created a soft link)

		cd wlan

6) Inspect the config.mk file. It contains the values of symbols used 
	during compilation. Make sure the LINUX symbol contains the root 
	directory of your Linux kernel source tree. Make sure the PCMCIA 
	symbol contains the root directory of your PCMCIA package
	source tree. Make sure that UTS_RELEASE contains the version of the
	kernel you're running.  All of the values for these symbols are
	dependent on the distribution of Linux you're using and the
	directories where the necessary files reside.

7) Now, compile the driver using the command:
	
		make all

8) If there are no errors (there may be a few warnings), use the following 
	command to install the files:

		make install

9) Next you need to update the PCMCIA package configuration (usually found 
	in the /etc/pcmcia directory).  This involves copying the three
	files found in the 'scripts' subdirectory under
	/usr/src/linux-wlan-0.3.2: wlan, wlan.config and wlan.opts.

	The file called wlan.config contains the entries that you should put
        in the file called 'config' in the PCMCIA directory (e.g.
	/etc/pcmcia/config).  The easiest way to include these entries in
	the PCMCIA config file is to copy wlan.config into the PCMCIA
	directory and add a line at the top of the PCMCIA config file:

	EXAMPLE:
		Copy wlan.config to PCMCIA directory:
			EXAMPLE:
			cp /usr/src/wlan/scripts/wlan.config /etc/pcmcia

		Using an editor of your choosing, open the config file
		in the PCMCIA directory:

			EXAMPLE:
			vi /etc/pcmcia/config

		Add the following line after the comments at the top,
		and save the config file:

			source ./wlan.config

	The wlan and wlan.opts files are shell scripts invoked when your
	card is inserted.  You shouldn't need to modify wlan, but wlan.opts
	has variable assignments that allow you to set up the IP address,
	gateway and 802.11 options the way you want. The wlan and wlan.opts
	files should be copied to the PCMCIA configuration directory and
	made executable so the cardmgr daemon can find them.

			EXAMPLE:
			cp /usr/src/wlan/scripts/wlan /etc/pcmcia
			cp /usr/src/wlan/scripts/wlan.opts /etc/pcmcia
			cd /etc/pcmcia
			chmod 755 wlan wlan.opts

10) Before using your wireless LAN card, you need to first stop and restart
	PCMCIA services:
			EXAMPLE:
			cd /etc/rc.d/init.d
			./pcmcia stop
			./pcmcia start
	Insert your wireless LAN card and cross your fingers.  :-)

IMPLEMENTATION NOTES
In prior releases, the driver used memory mapped i/o to access the memory
on the wlan card.  The driver now, by default, doesn't use memory mapping, it
only uses the i/o space to gain access to the card registers.  This should  
help for  those of you who have trouble finding a 32k region of unused 
physical address space (that's usable by your PCMCIA controller).

Memory mapped i/o is still available as an option.  To enable  it, add the 
following line to /etc/pcmcia/config.opts:

   module "am930_cs" opts "am930_use_mmio=1 am930_iodelay=0"


One user of an IBM Thinkpad (Robert Coie) using a TI1130 PCI cardbus bridge
found that reads and writes to the card via memory mapped i/o would only 
work reliably if done one byte at a time and with a delay between the accesses.
If you have a similar problem, you may adjust the delay value in the above
config.opts line.  Robert has provided the following note regarding his
observations:


> If you are having trouble using this driver with an IBM Thinkpad 760
> or 380 (or any other machine that uses a TI1130 PCI Cardbus bridge),
> try setting TICARDBUS=1 in config.mk.  This changes the way that
> memory-mapped IO access is performed in such a way as to avoid
> multibyte transfer operations, which appear to break on this hardware.
> 
> This was inspired by similar work done by Emilio (last name unknown)
> <emilio@siel.to.alespazio.it> on the EtherJet driver.  The initial
> implementation for the PRISM driver was done by Robert Coie
> <rac@intrigue.com>.


Don't forget to stop and restart PCMCIA services after any change to 
config.opts (in the PCMCIA directory)!


	-- Mark Mathews
		mark@absoval.com


