1.\" $OpenBSD: ath.4,v 1.46 2009/02/16 08:15:22 jmc Exp $ 2.\" $NetBSD: ath.4,v 1.5 2004/07/03 16:58:18 mycroft Exp $ 3.\" 4.\" Copyright (c) 2002, 2003 Sam Leffler, Errno Consulting 5.\" All rights reserved. 6.\"" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer, 12.\" without modification. 13.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer 14.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any 15.\" redistribution must be conditioned upon including a substantially 16.\" similar Disclaimer requirement for further binary redistribution. 17.\" 3. Neither the names of the above-listed copyright holders nor the names 18.\" of any contributors may be used to endorse or promote products derived 19.\" from this software without specific prior written permission. 20.\" 21.\" NO WARRANTY 22.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 23.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 24.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY 25.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 26.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, 27.\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 28.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 29.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 30.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 31.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 32.\" THE POSSIBILITY OF SUCH DAMAGES. 33.\" 34.\" 35.\" Note: This man page was taken by Perry Metzger almost entirely 36.\" from the "ath" and "ath_hal" man pages in FreeBSD. I claim no 37.\" copyright because there was nearly no original work performed in 38.\" doing so. Maintainers should check the FreeBSD originals for 39.\" updates against the following two revisions and incorporate them 40.\" if needed: 41.\" 42.\" $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ath.4,v 1.16 2004/02/18 08:30:08 maxim Exp $ 43.\" parts from $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ath_hal.4,v 1.7 2004/01/07 20:49:51 blackend Exp $ 44.\" 45.Dd $Mdocdate: February 16 2009 $ 46.Dt ATH 4 47.Os 48.Sh NAME 49.Nm ath 50.Nd Atheros IEEE 802.11a/b/g wireless network device with GPIO 51.Sh SYNOPSIS 52.Cd "ath* at pci? dev ? function ?" 53.Cd "ath* at cardbus? dev ? function ?" 54.Cd "gpio* at ath?" 55.Sh DESCRIPTION 56The 57.Nm 58driver provides support for wireless network devices based on 59the Atheros AR5210, AR5211, and AR5212 chips. 60.Pp 61All host/device interaction is via DMA. 62The 63.Nm 64driver encapsulates all IP and ARP traffic as 802.11 frames, though 65it can receive either 802.11 or 802.3 frames. 66Transmit speed and operating mode is selectable and 67depends on the specific chipset. 68.Pp 69Support for the various devices is as follows: 70.Bl -tag -width "ARxxxx" 71.It AR5210 72These devices support 802.11a operation with transmit speeds 73of 6 Mbps, 9 Mbps, 12 Mbps, 18 Mbps, 24 Mbps, 36 Mbps, 48 Mbps, and 54 Mbps. 74.Pp 75.It AR5211 76These devices support 802.11a and 802.11b operation with 77transmit speeds as above for 802.11a and 781Mbps, 2Mbps, 5.5 Mbps, and 11Mbps for 802.11b operation. 79.Pp 80.It AR5212 81These devices support 802.11a, 802.11b, and 802.11g operation with 82transmit speeds as above for 802.11a, 802.11b, and 802.11g operation 83(802.11g speeds are the same as for 802.11a speeds). 84.El 85.Pp 86All chips also support an Atheros Turbo Mode (TM) that operates in the 87802.11a frequency range with 2x the transmit speeds. 88(This mode is, however, only interoperable with other Atheros-based devices.) 89.Pp 90The actual transmit speed used is dependent on signal quality and the 91.Dq rate control 92algorithm employed by the driver. 93.Pp 94These are the modes the 95.Nm 96driver can operate in: 97.Bl -tag -width "IBSS-masterXX" 98.It BSS mode 99Also known as 100.Em infrastructure 101mode, this is used when associating with an access point, through 102which all traffic passes. 103This mode is the default. 104.It IBSS mode 105Also known as 106.Em IEEE ad-hoc 107mode or 108.Em peer-to-peer 109mode. 110This is the standardized method of operating without an access point. 111Stations associate with a service set. 112However, actual connections between stations are peer-to-peer. 113.It Host AP 114In this mode the adapter acts as an access point (base station) 115for other cards. 116.It monitor mode 117In this mode the driver is able to receive packets without 118associating with an access point. 119This disables the internal receive filter and enables the card to 120capture packets from networks which it wouldn't normally have access to, 121or to scan for access points. 122.El 123.Pp 124The 125.Nm 126driver can be configured to use 127Wireless Equivalent Privacy (WEP) or 128Wi-Fi Protected Access (WPA-PSK and WPA2-PSK). 129WPA is the de facto encryption standard for wireless networks. 130It is strongly recommended that WEP 131not be used as the sole mechanism 132to secure wireless communication, 133due to serious weaknesses in it. 134.Pp 135AR5211 and AR5212 support the AES, TKIP, and Michael cryptographic 136operations required for WPA in hardware but at this time the driver 137does not support them. 138.Pp 139The 140.Nm 141driver can be configured at runtime with 142.Xr ifconfig 8 143or on boot with 144.Xr hostname.if 5 . 145.Sh HARDWARE 146Devices supported by the 147.Nm 148driver come in either CardBus or Mini PCI packages. 149Wireless cards in CardBus slots may be inserted and ejected on the fly. 150.Pp 151The following cards are among those supported by the 152.Nm 153driver: 154.Pp 155.Bl -column -compact "Samsung SWL-5200N" "AR5212" "CardBus" "a/b/g" -offset 6n 156.Em "Card Chip Bus Standard" 1573Com 3CRPAG175 AR5212 CardBus a/b/g 158.\"Aztech WL830PC AR5212 CardBus b/g 159Cisco AIR-CB21AG AR5212 CardBus a/b/g 160D-Link DWL-A650 AR5210 CardBus a 161D-Link DWL-AB650 AR5211 CardBus a/b 162D-Link DWL-A520 AR5210 PCI a 163.\"D-Link DWL-AG520 AR5212 PCI a/b/g 164.\"D-Link DWL-AG650 AR5212 CardBus a/b/g 165.\"D-Link DWL-G520 AR5212 PCI b/g 166.\"D-Link DWL-G650B AR5212 CardBus b/g 167.\"Elecom LD-WL54AG AR5212 CardBus a/b/g 168Elecom LD-WL54 AR5211 CardBus a 169.\"Fujitsu E5454 AR5212 CardBus a/b/g 170.\"Fujitsu FMV-JW481 AR5212 CardBus a/b/g 171.\"Fujitsu E5454 AR5212 CardBus a/b/g 172.\"HP NC4000 AR5212 PCI a/b/g 173IBM 11ABG WL LAN AR5212 Mini PCI a/b/g 174.\"I/O Data WN-AB AR5212 CardBus a/b 175.\"I/O Data WN-AG AR5212 CardBus a/b/g 176.\"I/O Data WN-A54 AR5212 CardBus a 177.\"Linksys WMP55AG AR5212 PCI a/b/g 178Linksys WPC51AB AR5211 CardBus a/b 179.\"Linksys WPC55AG AR5212 CardBus a/b/g 180.\"NEC PA-WL/54AG AR5212 CardBus a/b/g 181.\"Netgear WAG311 AR5212 PCI a/b/g 182Netgear WAB501 AR5211 CardBus a/b 183.\"Netgear WAG511 AR5212 CardBus a/b/g 184.\"Netgear WG311 rev1 AR5212 PCI b/g 185.\"Netgear WG511T AR5212 CardBus b/g 186.\"Orinoco 8480 AR5212 CardBus a/b/g 187.\"Orinoco 8470WD AR5212 CardBus a/b/g 188Planet WL-3560 AR5211 CardBus a/b/g 189Proxim Skyline 4030 AR5210 CardBus a 190Proxim Skyline 4032 AR5210 PCI a 191.\"Samsung SWL-5200N AR5212 CardBus a/b/g 192Senao NL-5354MP AR5212 Mini PCI a/b/g 193SMC SMC2735W AR5210 CardBus a 194.\"Sony PCWA-C700 AR5212 CardBus a/b 195.\"Sony PCWA-C300S AR5212 CardBus b/g 196Sony PCWA-C500 AR5210 CardBus a 197Wistron CM9 AR5212 Mini PCI a/b/g 198.El 199.Pp 200An up to date list can be found at 201.Pa http://customerproducts.atheros.com/customerproducts/default.asp . 202.Sh EXAMPLES 203The following 204.Xr hostname.if 5 205example configures ath0 to join whatever network is available on boot, 206using WEP key 207.Dq 0x1deadbeef1 , 208channel 11, obtaining an IP address using DHCP: 209.Bd -literal -offset indent 210dhcp NONE NONE NONE nwkey 0x1deadbeef1 chan 11 211.Ed 212.Pp 213The following 214.Xr hostname.if 5 215example creates a host-based access point on boot: 216.Bd -literal -offset indent 217inet 192.168.1.1 255.255.255.0 NONE media autoselect \e 218 mediaopt hostap nwid my_net chan 11 219.Ed 220.Pp 221Configure ath0 to join network 222.Dq my_net 223using WPA-PSK with passphrase 224.Dq my_passphrase : 225.Bd -literal -offset indent 226# ifconfig ath0 nwid my_net wpa wpapsk \e 227 `wpa-psk my_net my_passphrase` 228.Ed 229.Pp 230Return ath0 to its default settings: 231.Bd -literal -offset indent 232# ifconfig ath0 -bssid -chan media autoselect \e 233 nwid "" -nwkey -wpa -wpapsk 234.Ed 235.Pp 236Join an existing BSS network, 237.Dq my_net : 238.Bd -literal -offset indent 239# ifconfig ath0 192.168.1.1 netmask 0xffffff00 nwid my_net 240.Ed 241.Sh DIAGNOSTICS 242.Bl -diag 243.It "ath%d: unable to attach hardware; HAL status %u" 244The Hardware Access Layer was unable to configure the hardware 245as requested. 246The status code is explained in the HAL include file 247.Pa sys/dev/ic/ar5xxx.h . 248.It "ath%d: failed to allocate descriptors: %d" 249The driver was unable to allocate contiguous memory for the transmit 250and receive descriptors. 251This usually indicates system memory is scarce and/or fragmented. 252.It "ath%d: unable to setup a data xmit queue!" 253The request to the HAL to set up the transmit queue for normal 254data frames failed. 255This should not happen. 256.It "ath%d: unable to setup a beacon xmit queue!" 257The request to the HAL to set up the transmit queue for 802.11 beacon frames 258failed. 259This should not happen. 260.It "ath%d: hardware error; resetting" 261An unrecoverable error in the hardware occurred. 262Errors of this sort include unrecoverable DMA errors. 263The driver will reset the hardware and continue. 264.It "ath%d: rx FIFO overrun; resetting" 265The receive FIFO in the hardware overflowed before the data could be 266transferred to the host. 267This typically occurs because the hardware ran short of receive 268descriptors and had no place to transfer received data. 269The driver will reset the hardware and continue. 270.It "ath%d: unable to reset hardware; hal status %u" 271The Hardware Access Layer was unable to reset the hardware 272as requested. 273The status code is explained in the HAL include file 274.Pa /sys/dev/ic/ar5xxx.h . 275This should not happen. 276.It "ath%d: unable to initialize the key cache" 277The driver was unable to initialize the hardware key cache. 278This should not happen. 279.It "ath%d: unable to start recv logic" 280The driver was unable to restart frame reception. 281This should not happen. 282.It "ath%d: device timeout" 283A frame dispatched to the hardware for transmission did not complete in time. 284The driver will reset the hardware and continue. 285This should not happen. 286.It "ath%d: bogus xmit rate 0x%x" 287An invalid transmit rate was specified for an outgoing frame. 288The frame is discarded. 289This should not happen. 290.It "ath%d: ath_chan_set: unable to reset channel %u (%u Mhz)" 291The Hardware Access Layer was unable to reset the hardware 292when switching channels during scanning. 293This should not happen. 294.It "ath%d: unable to allocate channel table" 295The driver was unable to allocate memory for the table used to hold 296the set of available channels. 297.It "ath%d: unable to collect channel list from hal" 298A problem occurred while querying the HAL to find the set of available 299channels for the device. 300This should not happen. 301.It "ath%d: failed to enable memory mapping" 302The driver was unable to enable memory-mapped I/O to the PCI device registers. 303This should not happen. 304.It "ath%d: failed to enable bus mastering" 305The driver was unable to enable the device as a PCI bus master for doing DMA. 306This should not happen. 307.It "ath%d: cannot map register space" 308The driver was unable to map the device registers into the host address space. 309This should not happen. 310.It "ath%d: could not map interrupt" 311The driver was unable to allocate an IRQ for the device interrupt. 312This should not happen. 313.It "ath%d: could not establish interrupt" 314The driver was unable to install the device interrupt handler. 315This should not happen. 316.El 317.Sh SEE ALSO 318.Xr arp 4 , 319.Xr cardbus 4 , 320.Xr gpio 4 , 321.Xr ifmedia 4 , 322.Xt intro 4 , 323.Xr netintro 4 , 324.Xr pci 4 , 325.Xr hostname.if 5 , 326.Xr gpioctl 8 , 327.Xr hostapd 8 , 328.Xr ifconfig 8 , 329.Xr wpa-psk 8 330.Sh HISTORY 331The 332.Nm 333device driver first appeared in 334.Fx 5.2 335using a binary-only HAL module which was ported to 336.Nx 2.0 . 337The driver using a free HAL-replacement first appeared in 338.Ox 3.7 . 339.Sh AUTHORS 340.An -nosplit 341The 342.Nm 343driver was written by 344.An Sam Leffler , 345and was ported to 346.Ox 347by 348.An Reyk Floeter Aq reyk@openbsd.org 349who also wrote a free replacement of the binary-only HAL. 350.Sh CAVEATS 351Different regulatory domains may not be able to communicate with each 352other with 802.11a as different regulatory domains do not necessarily 353have overlapping channels. 354.Pp 355Host AP mode doesn't support power saving. 356Clients attempting to use power saving mode may experience significant 357packet loss (disabling power saving on the client will fix this). 358.Sh BUGS 359Performance in lossy environments is suboptimal. 360The algorithm used to select the rate for transmitted packets is 361very simplistic. 362There is no software retransmit; only hardware retransmit is used. 363Contributors are encouraged to replace the existing rate control algorithm 364with a better one. 365.Pp 366The driver does not fully enable power-save operation of the chip; 367consequently power use is suboptimal. 368