Pull dock-bay into release branch
[linux-2.6] / Documentation / networking / README.ipw2100
1
2 Intel(R) PRO/Wireless 2100 Driver for Linux in support of:
3
4 Intel(R) PRO/Wireless 2100 Network Connection
5
6 Copyright (C) 2003-2006, Intel Corporation
7
8 README.ipw2100
9
10 Version: git-1.1.5
11 Date   : January 25, 2006
12
13 Index
14 -----------------------------------------------
15 0. IMPORTANT INFORMATION BEFORE USING THIS DRIVER
16 1. Introduction
17 2. Release git-1.1.5 Current Features
18 3. Command Line Parameters
19 4. Sysfs Helper Files
20 5. Radio Kill Switch
21 6. Dynamic Firmware
22 7. Power Management
23 8. Support
24 9. License
25
26
27 0.   IMPORTANT INFORMATION BEFORE USING THIS DRIVER
28 -----------------------------------------------
29
30 Important Notice FOR ALL USERS OR DISTRIBUTORS!!!!
31
32 Intel wireless LAN adapters are engineered, manufactured, tested, and
33 quality checked to ensure that they meet all necessary local and
34 governmental regulatory agency requirements for the regions that they
35 are designated and/or marked to ship into. Since wireless LANs are
36 generally unlicensed devices that share spectrum with radars,
37 satellites, and other licensed and unlicensed devices, it is sometimes
38 necessary to dynamically detect, avoid, and limit usage to avoid
39 interference with these devices. In many instances Intel is required to
40 provide test data to prove regional and local compliance to regional and
41 governmental regulations before certification or approval to use the
42 product is granted. Intel's wireless LAN's EEPROM, firmware, and
43 software driver are designed to carefully control parameters that affect
44 radio operation and to ensure electromagnetic compliance (EMC). These
45 parameters include, without limitation, RF power, spectrum usage,
46 channel scanning, and human exposure.
47
48 For these reasons Intel cannot permit any manipulation by third parties
49 of the software provided in binary format with the wireless WLAN
50 adapters (e.g., the EEPROM and firmware). Furthermore, if you use any
51 patches, utilities, or code with the Intel wireless LAN adapters that
52 have been manipulated by an unauthorized party (i.e., patches,
53 utilities, or code (including open source code modifications) which have
54 not been validated by Intel), (i) you will be solely responsible for
55 ensuring the regulatory compliance of the products, (ii) Intel will bear
56 no liability, under any theory of liability for any issues associated
57 with the modified products, including without limitation, claims under
58 the warranty and/or issues arising from regulatory non-compliance, and
59 (iii) Intel will not provide or be required to assist in providing
60 support to any third parties for such modified products.
61
62 Note: Many regulatory agencies consider Wireless LAN adapters to be
63 modules, and accordingly, condition system-level regulatory approval
64 upon receipt and review of test data documenting that the antennas and
65 system configuration do not cause the EMC and radio operation to be
66 non-compliant.
67
68 The drivers available for download from SourceForge are provided as a
69 part of a development project.  Conformance to local regulatory
70 requirements is the responsibility of the individual developer.  As
71 such, if you are interested in deploying or shipping a driver as part of
72 solution intended to be used for purposes other than development, please
73 obtain a tested driver from Intel Customer Support at:
74
75 http://support.intel.com/support/notebook/sb/CS-006408.htm
76
77
78 1. Introduction
79 -----------------------------------------------
80
81 This document provides a brief overview of the features supported by the 
82 IPW2100 driver project.  The main project website, where the latest 
83 development version of the driver can be found, is:
84
85         http://ipw2100.sourceforge.net
86
87 There you can find the not only the latest releases, but also information about
88 potential fixes and patches, as well as links to the development mailing list
89 for the driver project.
90
91
92 2. Release git-1.1.5 Current Supported Features
93 -----------------------------------------------
94 - Managed (BSS) and Ad-Hoc (IBSS)
95 - WEP (shared key and open)
96 - Wireless Tools support 
97 - 802.1x (tested with XSupplicant 1.0.1)
98
99 Enabled (but not supported) features:
100 - Monitor/RFMon mode
101 - WPA/WPA2
102
103 The distinction between officially supported and enabled is a reflection
104 on the amount of validation and interoperability testing that has been
105 performed on a given feature.
106
107
108 3. Command Line Parameters
109 -----------------------------------------------
110
111 If the driver is built as a module, the following optional parameters are used
112 by entering them on the command line with the modprobe command using this
113 syntax:
114
115         modprobe ipw2100 [<option>=<VAL1><,VAL2>...]
116
117 For example, to disable the radio on driver loading, enter:
118
119         modprobe ipw2100 disable=1
120
121 The ipw2100 driver supports the following module parameters:
122
123 Name            Value           Example:
124 debug           0x0-0xffffffff  debug=1024
125 mode            0,1,2           mode=1   /* AdHoc */
126 channel         int             channel=3 /* Only valid in AdHoc or Monitor */
127 associate       boolean         associate=0 /* Do NOT auto associate */
128 disable         boolean         disable=1 /* Do not power the HW */
129
130
131 4. Sysfs Helper Files
132 ---------------------------     
133 -----------------------------------------------
134
135 There are several ways to control the behavior of the driver.  Many of the 
136 general capabilities are exposed through the Wireless Tools (iwconfig).  There
137 are a few capabilities that are exposed through entries in the Linux Sysfs.
138
139
140 ----- Driver Level ------
141 For the driver level files, look in /sys/bus/pci/drivers/ipw2100/
142
143   debug_level  
144         
145         This controls the same global as the 'debug' module parameter.  For 
146         information on the various debugging levels available, run the 'dvals'
147         script found in the driver source directory.
148
149         NOTE:  'debug_level' is only enabled if CONFIG_IPW2100_DEBUG is turn
150                on.
151
152 ----- Device Level ------
153 For the device level files look in
154         
155         /sys/bus/pci/drivers/ipw2100/{PCI-ID}/
156
157 For example:
158         /sys/bus/pci/drivers/ipw2100/0000:02:01.0
159
160 For the device level files, see /sys/bus/pci/drivers/ipw2100:
161
162   rf_kill
163         read - 
164         0 = RF kill not enabled (radio on)
165         1 = SW based RF kill active (radio off)
166         2 = HW based RF kill active (radio off)
167         3 = Both HW and SW RF kill active (radio off)
168         write -
169         0 = If SW based RF kill active, turn the radio back on
170         1 = If radio is on, activate SW based RF kill
171
172         NOTE: If you enable the SW based RF kill and then toggle the HW
173         based RF kill from ON -> OFF -> ON, the radio will NOT come back on
174
175
176 5. Radio Kill Switch
177 -----------------------------------------------
178 Most laptops provide the ability for the user to physically disable the radio.
179 Some vendors have implemented this as a physical switch that requires no
180 software to turn the radio off and on.  On other laptops, however, the switch
181 is controlled through a button being pressed and a software driver then making
182 calls to turn the radio off and on.  This is referred to as a "software based
183 RF kill switch"
184
185 See the Sysfs helper file 'rf_kill' for determining the state of the RF switch
186 on your system.
187
188
189 6. Dynamic Firmware
190 -----------------------------------------------
191 As the firmware is licensed under a restricted use license, it can not be 
192 included within the kernel sources.  To enable the IPW2100 you will need a 
193 firmware image to load into the wireless NIC's processors.
194
195 You can obtain these images from <http://ipw2100.sf.net/firmware.php>.
196
197 See INSTALL for instructions on installing the firmware.
198
199
200 7. Power Management
201 -----------------------------------------------
202 The IPW2100 supports the configuration of the Power Save Protocol 
203 through a private wireless extension interface.  The IPW2100 supports 
204 the following different modes:
205
206         off     No power management.  Radio is always on.
207         on      Automatic power management
208         1-5     Different levels of power management.  The higher the 
209                 number the greater the power savings, but with an impact to 
210                 packet latencies. 
211
212 Power management works by powering down the radio after a certain 
213 interval of time has passed where no packets are passed through the 
214 radio.  Once powered down, the radio remains in that state for a given 
215 period of time.  For higher power savings, the interval between last 
216 packet processed to sleep is shorter and the sleep period is longer.
217
218 When the radio is asleep, the access point sending data to the station 
219 must buffer packets at the AP until the station wakes up and requests 
220 any buffered packets.  If you have an AP that does not correctly support 
221 the PSP protocol you may experience packet loss or very poor performance 
222 while power management is enabled.  If this is the case, you will need 
223 to try and find a firmware update for your AP, or disable power 
224 management (via `iwconfig eth1 power off`)
225
226 To configure the power level on the IPW2100 you use a combination of 
227 iwconfig and iwpriv.  iwconfig is used to turn power management on, off, 
228 and set it to auto.
229
230         iwconfig eth1 power off    Disables radio power down
231         iwconfig eth1 power on     Enables radio power management to 
232                                    last set level (defaults to AUTO)
233         iwpriv eth1 set_power 0    Sets power level to AUTO and enables 
234                                    power management if not previously 
235                                    enabled.
236         iwpriv eth1 set_power 1-5  Set the power level as specified, 
237                                    enabling power management if not 
238                                    previously enabled.
239
240 You can view the current power level setting via:
241         
242         iwpriv eth1 get_power
243
244 It will return the current period or timeout that is configured as a string
245 in the form of xxxx/yyyy (z) where xxxx is the timeout interval (amount of
246 time after packet processing), yyyy is the period to sleep (amount of time to 
247 wait before powering the radio and querying the access point for buffered
248 packets), and z is the 'power level'.  If power management is turned off the
249 xxxx/yyyy will be replaced with 'off' -- the level reported will be the active
250 level if `iwconfig eth1 power on` is invoked.
251
252
253 8. Support
254 -----------------------------------------------
255
256 For general development information and support,
257 go to:
258         
259     http://ipw2100.sf.net/
260
261 The ipw2100 1.1.0 driver and firmware can be downloaded from:  
262
263     http://support.intel.com
264
265 For installation support on the ipw2100 1.1.0 driver on Linux kernels 
266 2.6.8 or greater, email support is available from:  
267
268     http://supportmail.intel.com
269
270 9. License
271 -----------------------------------------------
272
273   Copyright(c) 2003 - 2006 Intel Corporation. All rights reserved.
274
275   This program is free software; you can redistribute it and/or modify it 
276   under the terms of the GNU General Public License (version 2) as 
277   published by the Free Software Foundation.
278   
279   This program is distributed in the hope that it will be useful, but WITHOUT 
280   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
281   FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for 
282   more details.
283   
284   You should have received a copy of the GNU General Public License along with
285   this program; if not, write to the Free Software Foundation, Inc., 59 
286   Temple Place - Suite 330, Boston, MA  02111-1307, USA.
287   
288   The full GNU General Public License is included in this distribution in the
289   file called LICENSE.
290   
291   License Contact Information:
292   James P. Ketrenos <ipw2100-admin@linux.intel.com>
293   Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497
294