1.\" $OpenBSD: athn.4,v 1.40 2020/07/13 16:35:52 stsp 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: July 13 2020 $ 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 offloads both encryption and decryption to the hardware for the 163CCMP cipher. 164.Pp 165The transmit speed is user-selectable or can be adapted automatically by the 166driver depending on the number of hardware transmission retries. 167.Pp 168In BSS mode, 169the driver supports powersave mode, 170which can be enabled via 171.Xr ifconfig 8 . 172In Host AP mode, 173the driver is compatible with clients using powersave. 174.Pp 175The 176.Nm 177driver can be configured at runtime with 178.Xr ifconfig 8 179or on boot with 180.Xr hostname.if 5 . 181.Sh FILES 182For USB devices, the driver needs at least version 1.1p4 of the following 183firmware files, which are loaded when an interface is attached: 184.Pp 185.Bl -tag -width Ds -offset indent -compact 186.It Pa /etc/firmware/athn-open-ar7010 187.It Pa /etc/firmware/athn-open-ar9271 188.El 189.Pp 190A prepackaged version of the firmware can be installed using 191.Xr fw_update 1 . 192Firmware source code is available under a mix of BSD and GPLv2 licences. 193A port which cross-compiles the firmware can be found in 194.Pa /usr/ports/devel/open-ath9k-htc-firmware . 195.Sh EXAMPLES 196The following example scans for available networks: 197.Pp 198.Dl # ifconfig athn0 scan 199.Pp 200The following 201.Xr hostname.if 5 202example configures athn0 to join network 203.Dq mynwid , 204using WPA key 205.Dq mywpakey , 206obtaining an IP address using DHCP: 207.Bd -literal -offset indent 208nwid mynwid wpakey mywpakey 209dhcp 210.Ed 211.Pp 212The following 213.Xr hostname.if 5 214example creates a host-based access point on boot: 215.Bd -literal -offset indent 216mediaopt hostap 217nwid mynwid wpakey mywpakey 218inet 192.168.1.1 255.255.255.0 219.Ed 220.Sh DIAGNOSTICS 221.Bl -diag 222.It "athn0: device timeout" 223A frame dispatched to the hardware for transmission did not complete in time. 224The driver will reset the hardware. 225This should not happen. 226.It "athn0: radio is disabled by hardware switch" 227The radio transmitter is off and thus no packet can go out. 228The driver will reset the hardware. 229Make sure the laptop radio switch is on. 230.It "athn0: radio switch turned off" 231The radio switch has been turned off while the interface was up and running. 232The driver will turn the interface down. 233.It "athn0: error N, could not read firmware ..." 234For some reason, the driver was unable to read the firmware file from the 235filesystem. 236The file might be missing or corrupted. 237.El 238.Sh SEE ALSO 239.Xr arp 4 , 240.Xr cardbus 4 , 241.Xr ifmedia 4 , 242.Xr intro 4 , 243.Xr netintro 4 , 244.Xr pci 4 , 245.Xr usb 4 , 246.Xr hostname.if 5 , 247.Xr ifconfig 8 248.Sh HISTORY 249The 250.Nm 251driver first appeared in 252.Ox 4.7 . 253Support for USB 2.0 devices first appeared in 254.Ox 4.9 . 255.Sh AUTHORS 256The 257.Nm 258driver was written by 259.An Damien Bergamini Aq Mt damien.bergamini@free.fr 260based on source code licensed under the ISC released in 2008 by 261Atheros Communications for Linux. 262.An Anthony J. Bentley Aq Mt bentley@openbsd.org 263added the open source USB firmware and its cross-compiler to the ports tree. 264.An Stefan Sperling Aq Mt stsp@openbsd.org 265implemented driver support for the open source USB firmware. 266.Sh CAVEATS 267Support for 802.11n 40MHz channels and Tx aggregation is not yet implemented. 268Additional work is required in 269.Xr ieee80211 9 270before those features can be supported. 271.Pp 272On USB devices, the firmware limits Host AP mode to 7 concurrent clients. 273