Prism54 Linux kernel driver
===========================

This is the Linux WLAN 802.11(a/b/g) kernel driver for
Prism Frisbee/GT/Duette/Indigo chipset cards (PCI and Cardbus).

Historic reference: 

* prism54 has been in 2.6 on since 2.6.4-bk2 (2.6.5 stable)
* prism54 has been in 2.4 since 2.4.28-pre1 (2.6.28 stable)

General minimum requirements:

* Kernel >= 2.6.5
* Kernel >= 2.4.23

* sysfs mounted
* hotplug

Translations
---------------

TBA

CVS install instructions:
--------------------------------------------------

You now have the option of either using a 2.4, 2.6 kernel or one of
our prism54.org CVS releases. If you are looking for stock kernel 
instructions search for the "Kernel requirements" section in this 
README. Following we explain how to use our CVS HEAD release. 

Download the latest CVS tarball, updated every 30 minutes:
http://prism54.org/pub/linux/snapshot/tars/prism54-cvs-latest.tar.bz2

Unpack the tarball :
tar jxvf prism54-cvs-latest.tar.bz2

Change to the prism directory:
cd prism54-cvs-latest

If you are running the target kernel, then you should be
able to do :

make clean modules
(and as root or with sudo)
make install
depmod -a

If the make complains about missing files, then you may need
to specify the source directory :

make KDIR=/path/to/kernel/linux-2.x.x/ clean modules
# as root
make KDIR=/path/to/kernel/linux-2.x.x/ install
depmod -a

Or if you have sudo:
sudo make KDIR=/path/to/kernel/linux-2.x.x/ clean modules install
# Lazy tip: I'm lazy so I just have an script in $HOME/bin/build that'll do:
# sudo make KDIR=/home/mcgrof/linux clean modules install
# sudo depmod -a
# and have /home/mcgrof/linux as a symlink to the latest kernel ;)

NOTE: If you are compiling the driver while running a different version of
the kernel then the one specified in KDIR, make install will copy it to the
wrong directory. You can solve this by doing:

make KDIR=/usr/src/linux-2.4.23 \
KMISC=/lib/modules/2.4.23/kernel/drivers/net/wireless/prism54 \
install


Driver status
-------------

First let me explain how our releases work. We've automated cvs 
snapshots for now, of both tarballs (aka tar) and Kernel patches 
(aka Kp) for the driver. These are the "snapshots"; they are updated
every half hour. After a while, we will hopefully have completed certain 
goals and made the driver more stable so we'll focus on releasing a 
"testing" series. Once those testing series go into effect, some will 
move into "stable". 

For now, I thought it'd be nice to keep you updated as to where we
stand with our latest release: (this is a review of our TODO really)

Almost there	-	SMP-safe
24Mbs		-	Throughput (tested with `bing localhost wifi-ap`)
Awaiting reply	-	Firmware
OK		-	Client Mode
OK		-	Master Mode (AP mode)
OK		-	Ad-Hoc
OK		-	Monitor / Promiscuous
OK		-	Kismet support
OK		-	Using new Linux Wireless API
OK		-	Platform independence
OK		-	Full Linux Wireless compat
OK		-	ACPI support
OK		-	WDS support
OK		-	WPA Version 1 AP  support through hostapd
Committed	-	WPA Version 1 STA support through wpa_supplicant
Eeeh		-	Documentation

WPA Note: WPA STA support does not yet work. Please wait until we complete its support.
WPA Note: WPA AP mode was just added. Please test. 

Recommendations
---------------

Since this driver is still in heavy development we recommend you
disable Modversioning support so that you can recompile the the latest
cvs module from the tarball (or directly from a cvs checkout) and use
that instead of having to patch and recompile your entire kernel over
and over again for future releases. 

Requirements
------------
 * kernel source tree (supported versions 2.4.23+ or 2.6.5+)
 * firmware: http://prism54.org/firmware/
 	mkdir -p /usr/lib/hotplug/firmware
	cd /usr/lib/hotplug/firmware
	# Firmware will be available soon, for now we
	# brought it down since we have no official license
	# for free redistribution
	wget http://prism54.org/firmware/isl3890
	# You may want to test older version of firmware 
	# if you have problems with the latest

 * compiler/binutils for kernel compilation
 * wireless-tools
 * firmware utilities (see below for distribution notes)
 * Kernel requirements:
	-----------------------------------------------------------
	v2.6:
 	CONFIG_EXPERIMENTAL: y
 	CONFIG_CLEAN_COMPILE: n
 	CONFIG_STANDALONE: n
		Code maturity level options  --->
			Prompt for development and/or incomplete code/drivers
			Select only drivers expected to compile cleanly
			Select only drivers that don't need 
				compile-time external firmware

	CONFIG_HOTPLUG : y
		Bus options (PCI, PCMCIA, EISA, MCA, ISA) --->
			Support for hot-pluggable devices

	CONFIG_FW_LOADER: m/y (either one will work) 
		Generic Driver Options  --->
			Hotplug firmware loading support	

	CONFIG_NET_RADIO : y
	CONFIG_NET_WIRELESS : y
		Device Drivers --->
			Networking Support --->
				Wireless Lan drivers

	For PCMCIA Cards and for cards that go over bus bridge
	(mini-pci that are routed) :

	CONFIG_PCMCIA && CONFIG_CARDBUS
		Bus options (PCI, PCMCIA, EISA, MCA, ISA) --->
			PCMCIA/CardBus support --->
			 PCMCIA/CardBus support (m or y)
			 CardBus yenta-compatible bridge support (m or y)
	
	You need sysfs mounted:
	mkdir /sys
	Add "none /sys sysfs defaults 0 0" to /etc/fstab
	mount /sys
		
	-----------------------------------------------------------
	v2.4
	CONFIG_EXPERIMENTAL: y
		Code maturity level options  --->
			 Prompt for development and/or incomplete code/drivers
	
	CONFIG_HOTPLUG: : y
		General setup --->
			Support for hot-pluggable devices

	CONFIG_FW_LOADER: m/y (either one will work) 
 		Library routines  --->
			Hotplug firmware loading support (EXPERIMENTAL)

	CONFIG_NET_RADIO : y
	CONFIG_NET_WIRELESS : y
		Network device support --->
			Wireless Lan (non-hamradio)

	For PCMCIA Cards :

	CONFIG_PCMCIA && CONFIG_CARDBUS
		General setup  ---> 
			PCMCIA/CardBus support  --->
				PCMCIA/CardBus support (m or y)
				[*]   CardBus support (Important!)
				
	-----------------------------------------------------------

	Note 1: For both 2.4 and 2.6 kernels, CONFIG_FW_LOADER will
		be enabled for you if you enable prism54, just in
		case you're lazy or if you forget.

	-----------------------------------------------------------

Compilation
-----------
 There are two ways to build the kernel driver:
 
 1) Patching 2.4 or 2.6 kernel source tree with the prism54 driver and
    compiling your kernel:
    * Grab 2.4 or 2.6 kernel source from kernel.org
    * Grab a 2.4 or 2.6 prism54 kernel patch (aka Kp to us):
    	http://prism54.org/pub/linux/snapshot/kernel/
    * cd linux-2.x/
    * bzip -cd /path/to/patch-2.x-prism54.patch.bz2 | patch -p1
    * Configure your kernel, the prism54 driver option is under:
    	v2.4: Network device support ---> 
		Wireless LAN (non-hamradio) --->
		Prism54 - Intersil Prism GT/Duette/Indigo PCI/Cardbus
	v2.6: Device Drivers --->
		Networking support --->
			Wireless LAN (non-hamradio) --->
			Prism54 - Intersil Prism GT/Duette/Indigo PCI/Cardbus

 2) Build the driver using your current kernel *with your current kernel source tree*:
    * Make sure your current kernel had CONFIG_FW_LOADER enabled, either as a module,
      or built in. If you have it as a module you should be able to:
    
    	modprobe firmware_class
    
    If you're not sure you have CONFIG_FW_LOADER support you can easily 
    check if you do this by doing:
    
    	ksyms -a | egrep "request_firmware|release_firmware|register_firmware"

    if you get output, then smile -- it means you do ;)
    
    * Get our prism54 driver tarball driver package (works for both 2.4 and 2.6! ;)
    	http://prism54.org/pub/linux/snapshot/tars/
	Note: snapshots people have reported most success with:
	* http://prism54.org/pub/linux/snapshot/tars/old/prism54-cvs20031111.tar.bz2
	* >= cvs20031129
    * Untar the package, cd in there	
    * Build the driver giving your kernel source tree path as an argument:
    	make KDIR=/usr/src/linux... clean modules
       (KDIR defaults to "/lib/modules/`uname -r`/build")
    * As root do:
    	make KDIR=/usr/src/linux... install

Firmware/hotplug
----------------

 This driver needs to upload the firmware to the NIC's ram on initialization
 it does so by requesting the firmware from the hotplug subsystem by asking
 for "isl3890" or "isl3877" depending on the hardware detected. We don't 
 actually know of any card using isl3877 so if you do let us know ;)

 Make sure the hotplug system has been setup properly, otherwise you
 might get errors in the kernel log stating that request_firmware() has failed

  *) does "cat /proc/sys/kernel/hotplug" show something like "/sbin/hotplug"?

  *) is /sbin/hotplug present?

  *) is the "firmware" agent is present (call /sbin/hotplug without
     any argument to show a list of available agents)

  *) have you copied the firmware file into the folder expected by
     firmware.agent? (usually "/usr/lib/hotplug/firmware/")

  *) for 2.6.x you need to mount sysfs!

Other issues not directly related to firmware uploading:

  *) [cardbus] have 'yenta_socket' module loaded in order to make cardbus
     card visible to the kernel pci subsystem? (check with lspci(1) whether
     device is visible to the kernel)

Access Point mode
-----------------
ifconfig eth0 up 
iwconfig eth0 mode Master

MAC based access control list in Master mode
------------------------------------------
It is based on a mac list and on a default policy. The possible policies are :
	* MAC_POLICY_OPEN =   0 : Accept every client.
	* MAC_POLICY_ACCEPT = 1 : Accept everybody except client whose MAC
				  is in the list.
	* MAC_POLICY_REJECT = 2 : Reject everybody except clients in the list.

By default, the card is in MAC_POLICY_OPEN, but you can change it with some
private ioctls :
	* iwpriv eth0 setPolicy x 
		 where x in {0,1,2}.
	* iwpriv eth0 getPolicy
Please note that setting the policy also clears the MAC list.

Here is how to manage the MAC list :
	* iwpriv eth0 addMac xx:xx:xx:xx:xx:xx
	* iwpriv eth0 delMac xx:xx:xx:xx:xx:xx
You can retrieve the list with :
	iwpriv eth0 getMac 

There are also 2 more commands to kick a client (given its MAC address) or to
kick everybody from your AP.
	* iwpriv eth0 kickMac xx:xx:xx:xx:xx:xx
	* iwpriv eth0 kickAll
Note : It only kicks clients. They are not banned and can reconnect immediately.

If you want to monitor your card doing its job, just use :
	iwevent

Access Point WPA support (NEW)
------------------------

	You have to download the development branch from hostapd project site at:
	http://hostap.epitest.fi/
	
	Be sure to make the .config file with CONFIG_DRIVER_PRISM54=y
	in the hostapd directory. This code is experimental. Please
	e-mail your results to hostap mailing list and CC prism54-devel list.

Access Point WDS Support (NEW)
------------------------

Here are instruction to enable WDS (repeater) mode on prism54

	0. Say YES to the kernel config option "Add WDS Support"

	1. Basic command

	iwpriv eth? setwds x

	set to 1 enable WDS, 0 disable
	set 0 also remove the WDS device created

	iwpriv eth? wdsadd xx:xx:xx:xx:xx:xx

	will add wdslink to mac address xx:xx:xx:xx:xx:xx
	only works before setwds 1

	iwpriv eth? wdsrem xx:xx:xx:xx:xx:xx
	will remove wdslink to mac address xx:xx:xx:xx:xx:xx
	only works before setwds 1


	2. Configuration

	the WDS will be created as ethx_y
	it means #y WDS link of device ethx
	it can be used as bridge device(send as other SA)
	or a normal device

	example:

	[card2(wire)]AP1[card1] -------AIR-------[card1]AP2[card2(wire)]

	card1 is eth0, card2 is eth1
	WDS link between card1 of AP1 and AP2

	on both APs:
	brctl addbr br0
	brctl addif br0 eth0_0
	brctl addif br0 eth1

	now there is a bridge between AP1 and AP2


	3.Special notes
	setwds bug:
	the WDS need to be set each dev up, but the driver did not
	record WDS peers in driver(for now),
	to let the WDS run normally, you must issue setwds 1 before device start(ifup),
	after ifup, finally wdsadd when device is up.
 
Client Mode
-----------
ifconfig eth0 up
iwconfig eth0 mode Managed # not necessary since this is the default

Scanning for APs
----------------
iwlist eth0 scanning

Monitor mode
------------
iwconfig eth0 mode monitor

If you want to use kismet edit your kismet.conf file (often in 
/usr/local/etc/kismet.conf) and put the following line :

source=prism54g,eth0,prism54

Note that kismet now has direct prism54 support. This should allow kismet
to put the device directly into monitor mode.

Then run kismet_server and kismet_client.

Distribution notes:
-------------------

 Debian: 
 	* hotplug (only unstable package has firmware.agent)
	* wireless-tools
	* pcmcia-cs (optional, you get commands such as cardctl)

--

 Gentoo:
 # ACCEPT_KEYWORDS="~x86" 
	* emerge pcmcia-cs-tools
 	* emerge sys-apps/hotplug 
	* etc-update

--

 Slackware & Mandrake:
 Slackware and Mandrake's hotplug packages do not have firmware.agent, 
 so go grab Debian's one: or just grab the firmware.agent file and 
 put it in /etc/hotplug and chmod +x:
 http://prism54.org/~hvr/firmware.agent

--

 Suse 9.0:
 Grab the firmware.agent file from http://prism54.org/~hvr/firmware.agent
 Put it into /etc/hotplug
 chmod +x /etc/hotplug/firmware.agent
 The driver works with the standard Suse kernel (2.4.21-99)
 See topic Tips & Tricks for 9.0 in the Prism Suse forum :
 http://prism54.org/forums/viewforum.php?f=28

 Suse 8.2:
 Update to a Suse kernel >= 2.4.21-99 or use vanilla kernel
 Grab the firmware.agent file from http://prism54.org/~hvr/firmware.agent
 Put it into /etc/hotplug
 chmod +x /etc/hotplug/firmware.agent
 Update Wireless Tools
 Go to http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html
 Grab the Version 27(-pre) release, unpack and do (as root) :
 cd wireless_tools.27
 PREFIX=/usr make install
 ldconfig

 See topic Tips & Tricks for 9.0 in the Prism Suse forum :
 http://prism54.org/forums/viewforum.php?f=28

 Suse 8.1 and older:
 Follow instructions for 8.2, This may work - is being looked into.

--

 Others:
 Just make sure you have a current hotplug package.
 You can grab Debian's one from:
 http://prism54.org/~mcgrof/hotplug.tar.gz

Bug reports
-----------

Bugs? What? No way! Yeah, just take into consideration that we haven't yet
released a stable driver or even a "testing" one. The driver should be 
*usable* but since all the releases are snapshots we can't gaurantee 
anything. 

Honestly, if you happen to detect some (software) bug in the driver
please take the time and act according to the following recommended 
procedures:

1. Might want to quickly check on IRC see if someone knows anything about
the issue first. Check with #prism54 on irc.freenode.net. Check then our
Bugziilla to see if you find the bug already reported.

2. Next, try the mailing lists. If you're *sure* it's a bug then send
an e-mail out to prism54-devel@prism54.org. If you're not sure if it is a bug
and would like insight on the issue send an e-mail out to 
prism54-users@prism54.org. 

3. If you get confirmation that it is a bug you can
then procceed to report it on our Bugzilla. Our bugzilla database
can be reached at http://prism54.org/bugzilla/

Note: our bugzilla should be sending out e-mails to 
prism54-devel@prism54.org but I think it stopped... If we get it working
again then if you 100% sure what you found is a bug then you can just
submit the bug to Bugzilla.

Submitting Patches
-------------------

If you have a patch just send it to prism54-devel@prism54.org. But first:

1. Check first through the prism54-devel@prism54.org mailing 
list to see if someone is already working on it; or check on the 
#prism54-devel IRC channel too.

2. Make sure your patch is unified, 
diff -Naur prism54-cvsxxxx prism54-cvsxxxx-changed > description_fix.diff
works well.

2. Name the bugs, if any, that your patch fixes from Bugzilla. Close them
if your patch was committed (or we can do it for you).

--
$Id: README 517 2004-11-08 12:25:14Z mcgrof $
