1.\" $OpenBSD: athn.4,v 1.39 2019/11/10 14:10:41 sthen Exp $ 2.\" 3.\" Copyright (c) 2009 Damien Bergamini <damien.bergamini@free.fr>. 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: November 10 2019 $ 18.Dt ATHN 4 19.Os 20.Sh NAME 21.Nm athn 22.Nd Atheros IEEE 802.11a/b/g/n wireless network device 23.Sh SYNOPSIS 24.Cd "athn* at cardbus?" 25.Cd "athn* at pci?" 26.Cd "athn* at uhub? port ?" 27.Sh DESCRIPTION 28The 29.Nm 30driver provides support for a wide variety of 31Atheros 802.11n devices, ranging from the AR5008 up to the AR9287. 32.Pp 33The AR5008 (codenamed Owl) is the first generation of 34Atheros 802.11n solutions. 35It consists of two chips, a MAC/Baseband Processor and a Radio-on-a-Chip. 36The MAC/Baseband Processor can be an AR5416 (PCI and CardBus form factors) 37or an AR5418 (PCIe Mini Card form factor). 38The radio can be an AR2122, AR2133, AR5122 or an AR5133 chip. 39The AR2122 chip operates in the 2GHz spectrum and supports up to 2 40transmit paths and 2 receiver paths (2T2R). 41The AR2133 chip operates in the 2GHz spectrum and supports up to 3 42transmit paths and 3 receiver paths (3T3R). 43The AR5122 chip operates in the 2GHz and 5GHz spectra and supports 44up to 2 transmit paths and 2 receiver paths (2T2R). 45The AR5133 chip operates in the 2GHz and 5GHz spectra and supports 46up to 3 transmit paths and 3 receiver paths (3T3R). 47.Pp 48The AR9001 (codenamed Sowl) is a Mini-PCI 802.11n solution. 49It consists of two chips, an AR9160 MAC/Baseband Processor and an 50AR9103 or AR9106 Radio-on-a-Chip. 51The AR9103 chip operates in the 2GHz spectrum and supports up to 3 52transmit paths and 3 receiver paths (3T3R). 53The AR9106 chip operates in the 2GHz and 5GHz spectra and supports 54up to 3 transmit paths and 3 receiver paths (3T3R). 55.Pp 56The AR9220, AR9223 and AR9280 (codenamed Merlin) are the 57first generation of 58Atheros single-chip 802.11n solutions. 59The AR9220 and AR9223 exist in PCI and Mini-PCI form factors. 60The AR9280 exists in PCIe (DT92), PCIe Mini Card (XB92), 61half Mini Card (HB92) and USB 2.0 (AR9280+AR7010) form factors. 62The AR9220 and AR9280 operate in the 2GHz and 5GHz spectra and 63support 2 transmit paths and 2 receiver paths (2T2R). 64The AR9223 operates in the 2GHz spectrum and supports 2 65transmit paths and 2 receiver paths (2T2R). 66.Pp 67The AR9281 is a single-chip PCIe 802.11n solution. 68It exists in PCIe Mini Card (XB91) and half Mini Card (HB91) form 69factors. 70It operates in the 2GHz spectrum and supports 1 transmit path and 712 receiver paths (1T2R). 72.Pp 73The AR9285 (codenamed Kite) is a single-chip PCIe 802.11n solution that 74targets the value PC market. 75It exists in PCIe half Mini Card (HB95) form factor only. 76It operates in the 2GHz spectrum and supports a single stream (1T1R). 77It can be combined with the AR3011 chip to form a combo WiFi/Bluetooth 78device (WB195). 79.Pp 80The AR9271 is a single-chip USB 2.0 802.11n solution. 81It operates in the 2GHz spectrum and supports a single stream (1T1R). 82.Pp 83The AR2427 is a single-chip PCIe 802.11b/g solution similar to the other 84AR9280 solutions but with 802.11n capabilities removed. 85It exists in PCIe Mini Card form factor only. 86It operates in the 2GHz spectrum. 87.Pp 88The AR9227 and AR9287 are single-chip 802.11n solutions that 89target mid-tier PCs. 90The AR9227 exists in PCI and Mini-PCI form factors. 91The AR9287 exists in PCIe half Mini Card (HB97) 92and USB 2.0 (AR9287+AR7010) form factors. 93They operate in the 2GHz spectrum and support 2 transmit paths and 2 94receiver paths (2T2R). 95.Pp 96The following table summarizes the supported chips and their capabilities. 97.Bl -column "AR9001-3NX2 (AR9160+AR9106)" "2GHz/5GHz" "3x3:3" "PCI/CardBus" -offset 6n 98.It Em Chipset Ta Em Spectrum Ta Em TxR:S Ta Em Bus 99.It "AR5008-2NG (AR5416+AR2122)" Ta 2GHz Ta 2x2:2 Ta PCI/CardBus 100.It "AR5008-3NG (AR5416+AR2133)" Ta 2GHz Ta 3x3:2 Ta PCI/CardBus 101.It "AR5008-2NX (AR5416+AR5122)" Ta 2GHz/5GHz Ta 2x2:2 Ta PCI/CardBus 102.It "AR5008-3NX (AR5416+AR5133)" Ta 2GHz/5GHz Ta 3x3:2 Ta PCI/CardBus 103.It "AR5008E-2NG (AR5418+AR2122)" Ta 2GHz Ta 2x2:2 Ta PCIe 104.It "AR5008E-3NG (AR5418+AR2133)" Ta 2GHz Ta 3x3:2 Ta PCIe 105.It "AR5008E-2NX (AR5418+AR5122)" Ta 2GHz/5GHz Ta 2x2:2 Ta PCIe 106.It "AR5008E-3NX (AR5418+AR5133)" Ta 2GHz/5GHz Ta 3x3:2 Ta PCIe 107.It "AR9001-2NG (AR9160+AR9103)" Ta 2GHz Ta 2x2:2 Ta PCI 108.It "AR9001-3NG (AR9160+AR9103)" Ta 2GHz Ta 3x3:2 Ta PCI 109.It "AR9001-3NX2 (AR9160+AR9106)" Ta 2GHz/5GHz Ta 3x3:2 Ta PCI 110.It "AR9220" Ta 2GHz/5GHz Ta 2x2:2 Ta PCI 111.It "AR9223" Ta 2GHz Ta 2x2:2 Ta PCI 112.It "AR9280" Ta 2GHz/5GHz Ta 2x2:2 Ta PCIe 113.It "AR9280+AR7010" Ta 2GHz/5GHz Ta 2x2:2 Ta USB 2.0 114.It "AR9281" Ta 2GHz Ta 1x2:2 Ta PCIe 115.It "AR9285" Ta 2GHz Ta 1x1:1 Ta PCIe 116.It "AR9271" Ta 2GHz Ta 1x1:1 Ta USB 2.0 117.It "AR2427" Ta 2GHz Ta 1x1:1 Ta PCIe 118.It "AR9227" Ta 2GHz Ta 2x2:2 Ta PCI 119.It "AR9287" Ta 2GHz Ta 2x2:2 Ta PCIe 120.It "AR9287+AR7010" Ta 2GHz Ta 2x2:2 Ta USB 2.0 121.El 122.Pp 123These are the modes the 124.Nm 125driver can operate in: 126.Bl -tag -width "IBSS-masterXX" 127.It BSS mode 128Also known as 129.Em infrastructure 130mode, this is used when associating with an access point, through 131which all traffic passes. 132This mode is the default. 133.It Host AP 134In this mode the driver acts as an access point (base station) 135for other cards. 136.It monitor mode 137In this mode the driver is able to receive packets without 138associating with an access point. 139This disables the internal receive filter and enables the card to 140capture packets from networks which it wouldn't normally have access to, 141or to scan for access points. 142.El 143.Pp 144The 145.Nm 146driver can be configured to use 147Wired Equivalent Privacy (WEP) or 148Wi-Fi Protected Access (WPA1 and WPA2). 149WPA2 is the current encryption standard for wireless networks. 150It is strongly recommended that neither WEP nor WPA1 151are used as the sole mechanism to secure wireless communication, 152due to serious weaknesses. 153WPA1 is disabled by default and may be enabled using the option 154.Qq Cm wpaprotos Ar wpa1,wpa2 . 155For standard WPA networks which use pre-shared keys (PSK), 156keys are configured using the 157.Qq Cm wpakey 158option. 159WPA-Enterprise networks require use of the wpa_supplicant package. 160The 161.Nm 162driver relies on the software 802.11 stack for both encryption and decryption 163of data frames. 164.\" driver offloads encryption and decryption to the hardware for the WEP40, 165.\" WEP104, TKIP(+MIC) and CCMP ciphers. 166.Pp 167The transmit speed is user-selectable or can be adapted automatically by the 168driver depending on the number of hardware transmission retries. 169.Pp 170In BSS mode, 171the driver supports powersave mode, 172which can be enabled via 173.Xr ifconfig 8 . 174In Host AP mode, 175the driver is compatible with clients using powersave. 176.Pp 177The 178.Nm 179driver can be configured at runtime with 180.Xr ifconfig 8 181or on boot with 182.Xr hostname.if 5 . 183.Sh FILES 184For USB devices, the driver needs at least version 1.1p4 of the following 185firmware files, which are loaded when an interface is attached: 186.Pp 187.Bl -tag -width Ds -offset indent -compact 188.It Pa /etc/firmware/athn-open-ar7010 189.It Pa /etc/firmware/athn-open-ar9271 190.El 191.Pp 192A prepackaged version of the firmware can be installed using 193.Xr fw_update 1 . 194Firmware source code is available under a mix of BSD and GPLv2 licences. 195A port which cross-compiles the firmware can be found in 196.Pa /usr/ports/devel/open-ath9k-htc-firmware . 197.Sh EXAMPLES 198The following example scans for available networks: 199.Pp 200.Dl # ifconfig athn0 scan 201.Pp 202The following 203.Xr hostname.if 5 204example configures athn0 to join network 205.Dq mynwid , 206using WPA key 207.Dq mywpakey , 208obtaining an IP address using DHCP: 209.Bd -literal -offset indent 210nwid mynwid wpakey mywpakey 211dhcp 212.Ed 213.Pp 214The following 215.Xr hostname.if 5 216example creates a host-based access point on boot: 217.Bd -literal -offset indent 218mediaopt hostap 219nwid mynwid wpakey mywpakey 220inet 192.168.1.1 255.255.255.0 221.Ed 222.Sh DIAGNOSTICS 223.Bl -diag 224.It "athn0: device timeout" 225A frame dispatched to the hardware for transmission did not complete in time. 226The driver will reset the hardware. 227This should not happen. 228.It "athn0: radio is disabled by hardware switch" 229The radio transmitter is off and thus no packet can go out. 230The driver will reset the hardware. 231Make sure the laptop radio switch is on. 232.It "athn0: radio switch turned off" 233The radio switch has been turned off while the interface was up and running. 234The driver will turn the interface down. 235.It "athn0: error N, could not read firmware ..." 236For some reason, the driver was unable to read the firmware file from the 237filesystem. 238The file might be missing or corrupted. 239.El 240.Sh SEE ALSO 241.Xr arp 4 , 242.Xr cardbus 4 , 243.Xr ifmedia 4 , 244.Xr intro 4 , 245.Xr netintro 4 , 246.Xr pci 4 , 247.Xr usb 4 , 248.Xr hostname.if 5 , 249.Xr ifconfig 8 250.Sh HISTORY 251The 252.Nm 253driver first appeared in 254.Ox 4.7 . 255Support for USB 2.0 devices first appeared in 256.Ox 4.9 . 257.Sh AUTHORS 258The 259.Nm 260driver was written by 261.An Damien Bergamini Aq Mt damien.bergamini@free.fr 262based on source code licensed under the ISC released in 2008 by 263Atheros Communications for Linux. 264.An Anthony J. Bentley Aq Mt bentley@openbsd.org 265added the open source USB firmware and its cross-compiler to the ports tree. 266.An Stefan Sperling Aq Mt stsp@openbsd.org 267implemented driver support for the open source USB firmware. 268.Sh CAVEATS 269Support for 802.11n 40MHz channels and Tx aggregation is not yet implemented. 270Additional work is required in 271.Xr ieee80211 9 272before those features can be supported. 273.Pp 274On USB devices, the firmware limits Host AP mode to 7 concurrent clients. 275