xref: /freebsd/share/man/man4/rtwn.4 (revision 93b30f1b6caec5083efacf3fb5049b72e75cc09e)
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