rsu(4), a driver for Realtek RTL8188SU, RTL8191SU and RTL8192SU

802.11n USB devices.
These are FullMAC devices that require a firmware to operate;
see man page for details.

Great thanks to Brad for donating hardware.
Committed over the TRENDnet TEW-649UB.

ok deraadt@

3 files changed, 166 insertions, 4 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 3f2961231e2..52e28c32226 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.517 2010/11/05 16:58:12 damien Exp $
+#	$OpenBSD: Makefile,v 1.518 2010/12/11 20:48:21 damien Exp $
 
 MAN=	aac.4 ac97.4 acphy.4 \
 	acpi.4 acpiac.4 acpiasus.4 acpibat.4 acpibtn.4 acpicpu.4 acpidock.4 \
@@ -44,7 +44,7 @@ MAN=	aac.4 ac97.4 acphy.4 \
 	pf.4 pflog.4 pflow.4 pfsync.4 pgt.4 piixpm.4 pim.4 \
 	pms.4 ppb.4 ppp.4 pppoe.4 pty.4 puc.4 pwdog.4 qsphy.4 radio.4 raid.4 \
 	ral.4 random.4 ray.4 rd.4 re.4 rgephy.4 ricohrtc.4 \
-	rl.4 rlphy.4 route.4 rt.4 rum.4 run.4 \
+	rl.4 rlphy.4 route.4 rsu.4 rt.4 rum.4 run.4 \
 	rtfps.4 rtii.4 rtw.4 safe.4 safte.4 san.4 sbt.4 sbus.4 schsio.4 \
 	scsi.4 sd.4 \
 	sdmmc.4 sdhc.4 se.4 ses.4 \
diff --git a/share/man/man4/rsu.4 b/share/man/man4/rsu.4
new file mode 100644
index 00000000000..56eddfc988a
--- /dev/null
+++ b/share/man/man4/rsu.4
@@ -0,0 +1,160 @@
+.\" $OpenBSD: rsu.4,v 1.1 2010/12/11 20:48:21 damien Exp $
+.\"
+.\" Copyright (c) 2010 Damien Bergamini <damien.bergamini@free.fr>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 11 2010 $
+.Dt RSU 4
+.Os
+.Sh NAME
+.Nm rsu
+.Nd Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n wireless network device
+.Sh SYNOPSIS
+.Cd "rsu* at uhub? port ?"
+.Sh DESCRIPTION
+The
+.Nm
+driver supports USB 2.0 wireless network devices based on Realtek
+RTL8188SU, RTL8191SU and RTL8192SU chipsets.
+.Pp
+The RTL8188SU is a highly integrated 802.11n adapter that combines
+a MAC, a 1T1R capable baseband and an RF in a single chip.
+It operates in the 2GHz spectrum only.
+.Pp
+The RTL8191SU is a highly integrated multiple-in, single-out (MISO)
+802.11n adapter that combines a MAC, a 1T2R capable baseband and an
+RF in a single chip.
+It operates in the 2GHz spectrum only.
+.Pp
+The RTL8192CU is a highly integrated multiple-in, multiple-out (MIMO)
+802.11n adapter that combines a MAC, a 2T2R capable baseband and an
+RF in a single chip.
+It operates in the 2GHz spectrum only.
+.Pp
+These are the modes the
+.Nm
+driver can operate in:
+.Bl -tag -width "IBSS-masterXX"
+.It BSS mode
+Also known as
+.Em infrastructure
+mode, this is used when associating with an access point, through
+which all traffic passes.
+This mode is the default.
+.El
+.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.
+.Pp
+The
+.Nm
+driver can be configured at runtime with
+.Xr ifconfig 8
+or on boot with
+.Xr hostname.if 5 .
+.Sh FILES
+The driver needs at least version 1.1 of the following firmware file,
+which is loaded when an interface is attached:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It /etc/firmware/rsu-rtl8712fw
+.El
+.Pp
+A prepackaged version of the firmware, designed to be used with
+.Xr pkg_add 1 ,
+can be found at:
+.Bd -literal -offset 3n
+http://damien.bergamini.free.fr/packages/openbsd/rsu-firmware-1.1.tgz
+.Ed
+.Sh HARDWARE
+The following adapters should work:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It ASUS USB-N10
+.It D-Link DWA-131 A1
+.It Hercules HWNUm-300
+.It Sitecom WL-353
+.It TRENDnet TEW-648UB
+.It TRENDnet TEW-649UB
+.El
+.Sh EXAMPLES
+The following
+.Xr hostname.if 5
+example configures rsu0 to join whatever network is available on boot,
+using WEP key
+.Dq 0x1deadbeef1 ,
+channel 11, obtaining an IP address using DHCP:
+.Bd -literal -offset indent
+dhcp NONE NONE NONE nwkey 0x1deadbeef1 chan 11
+.Ed
+.Pp
+Configure rsu0 to join network
+.Dq my_net
+using WPA with passphrase
+.Dq my_passphrase :
+.Bd -literal -offset indent
+# ifconfig rsu0 nwid my_net wpakey my_passphrase
+.Ed
+.Pp
+Join an existing BSS network,
+.Dq my_net :
+.Bd -literal -offset indent
+# ifconfig rsu0 192.168.1.1 netmask 0xffffff00 nwid my_net
+.Ed
+.Sh DIAGNOSTICS
+.Bl -diag
+.It "rsu%d: error %d, could not read firmware %s"
+For some reason, the driver was unable to read the microcode file from the
+filesystem.
+The file might be missing or corrupted.
+.It "rsu%d: device timeout"
+A frame dispatched to the hardware for transmission did not complete in time.
+The driver will reset the hardware.
+This should not happen.
+.El
+.Sh SEE ALSO
+.Xr arp 4 ,
+.Xr ifmedia 4 ,
+.Xr intro 4 ,
+.Xr netintro 4 ,
+.Xr usb 4 ,
+.Xr hostname.if 5 ,
+.Xr ifconfig 8
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Ox 4.9 .
+.Sh AUTHORS
+The
+.Nm
+driver was written by
+.An Damien Bergamini Aq damien@openbsd.org
+.
+.Sh CAVEATS
+The
+.Nm
+driver does not support any of the 802.11n capabilities offered by the
+adapters.
+Additional work is required in
+.Xr ieee80211 9
+before those features can be supported.
diff --git a/share/man/man4/usb.4 b/share/man/man4/usb.4
index 93fb83ab16e..9c4cc8b3e2b 100644
--- a/share/man/man4/usb.4
+++ b/share/man/man4/usb.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: usb.4,v 1.123 2010/11/05 17:01:59 damien Exp $
+.\"	$OpenBSD: usb.4,v 1.124 2010/12/11 20:48:21 damien Exp $
 .\"	$NetBSD: usb.4,v 1.15 1999/07/29 14:20:32 augustss Exp $
 .\"
 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
@@ -28,7 +28,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 5 2010 $
+.Dd $Mdocdate: December 11 2010 $
 .Dt USB 4
 .Os
 .Sh NAME
@@ -146,6 +146,8 @@ USB Remote NDIS Ethernet device
 Atmel AT76C50x IEEE 802.11b wireless network device
 .It Xr otus 4
 Atheros USB IEEE 802.11a/g/n wireless network device
+.It Xr rsu 4
+Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n wireless network device
 .It Xr rum 4
 Ralink Technology USB IEEE 802.11a/b/g wireless network device
 .It Xr run 4