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