share/man/man4/wpi.4

   1 .\" $NetBSD: wpi.4,v 1.11 2009/02/04 20:46:14 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2006
   4 .\"     Damien Bergamini <damien.bergamini@free.fr>. All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice unmodified, this list of conditions, and the following
  11 .\"    disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd February 4, 2009
  29 .Dt WPI 4
  30 .Os
  31 .Sh NAME
  32 .Nm wpi
  33 .Nd Intel PRO/Wireless 3945ABG IEEE 802.11a/b/g wireless network driver
  34 .Sh SYNOPSIS
  35 .Cd "wpi* at pci? dev ? function ?"
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 driver provides support for
  40 .Tn Intel
  41 PRO/Wireless 3945ABG Mini PCI Express network adapters.
  42 .Pp
  43 These are the modes the
  44 .Nm
  45 driver can operate in:
  46 .Bl -tag -width Ds
  47 .It BSS mode
  48 Also known as
  49 .Em infrastructure
  50 mode, this is used when associating with an access point, through
  51 which all traffic passes.
  52 This mode is the default.
  53 .It monitor mode
  54 In this mode the driver is able to receive packets without
  55 associating with an access point.
  56 This disables the internal receive filter and enables the card to
  57 capture packets from networks to which it wouldn't normally have access,
  58 or to scan for access points.
  59 .El
  60 .Pp
  61 .Nm
  62 supports software WEP.
  63 Wired Equivalent Privacy (WEP) is the de facto encryption standard
  64 for wireless networks.
  65 It can be typically configured in one of three modes:
  66 no encryption; 40-bit encryption; or 104-bit encryption.
  67 Unfortunately, due to serious weaknesses in the WEP protocol
  68 it is strongly recommended that it not be used as the
  69 sole mechanism to secure wireless communication.
  70 WEP is not enabled by default.
  71 .Sh CONFIGURATION
  72 The
  73 .Nm
  74 driver can be configured at runtime with
  75 .Xr ifconfig 8
  76 using the following parameters:
  77 .Bl -tag -width Ds
  78 .It Cm bssid Ar bssid
  79 Set the desired BSSID.
  80 .It Fl bssid
  81 Unset the desired BSSID.
  82 The interface will automatically select a BSSID in this mode, which is
  83 the default.
  84 .It Cm chan Ar n
  85 Set the channel (radio frequency) to be used by the driver based on
  86 the given channel ID
  87 .Ar n .
  88 .It Fl chan
  89 Unset the desired channel to be used by the driver.
  90 The driver will automatically select a channel in this mode, which is
  91 the default.
  92 .It Cm media Ar media
  93 The
  94 .Nm
  95 driver supports the following
  96 .Ar media
  97 types:
  98 .Pp
  99 .Bl -tag -width autoselect -compact
 100 .It Cm autoselect
 101 Enable autoselection of the media type and options.
 102 .El
 103 .It Cm mediaopt Ar opts
 104 The
 105 .Nm
 106 driver supports the following media options:
 107 .Pp
 108 .Bl -tag -width monitor -compact
 109 .It Cm monitor
 110 Select monitor mode.
 111 .El
 112 .It Fl mediaopt Ar opts
 113 Disable the specified media options on the driver and return it to the
 114 default mode of operation (BSS).
 115 .It Cm mode Ar mode
 116 The
 117 .Nm
 118 driver supports the following modes:
 119 .Pp
 120 .Bl -tag -width 11b -compact
 121 .It Cm 11a
 122 Force 802.11a operation.
 123 .It Cm 11b
 124 Force 802.11b operation.
 125 .It Cm 11g
 126 Force 802.11g operation.
 127 .El
 128 .It Cm nwid Ar id
 129 Set the network ID.
 130 The
 131 .Ar id
 132 can either be any text string up to 32 characters in length,
 133 or a series of hexadecimal digits up to 64 digits.
 134 An empty
 135 .Ar id
 136 string allows the interface to connect to any available access points.
 137 By default the
 138 .Nm
 139 driver uses an empty string.
 140 Note that network ID is synonymous with Extended Service Set ID (ESSID).
 141 .It Cm nwkey Ar key
 142 Enable WEP encryption using the specified
 143 .Ar key .
 144 The
 145 .Ar key
 146 can either be a string, a series of hexadecimal digits (preceded by
 147 .Sq 0x ) ,
 148 or a set of keys of the form
 149 .Dq n:k1,k2,k3,k4 ,
 150 where
 151 .Sq n
 152 specifies which of the keys will be used for transmitted packets,
 153 and the four keys,
 154 .Dq k1
 155 through
 156 .Dq k4 ,
 157 are configured as WEP keys.
 158 If a set of keys is specified, a comma
 159 .Pq Sq \&,
 160 within the key must be escaped with a backslash.
 161 Note that if multiple keys are used, their order must be the same within
 162 the network.
 163 .Nm
 164 is capable of using both 40-bit (5 characters or 10 hexadecimal digits)
 165 or 104-bit (13 characters or 26 hexadecimal digits) keys.
 166 .It Fl nwkey
 167 Disable WEP encryption.
 168 This is the default mode of operation.
 169 .El
 170 .Sh FILES
 171 The driver needs at least version 2.14.4 of the following firmware file,
 172 which is loaded when an interface is brought up:
 173 .Pp
 174 .Bl -tag -width Ds -offset indent -compact
 175 .It Pa /libdata/if_wpi/iwlwifi-3945.ucode
 176 .El
 177 .Sh EXAMPLES
 178 .Bd -literal -offset indent
 179 # ifconfig wpi0 nwkey 0x1deadbeef1
 180 .Ed
 181 .Pp
 182 Return wpi0 to its default settings:
 183 .Bd -literal -offset indent
 184 # ifconfig wpi0 -bssid -chan media autoselect \e
 185         nwid "" -nwkey
 186 .Ed
 187 .Pp
 188 Join an existing BSS network,
 189 .Dq my_net :
 190 .Bd -literal -offset indent
 191 # ifconfig wpi0 192.168.1.1 netmask 0xffffff00 nwid my_net
 192 .Ed
 193 .Sh DIAGNOSTICS
 194 .Bl -diag
 195 .It "wpi%d: device timeout"
 196 A frame dispatched to the hardware for transmission did not complete in time.
 197 The driver will reset the hardware.
 198 This should not happen.
 199 .It "wpi%d: fatal firmware error"
 200 For some reason, the firmware crashed.
 201 The driver will reset the hardware.
 202 This should not happen.
 203 .It "wpi%d: Radio transmitter is off"
 204 The radio transmitter is off and thus no packet can go out.
 205 The driver will reset the hardware.
 206 Make sure the laptop radio switch is on.
 207 .It "wpi%d: could not read firmware file"
 208 For some reason, the driver was unable to read the firmware image from the
 209 filesystem.
 210 The file might be missing or corrupted.
 211 .It "wpi%d: firmware file too short: %d bytes"
 212 The firmware image is corrupted and can't be loaded into the adapter.
 213 .It "wpi%d: could not load firmware"
 214 An attempt to load the firmware into the adapter failed.
 215 The driver will reset the hardware.
 216 .El
 217 .Sh NOTES
 218 On some laptops the radio transmitter button must be pushed twice
 219 to get the driver working, or you will get a
 220 .Pa "wpi%d: fatal firmware error"
 221 when the interface will be set to up
 222 .Sh SEE ALSO
 223 .Xr arp 4 ,
 224 .Xr ifmedia 4 ,
 225 .Xr intro 4 ,
 226 .Xr netintro 4 ,
 227 .Xr pci 4 ,
 228 .Xr ifconfig 8 ,
 229 .Xr firmload 9
 230 .Rs
 231 .%T The IPW Web Page
 232 .%O http://damien.bergamini.free.fr/ipw/
 233 .Re
 234 .Sh AUTHORS
 235 The
 236 .Nm
 237 driver was originally written by
 238 .An Damien Bergamini Aq damien@openbsd.org .
 239 .Nx
 240 porting was done by
 241 .An Jean-Baptiste Campesato Aq camjelemon@gmail.com .