aboutsummaryrefslogtreecommitdiffstats
path: root/README.prism2
blob: f0c3e3adb366fbaf1799cd6163ac92e1da0eba64 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
Host AP driver for Intersil Prism2	(DEVELOPMENT VERSION!)
==================================

Copyright (c) 2001, SSH Communications Security Corp
Author: Jouni Malinen, <jkm@ssh.com> or <jkmaline@cc.hut.fi>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation. See COPYING for more
details.


Note!
This development version is mainly for research use; it has not
been thoroughly tested and may contain various bugs. This is not for
production use and use of this driver may require thorough knowledge
of IEEE 802.11, pcmcia-cs, Linux, etc.

Known issues in this version:
- shutting down pcmcia-cs when wireless LAN device is open may leave the
  module loaded and removing the card after this may crash kernel
  (this can be avoided by always closing the device, e.g., with
  'ifconfig wlan0 down', before shutting down pcmcia-cs)

Any comments, reports on success/failure, ideas for further
improvement, feature requests, etc. are welcome at jkm@ssh.com and/or
jkmaline@cc.hut.fi. Please note, that I may not always have time for
replying emails quickly, but I'll try to go through my mail when ever
time permits.


Introduction
============

This is a Linux driver for wireless LAN cards based on Intersil's
Prism2 chipset. The driver supports a so called Host AP mode, i.e., it
takes care of IEEE 802.11 management functions in the host computer
and acts as an access point. This does not require any special
firmware for the wireless LAN card. In addition to this, it has
support for normal station operations in BSS and possible also in
IBSS.

Intersil's station firmware for Prism2 chipset supports a so called
Host AP mode in which the firmware takes care of time critical tasks
like beacon sending and frame acknowledging, but leaves other
management tasks to host computer driver. This driver implements basic
functionality needed to initialize and configure Prism2-based cards,
to send and receive frames, and to gather statistics. In addition, it
includes an implementation of following IEEE 802.11 functions:
authentication (and deauthentication), association (reassociation, and
disassociation), data transmission between two wireless stations,
power saving (PS) mode signaling and frame buffering for PS
stations. The driver has also various features for development
debugging and for researching IEEE 802.11 environments like access to
hardware configuration records, I/O registers, and frames with 802.11
headers.


Supported environment
=====================

Hardware
--------

The driver should work with wireless LAN cards that are based on
Intersil's Prism2 chipset and especially its MAC processor (HFA3841 or
HFA3842). This version has been successfully tested with couple of
different models, e.g., Compaq WL100 and WL200, D-Link DWL-650, and
Linksys WPC11, but there may still be issues with other models.

If you happen to have a wireless LAN card that is based on Prism2, but
does not seem to work with this driver, please let me know the model
and I can try to come up with a solution for any problems. This will
be easier if I have access to the non-functioning card model, but I
might also be able to solve some cases based on debug logs and other
easily collectible information.

In addition to Intersil's Prism2 chipset, this driver may partly
support other chipsets. As far as I know, other chipsets do not have
Host AP mode, so this is not supported, but managed mode (i.e., being
a station in a BSS) seems to work with Prism1 (e.g., Intel, 3Com, and
Symbol cards) and Lucent WaveLAN. I would like to add support for AP
functionality also with these cards, but I'm not sure whether it can
be done without special firmware. Please let me know, if you have
further information about this.

The driver should be portable to different host CPUs. I have tested it 
with ix86 and PowerPC platforms; other platforms will probably need
some changes at least to the I/O macros.

Software
--------

This driver is developed in Linux 2.4.x environment, but it may also
work with Linux 2.2.x kernels (I have tested it few times with 2.2.x
kernel successfully, but I'm not really used those kernel versions
anymore so there may be some compatibility problems).


Installation and configuration
==============================

Untar the driver tarball (prism2-x.y.z.tar.gz) on top of root
pcmcia-cs directory, i.e., so that prism2.c ends up in pcmcia-cs's
'modules' directory. After this you should be able to build and
install pcmcia-cs with this driver (prism2.o) using normal commands
('make config', 'make all', and 'make install').

pcmcia-cs need to know which driver to use for each PC Card. This
driver has its own file (/etc/pcmcia/prism2.conf) that lists few PC
Cards that are supported. It does not include every Prism2-based card, 
so you may need to add your model to prism2.conf in order to get the
driver started.

The driver support Linux Wireless Extensions and certain configuration
items can be viewed and changed with iwconfig(8) and iwpriv(8) from
wireless utilities, e.g., mode (AP/station; iwconfig's 'mode'),
channel (iwconfig's 'freq' or 'channel'), WEP (encryption,; iwconfig's
'key'; however, WEP is not supported in Host AP mode), beacon interval
(iwpriv's 'beacon_int'), and pseudo vs. normal IBSS (ad-hoc) mode
(iwpriv's 'pseudo_ibss').


Bridging between wireless and wired networks
============================================

Prism2 AP driver controls a wireless device (wlan#), but does not take 
care of bridging between wireless and wired networks. If this AP
feature is required, it has to be implemented using an external
software.

Linux kernels support Ethernet bridging (code already present in 2.4.x
kernels and also as a separate patch for 2.2.x kernels). This can be
used to easily build an AP between the wired and wireless
networks. Below is an example of a simple setup in which the AP has
one Ethernet interface and one wireless interface. If needed, see
http://bridge.sourceforge.net/ for more information on Linux kernel's
Ethernet bridging.

Example:

(after loading Prism2 AP driver)

brctl addbr br0
brctl addif br0 eth0
brctl addif br0 wlan0
ifconfig eth0 0.0.0.0
ifconfig wlan0 0.0.0.0
ifconfig br0 192.168.100.200 up

(the AP bridges packets between Ethernet and wireless LAN and can be
reached with IP address 192.168.100.200 from either network; stations
associated to this AP can then communicate with other wireless LAN
stations and with the hosts in the wired network)


Driver status and debug information
===================================

/proc/net/prism2/wlan#
	##:##:##:##:##:## for each authenticated station
		STA information, TX/RX statistics, etc.

	ap_debug
		AP debugging information (wireless bridging statistics)

	debug
		driver debugging information (TX queue)

	registers
		Prism2 I/O register contents (for development use)

	rids
		Prism2 configuration/statistics registers
		(mainly for development use)

	stats
		TX/RX statistics

kernel messages (dmesg/syslog)
	The driver send debugging information to kernel log. The last
	entries from the kernel ring buffer can be viewed with
	dmesg(8) and the log entries can also be recorded with
	syslogd(8).


IEEE 802.11 monitoring
======================

Prism2 cards have a test mode that can be used for monitoring wireless
networks. In this mode the driver receives all raw IEEE 802.11 frames
(including management frames). Monitoring mode can be started using iwpriv(8):

iwpriv wlan0 monitor 1
	start monitor mode and send received frames (including Prism2 RX
	structure and 802.11 header) to user space using netlink socket

iwpriv wlan0 monitor 2
	start monitor mode and send received frames (including 802.11 header)
	to user space using normal netdevice. This changes the device type
	to ARPHRD_IEEE80211 so that user space programs know how to handle
	different header type.

iwpriv wlan0 monitor 0
	disable monitor mode and return to Host AP mode


Example programs in 'sniff' directory can be used to receive monitored
frames send using netlink socket (monitor 1 mode above). wlansniff.c
is a simple 802.11 frame parser that shows both the Prism2-specific
data from the RX frame and parsed contents of the 802.11
frame. prism2ethereal is a utility that writes receives frames into a
dump file that can be read, e.g., to Ethereal for further analysis.

Latest versions of libpcap and Ethereal support ARPHDR_IEEE80211 so
monitor 2 mode above can be used with them for real time IEEE 802.11
network monitoring.


Miscellaneous commands
======================

iwpriv wlan0 dump <bitfield>
	setup RX/RX frame header dumping (mainly for debug use)

iwpriv wlan0 txratectrl 1
	use f/w based TX rate control (i.e., disable driver's host-based
	TX rate control)