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