share/man/man4/rtwn.4

   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
  31 To compile this driver into the kernel,
  32 place the following lines in your
  33 kernel 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
  43 Alternatively, to load the driver as a
  44 module at boot time, place following lines in
  45 .Xr loader.conf 5 :
  46 .Bd -literal -offset indent
  47 if_rtwn_pci_load="YES"
  48 if_rtwn_usb_load="YES"
  49 .Ed
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 driver provides support for wireless network devices based on
  54 the Realtek RTL8192C, RTL8188E, RTL8192E, RTL8812A and RTL8821A
  55 programming APIs.
  56 These APIs are used by a wide variety of chips;
  57 most chips with USB and some with PCI interface are supported.
  58 .Pp
  59 To enable use for PCI/PCIe systems, see the rtwn_pci(4) driver;
  60 for USB devices, use the rtwn_usb(4) driver.
  61 .Pp
  62 The driver supports
  63 .Cm station ,
  64 .Cm adhoc ,
  65 .Cm hostap
  66 and
  67 .Cm monitor
  68 mode operation.
  69 There are no limitations for number of
  70 .Cm monitor
  71 mode
  72 virtual interfaces; in addition to any other virtual interface
  73 one
  74 .Cm station
  75 interface can be added (Note: RTL8821AU supports two non-monitor
  76 mode interfaces at the same time).
  77 .Pp
  78 All chips have hardware support for WEP, AES-CCM and TKIP encryption.
  79 .Pp
  80 The
  81 .Nm
  82 driver 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
  88 firmware license
  89 .El
  90 .Pp
  91 The driver (if not compiled with
  92 .Cd options RTWN_WITHOUT_UCODE
  93 ) may use following firmware files, which are loaded
  94 when 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
 107 Join an existing BSS network (i.e., connect to an access point):
 108 .Bd -literal -offset indent
 109 ifconfig wlan create wlandev rtwn0 inet 192.168.0.20 \e
 110     netmask 0xffffff00
 111 .Ed
 112 .Pp
 113 Join 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
 118 Join a specific BSS network with 64-bit WEP encryption:
 119 .Bd -literal -offset indent
 120 ifconfig wlan create wlandev rtwn0 ssid my_net \e
 121         wepmode on wepkey 0x1234567890 weptxkey 1 up
 122 .Ed
 123 .Pp
 124 Create an IBSS network with 128-bit WEP encryption on the channel 4:
 125 .Bd -literal -offset indent
 126 ifconfig 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
 131 Join/create an 802.11b IBSS network with network name
 132 .Dq Li my_net :
 133 .Bd -literal -offset indent
 134 ifconfig wlan0 create wlandev rtwn0 wlanmode adhoc
 135 ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e
 136         mode 11b
 137 .Ed
 138 .Pp
 139 Create a host-based access point:
 140 .Bd -literal -offset indent
 141 ifconfig wlan0 create wlandev rtwn0 wlanmode hostap
 142 ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap
 143 .Ed
 144 .Sh LOADER TUNABLES
 145 Tunables can be set at the
 146 .Xr loader 8
 147 prompt before booting the kernel or stored in
 148 .Xr loader.conf 5 .
 149 .Bl -tag -width indent
 150 .It Va dev.rtwn.%d.hwcrypto
 151 This tunable controls how key slots are assigned:
 152 .br
 153 0 - disable h/w crypto support.
 154 Features that require access to frame contents (e.g., TCP/UDP/IP Rx
 155 checksum validation) will not work;
 156 .br
 157 1 - use h/w crypto support for pairwise keys only;
 158 .br
 159 2 - use h/w crypto support for all keys; may not work for
 160 multi-vap configurations.
 161 .br
 162 By default it is set to 1.
 163 .It Va dev.rtwn.%d.ratectl
 164 This tunable switches between rate control implementations:
 165 .br
 166 0 - no rate control;
 167 .br
 168 1 - driver sends 'tx complete' reports to net80211; algorithm
 169 is controlled via net80211;
 170 .br
 171 2 - firmware-based rate control.
 172 .br
 173 By default it is set to 1; however driver may choose another
 174 algorithm in case if it is not implemented
 175 .br
 176 Currently selected algorithm is reported via
 177 .Em Va dev.rtwn.%d.ratectl_selected
 178 read-only OID.
 179 .It Va dev.rtwn.%d.rx_buf_size
 180 (USB only) Controls size of temporary Rx buffer; smaller buffer size
 181 may 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"
 187 There was an error while reading ROM; device attach will be aborted.
 188 This should not happen.
 189 .It "rtwn%d: failed loadfirmware of file %s"
 190 For some reason, the driver was unable to read the microcode file from the
 191 filesystem.
 192 The file might be missing or corrupted.
 193 The 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"
 197 Firmware upload failed; the file might be corrupted.
 198 The driver will disable firmware-dependent features.
 199 This should not happen.
 200 .It "rtwn%d: device timeout"
 201 A frame dispatched to the hardware for transmission did not complete in time.
 202 The driver will reset the hardware.
 203 This 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
 221 The
 222 .Cm urtwn
 223 driver first appeared in
 224 .Ox 4.9
 225 and
 226 .Fx 10.0 ;
 227 the
 228 .Nm
 229 driver first appeared in
 230 .Ox 5.8 .
 231 .Sh AUTHORS
 232 The
 233 .Nm
 234 driver was initially written by
 235 .An -nosplit
 236 .An Stefan Sperling Aq Mt stsp@openbsd.org
 237 and ported by
 238 .An Kevin Lo Aq Mt kevlo@freebsd.org .
 239 It was based on the
 240 .Cm urtwn
 241 driver written by
 242 .An Damien Bergamini Aq Mt damien.bergamini@free.fr .
 243 .Sh BUGS
 244 The
 245 .Nm
 246 driver currently does not implement firmware-based rate control.