1.\" $OpenBSD: rtwn.4,v 1.2 2015/07/09 11:28:53 stsp Exp $ 2.\" 3.\" Copyright (c) 2010 Damien Bergamini <damien.bergamini@free.fr> 4.\" Copyright (c) 2015 Stefan Sperling <stsp@openbsd.org> 5.\" Copyright (c) 2016 Andriy Voskoboinyk <avos@freebsd.org> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd January 2, 2019 20.Dt RTWN 4 21.Os 22.Sh NAME 23.Nm rtwn 24.Nd Realtek IEEE 802.11 wireless network driver 25.Sh SYNOPSIS 26.Cd "options RTWN_DEBUG" 27.Cd "options RTWN_WITHOUT_UCODE" 28.Pp 29To compile this driver into the kernel, 30place the following lines in your 31kernel configuration file: 32.Bd -ragged -offset indent 33.Cd "device rtwn" 34.Cd "device rtwnfw" 35.Cd "device rtwn_usb" 36.Cd "device rtwn_pci" 37.Cd "device wlan" 38.Cd "device firmware" 39.Ed 40.Pp 41Alternatively, to load the driver as a 42module at boot time, place following lines in 43.Xr loader.conf 5 : 44.Bd -literal -offset indent 45if_rtwn_pci_load="YES" 46if_rtwn_usb_load="YES" 47.Ed 48.Sh DESCRIPTION 49The 50.Nm 51driver provides support for wireless network devices based on 52the Realtek RTL8192C, RTL8188E, RTL8192E, RTL8812A and RTL8821A 53programming APIs. 54These APIs are used by a wide variety of chips; 55most chips with USB and some with PCI interface are supported. 56.Pp 57To enable use for PCI/PCIe systems, see the rtwn_pci(4) driver; 58for USB devices, use the rtwn_usb(4) driver. 59.Pp 60The driver supports 61.Cm station , 62.Cm adhoc , 63.Cm hostap 64and 65.Cm monitor 66mode operation. 67There are no limitations for number of 68.Cm monitor 69mode 70virtual interfaces; in addition to any other virtual interface 71one 72.Cm station 73interface can be added (Note: RTL8821AU supports two non-monitor 74mode interfaces at the same time). 75.Pp 76All chips have hardware support for WEP, AES-CCM and TKIP encryption. 77.Pp 78The 79.Nm 80driver can be configured at runtime with 81.Xr ifconfig 8 . 82.Sh FILES 83.Bl -tag -width ".Pa /usr/share/doc/legal/realtek.LICENSE" -compact 84.It Pa /usr/share/doc/legal/realtek.LICENSE 85.Nm 86firmware license 87.El 88.Pp 89The driver (if not compiled with 90.Cd options RTWN_WITHOUT_UCODE 91) may use following firmware files, which are loaded 92when an interface is brought up: 93.Bl -tag -width Ds -offset indent -compact 94.It Pa /boot/kernel/rtwn-rtl8188eefw.ko 95.It Pa /boot/kernel/rtwn-rtl8188eufw.ko 96.It Pa /boot/kernel/rtwn-rtl8192cfwE_B.ko 97.It Pa /boot/kernel/rtwn-rtl8192cfwE.ko 98.It Pa /boot/kernel/rtwn-rtl8192cfwT.ko 99.It Pa /boot/kernel/rtwn-rtl8192cfwU.ko 100.It Pa /boot/kernel/rtwn-rtl8192eufw.ko 101.It Pa /boot/kernel/rtwn-rtl8812aufw.ko 102.It Pa /boot/kernel/rtwn-rtl8821aufw.ko 103.El 104.Sh EXAMPLES 105Join an existing BSS network (i.e., connect to an access point): 106.Bd -literal -offset indent 107ifconfig wlan create wlandev rtwn0 inet 192.168.0.20 \e 108 netmask 0xffffff00 109.Ed 110.Pp 111Join a specific BSS network with network name 112.Dq Li my_net : 113.Pp 114.Dl "ifconfig wlan create wlandev rtwn0 ssid my_net up" 115.Pp 116Join a specific BSS network with 64-bit WEP encryption: 117.Bd -literal -offset indent 118ifconfig wlan create wlandev rtwn0 ssid my_net \e 119 wepmode on wepkey 0x1234567890 weptxkey 1 up 120.Ed 121.Pp 122Create an IBSS network with 128-bit WEP encryption on the channel 4: 123.Bd -literal -offset indent 124ifconfig wlan create wlandev rtwn0 wlanmode adhoc ssid my_net \e 125 wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \e 126 channel 4 127.Ed 128.Pp 129Join/create an 802.11b IBSS network with network name 130.Dq Li my_net : 131.Bd -literal -offset indent 132ifconfig wlan0 create wlandev rtwn0 wlanmode adhoc 133ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e 134 mode 11b 135.Ed 136.Pp 137Create a host-based access point: 138.Bd -literal -offset indent 139ifconfig wlan0 create wlandev rtwn0 wlanmode hostap 140ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap 141.Ed 142.Sh LOADER TUNABLES 143Tunables can be set at the 144.Xr loader 8 145prompt before booting the kernel or stored in 146.Xr loader.conf 5 . 147.Bl -tag -width indent 148.It Va dev.rtwn.%d.hwcrypto 149This tunable controls how key slots are assigned: 150.br 1510 - disable h/w crypto support. 152Features that require access to frame contents (e.g., TCP/UDP/IP Rx 153checksum validation) will not work; 154.br 1551 - use h/w crypto support for pairwise keys only; 156.br 1572 - use h/w crypto support for all keys; may not work for 158multi-vap configurations. 159.br 160By default it is set to 1. 161.It Va dev.rtwn.%d.ratectl 162This tunable switches between rate control implementations: 163.br 1640 - no rate control; 165.br 1661 - driver sends 'tx complete' reports to net80211; algorithm 167is controlled via net80211; 168.br 1692 - firmware-based rate control. 170.br 171By default it is set to 1; however driver may choose another 172algorithm in case if it is not implemented 173.br 174Currently selected algorithm is reported via 175.Em Va dev.rtwn.%d.ratectl_selected 176read-only OID. 177.It Va dev.rtwn.%d.rx_buf_size 178(USB only) Controls size of temporary Rx buffer; smaller buffer size 179may increase number of interrupts. 180.El 181.Sh DIAGNOSTICS 182.Bl -diag 183.It "rtwn%d: could not read efuse byte at address 0x%x" 184.It "rtwn%d: %s: cannot read rom, error %d" 185There was an error while reading ROM; device attach will be aborted. 186This should not happen. 187.It "rtwn%d: failed loadfirmware of file %s" 188For some reason, the driver was unable to read the microcode file from the 189filesystem. 190The file might be missing or corrupted. 191The driver will disable firmware-dependent features. 192.It "rtwn%d: wrong firmware size (%zu)" 193.It "rtwn%d: %s: failed to upload firmware %s (error %d)" 194.It "rtwn%d: timeout waiting for firmware readiness" 195Firmware upload failed; the file might be corrupted. 196The driver will disable firmware-dependent features. 197This should not happen. 198.It "rtwn%d: device timeout" 199A frame dispatched to the hardware for transmission did not complete in time. 200The driver will reset the hardware. 201This should not happen. 202.El 203.Sh SEE ALSO 204.Xr intro 4 , 205.Xr netintro 4 , 206.Xr rtwn_pci 4 , 207.Xr rtwn_usb 4 , 208.Xr rtwnfw 4 , 209.Xr wlan 4 , 210.Xr wlan_amrr 4 , 211.Xr wlan_ccmp 4 , 212.Xr wlan_tkip 4 , 213.Xr wlan_wep 4 , 214.Xr wlan_xauth 4 , 215.Xr hostapd 8 , 216.Xr ifconfig 8 , 217.Xr wpa_supplicant 8 218.Sh HISTORY 219The 220.Cm urtwn 221driver first appeared in 222.Ox 4.9 223and 224.Fx 10.0 ; 225the 226.Nm 227driver first appeared in 228.Ox 5.8 . 229.Sh AUTHORS 230The 231.Nm 232driver was initially written by 233.An -nosplit 234.An Stefan Sperling Aq Mt stsp@openbsd.org 235and ported by 236.An Kevin Lo Aq Mt kevlo@freebsd.org . 237It was based on the 238.Cm urtwn 239driver written by 240.An Damien Bergamini Aq Mt damien.bergamini@free.fr . 241.Sh BUGS 242The 243.Nm 244driver currently does not implement firmware-based rate control. 245