xref: /freebsd/share/man/man4/wpi.4 (revision f126890ac5386406dadf7c4cfa9566cbb56537c5)
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.Dd January 31, 2016
30.Dt WPI 4
31.Os
32.Sh NAME
33.Nm wpi
34.Nd "Intel 3945ABG Wireless LAN IEEE 802.11 driver"
35.Sh SYNOPSIS
36To compile this driver into the kernel,
37place the following lines in your
38kernel configuration file:
39.Bd -ragged -offset indent
40.Cd "device wpi"
41.Cd "device wpifw"
42.Cd "device pci"
43.Cd "device wlan"
44.Cd "device wlan_amrr"
45.Cd "device firmware"
46.Ed
47.Pp
48Alternatively, to load the driver as a
49module at boot time, place the following line in
50.Xr loader.conf 5 :
51.Bd -literal -offset indent
52if_wpi_load="YES"
53.Ed
54.Sh DESCRIPTION
55The
56.Nm
57driver provides support for the
58.Tn Intel
593945ABG Wireless network adapter.
60The driver supports
61.Cm station ,
62.Cm adhoc ,
63.Cm adhoc-demo ,
64.Cm hostap ,
65and
66.Cm monitor
67mode operation.
68Only one virtual interface may be configured at any time.
69.Pp
70The
71.Nm
72driver can be configured to use
73Wired Equivalent Privacy (WEP) or
74Wi-Fi Protected Access (WPA-PSK and WPA2-PSK).
75WPA is the de facto encryption standard for wireless networks.
76It is strongly recommended that WEP
77not be used as the sole mechanism
78to secure wireless communication,
79due to serious weaknesses in it.
80The
81.Nm
82driver offloads both encryption and decryption of data frames to the
83hardware for the CCMP cipher.
84.Pp
85This driver requires the firmware built with the
86.Nm wpifw 4
87module to work.
88.Pp
89The
90.Nm
91driver can be configured at runtime with
92.Xr ifconfig 8 .
93.Sh FILES
94.Bl -tag -width ".Pa /usr/share/doc/legal/intel_wpi.LICENSE" -compact
95.It Pa /usr/share/doc/legal/intel_wpi.LICENSE
96.Nm
97firmware license
98.El
99.Sh EXAMPLES
100Join an existing BSS network (i.e., connect to an access point):
101.Bd -literal -offset indent
102ifconfig wlan0 create wlandev wpi0 inet 192.168.0.20 \e
103    netmask 0xffffff00
104.Ed
105.Pp
106Join a specific BSS network with network name
107.Dq Li my_net :
108.Pp
109.Dl "ifconfig wlan0 create wlandev wpi0 ssid my_net up"
110.Pp
111Join a specific BSS network with 64-bit WEP encryption:
112.Bd -literal -offset indent
113ifconfig wlan0 create wlandev wpi0 ssid my_net \e
114	wepmode on wepkey 0x1234567890 weptxkey 1 up
115.Ed
116.Pp
117Create an IBSS network with 128-bit WEP encryption on the channel 4:
118.Bd -literal -offset indent
119ifconfig wlan0 create wlandev wpi0 wlanmode adhoc ssid my_net \e
120	wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \e
121	channel 4
122.Ed
123.Pp
124Join/create an 802.11b IBSS network with network name
125.Dq Li my_net :
126.Bd -literal -offset indent
127ifconfig wlan0 create wlandev wpi0 wlanmode adhoc
128ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e
129	mode 11b
130.Ed
131.Pp
132Create an 802.11g host-based access point:
133.Bd -literal -offset indent
134ifconfig wlan0 create wlandev wpi0 wlanmode hostap
135ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e
136	mode 11g
137.Ed
138.Sh DIAGNOSTICS
139.Bl -diag
140.It "wpi%d: could not load firmware image '%s'"
141The driver failed to load the firmware image using the
142.Xr firmware 9
143subsystem.
144Verify the
145.Xr wpifw 4
146firmware module is installed.
147.It "wpi%d: %s: timeout waiting for adapter to initialize, error %d"
148The onboard microcontroller failed to initialize in time.
149This should not happen.
150.It "wpi%d: %s: could not load boot firmware"
151An attempt to upload the boot firmware image to the onboard microcontroller
152failed.
153This should not happen.
154.It "wpi%d: device timeout"
155A frame dispatched to the hardware for transmission did not complete in time.
156The driver will reset the hardware and continue.
157This should not happen.
158.It "wpi%d: scan timeout"
159Firmware scan command response was not received in time.
160The driver will reset the hardware and continue.
161This should not happen.
162.It "wpi%d: fatal firmware error"
163The onboard microcontroller crashed for some reason.
164The driver will reset the hardware and continue.
165This should not happen.
166.It "wpi%d: RF switch: radio disabled"
167The hardware switch controlling the radio is currently turned off.
168Data transmission is not possible in this state.
169.It "wpi%d: can't map mem space"
170The driver was unable to map the device registers into the host address space.
171This should not happen.
172.It "wpi%d: can't map interrupt"
173The driver was unable to allocate an IRQ for the device interrupt.
174This should not happen.
175.It "wpi%d: can't establish interrupt, error %d"
176The driver was unable to install the device interrupt handler.
177This should not happen.
178.It "wpi%d: %s: bus_dmamap_load failed, error %d"
179The driver was unable to map newly allocated mbuf to device
180visible address space.
181Contents of currently received frame will be lost.
182This should not happen.
183.El
184.Sh SEE ALSO
185.Xr pci 4 ,
186.Xr wlan 4 ,
187.Xr wlan_amrr 4 ,
188.Xr wlan_ccmp 4 ,
189.Xr wlan_tkip 4 ,
190.Xr wlan_wep 4 ,
191.Xr wlan_xauth 4 ,
192.Xr wpifw 4 ,
193.Xr hostapd 8 ,
194.Xr ifconfig 8 ,
195.Xr wpa_supplicant 8
196.Sh AUTHORS
197.An -nosplit
198The original
199.Nm
200driver was written for
201.Ox
202by
203.An Damien Bergamini Aq Mt damien.bergamini@free.fr .
204.An Benjamin Close Aq Mt benjsc@FreeBSD.org
205ported
206.Nm
207to
208.Fx .
209.Sh CAVEATS
210Hostap mode is not directly supported by the device;
211it is implemented through IBSS mode (as a result, DFS/passive
212channels are not available in this mode).
213.Pp
214Powersave may be unstable on some networks (results in
215occasional 'wpi%d: device timeout' messages); you can try
216to disable it to improve device stability.
217