1*93b30f1bSAlexander Ziaee.\"- 2*93b30f1bSAlexander Ziaee.\" SPDX-License-Identifier: ISC 3*93b30f1bSAlexander Ziaee.\" 42600131bSAdrian Chadd.\" $OpenBSD: rtwn.4,v 1.2 2015/07/09 11:28:53 stsp Exp $ 52600131bSAdrian Chadd.\" 62600131bSAdrian Chadd.\" Copyright (c) 2010 Damien Bergamini <damien.bergamini@free.fr> 72600131bSAdrian Chadd.\" Copyright (c) 2015 Stefan Sperling <stsp@openbsd.org> 87453645fSAndriy Voskoboinyk.\" Copyright (c) 2016 Andriy Voskoboinyk <avos@freebsd.org> 92600131bSAdrian Chadd.\" 102600131bSAdrian Chadd.\" Permission to use, copy, modify, and distribute this software for any 112600131bSAdrian Chadd.\" purpose with or without fee is hereby granted, provided that the above 122600131bSAdrian Chadd.\" copyright notice and this permission notice appear in all copies. 132600131bSAdrian Chadd.\" 142600131bSAdrian Chadd.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 152600131bSAdrian Chadd.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 162600131bSAdrian Chadd.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 172600131bSAdrian Chadd.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 182600131bSAdrian Chadd.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 192600131bSAdrian Chadd.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 202600131bSAdrian Chadd.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 212600131bSAdrian Chadd.\" 22*93b30f1bSAlexander Ziaee.Dd November 10, 2024 232600131bSAdrian Chadd.Dt RTWN 4 242600131bSAdrian Chadd.Os 252600131bSAdrian Chadd.Sh NAME 262600131bSAdrian Chadd.Nm rtwn 27*93b30f1bSAlexander Ziaee.Nd Realtek IEEE 802.11n/ac wireless network driver 282600131bSAdrian Chadd.Sh SYNOPSIS 297453645fSAndriy Voskoboinyk.Cd "options RTWN_DEBUG" 307453645fSAndriy Voskoboinyk.Cd "options RTWN_WITHOUT_UCODE" 317453645fSAndriy Voskoboinyk.Pp 322600131bSAdrian ChaddTo compile this driver into the kernel, 332600131bSAdrian Chaddplace the following lines in your 342600131bSAdrian Chaddkernel configuration file: 352600131bSAdrian Chadd.Bd -ragged -offset indent 362600131bSAdrian Chadd.Cd "device rtwn" 372600131bSAdrian Chadd.Cd "device rtwnfw" 387453645fSAndriy Voskoboinyk.Cd "device rtwn_usb" 397453645fSAndriy Voskoboinyk.Cd "device rtwn_pci" 402600131bSAdrian Chadd.Cd "device wlan" 412600131bSAdrian Chadd.Cd "device firmware" 422600131bSAdrian Chadd.Ed 432600131bSAdrian Chadd.Pp 442600131bSAdrian ChaddAlternatively, to load the driver as a 457453645fSAndriy Voskoboinykmodule at boot time, place following lines in 462600131bSAdrian Chadd.Xr loader.conf 5 : 472600131bSAdrian Chadd.Bd -literal -offset indent 487453645fSAndriy Voskoboinykif_rtwn_pci_load="YES" 497453645fSAndriy Voskoboinykif_rtwn_usb_load="YES" 502600131bSAdrian Chadd.Ed 512600131bSAdrian Chadd.Sh DESCRIPTION 522600131bSAdrian ChaddThe 532600131bSAdrian Chadd.Nm 54*93b30f1bSAlexander Ziaeedriver provides support for 802.11n/ac wireless network PHYs supplied by 55*93b30f1bSAlexander Ziaee.Xr rtwn_pci 4 56*93b30f1bSAlexander Ziaeeand 57*93b30f1bSAlexander Ziaee.Xr rtwn_usb 4 . 582600131bSAdrian Chadd.Pp 59*93b30f1bSAlexander ZiaeeThe 60*93b30f1bSAlexander Ziaee.Nm 61*93b30f1bSAlexander Ziaeedriver supports 627453645fSAndriy Voskoboinyk.Cm station , 637453645fSAndriy Voskoboinyk.Cm adhoc , 647453645fSAndriy Voskoboinyk.Cm hostap 657453645fSAndriy Voskoboinykand 667453645fSAndriy Voskoboinyk.Cm monitor 677453645fSAndriy Voskoboinykmode operation. 687453645fSAndriy VoskoboinykThere are no limitations for number of 697453645fSAndriy Voskoboinyk.Cm monitor 707453645fSAndriy Voskoboinykmode 717453645fSAndriy Voskoboinykvirtual interfaces; in addition to any other virtual interface 727453645fSAndriy Voskoboinykone 737453645fSAndriy Voskoboinyk.Cm station 747453645fSAndriy Voskoboinykinterface can be added (Note: RTL8821AU supports two non-monitor 757453645fSAndriy Voskoboinykmode interfaces at the same time). 762600131bSAdrian Chadd.Pp 777453645fSAndriy VoskoboinykAll chips have hardware support for WEP, AES-CCM and TKIP encryption. 782600131bSAdrian Chadd.Pp 792600131bSAdrian ChaddThe 802600131bSAdrian Chadd.Nm 812600131bSAdrian Chadddriver can be configured at runtime with 822600131bSAdrian Chadd.Xr ifconfig 8 . 83*93b30f1bSAlexander Ziaee.Sh HARDWARE 84*93b30f1bSAlexander ZiaeeThe 85*93b30f1bSAlexander Ziaee.Nm 86*93b30f1bSAlexander Ziaeedriver supports USB and PCI devices with the following chipsets: 87*93b30f1bSAlexander Ziaee.Pp 88*93b30f1bSAlexander Ziaee.Bl -bullet -offset indent -compact 89*93b30f1bSAlexander Ziaee.It 90*93b30f1bSAlexander ZiaeeRealtek 802.11n wireless 8188e (RTL8188E) 91*93b30f1bSAlexander Ziaee.It 92*93b30f1bSAlexander ZiaeeRealtek 802.11n wireless 8192c (RTL8192C) 93*93b30f1bSAlexander Ziaee.It 94*93b30f1bSAlexander ZiaeeRealtek 802.11n wireless 8192e (RTL8192E) 95*93b30f1bSAlexander Ziaee.It 96*93b30f1bSAlexander ZiaeeRealtek 802.11ac wireless 8812a (RTL8812A) 97*93b30f1bSAlexander Ziaee.It 98*93b30f1bSAlexander ZiaeeRealtek 802.11ac wireless 8821a (RTL8821A) 99*93b30f1bSAlexander Ziaee.El 100*93b30f1bSAlexander Ziaee.Pp 101*93b30f1bSAlexander ZiaeeFor specific devices, see 102*93b30f1bSAlexander Ziaee.Xr rtwn_pci 4 103*93b30f1bSAlexander Ziaeeand 104*93b30f1bSAlexander Ziaee.Xr rtwn_usb 4 . 1052600131bSAdrian Chadd.Sh FILES 106*93b30f1bSAlexander Ziaee.Bl -tag -width "/usr/share/doc/legal/realtek.LICENSE" -compact 1077453645fSAndriy Voskoboinyk.It Pa /usr/share/doc/legal/realtek.LICENSE 1087453645fSAndriy Voskoboinyk.Nm 1097453645fSAndriy Voskoboinykfirmware license 1107453645fSAndriy Voskoboinyk.El 1112600131bSAdrian Chadd.Pp 112*93b30f1bSAlexander ZiaeeThe driver 113*93b30f1bSAlexander Ziaee.Pq if not compiled with Cd options RTWN_WITHOUT_UCODE 114*93b30f1bSAlexander Ziaeemay use following firmware files, 115*93b30f1bSAlexander Ziaeewhich are loaded when an interface is brought up: 116*93b30f1bSAlexander Ziaee.Pp 1172600131bSAdrian Chadd.Bl -tag -width Ds -offset indent -compact 118b3f3786eSAndriy Voskoboinyk.It Pa /boot/kernel/rtwn-rtl8188eefw.ko 1197453645fSAndriy Voskoboinyk.It Pa /boot/kernel/rtwn-rtl8188eufw.ko 1207453645fSAndriy Voskoboinyk.It Pa /boot/kernel/rtwn-rtl8192cfwE_B.ko 1217453645fSAndriy Voskoboinyk.It Pa /boot/kernel/rtwn-rtl8192cfwE.ko 1227453645fSAndriy Voskoboinyk.It Pa /boot/kernel/rtwn-rtl8192cfwT.ko 1232600131bSAdrian Chadd.It Pa /boot/kernel/rtwn-rtl8192cfwU.ko 12460b9567dSKevin Lo.It Pa /boot/kernel/rtwn-rtl8192eufw.ko 1257453645fSAndriy Voskoboinyk.It Pa /boot/kernel/rtwn-rtl8812aufw.ko 1267453645fSAndriy Voskoboinyk.It Pa /boot/kernel/rtwn-rtl8821aufw.ko 1272600131bSAdrian Chadd.El 1282600131bSAdrian Chadd.Sh EXAMPLES 1292600131bSAdrian ChaddJoin an existing BSS network (i.e., connect to an access point): 130*93b30f1bSAlexander Ziaee.Pp 131*93b30f1bSAlexander Ziaee.Dl ifconfig wlan create wlandev rtwn0 inet 192.0.2.20/24 1322600131bSAdrian Chadd.Pp 1332600131bSAdrian ChaddJoin a specific BSS network with network name 134*93b30f1bSAlexander Ziaee.Ar my_net : 1352600131bSAdrian Chadd.Pp 136*93b30f1bSAlexander Ziaee.Dl ifconfig wlan create wlandev rtwn0 ssid my_net up 1372600131bSAdrian Chadd.Pp 1382600131bSAdrian ChaddJoin a specific BSS network with 64-bit WEP encryption: 1392600131bSAdrian Chadd.Bd -literal -offset indent 1402600131bSAdrian Chaddifconfig wlan create wlandev rtwn0 ssid my_net \e 1412600131bSAdrian Chadd wepmode on wepkey 0x1234567890 weptxkey 1 up 1422600131bSAdrian Chadd.Ed 1437453645fSAndriy Voskoboinyk.Pp 1447453645fSAndriy VoskoboinykCreate an IBSS network with 128-bit WEP encryption on the channel 4: 1457453645fSAndriy Voskoboinyk.Bd -literal -offset indent 1467453645fSAndriy Voskoboinykifconfig wlan create wlandev rtwn0 wlanmode adhoc ssid my_net \e 1477453645fSAndriy Voskoboinyk wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \e 1487453645fSAndriy Voskoboinyk channel 4 1497453645fSAndriy Voskoboinyk.Ed 1507453645fSAndriy Voskoboinyk.Pp 1517453645fSAndriy VoskoboinykJoin/create an 802.11b IBSS network with network name 152*93b30f1bSAlexander Ziaee.Ar my_net : 1537453645fSAndriy Voskoboinyk.Bd -literal -offset indent 1547453645fSAndriy Voskoboinykifconfig wlan0 create wlandev rtwn0 wlanmode adhoc 155*93b30f1bSAlexander Ziaeeifconfig wlan0 inet 192.0.2.20/24 ssid my_net mode 11b 1567453645fSAndriy Voskoboinyk.Ed 1577453645fSAndriy Voskoboinyk.Pp 1587453645fSAndriy VoskoboinykCreate a host-based access point: 1597453645fSAndriy Voskoboinyk.Bd -literal -offset indent 1607453645fSAndriy Voskoboinykifconfig wlan0 create wlandev rtwn0 wlanmode hostap 161*93b30f1bSAlexander Ziaeeifconfig wlan0 inet 192.0.2.20/24 ssid my_ap 1627453645fSAndriy Voskoboinyk.Ed 1637453645fSAndriy Voskoboinyk.Sh LOADER TUNABLES 1647453645fSAndriy VoskoboinykTunables can be set at the 1657453645fSAndriy Voskoboinyk.Xr loader 8 1667453645fSAndriy Voskoboinykprompt before booting the kernel or stored in 1677453645fSAndriy Voskoboinyk.Xr loader.conf 5 . 1687453645fSAndriy Voskoboinyk.Bl -tag -width indent 1697453645fSAndriy Voskoboinyk.It Va dev.rtwn.%d.hwcrypto 1707453645fSAndriy VoskoboinykThis tunable controls how key slots are assigned: 171*93b30f1bSAlexander Ziaee.Pp 1723d265fceSGordon Bergling0 - disable h/w crypto support. 1733d265fceSGordon BerglingFeatures that require access to frame contents (e.g., TCP/UDP/IP Rx 1743d265fceSGordon Berglingchecksum validation) will not work; 175*93b30f1bSAlexander Ziaee.Pp 1767453645fSAndriy Voskoboinyk1 - use h/w crypto support for pairwise keys only; 177*93b30f1bSAlexander Ziaee.Pp 1787453645fSAndriy Voskoboinyk2 - use h/w crypto support for all keys; may not work for 1797453645fSAndriy Voskoboinykmulti-vap configurations. 180*93b30f1bSAlexander Ziaee.Pp 1817453645fSAndriy VoskoboinykBy default it is set to 1. 1827453645fSAndriy Voskoboinyk.It Va dev.rtwn.%d.ratectl 1837453645fSAndriy VoskoboinykThis tunable switches between rate control implementations: 184*93b30f1bSAlexander Ziaee.Pp 1857453645fSAndriy Voskoboinyk0 - no rate control; 186*93b30f1bSAlexander Ziaee.Pp 1877453645fSAndriy Voskoboinyk1 - driver sends 'tx complete' reports to net80211; algorithm 1887453645fSAndriy Voskoboinykis controlled via net80211; 189*93b30f1bSAlexander Ziaee.Pp 1907453645fSAndriy Voskoboinyk2 - firmware-based rate control. 191*93b30f1bSAlexander Ziaee.Pp 1927453645fSAndriy VoskoboinykBy default it is set to 1; however driver may choose another 1937453645fSAndriy Voskoboinykalgorithm in case if it is not implemented 194*93b30f1bSAlexander Ziaee.Pp 1957453645fSAndriy VoskoboinykCurrently selected algorithm is reported via 196*93b30f1bSAlexander Ziaee.Va dev.rtwn.%d.ratectl_selected 1977453645fSAndriy Voskoboinykread-only OID. 1987e8196cdSAndriy Voskoboinyk.It Va dev.rtwn.%d.rx_buf_size 1997e8196cdSAndriy Voskoboinyk(USB only) Controls size of temporary Rx buffer; smaller buffer size 2007e8196cdSAndriy Voskoboinykmay increase number of interrupts. 2017453645fSAndriy Voskoboinyk.El 2022600131bSAdrian Chadd.Sh DIAGNOSTICS 2032600131bSAdrian Chadd.Bl -diag 2047453645fSAndriy Voskoboinyk.It "rtwn%d: could not read efuse byte at address 0x%x" 2057453645fSAndriy Voskoboinyk.It "rtwn%d: %s: cannot read rom, error %d" 2067453645fSAndriy VoskoboinykThere was an error while reading ROM; device attach will be aborted. 2077453645fSAndriy VoskoboinykThis should not happen. 2087453645fSAndriy Voskoboinyk.It "rtwn%d: failed loadfirmware of file %s" 2092600131bSAdrian ChaddFor some reason, the driver was unable to read the microcode file from the 2102600131bSAdrian Chaddfilesystem. 2112600131bSAdrian ChaddThe file might be missing or corrupted. 2127453645fSAndriy VoskoboinykThe driver will disable firmware-dependent features. 2137453645fSAndriy Voskoboinyk.It "rtwn%d: wrong firmware size (%zu)" 2147453645fSAndriy Voskoboinyk.It "rtwn%d: %s: failed to upload firmware %s (error %d)" 2157453645fSAndriy Voskoboinyk.It "rtwn%d: timeout waiting for firmware readiness" 2167453645fSAndriy VoskoboinykFirmware upload failed; the file might be corrupted. 2177453645fSAndriy VoskoboinykThe driver will disable firmware-dependent features. 2187453645fSAndriy VoskoboinykThis should not happen. 2197453645fSAndriy Voskoboinyk.It "rtwn%d: device timeout" 2202600131bSAdrian ChaddA frame dispatched to the hardware for transmission did not complete in time. 2212600131bSAdrian ChaddThe driver will reset the hardware. 2222600131bSAdrian ChaddThis should not happen. 2232600131bSAdrian Chadd.El 2242600131bSAdrian Chadd.Sh SEE ALSO 2257453645fSAndriy Voskoboinyk.Xr intro 4 , 2267453645fSAndriy Voskoboinyk.Xr netintro 4 , 2277453645fSAndriy Voskoboinyk.Xr rtwn_pci 4 , 2287453645fSAndriy Voskoboinyk.Xr rtwn_usb 4 , 2292600131bSAdrian Chadd.Xr rtwnfw 4 , 2302600131bSAdrian Chadd.Xr wlan 4 , 2317453645fSAndriy Voskoboinyk.Xr wlan_amrr 4 , 2322600131bSAdrian Chadd.Xr wlan_ccmp 4 , 2332600131bSAdrian Chadd.Xr wlan_tkip 4 , 2342600131bSAdrian Chadd.Xr wlan_wep 4 , 2357453645fSAndriy Voskoboinyk.Xr wlan_xauth 4 , 236*93b30f1bSAlexander Ziaee.Xr networking 7 , 2377d1ad5c3SAndriy Voskoboinyk.Xr hostapd 8 , 2382600131bSAdrian Chadd.Xr ifconfig 8 , 2392600131bSAdrian Chadd.Xr wpa_supplicant 8 2402600131bSAdrian Chadd.Sh HISTORY 2412600131bSAdrian ChaddThe 2427453645fSAndriy Voskoboinyk.Cm urtwn 2437453645fSAndriy Voskoboinykdriver first appeared in 2447453645fSAndriy Voskoboinyk.Ox 4.9 2457453645fSAndriy Voskoboinykand 2467453645fSAndriy Voskoboinyk.Fx 10.0 ; 2477453645fSAndriy Voskoboinykthe 2482600131bSAdrian Chadd.Nm 2492600131bSAdrian Chadddriver first appeared in 250*93b30f1bSAlexander Ziaee.Ox 5.8 251*93b30f1bSAlexander Ziaeeand 252*93b30f1bSAlexander Ziaee.Fx 11.0 . 2532600131bSAdrian Chadd.Sh AUTHORS 2542600131bSAdrian ChaddThe 2552600131bSAdrian Chadd.Nm 2567453645fSAndriy Voskoboinykdriver was initially written by 2572600131bSAdrian Chadd.An -nosplit 2582600131bSAdrian Chadd.An Stefan Sperling Aq Mt stsp@openbsd.org 2592600131bSAdrian Chaddand ported by 2602600131bSAdrian Chadd.An Kevin Lo Aq Mt kevlo@freebsd.org . 2612600131bSAdrian ChaddIt was based on the 2627453645fSAndriy Voskoboinyk.Cm urtwn 2632600131bSAdrian Chadddriver written by 2642600131bSAdrian Chadd.An Damien Bergamini Aq Mt damien.bergamini@free.fr . 2657453645fSAndriy Voskoboinyk.Sh BUGS 2662600131bSAdrian ChaddThe 2672600131bSAdrian Chadd.Nm 2687453645fSAndriy Voskoboinykdriver currently does not implement firmware-based rate control. 269