wpi: refresh manpage.

Reflect all recent changes in the manpage:
- add adhoc-demo and hostap into list of supported modes;
add few examples for them;
- mention encryption/decryption offload for CCMP cipher;
- extend list of driver messages in the DIAGNOSTICS;
- document hostap mode limitations / powersave instability
in the CAVEATS section.

Differential Revision:	https://reviews.freebsd.org/D5149

1 files changed, 87 insertions, 13 deletions

diff --git a/share/man/man4/wpi.4 b/share/man/man4/wpi.4
index 04539f7..1de3c8d 100644
--- a/share/man/man4/wpi.4
+++ b/share/man/man4/wpi.4
@@ -1,6 +1,8 @@
 .\" Copyright (c) 2004-2007
 .\"	Damien Bergamini <damien.bergamini@free.fr>. All rights reserved.
 .\"	Benjamin Close <Benjamin.Close@clearchain.com>. All rights reserved.
+.\" Copyright (c) 2016 Andriy Voskoboinyk <avos@FreeBSD.org>
+.\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -26,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd October 15, 2015
+.Dd January 31, 2016
 .Dt WPI 4
 .Os
 .Sh NAME
@@ -57,20 +59,39 @@ The
 driver provides support for the
 .Tn Intel
 3945ABG Wireless network adapter.
-.Nm
-supports
+The driver supports
 .Cm station ,
 .Cm adhoc ,
+.Cm adhoc-demo ,
+.Cm hostap ,
 and
 .Cm monitor
 mode operation.
 Only one virtual interface may be configured at any time.
-For more information on configuring this device, see
-.Xr ifconfig 8 .
+.Pp
+The
+.Nm
+driver can be configured to use
+Wired Equivalent Privacy (WEP) or
+Wi-Fi Protected Access (WPA-PSK and WPA2-PSK).
+WPA is the de facto encryption standard for wireless networks.
+It is strongly recommended that WEP
+not be used as the sole mechanism
+to secure wireless communication,
+due to serious weaknesses in it.
+The
+.Nm
+driver offloads both encryption and decryption of data frames to the
+hardware for the CCMP cipher.
 .Pp
 This driver requires the firmware built with the
 .Nm wpifw
 module to work.
+.Pp
+The
+.Nm
+driver can be configured at runtime with
+.Xr ifconfig 8 .
 .Sh FILES
 .Bl -tag -width ".Pa /usr/share/doc/legal/intel_wpi.LICENSE" -compact
 .It Pa /usr/share/doc/legal/intel_wpi.LICENSE
@@ -95,10 +116,26 @@ ifconfig wlan0 create wlandev wpi0 ssid my_net \e
 	wepmode on wepkey 0x1234567890 weptxkey 1 up
 .Ed
 .Pp
-Join a specific BSS network with 128-bit WEP encryption:
+Create an IBSS network with 128-bit WEP encryption on the channel 4:
 .Bd -literal -offset indent
 ifconfig wlan0 create wlandev wpi0 wlanmode adhoc ssid my_net \e
-    wepmode on wepkey 0x01020304050607080910111213 weptxkey 1
+	wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \e
+	channel 4
+.Ed
+.Pp
+Join/create an 802.11b IBSS network with network name
+.Dq Li my_net :
+.Bd -literal -offset indent
+ifconfig wlan0 create wlandev wpi0 wlanmode adhoc
+ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e
+	mode 11b
+.Ed
+.Pp
+Create an 802.11g host-based access point:
+.Bd -literal -offset indent
+ifconfig wlan0 create wlandev wpi0 wlanmode hostap
+ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e
+	mode 11g
 .Ed
 .Sh DIAGNOSTICS
 .Bl -diag
@@ -109,20 +146,53 @@ subsystem.
 Verify the
 .Xr wpifw
 firmware module is installed.
+.It "wpi%d: %s: timeout waiting for adapter to initialize, error %d"
+The onboard microcontroller failed to initialize in time.
+This should not happen.
+.It "wpi%d: %s: could not load boot firmware"
+An attempt to upload the boot firmware image to the onboard microcontroller
+failed.
+This should not happen.
+.It "wpi%d: device timeout"
+A frame dispatched to the hardware for transmission did not complete in time.
+The driver will reset the hardware and continue.
+This should not happen.
+.It "wpi%d: scan timeout"
+Firmware scan command response was not received in time.
+The driver will reset the hardware and continue.
+This should not happen.
 .It "wpi%d: fatal firmware error"
-An unknown error has occurred in the uploaded firmware, you may have to
-unload/reload the driver to continue.
-.It "wpi%d: Radio transmitter is switched off"
+The onboard microcontroller crashed for some reason.
+The driver will reset the hardware and continue.
+This should not happen.
+.It "wpi%d: RF switch: radio disabled"
 The hardware switch controlling the radio is currently turned off.
 Data transmission is not possible in this state.
+.It "wpi%d: can't map mem space"
+The driver was unable to map the device registers into the host address space.
+This should not happen.
+.It "wpi%d: can't map interrupt"
+The driver was unable to allocate an IRQ for the device interrupt.
+This should not happen.
+.It "wpi%d: can't establish interrupt, error %d"
+The driver was unable to install the device interrupt handler.
+This should not happen.
+.It "wpi%d: %s: bus_dmamap_load failed, error %d"
+The driver was unable to map newly allocated mbuf to device
+visible address space.
+Contents of currently received frame will be lost.
+This should not happen.
 .El
 .Sh SEE ALSO
 .Xr pci 4 ,
 .Xr wlan 4 ,
+.Xr wlan_amrr 4 ,
 .Xr wlan_ccmp 4 ,
 .Xr wlan_tkip 4 ,
 .Xr wlan_wep 4 ,
+.Xr wlan_xauth 4 ,
 .Xr wpifw 4 ,
+.Xr hostapd 8 ,
 .Xr ifconfig 8 ,
 .Xr wpa_supplicant 8
 .Sh AUTHORS
@@ -138,7 +208,11 @@ ported
 .Nm
 to
 .Fx .
-.Sh BUGS
-Not all the error messages are documented here.
+.Sh CAVEATS
+Hostap mode is not directly supported by the device;
+it is implemented through IBSS mode (as a result, DFS/passive
+channels are not available in this mode).
 .Pp
-Background scanning is not currently supported.
+Powersave may be unstable on some networks (results in
+occasional 'wpi%d: device timeout' messages); you can try
+to disable it to improve device stability.