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