1.\" $OpenBSD: ath.4,v 1.43 2008/08/29 09:44:16 damien 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: August 29 2008 $ 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 hardware 127Wireless Equivalent Privacy (WEP). 128It is strongly recommended that WEP 129not be used as the sole mechanism 130to secure wireless communication, 131due to serious weaknesses in it. 132.Pp 133AR5211 and AR5212 support the AES, TKIP, and Michael cryptographic 134operations required for WPA but at this time the driver does not support them. 135.Pp 136The 137.Nm 138driver can be configured at runtime with 139.Xr ifconfig 8 140or on boot with 141.Xr hostname.if 5 . 142.Sh HARDWARE 143Devices supported by the 144.Nm 145driver come in either CardBus or Mini PCI packages. 146Wireless cards in CardBus slots may be inserted and ejected on the fly. 147.Pp 148The following cards are among those supported by the 149.Nm 150driver: 151.Pp 152.Bl -column -compact "Samsung SWL-5200N" "AR5212" "CardBus" "a/b/g" -offset 6n 153.Em "Card Chip Bus Standard" 1543Com 3CRPAG175 AR5212 CardBus a/b/g 155.\"Aztech WL830PC AR5212 CardBus b/g 156Cisco AIR-CB21AG AR5212 CardBus a/b/g 157D-Link DWL-A650 AR5210 CardBus a 158D-Link DWL-AB650 AR5211 CardBus a/b 159D-Link DWL-A520 AR5210 PCI a 160.\"D-Link DWL-AG520 AR5212 PCI a/b/g 161.\"D-Link DWL-AG650 AR5212 CardBus a/b/g 162.\"D-Link DWL-G520 AR5212 PCI b/g 163.\"D-Link DWL-G650B AR5212 CardBus b/g 164.\"Elecom LD-WL54AG AR5212 CardBus a/b/g 165Elecom LD-WL54 AR5211 CardBus a 166.\"Fujitsu E5454 AR5212 CardBus a/b/g 167.\"Fujitsu FMV-JW481 AR5212 CardBus a/b/g 168.\"Fujitsu E5454 AR5212 CardBus a/b/g 169.\"HP NC4000 AR5212 PCI a/b/g 170IBM 11ABG WL LAN AR5212 Mini PCI a/b/g 171.\"I/O Data WN-AB AR5212 CardBus a/b 172.\"I/O Data WN-AG AR5212 CardBus a/b/g 173.\"I/O Data WN-A54 AR5212 CardBus a 174.\"Linksys WMP55AG AR5212 PCI a/b/g 175Linksys WPC51AB AR5211 CardBus a/b 176.\"Linksys WPC55AG AR5212 CardBus a/b/g 177.\"NEC PA-WL/54AG AR5212 CardBus a/b/g 178.\"Netgear WAG311 AR5212 PCI a/b/g 179Netgear WAB501 AR5211 CardBus a/b 180.\"Netgear WAG511 AR5212 CardBus a/b/g 181.\"Netgear WG311 rev1 AR5212 PCI b/g 182.\"Netgear WG511T AR5212 CardBus b/g 183.\"Orinoco 8480 AR5212 CardBus a/b/g 184.\"Orinoco 8470WD AR5212 CardBus a/b/g 185Planet WL-3560 AR5211 CardBus a/b/g 186Proxim Skyline 4030 AR5210 CardBus a 187Proxim Skyline 4032 AR5210 PCI a 188.\"Samsung SWL-5200N AR5212 CardBus a/b/g 189Senao NL-5354MP AR5212 Mini PCI a/b/g 190SMC SMC2735W AR5210 CardBus a 191.\"Sony PCWA-C700 AR5212 CardBus a/b 192.\"Sony PCWA-C300S AR5212 CardBus b/g 193Sony PCWA-C500 AR5210 CardBus a 194Wistron CM9 AR5212 Mini PCI a/b/g 195.El 196.Pp 197An up to date list can be found at 198.Pa http://customerproducts.atheros.com/customerproducts/default.asp . 199.Sh EXAMPLES 200The following 201.Xr hostname.if 5 202example configures ath0 to join whatever network is available on boot, 203using WEP key 204.Dq 0x1deadbeef1 , 205channel 11, obtaining an IP address using DHCP: 206.Bd -literal -offset indent 207dhcp NONE NONE NONE nwkey 0x1deadbeef1 chan 11 208.Ed 209.Pp 210The following 211.Xr hostname.if 5 212example creates a host-based access point on boot: 213.Bd -literal -offset indent 214inet 192.168.1.1 255.255.255.0 NONE media autoselect \e 215 mediaopt hostap nwid my_net chan 11 216.Ed 217.Pp 218Configure ath0 for WEP, using hex key 219.Dq 0x1deadbeef1 : 220.Bd -literal -offset indent 221# ifconfig ath0 nwkey 0x1deadbeef1 222.Ed 223.Pp 224Return ath0 to its default settings: 225.Bd -literal -offset indent 226# ifconfig ath0 -bssid -chan media autoselect \e 227 nwid "" -nwkey -powersave 228.Ed 229.Pp 230Join an existing BSS network, 231.Dq my_net : 232.Bd -literal -offset indent 233# ifconfig ath0 192.168.1.1 netmask 0xffffff00 nwid my_net 234.Ed 235.Sh DIAGNOSTICS 236.Bl -diag 237.It "ath%d: unable to attach hardware; HAL status %u" 238The Hardware Access Layer was unable to configure the hardware 239as requested. 240The status code is explained in the HAL include file 241.Pa sys/dev/ic/ar5xxx.h . 242.It "ath%d: failed to allocate descriptors: %d" 243The driver was unable to allocate contiguous memory for the transmit 244and receive descriptors. 245This usually indicates system memory is scarce and/or fragmented. 246.It "ath%d: unable to setup a data xmit queue!" 247The request to the HAL to set up the transmit queue for normal 248data frames failed. 249This should not happen. 250.It "ath%d: unable to setup a beacon xmit queue!" 251The request to the HAL to set up the transmit queue for 802.11 beacon frames 252failed. 253This should not happen. 254.It "ath%d: hardware error; resetting" 255An unrecoverable error in the hardware occurred. 256Errors of this sort include unrecoverable DMA errors. 257The driver will reset the hardware and continue. 258.It "ath%d: rx FIFO overrun; resetting" 259The receive FIFO in the hardware overflowed before the data could be 260transferred to the host. 261This typically occurs because the hardware ran short of receive 262descriptors and had no place to transfer received data. 263The driver will reset the hardware and continue. 264.It "ath%d: unable to reset hardware; hal status %u" 265The Hardware Access Layer was unable to reset the hardware 266as requested. 267The status code is explained in the HAL include file 268.Pa /sys/dev/ic/ar5xxx.h . 269This should not happen. 270.It "ath%d: unable to initialize the key cache" 271The driver was unable to initialize the hardware key cache. 272This should not happen. 273.It "ath%d: unable to start recv logic" 274The driver was unable to restart frame reception. 275This should not happen. 276.It "ath%d: device timeout" 277A frame dispatched to the hardware for transmission did not complete in time. 278The driver will reset the hardware and continue. 279This should not happen. 280.It "ath%d: bogus xmit rate 0x%x" 281An invalid transmit rate was specified for an outgoing frame. 282The frame is discarded. 283This should not happen. 284.It "ath%d: ath_chan_set: unable to reset channel %u (%u Mhz)" 285The Hardware Access Layer was unable to reset the hardware 286when switching channels during scanning. 287This should not happen. 288.It "ath%d: unable to allocate channel table" 289The driver was unable to allocate memory for the table used to hold 290the set of available channels. 291.It "ath%d: unable to collect channel list from hal" 292A problem occurred while querying the HAL to find the set of available 293channels for the device. 294This should not happen. 295.It "ath%d: failed to enable memory mapping" 296The driver was unable to enable memory-mapped I/O to the PCI device registers. 297This should not happen. 298.It "ath%d: failed to enable bus mastering" 299The driver was unable to enable the device as a PCI bus master for doing DMA. 300This should not happen. 301.It "ath%d: cannot map register space" 302The driver was unable to map the device registers into the host address space. 303This should not happen. 304.It "ath%d: could not map interrupt" 305The driver was unable to allocate an IRQ for the device interrupt. 306This should not happen. 307.It "ath%d: could not establish interrupt" 308The driver was unable to install the device interrupt handler. 309This should not happen. 310.El 311.Sh SEE ALSO 312.Xr arp 4 , 313.Xr cardbus 4 , 314.Xr gpio 4 , 315.Xr ifmedia 4 , 316.Xt intro 4 , 317.Xr netintro 4 , 318.Xr pci 4 , 319.Xr hostname.if 5 , 320.Xr gpioctl 8 , 321.Xr hostapd 8 , 322.Xr ifconfig 8 323.Sh HISTORY 324The 325.Nm 326device driver first appeared in 327.Fx 5.2 328using a binary-only HAL module which was ported to 329.Nx 2.0 . 330The driver using a free HAL-replacement first appeared in 331.Ox 3.7 . 332.Sh AUTHORS 333.An -nosplit 334The 335.Nm 336driver was written by 337.An Sam Leffler , 338and was ported to 339.Ox 340by 341.An Reyk Floeter Aq reyk@openbsd.org 342who also wrote a free replacement of the binary-only HAL. 343.Sh CAVEATS 344Different regulatory domains may not be able to communicate with each 345other with 802.11a as different regulatory domains do not necessarily 346have overlapping channels. 347.Pp 348Host AP mode doesn't support power saving. 349Clients attempting to use power saving mode may experience significant 350packet loss (disabling power saving on the client will fix this). 351.Sh BUGS 352Performance in lossy environments is suboptimal. 353The algorithm used to select the rate for transmitted packets is 354very simplistic. 355There is no software retransmit; only hardware retransmit is used. 356Contributors are encouraged to replace the existing rate control algorithm 357with a better one. 358.Pp 359The driver does not fully enable power-save operation of the chip; 360consequently power use is suboptimal. 361