RTWN(4)

💖 RTWN(4) 💖 — the rtwn Realtek IEEE 802.11 wireless network driver

okay bestie, sit down, hydrate, because we're about to get you on the wifi with the Realtek driver and it's actually gonna be cute. This is the kernel interfaces manual page for rtwn, and yes it goes hard. 🦋

---

✨ SYNOPSIS ✨

options RTWN_DEBUG
options RTWN_WITHOUT_UCODE

So to compile this driver into the kernel, you drop these lines into your kernel configuration file:

device rtwn
device rtwnfw
device rtwn_usb
device rtwn_pci
device wlan
device firmware

Orrrrr, if you'd rather load it as a module at boot time (main character energy, no reboot, we love her), put these lines in loader.conf(5):

if_rtwn_pci_load="YES"
if_rtwn_usb_load="YES"

---

🌸 DESCRIPTION 🌸

The rtwn driver has your back for wireless network devices built on the Realtek RTL8192C, RTL8188E, RTL8192E, RTL8812A and RTL8821A programming APIs. And the way these APIs get used by such a wide variety of chips?? Iconic. Most chips with a USB interface are supported, and some with a PCI interface too. 💅

If you're on a PCI/PCIe system, go look at the rtwn_pci(4) driver — and for USB devices, that's rtwn_usb(4). Pick your fighter.

The driver supports station, adhoc, hostap and monitor mode operation. And there's literally no cap on the number of monitor mode virtual interfaces — none. On top of that, in addition to any other virtual interface, one station interface can be added. (Note: RTL8821AU supports two non-monitor mode interfaces at the same time, she's special like that ✨).

All chips have hardware support for WEP, AES-CCM and TKIP encryption. Hardware crypto?? We ate.

And you can configure the rtwn driver at runtime with ifconfig(8), because of course you can. 🎀

---

🎀 FILES 🎀

• /usr/share/doc/legal/realtek.LICENSE — the rtwn firmware license. (Yes bestie, there's a license, read it, it's giving legal.)

The driver — as long as it wasn't compiled with options RTWN_WITHOUT_UCODE — may use the following firmware files, which get loaded when an interface is brought up:

/boot/kernel/rtwn-rtl8188eefw.ko
/boot/kernel/rtwn-rtl8188eufw.ko
/boot/kernel/rtwn-rtl8192cfwE_B.ko
/boot/kernel/rtwn-rtl8192cfwE.ko
/boot/kernel/rtwn-rtl8192cfwT.ko
/boot/kernel/rtwn-rtl8192cfwU.ko
/boot/kernel/rtwn-rtl8192eufw.ko
/boot/kernel/rtwn-rtl8812aufw.ko
/boot/kernel/rtwn-rtl8821aufw.ko

---

🦋 EXAMPLES 🦋

Join an existing BSS network (i.e., connect to an access point). Slay:

ifconfig wlan create wlandev rtwn0 inet 192.168.0.20 \
    netmask 0xffffff00

Join a specific BSS network with network name “my_net”:

ifconfig wlan create wlandev rtwn0 ssid my_net up

Join a specific BSS network with 64-bit WEP encryption:

ifconfig wlan create wlandev rtwn0 ssid my_net \
        wepmode on wepkey 0x1234567890 weptxkey 1 up

Create an IBSS network with 128-bit WEP encryption on the channel 4:

ifconfig wlan create wlandev rtwn0 wlanmode adhoc ssid my_net \
        wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \
        channel 4

Join/create an 802.11b IBSS network with network name “my_net”:

ifconfig wlan0 create wlandev rtwn0 wlanmode adhoc
ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \
        mode 11b

Create a host-based access point:

ifconfig wlan0 create wlandev rtwn0 wlanmode hostap
ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap

---

⭐ LOADER TUNABLES ⭐

You can set tunables at the loader(8) prompt before booting the kernel, or store them in loader.conf(5). Your choice, bestie, both are valid.

• dev.rtwn.%d.hwcrypto — this tunable controls how key slots are assigned:
  • 0 — disable h/w crypto support. Features that require access to frame contents (e.g., TCP/UDP/IP Rx checksum validation) will not work;
  • 1 — use h/w crypto support for pairwise keys only;
  • 2 — use h/w crypto support for all keys; may not work for multi-vap configurations.

By default it is set to 1.

• dev.rtwn.%d.ratectl — this tunable switches between rate control implementations:
  • 0 — no rate control;
  • 1 — driver sends 'tx complete' reports to net80211; algorithm is controlled via net80211;
  • 2 — firmware-based rate control.

By default it is set to 1; however the driver may choose another algorithm in case it is not implemented. The currently selected algorithm is reported via the dev.rtwn.%d.ratectl_selected read-only OID.

• dev.rtwn.%d.rx_buf_size — (USB only) controls size of temporary Rx buffer; a smaller buffer size may increase the number of interrupts.

---

💀 DIAGNOSTICS 💀

• rtwn%d: could not read efuse byte at address 0x%x
• rtwn%d: %s: cannot read rom, error %d — there was an error while reading ROM; device attach will be aborted. This should not happen.
• rtwn%d: failed loadfirmware of file %s — for some reason, the driver was unable to read the microcode file from the filesystem. The file might be missing or corrupted. The driver will disable firmware-dependent features.
• rtwn%d: wrong firmware size (%zu)
• rtwn%d: %s: failed to upload firmware %s (error %d)
• rtwn%d: timeout waiting for firmware readiness — firmware upload failed; the file might be corrupted. The driver will disable firmware-dependent features. This should not happen.
• rtwn%d: device timeout — a frame dispatched to the hardware for transmission did not complete in time. The driver will reset the hardware. This should not happen.

Not the "this should not happen" popping up three separate times 😭 like okay driver, we hear you, it should not happen.

---

🌈 SEE ALSO 🌈

intro(4), netintro(4), rtwn_pci(4), rtwn_usb(4), rtwnfw(4), wlan(4), wlan_amrr(4), wlan_ccmp(4), wlan_tkip(4), wlan_wep(4), wlan_xauth(4), hostapd(8), ifconfig(8), wpa_supplicant(8)

---

👑 HISTORY 👑

The urtwn driver first appeared in OpenBSD 4.9 and FreeBSD 10.0; the rtwn driver first appeared in OpenBSD 5.8. Glow-up era. 💖

---

🫶 AUTHORS 🫶

The rtwn driver was initially written by Stefan Sperling <stsp@openbsd.org> and ported by Kevin Lo <kevlo@freebsd.org>. It was based on the urtwn driver written by Damien Bergamini <damien.bergamini@free.fr>. Legends, all of them, fr fr. ✨

---

🙈 BUGS 🙈

The rtwn driver currently does not implement firmware-based rate control. That's it, that's the bug. She's just not doing it yet. 😭

---

and that's the whole page bestie!! 🎀💅✨ this one shipped with Debian, dated January 7, 2019 — so like, go forth and get yourself connected, no cap. mwah 💖