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 July 31, 2017
  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-rtl8188eufw.ko
  97 .It Pa /boot/kernel/rtwn-rtl8192cfwE_B.ko
  98 .It Pa /boot/kernel/rtwn-rtl8192cfwE.ko
  99 .It Pa /boot/kernel/rtwn-rtl8192cfwT.ko
 100 .It Pa /boot/kernel/rtwn-rtl8192cfwU.ko
 101 .It Pa /boot/kernel/rtwn-rtl8192eufw.ko
 102 .It Pa /boot/kernel/rtwn-rtl8812aufw.ko
 103 .It Pa /boot/kernel/rtwn-rtl8821aufw.ko
 104 .El
 105 .Sh EXAMPLES
 106 Join an existing BSS network (i.e., connect to an access point):
 107 .Bd -literal -offset indent
 108 ifconfig wlan create wlandev rtwn0 inet 192.168.0.20 \e
 109     netmask 0xffffff00
 110 .Ed
 111 .Pp
 112 Join a specific BSS network with network name
 113 .Dq Li my_net :
 114 .Pp
 115 .Dl "ifconfig wlan create wlandev rtwn0 ssid my_net up"
 116 .Pp
 117 Join a specific BSS network with 64-bit WEP encryption:
 118 .Bd -literal -offset indent
 119 ifconfig wlan create wlandev rtwn0 ssid my_net \e
 120         wepmode on wepkey 0x1234567890 weptxkey 1 up
 121 .Ed
 122 .Pp
 123 Create an IBSS network with 128-bit WEP encryption on the channel 4:
 124 .Bd -literal -offset indent
 125 ifconfig wlan create wlandev rtwn0 wlanmode adhoc ssid my_net \e
 126         wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \e
 127         channel 4
 128 .Ed
 129 .Pp
 130 Join/create an 802.11b IBSS network with network name
 131 .Dq Li my_net :
 132 .Bd -literal -offset indent
 133 ifconfig wlan0 create wlandev rtwn0 wlanmode adhoc
 134 ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e
 135         mode 11b
 136 .Ed
 137 .Pp
 138 Create a host-based access point:
 139 .Bd -literal -offset indent
 140 ifconfig wlan0 create wlandev rtwn0 wlanmode hostap
 141 ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap
 142 .Ed
 143 .Sh LOADER TUNABLES
 144 Tunables can be set at the
 145 .Xr loader 8
 146 prompt before booting the kernel or stored in
 147 .Xr loader.conf 5 .
 148 .Bl -tag -width indent
 149 .It Va dev.rtwn.%d.hwcrypto
 150 This tunable controls how key slots are assigned:
 151 .br
 152 0 - disable h/w crypto support. Features that require access
 153 to frame contents (e.g., TCP/UDP/IP Rx checksum validation)
 154 will not work;
 155 .br
 156 1 - use h/w crypto support for pairwise keys only;
 157 .br
 158 2 - use h/w crypto support for all keys; may not work for
 159 multi-vap configurations.
 160 .br
 161 By default it is set to 1.
 162 .It Va dev.rtwn.%d.ratectl
 163 This tunable switches between rate control implementations:
 164 .br
 165 0 - no rate control;
 166 .br
 167 1 - driver sends 'tx complete' reports to net80211; algorithm
 168 is controlled via net80211;
 169 .br
 170 2 - firmware-based rate control.
 171 .br
 172 By default it is set to 1; however driver may choose another
 173 algorithm in case if it is not implemented
 174 .br
 175 Currently selected algorithm is reported via
 176 .Em Va dev.rtwn.%d.ratectl_selected
 177 read-only OID.
 178 .It Va dev.rtwn.%d.rx_buf_size
 179 (USB only) Controls size of temporary Rx buffer; smaller buffer size
 180 may increase number of interrupts.
 181 .El
 182 .Sh DIAGNOSTICS
 183 .Bl -diag
 184 .It "rtwn%d: could not read efuse byte at address 0x%x"
 185 .It "rtwn%d: %s: cannot read rom, error %d"
 186 There was an error while reading ROM; device attach will be aborted.
 187 This should not happen.
 188 .It "rtwn%d: failed loadfirmware of file %s"
 189 For some reason, the driver was unable to read the microcode file from the
 190 filesystem.
 191 The file might be missing or corrupted.
 192 The driver will disable firmware-dependent features.
 193 .It "rtwn%d: wrong firmware size (%zu)"
 194 .It "rtwn%d: %s: failed to upload firmware %s (error %d)"
 195 .It "rtwn%d: timeout waiting for firmware readiness"
 196 Firmware upload failed; the file might be corrupted.
 197 The driver will disable firmware-dependent features.
 198 This should not happen.
 199 .It "rtwn%d: device timeout"
 200 A frame dispatched to the hardware for transmission did not complete in time.
 201 The driver will reset the hardware.
 202 This should not happen.
 203 .El
 204 .Sh SEE ALSO
 205 .Xr intro 4 ,
 206 .Xr netintro 4 ,
 207 .Xr rtwn_pci 4 ,
 208 .Xr rtwn_usb 4 ,
 209 .Xr rtwnfw 4 ,
 210 .Xr wlan 4 ,
 211 .Xr wlan_amrr 4 ,
 212 .Xr wlan_ccmp 4 ,
 213 .Xr wlan_tkip 4 ,
 214 .Xr wlan_wep 4 ,
 215 .Xr wlan_xauth 4 ,
 216 .Xr hostapd 8 ,
 217 .Xr ifconfig 8 ,
 218 .Xr wpa_supplicant 8
 219 .Sh HISTORY
 220 The
 221 .Cm urtwn
 222 driver first appeared in
 223 .Ox 4.9
 224 and
 225 .Fx 10.0 ;
 226 the
 227 .Nm
 228 driver first appeared in
 229 .Ox 5.8 .
 230 .Sh AUTHORS
 231 The
 232 .Nm
 233 driver was initially written by
 234 .An -nosplit
 235 .An Stefan Sperling Aq Mt stsp@openbsd.org
 236 and ported by
 237 .An Kevin Lo Aq Mt kevlo@freebsd.org .
 238 It was based on the
 239 .Cm urtwn
 240 driver written by
 241 .An Damien Bergamini Aq Mt damien.bergamini@free.fr .
 242 .Sh BUGS
 243 The
 244 .Nm
 245 driver currently does not implement firmware-based rate control.