readme

Linux Wireless LAN Project 的目标是开发一个完整的

Linux WLAN package
version 0.3.4

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
Please refer to the THANKS file in this directory for a list of contributors.

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, visit our Linux WLAN web site:
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.2.9 & 2.2.12
   - pcmcia-cs version 3.0.9 & 3.0.14

It currently doesn't support 2.0.x kernels at all.

PACKAGE CONTENTS
Enclosed in this package is the code for a PCMCIA device driver module
(am930_cs.o) and and ISA PnP driver module (am930_isa.o), a control 
utility (wlanctl), a man page for the utility (wlanctl.8), a 'sniffer'
utility (wlandump) and some samples to help you set up your PCMCIA and 
rc.XX 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
NOTE: In all the following examples, 'X.X.X' represents the version
	number of the Linux WLAN package you are installing. Substitute
	the version number for 'X.X.X' in all the following examples.

NOTE 2: The following instructions are for PCMCIA users (the most common
	type).  For instructions on using the ISA PnP driver, see README.isa.

1)	Make sure you're running one of the tested kernels or later.
2)	If your building for PCMCIA, 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-X.X.X.tar.gz

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

		ln -s linux-wlan-X.X.X wlan

5)	Change to the wlan directory:

		cd linux-wlan-X.X.X

			-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_SRC symbol contains the root 
	directory of your Linux kernel source tree. Make sure the PCMCIA_SRC
	symbol contains the root directory of your PCMCIA package
	source tree. 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.

	The following is a sample config.mk file:
	-----------------------------------------
	LINUX_SRC=/usr/src/linux
	PCMCIA_SRC=/usr/src/pcmcia-cs-3.0.12
	MODULES_DIR=/lib/modules/2.2.5-15
	INST_EXEDIR=/sbin
	DESTDIR=
	MAKE_ISA=n
	MAKE_CS=y

	The following are what the variables represent:
	-----------------------------------------------
	LINUX_SRC: directory containing your Linux kernel source code
	PCMCIA_SRC: directory containing your pcmcia source code
	MODULES_DIR: directory where the compiled wlan driver module file(s)
	             will be installed
	INST_EXEDIR: directory to install all Linux wlan utility programs, such
	             as wlanctl and wlandump
	DESTDIR: optional directory prefix prepended to all install directories
	MAKE_ISA: compile the Linux wlan IEEE802.11 driver to support
	          an ISA wireless network card; the value to set this variable
	          is either 'y' or 'Y' (e.g. MAKE_ISA=y) to compile the driver
	          to include ISA support or 'n' or 'N' (e.g. MAKE_ISA=n) to
	          exclude ISA support in the compiled driver

	          NOTE: if you're building only for ISA support (i.e.
			  MAKE_ISA=y, MAKE_CS=n), you may set the 
			  PCMCIA_SRC variable to the empty string, 
			  i.e. PCMCIA_SRC=
	MAKE_CS: compile the Linux wlan IEEE802.11 driver to support
	          a PCMCIA wireless network card; the value to set this variable
	          is either 'y' or 'Y' (e.g. MAKE_CS=y) to compile the driver
	          to include PCMCIA support or 'n' or 'N' (e.g. MAKE_CS=n) to
	          exclude PCMCIA support in the compiled driver

7)	Now, compile the driver using the following commands:
	
		make clean
		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 following
	files found in the 'scripts' subdirectory under
	/usr/src/linux-wlan-X.X.X:
		1]	wlan,
		2]	wlan.config and
		3]	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 to
	include the wlan.config file:

	EXAMPLE:
		1]	Copy wlan.config to PCMCIA directory:

			cp /usr/src/wlan/scripts/wlan.config /etc/pcmcia

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

			vi /etc/pcmcia/config

		3]	Add the following line after the comments at the top
			of the config file and save the 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
9b) wlan.opts settings
The wlan.opts file (and rc.wlan) contain a bunch of variable assignments that
affect how the card config script will set up your card.  Here's a quick list:

SCAN_SSID	If you wish to scan for a specific ssid, put it here.
		Leaving it blank means 'scan for all SSIDs'.
DESIRED_SSID	Which SSID am I interested in joining? (if it exists).
SCAN		(yes|no) Perform the scan or not.  If this station is always
		responsible for _creating_ its BSS, you can say no here.
SCAN_BSSID	If you want to scan for a specific BSSID, put it here.
		ff:ff:ff:ff:ff:ff is the wildcard.
SCAN_BSSTYPE	(both|ind|infr) What types of BSSs to scan for?
SCAN_TYPE	(active|passive) Only active is supported right now.
SCAN_STARTCH	First channel to scan.
SCAN_ENDCH	Last channel to scan.
SCAN_TIMEPERCHANNEL	Amount of time in Kusec to spend scanning each channel.
CREATEBSS	If the DESIRED_SSID isn't found, should we create a BSS?
CREATE_SSID	If CREATEBSS is true, use this SSID for the new BSS.
CREATE_CHANNEL	If CREATEBSS is true, use this channel for the new BSS.
CREATE_BCN_INT	If CREATEBSS is true, use this beacon interval for the new BSS.
SNIFONLY	Is this machine a sniffer only? (not a general use station).
		If so and the BSS is infrastructure, we skip the authentication
		and association.
P80211_CONVERSION	(encapsulation|rfc1042|802.1h) Set to match the other
		stations.
PRIVACY		Always set to no, WEP is unsupported (see README.wep)

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)
> <[e-mail]> on the EtherJet driver.  The IBM Thinkpad
> 'fix' for the PRISM driver was done by Robert Coie <[e-mail]>.


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


	-- Mark Mathews
		[e-mail]