1.\" $NetBSD: ath.4,v 1.17 2006/10/14 07:27:43 wiz 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 October 14, 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, AR5212, and AR5213 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 and AR5213-based devices support 802.11a, 802.11b, and 81802.11g operation with 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" 1303Com 3CRPAG175 AR5212 CardBus a/b/g 131Airlink AWLH4030 AR5212 PCI b/g 132Aztech WL830PC AR5212 CardBus b/g 133Belkin F6D3000 AR5212 PCI a/b/g 134D-Link DWL-A520 AR5210 PCI a 135D-Link DWL-A650 AR5210 CardBus a 136D-Link DWL-AB650 AR5211 CardBus a/b 137D-Link DWL-AG520 AR5212 PCI a/b/g 138D-Link DWL-AG650 AR5212 CardBus a/b/g 139D-Link DWL-G520 AR5212 PCI b/g 140D-Link DWL-G650B AR5212 CardBus b/g 141Elecom LD-WL54 AR5211 CardBus a 142Elecom LD-WL54AG AR5212 CardBus a/b/g 143Fujitsu E5454 AR5212 CardBus a/b/g 144Fujitsu E5454 AR5212 CardBus a/b/g 145Fujitsu FMV-JW481 AR5212 CardBus a/b/g 146HP NC4000 AR5212 PCI a/b/g 147I/O Data WN-A54 AR5212 CardBus a 148I/O Data WN-AB AR5212 CardBus a/b 149I/O Data WN-AG AR5212 CardBus a/b/g 150Linksys WMP55AG AR5212 PCI a/b/g 151Linksys WPC51AB AR5211 CardBus a/b 152Linksys WPC55AG AR5212 CardBus a/b/g 153NEC PA-WL/54AG AR5212 CardBus a/b/g 154Netgear WAB501 AR5211 CardBus a/b 155Netgear WAG311 AR5212 PCI a/b/g 156Netgear WAG511 AR5212 CardBus a/b/g 157Netgear WG311 AR5212 PCI b/g 158Netgear WG511T AR5212 CardBus b/g 159Orinoco 8470WD AR5212 CardBus a/b/g 160Orinoco 8480 AR5212 CardBus a/b/g 161Planex GW-NS54AG AR5212 CardBus a/b/g 162Proxim Skyline 4030 AR5210 CardBus a 163Proxim Skyline 4032 AR5210 PCI a 164Samsung SWL-5200N AR5212 CardBus a/b/g 165SMC SMC2735W AR5210 CardBus a 166Sony PCWA-C300S AR5212 CardBus b/g 167Sony PCWA-C500 AR5210 CardBus a 168Sony PCWA-C700 AR5212 CardBus a/b 169Ubiquiti SRC AR5213 CardBus a/b/g 170.El 171.Pp 172An up to date list can be found at 173.Pa http://customerproducts.atheros.com/customerproducts . 174.Sh DIAGNOSTICS 175.Bl -diag 176.It "ath%d: unable to attach hardware; HAL status %u" 177The Atheros Hardware Access Layer was unable to configure the hardware 178as requested. 179The status code is explained in the HAL include file 180.Pa contrib/sys/dev/ic/athhal.h . 181.It "ath%d: failed to allocate descriptors: %d" 182The driver was unable to allocate contiguous memory for the transmit 183and receive descriptors. 184This usually indicates system memory is scarce and/or fragmented. 185.It "ath%d: unable to setup a data xmit queue!" 186The request to the HAL to setup the transmit queue for normal 187data frames failed. 188This should not happen. 189.It "ath%d: unable to setup a beacon xmit queue!" 190The request to the HAL to setup the transmit queue for 802.11 beacon frames 191failed. 192This should not happen. 193.It "ath%d: 802.11 address: %s" 194The MAC address programmed in the EEPROM is displayed. 195.It "ath%d: hardware error; resetting" 196An unrecoverable error in the hardware occurred. 197Errors of this sort include unrecoverable DMA errors. 198The driver will reset the hardware and continue. 199.It "ath%d: rx FIFO overrun; resetting" 200The receive FIFO in the hardware overflowed before the data could be 201transferred to the host. 202This typically occurs because the hardware ran short of receive 203descriptors and had no place to transfer received data. 204The driver will reset the hardware and continue. 205.It "ath%d: unable to reset hardware; hal status %u" 206The Atheros Hardware Access Layer was unable to reset the hardware 207as requested. 208The status code is explained in the HAL include file 209.Pa contrib/sys/dev/ic/athhal.h . 210This should not happen. 211.It "ath%d: unable to start recv logic" 212The driver was unable to restart frame reception. 213This should not happen. 214.It "ath%d: device timeout" 215A frame dispatched to the hardware for transmission did not complete in time. 216The driver will reset the hardware and continue. 217This should not happen. 218.It "ath%d: bogus xmit rate 0x%x" 219An invalid transmit rate was specified for an outgoing frame. 220The frame is discarded. 221This should not happen. 222.It "ath%d: ath_chan_set: unable to reset channel %u (%u Mhz)" 223The Atheros Hardware Access Layer was unable to reset the hardware 224when switching channels during scanning. 225This should not happen. 226.It "ath%d: unable to allocate channel table" 227The driver was unable to allocate memory for the table used to hold 228the set of available channels. 229.It "ath%d: unable to collect channel list from hal" 230A problem occurred while querying the HAL to find the set of available 231channels for the device. 232This should not happen. 233.It "ath%d: %s: %dM -\*[Gt] %dM (%d ok, %d err, %d retr)" 234The driver's rate control algorithm changed the current rate for transmitting 235frames. 236This message is temporarily enabled for normal use to help in diagnosing 237and improving the rate control algorithm. 238The message indicates the new and old transmit rates and the statistics 239it used to decide on this change. 240.It "ath%d: failed to enable memory mapping" 241The driver was unable to enable memory-mapped I/O to the PCI device registers. 242This should not happen. 243.It "ath%d: failed to enable bus mastering" 244The driver was unable to enable the device as a PCI bus master for doing DMA. 245This should not happen. 246.It "ath%d: cannot map register space" 247The driver was unable to map the device registers into the host address space. 248This should not happen. 249.It "ath%d: could not map interrupt" 250The driver was unable to allocate an IRQ for the device interrupt. 251This should not happen. 252.It "ath%d: could not establish interrupt" 253The driver was unable to install the device interrupt handler. 254This should not happen. 255.El 256.Sh SEE ALSO 257.Xr arp 4 , 258.Xr cardbus 4 , 259.Xr ifmedia 4 , 260.Xr netintro 4 , 261.Xr pci 4 , 262.Xr ifconfig 8 263.Sh HISTORY 264The 265.Nm 266device driver first appeared in 267.Fx 5.2 . 268It was ported to 269.Nx 2.0 . 270.Sh AUTHORS 271.An -nosplit 272The 273.Nm 274driver was originally written by 275.An Sam Leffler , 276and was ported to 277.Nx 278by 279.An David Young . 280.Sh CAVEATS 281Different regulatory domains have different default channels for adhoc 282mode. 283See 284.Xr ifconfig 8 285for information on how to change the channel. 286Different regulatory domains may not be able to communicate with each 287other with 802.11a as different regulatory domains do not necessarily 288have overlapping channels. 289.Pp 290Revision A1 of the D-LINK DWL-G520 and DWL-G650 are based on an 291Intersil PrismGT chip and are not supported by this driver. 292.Pp 293Revision v2 of the Netgear WG311 is based on a Texas Instruments ACX111 294and is not supported by this driver. 295.Pp 296Revision v3 of the Netgear WG311 is based on a Marvell Libertas 29788W8335 and is not supported by this driver. 298.Pp 299The HAL module is constructed from a binary component and 300operating system-dependent source code. 301Redistribution and use in source and binary forms, without 302modification, are permitted provided that the conditions 303set forth in 304.Pa src/contrib/sys/dev/ic/athhal-COPYRIGHT 305are observed. 306.Sh BUGS 307Performance in lossy environments is suboptimal. 308The algorithm used to select the rate for transmitted packets is 309very simplistic. 310There is no software retransmit; only hardware retransmit is used. 311Contributors are encouraged to replace the existing rate control algorithm 312with a better one (hint: all the information needed is available to the driver). 313.Pp 314The driver does not fully enable power-save operation of the chip; 315consequently power use is suboptimal. 316