Documentation/networking/README.ipw2200

   1
   2 Intel(R) PRO/Wireless 2915ABG Driver for Linux in support of:
   3
   4 Intel(R) PRO/Wireless 2200BG Network Connection
   5 Intel(R) PRO/Wireless 2915ABG Network Connection
   6
   7 Note: The Intel(R) PRO/Wireless 2915ABG Driver for Linux and Intel(R)
   8 PRO/Wireless 2200BG Driver for Linux is a unified driver that works on
   9 both hardware adapters listed above. In this document the Intel(R)
  10 PRO/Wireless 2915ABG Driver for Linux will be used to reference the
  11 unified driver.
  12
  13 Copyright (C) 2004-2005, Intel Corporation
  14
  15 README.ipw2200
  16
  17 Version: 1.0.8
  18 Date   : October 20, 2005
  19
  20
  21 Index
  22 -----------------------------------------------
  23 0.   IMPORTANT INFORMATION BEFORE USING THIS DRIVER
  24 1.   Introduction
  25 1.1. Overview of features
  26 1.2. Module parameters
  27 1.3. Wireless Extension Private Methods
  28 1.4. Sysfs Helper Files
  29 2.   Ad-Hoc Networking
  30 3.   Interacting with Wireless Tools
  31 3.1. iwconfig mode
  32 4.   About the Version Numbers
  33 5.   Firmware installation
  34 6.   Support
  35 7.   License
  36
  37
  38 0.   IMPORTANT INFORMATION BEFORE USING THIS DRIVER
  39 -----------------------------------------------
  40
  41 Important Notice FOR ALL USERS OR DISTRIBUTORS!!!!
  42
  43 Intel wireless LAN adapters are engineered, manufactured, tested, and
  44 quality checked to ensure that they meet all necessary local and
  45 governmental regulatory agency requirements for the regions that they
  46 are designated and/or marked to ship into. Since wireless LANs are
  47 generally unlicensed devices that share spectrum with radars,
  48 satellites, and other licensed and unlicensed devices, it is sometimes
  49 necessary to dynamically detect, avoid, and limit usage to avoid
  50 interference with these devices. In many instances Intel is required to
  51 provide test data to prove regional and local compliance to regional and
  52 governmental regulations before certification or approval to use the
  53 product is granted. Intel's wireless LAN's EEPROM, firmware, and
  54 software driver are designed to carefully control parameters that affect
  55 radio operation and to ensure electromagnetic compliance (EMC). These
  56 parameters include, without limitation, RF power, spectrum usage,
  57 channel scanning, and human exposure.
  58
  59 For these reasons Intel cannot permit any manipulation by third parties
  60 of the software provided in binary format with the wireless WLAN
  61 adapters (e.g., the EEPROM and firmware). Furthermore, if you use any
  62 patches, utilities, or code with the Intel wireless LAN adapters that
  63 have been manipulated by an unauthorized party (i.e., patches,
  64 utilities, or code (including open source code modifications) which have
  65 not been validated by Intel), (i) you will be solely responsible for
  66 ensuring the regulatory compliance of the products, (ii) Intel will bear
  67 no liability, under any theory of liability for any issues associated
  68 with the modified products, including without limitation, claims under
  69 the warranty and/or issues arising from regulatory non-compliance, and
  70 (iii) Intel will not provide or be required to assist in providing
  71 support to any third parties for such modified products.
  72
  73 Note: Many regulatory agencies consider Wireless LAN adapters to be
  74 modules, and accordingly, condition system-level regulatory approval
  75 upon receipt and review of test data documenting that the antennas and
  76 system configuration do not cause the EMC and radio operation to be
  77 non-compliant.
  78
  79 The drivers available for download from SourceForge are provided as a
  80 part of a development project.  Conformance to local regulatory
  81 requirements is the responsibility of the individual developer.  As
  82 such, if you are interested in deploying or shipping a driver as part of
  83 solution intended to be used for purposes other than development, please
  84 obtain a tested driver from Intel Customer Support at:
  85
  86 http://support.intel.com/support/notebook/sb/CS-006408.htm
  87
  88
  89 1.   Introduction
  90 -----------------------------------------------
  91 The following sections attempt to provide a brief introduction to using
  92 the Intel(R) PRO/Wireless 2915ABG Driver for Linux.
  93
  94 This document is not meant to be a comprehensive manual on
  95 understanding or using wireless technologies, but should be sufficient
  96 to get you moving without wires on Linux.
  97
  98 For information on building and installing the driver, see the INSTALL
  99 file.
 100
 101
 102 1.1. Overview of Features
 103 -----------------------------------------------
 104 The current release (1.0.8) supports the following features:
 105
 106 + BSS mode (Infrastructure, Managed)
 107 + IBSS mode (Ad-Hoc)
 108 + WEP (OPEN and SHARED KEY mode)
 109 + 802.1x EAP via wpa_supplicant and xsupplicant
 110 + Wireless Extension support
 111 + Full B and G rate support (2200 and 2915)
 112 + Full A rate support (2915 only)
 113 + Transmit power control
 114 + S state support (ACPI suspend/resume)
 115
 116 The following features are currently enabled, but not officially
 117 supported:
 118
 119 + WPA
 120 + long/short preamble support
 121 + Monitor mode (aka RFMon)
 122
 123 The distinction between officially supported and enabled is a reflection
 124 on the amount of validation and interoperability testing that has been
 125 performed on a given feature.
 126
 127
 128
 129 1.2. Command Line Parameters
 130 -----------------------------------------------
 131
 132 Like many modules used in the Linux kernel, the Intel(R) PRO/Wireless
 133 2915ABG Driver for Linux allows configuration options to be provided
 134 as module parameters.  The most common way to specify a module parameter
 135 is via the command line.
 136
 137 The general form is:
 138
 139 % modprobe ipw2200 parameter=value
 140
 141 Where the supported parameter are:
 142
 143   associate
 144         Set to 0 to disable the auto scan-and-associate functionality of the
 145         driver.  If disabled, the driver will not attempt to scan
 146         for and associate to a network until it has been configured with
 147         one or more properties for the target network, for example configuring
 148         the network SSID.  Default is 1 (auto-associate)
 149
 150         Example: % modprobe ipw2200 associate=0
 151
 152   auto_create
 153         Set to 0 to disable the auto creation of an Ad-Hoc network
 154         matching the channel and network name parameters provided.
 155         Default is 1.
 156
 157   channel
 158         channel number for association.  The normal method for setting
 159         the channel would be to use the standard wireless tools
 160         (i.e. `iwconfig eth1 channel 10`), but it is useful sometimes
 161         to set this while debugging.  Channel 0 means 'ANY'
 162
 163   debug
 164         If using a debug build, this is used to control the amount of debug
 165         info is logged.  See the 'dvals' and 'load' script for more info on
 166         how to use this (the dvals and load scripts are provided as part
 167         of the ipw2200 development snapshot releases available from the
 168         SourceForge project at http://ipw2200.sf.net)
 169
 170   led
 171         Can be used to turn on experimental LED code.
 172         0 = Off, 1 = On.  Default is 0.
 173
 174   mode
 175         Can be used to set the default mode of the adapter.
 176         0 = Managed, 1 = Ad-Hoc, 2 = Monitor
 177
 178
 179 1.3. Wireless Extension Private Methods
 180 -----------------------------------------------
 181
 182 As an interface designed to handle generic hardware, there are certain
 183 capabilities not exposed through the normal Wireless Tool interface.  As
 184 such, a provision is provided for a driver to declare custom, or
 185 private, methods.  The Intel(R) PRO/Wireless 2915ABG Driver for Linux
 186 defines several of these to configure various settings.
 187
 188 The general form of using the private wireless methods is:
 189
 190         % iwpriv $IFNAME method parameters
 191
 192 Where $IFNAME is the interface name the device is registered with
 193 (typically eth1, customized via one of the various network interface
 194 name managers, such as ifrename)
 195
 196 The supported private methods are:
 197
 198   get_mode
 199         Can be used to report out which IEEE mode the driver is
 200         configured to support.  Example:
 201
 202         % iwpriv eth1 get_mode
 203         eth1    get_mode:802.11bg (6)
 204
 205   set_mode
 206         Can be used to configure which IEEE mode the driver will
 207         support.
 208
 209         Usage:
 210         % iwpriv eth1 set_mode {mode}
 211         Where {mode} is a number in the range 1-7:
 212         1       802.11a (2915 only)
 213         2       802.11b
 214         3       802.11ab (2915 only)
 215         4       802.11g
 216         5       802.11ag (2915 only)
 217         6       802.11bg
 218         7       802.11abg (2915 only)
 219
 220   get_preamble
 221         Can be used to report configuration of preamble length.
 222
 223   set_preamble
 224         Can be used to set the configuration of preamble length:
 225
 226         Usage:
 227         % iwpriv eth1 set_preamble {mode}
 228         Where {mode} is one of:
 229         1       Long preamble only
 230         0       Auto (long or short based on connection)
 231
 232
 233 1.4. Sysfs Helper Files:
 234 -----------------------------------------------
 235
 236 The Linux kernel provides a pseudo file system that can be used to
 237 access various components of the operating system.  The Intel(R)
 238 PRO/Wireless 2915ABG Driver for Linux exposes several configuration
 239 parameters through this mechanism.
 240
 241 An entry in the sysfs can support reading and/or writing.  You can
 242 typically query the contents of a sysfs entry through the use of cat,
 243 and can set the contents via echo.  For example:
 244
 245 % cat /sys/bus/pci/drivers/ipw2200/debug_level
 246
 247 Will report the current debug level of the driver's logging subsystem
 248 (only available if CONFIG_IPW_DEBUG was configured when the driver was
 249 built).
 250
 251 You can set the debug level via:
 252
 253 % echo $VALUE > /sys/bus/pci/drivers/ipw2200/debug_level
 254
 255 Where $VALUE would be a number in the case of this sysfs entry.  The
 256 input to sysfs files does not have to be a number.  For example, the
 257 firmware loader used by hotplug utilizes sysfs entries for transfering
 258 the firmware image from user space into the driver.
 259
 260 The Intel(R) PRO/Wireless 2915ABG Driver for Linux exposes sysfs entries
 261 at two levels -- driver level, which apply to all instances of the driver
 262 (in the event that there are more than one device installed) and device
 263 level, which applies only to the single specific instance.
 264
 265
 266 1.4.1 Driver Level Sysfs Helper Files
 267 -----------------------------------------------
 268
 269 For the driver level files, look in /sys/bus/pci/drivers/ipw2200/
 270
 271   debug_level
 272
 273         This controls the same global as the 'debug' module parameter
 274
 275
 276
 277 1.4.2 Device Level Sysfs Helper Files
 278 -----------------------------------------------
 279
 280 For the device level files, look in
 281
 282         /sys/bus/pci/drivers/ipw2200/{PCI-ID}/
 283
 284 For example:
 285         /sys/bus/pci/drivers/ipw2200/0000:02:01.0
 286
 287 For the device level files, see /sys/bus/pci/drivers/ipw2200:
 288
 289   rf_kill
 290         read -
 291         0 = RF kill not enabled (radio on)
 292         1 = SW based RF kill active (radio off)
 293         2 = HW based RF kill active (radio off)
 294         3 = Both HW and SW RF kill active (radio off)
 295         write -
 296         0 = If SW based RF kill active, turn the radio back on
 297         1 = If radio is on, activate SW based RF kill
 298
 299         NOTE: If you enable the SW based RF kill and then toggle the HW
 300         based RF kill from ON -> OFF -> ON, the radio will NOT come back on
 301
 302   ucode
 303         read-only access to the ucode version number
 304
 305   led
 306         read -
 307         0 = LED code disabled
 308         1 = LED code enabled
 309         write -
 310         0 = Disable LED code
 311         1 = Enable LED code
 312
 313         NOTE: The LED code has been reported to hang some systems when
 314         running ifconfig and is therefore disabled by default.
 315
 316
 317 2.   Ad-Hoc Networking
 318 -----------------------------------------------
 319
 320 When using a device in an Ad-Hoc network, it is useful to understand the
 321 sequence and requirements for the driver to be able to create, join, or
 322 merge networks.
 323
 324 The following attempts to provide enough information so that you can
 325 have a consistent experience while using the driver as a member of an
 326 Ad-Hoc network.
 327
 328 2.1. Joining an Ad-Hoc Network
 329 -----------------------------------------------
 330
 331 The easiest way to get onto an Ad-Hoc network is to join one that
 332 already exists.
 333
 334 2.2. Creating an Ad-Hoc Network
 335 -----------------------------------------------
 336
 337 An Ad-Hoc networks is created using the syntax of the Wireless tool.
 338
 339 For Example:
 340 iwconfig eth1 mode ad-hoc essid testing channel 2
 341
 342 2.3. Merging Ad-Hoc Networks
 343 -----------------------------------------------
 344
 345
 346 3.  Interaction with Wireless Tools
 347 -----------------------------------------------
 348
 349 3.1 iwconfig mode
 350 -----------------------------------------------
 351
 352 When configuring the mode of the adapter, all run-time configured parameters
 353 are reset to the value used when the module was loaded.  This includes
 354 channels, rates, ESSID, etc.
 355
 356
 357 4.   About the Version Numbers
 358 -----------------------------------------------
 359
 360 Due to the nature of open source development projects, there are
 361 frequently changes being incorporated that have not gone through
 362 a complete validation process.  These changes are incorporated into
 363 development snapshot releases.
 364
 365 Releases are numbered with a three level scheme:
 366
 367         major.minor.development
 368
 369 Any version where the 'development' portion is 0 (for example
 370 1.0.0, 1.1.0, etc.) indicates a stable version that will be made
 371 available for kernel inclusion.
 372
 373 Any version where the 'development' portion is not a 0 (for
 374 example 1.0.1, 1.1.5, etc.) indicates a development version that is
 375 being made available for testing and cutting edge users.  The stability
 376 and functionality of the development releases are not know.  We make
 377 efforts to try and keep all snapshots reasonably stable, but due to the
 378 frequency of their release, and the desire to get those releases
 379 available as quickly as possible, unknown anomalies should be expected.
 380
 381 The major version number will be incremented when significant changes
 382 are made to the driver.  Currently, there are no major changes planned.
 383
 384 5.  Firmware installation
 385 ----------------------------------------------
 386
 387 The driver requires a firmware image, download it and extract the
 388 files under /lib/firmware (or wherever your hotplug's firmware.agent
 389 will look for firmware files)
 390
 391 The firmware can be downloaded from the following URL:
 392
 393     http://ipw2200.sf.net/
 394
 395
 396 6.  Support
 397 -----------------------------------------------
 398
 399 For direct support of the 1.0.0 version, you can contact
 400 http://supportmail.intel.com, or you can use the open source project
 401 support.
 402
 403 For general information and support, go to:
 404
 405     http://ipw2200.sf.net/
 406
 407
 408 7.  License
 409 -----------------------------------------------
 410
 411   Copyright(c) 2003 - 2005 Intel Corporation. All rights reserved.
 412
 413   This program is free software; you can redistribute it and/or modify it
 414   under the terms of the GNU General Public License version 2 as
 415   published by the Free Software Foundation.
 416
 417   This program is distributed in the hope that it will be useful, but WITHOUT
 418   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 419   FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
 420   more details.
 421
 422   You should have received a copy of the GNU General Public License along with
 423   this program; if not, write to the Free Software Foundation, Inc., 59
 424   Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 425
 426   The full GNU General Public License is included in this distribution in the
 427   file called LICENSE.
 428
 429   Contact Information:
 430   James P. Ketrenos <ipw2100-admin@linux.intel.com>
 431   Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497
 432