Documentation/networking/device_drivers/wifi/intel/ipw2200.rst

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