share/man/man4/wpi.4

   1 .\" Copyright (c) 2004-2007
   2 .\"     Damien Bergamini <damien.bergamini@free.fr>. All rights reserved.
   3 .\"     Benjamin Close <Benjamin.Close@clearchain.com>. All rights reserved.
   4 .\" Copyright (c) 2016 Andriy Voskoboinyk <avos@FreeBSD.org>
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice unmodified, this list of conditions, and the following
  12 .\"    disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd January 31, 2016
  32 .Dt WPI 4
  33 .Os
  34 .Sh NAME
  35 .Nm wpi
  36 .Nd "Intel 3945ABG Wireless LAN IEEE 802.11 driver"
  37 .Sh SYNOPSIS
  38 To compile this driver into the kernel,
  39 place the following lines in your
  40 kernel configuration file:
  41 .Bd -ragged -offset indent
  42 .Cd "device wpi"
  43 .Cd "device wpifw"
  44 .Cd "device pci"
  45 .Cd "device wlan"
  46 .Cd "device wlan_amrr"
  47 .Cd "device firmware"
  48 .Ed
  49 .Pp
  50 Alternatively, to load the driver as a
  51 module at boot time, place the following line in
  52 .Xr loader.conf 5 :
  53 .Bd -literal -offset indent
  54 if_wpi_load="YES"
  55 .Ed
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 driver provides support for the
  60 .Tn Intel
  61 3945ABG Wireless network adapter.
  62 The driver supports
  63 .Cm station ,
  64 .Cm adhoc ,
  65 .Cm adhoc-demo ,
  66 .Cm hostap ,
  67 and
  68 .Cm monitor
  69 mode operation.
  70 Only one virtual interface may be configured at any time.
  71 .Pp
  72 The
  73 .Nm
  74 driver can be configured to use
  75 Wired Equivalent Privacy (WEP) or
  76 Wi-Fi Protected Access (WPA-PSK and WPA2-PSK).
  77 WPA is the de facto encryption standard for wireless networks.
  78 It is strongly recommended that WEP
  79 not be used as the sole mechanism
  80 to secure wireless communication,
  81 due to serious weaknesses in it.
  82 The
  83 .Nm
  84 driver offloads both encryption and decryption of data frames to the
  85 hardware for the CCMP cipher.
  86 .Pp
  87 This driver requires the firmware built with the
  88 .Nm wpifw 4
  89 module to work.
  90 .Pp
  91 The
  92 .Nm
  93 driver can be configured at runtime with
  94 .Xr ifconfig 8 .
  95 .Sh FILES
  96 .Bl -tag -width ".Pa /usr/share/doc/legal/intel_wpi.LICENSE" -compact
  97 .It Pa /usr/share/doc/legal/intel_wpi.LICENSE
  98 .Nm
  99 firmware license
 100 .El
 101 .Sh EXAMPLES
 102 Join an existing BSS network (i.e., connect to an access point):
 103 .Bd -literal -offset indent
 104 ifconfig wlan0 create wlandev wpi0 inet 192.168.0.20 \e
 105     netmask 0xffffff00
 106 .Ed
 107 .Pp
 108 Join a specific BSS network with network name
 109 .Dq Li my_net :
 110 .Pp
 111 .Dl "ifconfig wlan0 create wlandev wpi0 ssid my_net up"
 112 .Pp
 113 Join a specific BSS network with 64-bit WEP encryption:
 114 .Bd -literal -offset indent
 115 ifconfig wlan0 create wlandev wpi0 ssid my_net \e
 116         wepmode on wepkey 0x1234567890 weptxkey 1 up
 117 .Ed
 118 .Pp
 119 Create an IBSS network with 128-bit WEP encryption on the channel 4:
 120 .Bd -literal -offset indent
 121 ifconfig wlan0 create wlandev wpi0 wlanmode adhoc ssid my_net \e
 122         wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \e
 123         channel 4
 124 .Ed
 125 .Pp
 126 Join/create an 802.11b IBSS network with network name
 127 .Dq Li my_net :
 128 .Bd -literal -offset indent
 129 ifconfig wlan0 create wlandev wpi0 wlanmode adhoc
 130 ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e
 131         mode 11b
 132 .Ed
 133 .Pp
 134 Create an 802.11g host-based access point:
 135 .Bd -literal -offset indent
 136 ifconfig wlan0 create wlandev wpi0 wlanmode hostap
 137 ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e
 138         mode 11g
 139 .Ed
 140 .Sh DIAGNOSTICS
 141 .Bl -diag
 142 .It "wpi%d: could not load firmware image '%s'"
 143 The driver failed to load the firmware image using the
 144 .Xr firmware 9
 145 subsystem.
 146 Verify the
 147 .Xr wpifw 4
 148 firmware module is installed.
 149 .It "wpi%d: %s: timeout waiting for adapter to initialize, error %d"
 150 The onboard microcontroller failed to initialize in time.
 151 This should not happen.
 152 .It "wpi%d: %s: could not load boot firmware"
 153 An attempt to upload the boot firmware image to the onboard microcontroller
 154 failed.
 155 This should not happen.
 156 .It "wpi%d: device timeout"
 157 A frame dispatched to the hardware for transmission did not complete in time.
 158 The driver will reset the hardware and continue.
 159 This should not happen.
 160 .It "wpi%d: scan timeout"
 161 Firmware scan command response was not received in time.
 162 The driver will reset the hardware and continue.
 163 This should not happen.
 164 .It "wpi%d: fatal firmware error"
 165 The onboard microcontroller crashed for some reason.
 166 The driver will reset the hardware and continue.
 167 This should not happen.
 168 .It "wpi%d: RF switch: radio disabled"
 169 The hardware switch controlling the radio is currently turned off.
 170 Data transmission is not possible in this state.
 171 .It "wpi%d: can't map mem space"
 172 The driver was unable to map the device registers into the host address space.
 173 This should not happen.
 174 .It "wpi%d: can't map interrupt"
 175 The driver was unable to allocate an IRQ for the device interrupt.
 176 This should not happen.
 177 .It "wpi%d: can't establish interrupt, error %d"
 178 The driver was unable to install the device interrupt handler.
 179 This should not happen.
 180 .It "wpi%d: %s: bus_dmamap_load failed, error %d"
 181 The driver was unable to map newly allocated mbuf to device
 182 visible address space.
 183 Contents of currently received frame will be lost.
 184 This should not happen.
 185 .El
 186 .Sh SEE ALSO
 187 .Xr pci 4 ,
 188 .Xr wlan 4 ,
 189 .Xr wlan_amrr 4 ,
 190 .Xr wlan_ccmp 4 ,
 191 .Xr wlan_tkip 4 ,
 192 .Xr wlan_wep 4 ,
 193 .Xr wlan_xauth 4 ,
 194 .Xr wpifw 4 ,
 195 .Xr hostapd 8 ,
 196 .Xr ifconfig 8 ,
 197 .Xr wpa_supplicant 8
 198 .Sh AUTHORS
 199 .An -nosplit
 200 The original
 201 .Nm
 202 driver was written for
 203 .Ox
 204 by
 205 .An Damien Bergamini Aq Mt damien.bergamini@free.fr .
 206 .An Benjamin Close Aq Mt benjsc@FreeBSD.org
 207 ported
 208 .Nm
 209 to
 210 .Fx .
 211 .Sh CAVEATS
 212 Hostap mode is not directly supported by the device;
 213 it is implemented through IBSS mode (as a result, DFS/passive
 214 channels are not available in this mode).
 215 .Pp
 216 Powersave may be unstable on some networks (results in
 217 occasional 'wpi%d: device timeout' messages); you can try
 218 to disable it to improve device stability.