1.\" $OpenBSD: athn.4,v 1.18 2011/09/03 22:59:08 jmc 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: September 3 2011 $ 18.Dt ATHN 4 19.Os 20.Sh NAME 21.Nm athn 22.Nd Atheros IEEE 802.11a/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 Mini Card (XB92), half Mini Card (HB92) 61and 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 (WPA-PSK and WPA2-PSK). 149WPA is the de facto encryption standard for wireless networks. 150It is strongly recommended that WEP 151not be used as the sole mechanism 152to secure wireless communication, 153due to serious weaknesses in it. 154The 155.Nm 156driver relies on the software 802.11 stack for both encryption and decryption 157of data frames. 158.\" driver offloads encryption and decryption to the hardware for the WEP40, 159.\" WEP104, TKIP(+MIC) and CCMP ciphers. 160.Pp 161The transmit speed is user-selectable or can be adapted automatically by the 162driver depending on the number of hardware transmission retries. 163.Sh FILES 164For USB devices, the driver needs at least version 1.1 of the following 165firmware files, which are loaded when an interface is attached: 166.Pp 167.Bl -tag -width Ds -offset indent -compact 168.It /etc/firmware/athn-ar7010 169.It /etc/firmware/athn-ar7010-11 170.It /etc/firmware/athn-ar9271 171.El 172.Pp 173A prepackaged version of the firmware, designed to be used with 174.Xr pkg_add 1 , 175can be found at: 176.Bd -literal -offset 3n 177http://firmware.openbsd.org/firmware/athn-firmware-1.1.tgz 178.Ed 179.Sh EXAMPLES 180The following 181.Xr hostname.if 5 182example configures athn0 to join whatever network is available on boot, 183using WEP key 184.Dq 0x1deadbeef1 , 185channel 11, obtaining an IP address using DHCP: 186.Bd -literal -offset indent 187dhcp NONE NONE NONE nwkey 0x1deadbeef1 chan 11 188.Ed 189.Pp 190The following 191.Xr hostname.if 5 192example creates a host-based access point on boot: 193.Bd -literal -offset indent 194inet 192.168.1.1 255.255.255.0 NONE media autoselect \e 195 mediaopt hostap nwid my_net chan 11 196.Ed 197.Pp 198Configure athn0 to join network 199.Dq my_net 200using WPA with passphrase 201.Dq my_passphrase : 202.Bd -literal -offset indent 203# ifconfig athn0 nwid my_net wpakey my_passphrase 204.Ed 205.Pp 206Join an existing BSS network, 207.Dq my_net : 208.Bd -literal -offset indent 209# ifconfig athn0 192.168.1.1 netmask 0xffffff00 nwid my_net 210.Ed 211.Sh DIAGNOSTICS 212.Bl -diag 213.It "athn%d: device timeout" 214A frame dispatched to the hardware for transmission did not complete in time. 215The driver will reset the hardware. 216This should not happen. 217.It "athn%d: radio is disabled by hardware switch" 218The radio transmitter is off and thus no packet can go out. 219The driver will reset the hardware. 220Make sure the laptop radio switch is on. 221.It "athn%d: radio switch turned off" 222The radio switch has been turned off while the interface was up and running. 223The driver will turn the interface down. 224.It "athn%d: error %d, could not read firmware %s" 225For some reason, the driver was unable to read the firmware file from the 226filesystem. 227The file might be missing or corrupted. 228.El 229.Sh SEE ALSO 230.Xr arp 4 , 231.Xr cardbus 4 , 232.Xr ifmedia 4 , 233.Xr intro 4 , 234.Xr netintro 4 , 235.Xr pci 4 , 236.Xr usb 4 , 237.Xr hostname.if 5 , 238.Xr ifconfig 8 239.Sh HISTORY 240The 241.Nm 242driver first appeared in 243.Ox 4.7 . 244Support for USB 2.0 devices first appeared in 245.Ox 4.9 . 246.Sh AUTHORS 247The 248.Nm 249driver was written by 250.An Damien Bergamini Aq damien@openbsd.org 251based on source code licensed under the ISC released in 2008 by 252Atheros Communications for Linux. 253.Sh CAVEATS 254The 255.Nm 256driver does not support any of the 802.11n capabilities offered by 257the adapters. 258Additional work is required in 259.Xr ieee80211 9 260before those features can be supported. 261.Pp 262Host AP mode doesn't support power saving. 263Clients attempting to use power saving mode may experience significant 264packet loss (disabling power saving on the client will fix this). 265