aboutsummaryrefslogtreecommitdiffstats
path: root/README.prism2
blob: de467838cb8b47f0dbfb318446a46121299402a5 (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
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 only been tested with couple of different
models, e.g., Compaq WL100 and WL200, so 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).

I have tested this driver without kernel-tree PCMCIA support, i.e., by 
compiling it with pcmcia-cs package. Operation with kernel-tree PCMCIA 
support may require some changes. The driver should work with various
new pcmcia-cs versions, but I have tested this version only with
pcmcia-cs v3.1.26; other versions might need some minor changes.


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'), 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).