1.\" $NetBSD: ath.4,v 1.13 2006/09/23 04:03:24 jmcneill Exp $ 2.\" 3.\" Copyright (c) 2002, 2003 Sam Leffler, Errno Consulting 4.\" All rights reserved. 5.\"" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer, 11.\" without modification. 12.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer 13.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any 14.\" redistribution must be conditioned upon including a substantially 15.\" similar Disclaimer requirement for further binary redistribution. 16.\" 3. Neither the names of the above-listed copyright holders nor the names 17.\" of any contributors may be used to endorse or promote products derived 18.\" from this software without specific prior written permission. 19.\" 20.\" NO WARRANTY 21.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY 24.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 25.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, 26.\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 29.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 31.\" THE POSSIBILITY OF SUCH DAMAGES. 32.\" 33.\" 34.\" Note: This man page was taken by Perry Metzger almost entirely 35.\" from the "ath" and "ath_hal" man pages in FreeBSD. I claim no 36.\" copyright because there was nearly no original work performed in 37.\" doing so. Maintainers should check the FreeBSD originals for 38.\" updates against the following two revisions and incorporate them 39.\" if needed: 40.\" 41.\" $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ath.4,v 1.16 2004/02/18 08:30:08 maxim Exp $ 42.\" parts from $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ath_hal.4,v 1.7 2004/01/07 20:49:51 blackend Exp $ 43.\" 44.Dd September 12, 2006 45.Dt ATH 4 46.Os 47.Sh NAME 48.Nm ath 49.Nd Atheros IEEE 802.11 driver 50.Sh SYNOPSIS 51.Cd "ath* at pci? dev ? function ?" 52.Cd "ath* at cardbus? function ?" 53.Sh DESCRIPTION 54The 55.Nm 56driver provides support for wireless network adapters based on 57the Atheros AR5210, AR5211, and AR5212 chips. 58Chip-specific support is provided by the Atheros Hardware Access Layer 59(HAL), which is currently available only in binary form for selected 60architectures. 61.Pp 62Supported features include 802.11 and 802.3 frames, power management, BSS, 63IBSS, and host-based access point operation modes. 64All host/device interaction is via DMA. 65.Pp 66The 67.Nm 68driver encapsulates all IP and ARP traffic as 802.11 frames, however 69it can receive either 802.11 or 802.3 frames. 70Transmit speed and operating mode is selectable 71depending on your hardware. 72.Pp 73AR5210-based devices support 802.11a operation with transmit speeds 74of 6 Mbps, 9 Mbps, 12 Mbps, 18 Mbps, 24 Mbps, 36 Mbps, 48 Mbps, and 54 Mbps. 75.Pp 76AR5211-based devices support 802.11a and 802.11b operation with transmit 77speeds as above for 802.11a operation and 781Mbps, 2Mbps, 5.5 Mbps and 11Mbps for 802.11b operation. 79.Pp 80AR5212-based devices support 802.11a, 802.11b, and 802.11g operation 81with transmit speeds appropriate to each. 82.Pp 83All chips also support an Atheros Turbo Mode (TM) that operates in the 84802.11a frequency range with 2x the transmit speeds. 85(This mode is, however, only interoperable with other Atheros-based devices.) 86.Pp 87The actual transmit speed used is dependent on signal quality and the 88.Dq rate control 89algorithm employed by the driver. 90All chips support WEP encryption. 91AR5211 and AR5212 support the AES, TKIP, and Michael cryptographic 92operations required for WPA but at this time the driver does not support them. 93To enable encryption, use 94.Xr ifconfig 8 . 95.Pp 96By default, the 97.Nm 98driver configures the card for BSS operation (aka infrastructure 99mode). 100This mode requires the use of an access point (base station). 101.Pp 102The 103.Nm 104driver also supports the standard IBSS point-to-point mode 105where stations can communicate amongst themselves without the 106aid of an access point. 107.Pp 108The driver may also be configured to operate in hostap mode. 109In this mode a host may function as an access point (base station). 110Access points are different than operating in IBSS mode. 111They operate in BSS mode. 112They allow for easier roaming and bridge all ethernet traffic such 113that machines connected via an access point appear to be on the local 114ethernet segment. 115.Pp 116For more information on configuring this device, see 117.Xr ifconfig 8 . 118.Pp 119Devices supported by the 120.Nm 121driver come in either CardBus or mini-PCI packages. 122Wireless cards in CardBus slots may be inserted and ejected on the fly. 123.Pp 124The following cards are among those supported by the 125.Nm 126driver: 127.Pp 128.Bl -column -compact "Samsung SWL-5200N" "AR5212" "CardBus" "a/b/g" 129.Em "Card Chip Bus Standard" 130Airlink AWLH4030 AR5212 PCI b/g 131Aztech WL830PC AR5212 CardBus b/g 132Belkin F6D3000 AR5212 PCI a/b/g 133D-Link DWL-A650 AR5210 CardBus a 134D-Link DWL-AB650 AR5211 CardBus a/b 135D-Link DWL-A520 AR5210 PCI a 136D-Link DWL-AG520 AR5212 PCI a/b/g 137D-Link DWL-AG650 AR5212 CardBus a/b/g 138D-Link DWL-G520 AR5212 PCI b/g 139D-Link DWL-G650B AR5212 CardBus b/g 140Elecom LD-WL54AG AR5212 CardBus a/b/g 141Elecom LD-WL54 AR5211 CardBus a 142Fujitsu E5454 AR5212 CardBus a/b/g 143Fujitsu FMV-JW481 AR5212 CardBus a/b/g 144Fujitsu E5454 AR5212 CardBus a/b/g 145HP NC4000 AR5212 PCI a/b/g 146I/O Data WN-AB AR5212 CardBus a/b 147I/O Data WN-AG AR5212 CardBus a/b/g 148I/O Data WN-A54 AR5212 CardBus a 149Linksys WMP55AG AR5212 PCI a/b/g 150Linksys WPC51AB AR5211 CardBus a/b 151Linksys WPC55AG AR5212 CardBus a/b/g 152NEC PA-WL/54AG AR5212 CardBus a/b/g 153Netgear WAG311 AR5212 PCI a/b/g 154Netgear WAB501 AR5211 CardBus a/b 155Netgear WAG511 AR5212 CardBus a/b/g 156Netgear WG311 AR5212 PCI b/g 157Netgear WG511T AR5212 CardBus b/g 158Orinoco 8480 AR5212 CardBus a/b/g 159Orinoco 8470WD AR5212 CardBus a/b/g 160Planex GW-NS54AG AR5212 CardBus a/b/g 161Proxim Skyline 4030 AR5210 CardBus a 162Proxim Skyline 4032 AR5210 PCI a 163Samsung SWL-5200N AR5212 CardBus a/b/g 164SMC SMC2735W AR5210 CardBus a 165Sony PCWA-C700 AR5212 CardBus a/b 166Sony PCWA-C300S AR5212 CardBus b/g 167Sony PCWA-C500 AR5210 CardBus a 1683Com 3CRPAG175 AR5212 CardBus a/b/g 169.El 170.Pp 171An up to date list can be found at 172.Pa http://customerproducts.atheros.com/customerproducts . 173.Sh DIAGNOSTICS 174.Bl -diag 175.It "ath%d: unable to attach hardware; HAL status %u" 176The Atheros Hardware Access Layer was unable to configure the hardware 177as requested. 178The status code is explained in the HAL include file 179.Pa contrib/sys/dev/ic/athhal.h . 180.It "ath%d: failed to allocate descriptors: %d" 181The driver was unable to allocate contiguous memory for the transmit 182and receive descriptors. 183This usually indicates system memory is scarce and/or fragmented. 184.It "ath%d: unable to setup a data xmit queue!" 185The request to the HAL to setup the transmit queue for normal 186data frames failed. 187This should not happen. 188.It "ath%d: unable to setup a beacon xmit queue!" 189The request to the HAL to setup the transmit queue for 802.11 beacon frames 190failed. 191This should not happen. 192.It "ath%d: 802.11 address: %s" 193The MAC address programmed in the EEPROM is displayed. 194.It "ath%d: hardware error; resetting" 195An unrecoverable error in the hardware occurred. 196Errors of this sort include unrecoverable DMA errors. 197The driver will reset the hardware and continue. 198.It "ath%d: rx FIFO overrun; resetting" 199The receive FIFO in the hardware overflowed before the data could be 200transferred to the host. 201This typically occurs because the hardware ran short of receive 202descriptors and had no place to transfer received data. 203The driver will reset the hardware and continue. 204.It "ath%d: unable to reset hardware; hal status %u" 205The Atheros Hardware Access Layer was unable to reset the hardware 206as requested. 207The status code is explained in the HAL include file 208.Pa contrib/sys/dev/ic/athhal.h . 209This should not happen. 210.It "ath%d: unable to start recv logic" 211The driver was unable to restart frame reception. 212This should not happen. 213.It "ath%d: device timeout" 214A frame dispatched to the hardware for transmission did not complete in time. 215The driver will reset the hardware and continue. 216This should not happen. 217.It "ath%d: bogus xmit rate 0x%x" 218An invalid transmit rate was specified for an outgoing frame. 219The frame is discarded. 220This should not happen. 221.It "ath%d: ath_chan_set: unable to reset channel %u (%u Mhz)" 222The Atheros Hardware Access Layer was unable to reset the hardware 223when switching channels during scanning. 224This should not happen. 225.It "ath%d: unable to allocate channel table" 226The driver was unable to allocate memory for the table used to hold 227the set of available channels. 228.It "ath%d: unable to collect channel list from hal" 229A problem occurred while querying the HAL to find the set of available 230channels for the device. 231This should not happen. 232.It "ath%d: %s: %dM -\*[Gt] %dM (%d ok, %d err, %d retr)" 233The driver's rate control algorithm changed the current rate for transmitting 234frames. 235This message is temporarily enabled for normal use to help in diagnosing 236and improving the rate control algorithm. 237The message indicates the new and old transmit rates and the statistics 238it used to decide on this change. 239.It "ath%d: failed to enable memory mapping" 240The driver was unable to enable memory-mapped I/O to the PCI device registers. 241This should not happen. 242.It "ath%d: failed to enable bus mastering" 243The driver was unable to enable the device as a PCI bus master for doing DMA. 244This should not happen. 245.It "ath%d: cannot map register space" 246The driver was unable to map the device registers into the host address space. 247This should not happen. 248.It "ath%d: could not map interrupt" 249The driver was unable to allocate an IRQ for the device interrupt. 250This should not happen. 251.It "ath%d: could not establish interrupt" 252The driver was unable to install the device interrupt handler. 253This should not happen. 254.El 255.Sh SEE ALSO 256.Xr arp 4 , 257.Xr cardbus 4 , 258.Xr ifmedia 4 , 259.Xr netintro 4 , 260.Xr pci 4 , 261.Xr ifconfig 8 262.Sh HISTORY 263The 264.Nm 265device driver first appeared in 266.Fx 5.2 . 267It was ported to 268.Nx 2.0 . 269.Sh AUTHORS 270.An -nosplit 271The 272.Nm 273driver was originally written by 274.An Sam Leffler , 275and was ported to 276.Nx 277by 278.An David Young . 279.Sh CAVEATS 280Different regulatory domains have different default channels for adhoc 281mode. 282See 283.Xr ifconfig 8 284for information on how to change the channel. 285Different regulatory domains may not be able to communicate with each 286other with 802.11a as different regulatory domains do not necessarily 287have overlapping channels. 288.Pp 289Revision A1 of the D-LINK DWL-G520 and DWL-G650 are based on an 290Intersil PrismGT chip and are not supported by this driver. 291.Pp 292Revision v3 of the Netgear WG311 is based on a Marvell Libertas 29388W8335 and is not supported by this driver. 294.Pp 295The HAL module is constructed from a binary component and 296operating system-dependent source code. 297Redistribution and use in source and binary forms, without 298modification, are permitted provided that the conditions 299set forth in 300.Pa src/contrib/sys/dev/ic/athhal-COPYRIGHT 301are observed. 302.Sh BUGS 303Performance in lossy environments is suboptimal. 304The algorithm used to select the rate for transmitted packets is 305very simplistic. 306There is no software retransmit; only hardware retransmit is used. 307Contributors are encouraged to replace the existing rate control algorithm 308with a better one (hint: all the information needed is available to the driver). 309.Pp 310The driver does not fully enable power-save operation of the chip; 311consequently power use is suboptimal. 312