1.\"- 2.\" Copyright (c) 2002-2004 Sam Leffler, Errno Consulting 3.\" All rights reserved. 4.\"" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer, 10.\" without modification. 11.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer 12.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any 13.\" redistribution must be conditioned upon including a substantially 14.\" similar Disclaimer requirement for further binary redistribution. 15.\" 3. Neither the names of the above-listed copyright holders nor the names 16.\" of any contributors may be used to endorse or promote products derived 17.\" from this software without specific prior written permission. 18.\" 19.\" NO WARRANTY 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY 23.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 24.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, 25.\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 28.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 30.\" THE POSSIBILITY OF SUCH DAMAGES. 31.\" 32.\" $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ath.4,v 1.40 2006/05/12 17:58:11 keramida Exp $ 33.\" $DragonFly: src/share/man/man4/ath.4,v 1.11 2008/11/17 11:55:19 swildner Exp $ 34.\" 35.Dd November 17, 2008 36.Dt ATH 4 37.Os 38.Sh NAME 39.Nm ath 40.Nd "Atheros IEEE 802.11 wireless network driver" 41.Sh SYNOPSIS 42To compile this driver into the kernel, 43place the following lines in your 44kernel configuration file: 45.Bd -ragged -offset indent 46.Cd "device ath" 47.Cd "device ath_hal" 48.Cd "device ath_rate_sample" 49.Cd "device wlan" 50.Ed 51.Pp 52Alternatively, to load the driver as a 53module at boot time, place the following line in 54.Xr loader.conf 5 : 55.Bd -literal -offset indent 56if_ath_load="YES" 57.Ed 58.Sh DESCRIPTION 59The 60.Nm 61driver provides support for wireless network adapters based on 62the Atheros AR5210, AR5211, and AR5212 programming APIs. 63These APIs are used by a wide variety of chips; all chips with 64a PCI and/or CardBus interface are supported. 65Chip-specific support is provided by the Atheros Hardware Access Layer 66(HAL), that is packaged separately. 67.Pp 68Supported features include 802.11 and 802.3 frames, power management, BSS, 69IBSS, and host-based access point operation modes. 70All host/device interaction is via DMA. 71.Pp 72The 73.Nm 74driver encapsulates all IP and ARP traffic as 802.11 frames, however 75it can receive either 802.11 or 802.3 frames. 76Transmit speed and operating mode is selectable 77and depends on the specific chipset. 78AR5210-based devices support 802.11a operation with transmit speeds 79of 6 Mbps, 9 Mbps, 12 Mbps, 18 Mbps, 24 Mbps, 36 Mbps, 48 Mbps, and 54 Mbps. 80AR5211-based devices support 802.11a and 802.11b operation with transmit 81speeds as above for 802.11a operation and 821Mbps, 2Mbps, 5.5 Mbps and 11Mbps for 802.11b operation. 83AR5212-based devices support 802.11a, 802.11b, and 802.11g operation 84with transmit speeds appropriate to each. 85Most chips also support an Atheros Turbo Mode (TM) that operates in 86the 5Ghz frequency range with 2x the transmit speeds. 87Some chips also support Turbo mode in the 2.4Ghz range with 802.11g 88though this support is not presently available due to regulatory requirements. 89(Note that Turbo modes are, however, 90only interoperable with other Atheros-based devices.) 91The actual transmit speed used is dependent on signal quality and the 92.Dq "rate control" 93algorithm employed by the driver. 94All chips support WEP encryption. 95The AR5212 has hardware support for the AES-CCM, TKIP, and Michael cryptographic 96operations required for WPA. 97To enable encryption, use 98.Xr ifconfig 8 99as shown below. 100.Pp 101By default, the 102.Nm 103driver configures the card for BSS operation (aka infrastructure 104mode). 105This mode requires the use of an access point (base station). 106.Pp 107The 108.Nm 109driver also supports the standard IBSS point-to-point mode 110where stations can communicate amongst themselves without the 111aid of an access point. 112.Pp 113The driver may also be configured to operate in hostap mode. 114In this mode a host may function as an access point (base station). 115Access points are different than operating in IBSS mode. 116They operate in BSS mode. 117They allow for easier roaming and bridge all Ethernet traffic such 118that machines connected via an access point appear to be on the local 119Ethernet segment. 120.Pp 121For more information on configuring this device, see 122.Xr ifconfig 8 . 123.Pp 124Devices supported by the 125.Nm 126driver come in either Cardbus or mini-PCI packages. 127Wireless cards in Cardbus slots may be inserted and ejected on the fly. 128.Sh HARDWARE 129The 130.Nm 131driver supports all Atheros Cardbus or PCI cards, 132except those that are based on the AR5005VL chipset. 133.Pp 134A list of cards that are supported can be found at 135.Pp 136.Pa http://customerproducts.atheros.com/customerproducts . 137.Sh EXAMPLES 138Refer to the 139.Sx EXAMPLES 140section of 141.Xr wlan 4 . 142.Sh DIAGNOSTICS 143.Bl -diag 144.It "ath%d: unable to attach hardware; HAL status %u" 145The Atheros Hardware Access Layer was unable to configure the hardware 146as requested. 147The status code is explained in the HAL include file 148.Pa sys/contrib/dev/ath/ah.h . 149.It "ath%d: failed to allocate descriptors: %d" 150The driver was unable to allocate contiguous memory for the transmit 151and receive descriptors. 152This usually indicates system memory is scarce and/or fragmented. 153.It "ath%d: unable to setup a data xmit queue!" 154The request to the HAL to set up the transmit queue for normal 155data frames failed. 156This should not happen. 157.It "ath%d: unable to setup a beacon xmit queue!" 158The request to the HAL to set up the transmit queue for 802.11 beacon frames 159frames failed. 160This should not happen. 161.It "ath%d: 802.11 address: %s" 162The MAC address programmed in the EEPROM is displayed. 163.It "ath%d: hardware error; resetting" 164An unrecoverable error in the hardware occurred. 165Errors of this sort include unrecoverable DMA errors. 166The driver will reset the hardware and continue. 167.It "ath%d: rx FIFO overrun; resetting" 168The receive FIFO in the hardware overflowed before the data could be 169transferred to the host. 170This typically occurs because the hardware ran short of receive 171descriptors and had no place to transfer received data. 172The driver will reset the hardware and continue. 173.It "ath%d: unable to reset hardware; hal status %u" 174The Atheros Hardware Access Layer was unable to reset the hardware 175as requested. 176The status code is explained in the HAL include file 177.Pa sys/contrib/dev/ath/ah.h . 178This should not happen. 179.It "ath%d: unable to start recv logic" 180The driver was unable to restart frame reception. 181This should not happen. 182.It "ath%d: device timeout" 183A frame dispatched to the hardware for transmission did not complete in time. 184The driver will reset the hardware and continue. 185This should not happen. 186.It "ath%d: bogus xmit rate 0x%x" 187An invalid transmit rate was specified for an outgoing frame. 188The frame is discarded. 189This should not happen. 190.It "ath%d: ath_chan_set: unable to reset channel %u (%u Mhz)" 191The Atheros Hardware Access Layer was unable to reset the hardware 192when switching channels during scanning. 193This should not happen. 194.It "ath%d: unable to allocate channel table" 195The driver was unable to allocate memory for the table used to hold 196the set of available channels. 197.It "ath%d: unable to collect channel list from hal" 198A problem occurred while querying the HAL to find the set of available 199channels for the device. 200This should not happen. 201.It "ath%d: failed to enable memory mapping" 202The driver was unable to enable memory-mapped I/O to the PCI device registers. 203This should not happen. 204.It "ath%d: failed to enable bus mastering" 205The driver was unable to enable the device as a PCI bus master for doing DMA. 206This should not happen. 207.It "ath%d: cannot map register space" 208The driver was unable to map the device registers into the host address space. 209This should not happen. 210.It "ath%d: could not map interrupt" 211The driver was unable to allocate an IRQ for the device interrupt. 212This should not happen. 213.It "ath%d: could not establish interrupt" 214The driver was unable to install the device interrupt handler. 215This should not happen. 216.El 217.Sh SEE ALSO 218.Xr an 4 , 219.Xr arp 4 , 220.Xr ath_hal 4 , 221.Xr ifmedia 4 , 222.Xr netintro 4 , 223.Xr wi 4 , 224.Xr wlan 4 , 225.Xr hostapd 8 , 226.Xr ifconfig 8 , 227.Xr wpa_supplicant 8 228.Sh HISTORY 229The 230.Nm 231device driver first appeared in 232.Fx 5.2 233and was imported into 234.Dx 1.5 . 235.Sh CAVEATS 236Different regulatory domains have different default channels for adhoc 237mode. 238See 239.Xr ifconfig 8 240for information on how to change the channel. 241Different regulatory domains may not be able to communicate with each 242other with 802.11a as different regulatory domains do not necessarily 243have overlapping channels. 244.Pp 245Revision A1 of the D-LINK DWL-G520 and DWL-G650 are based on an 246Intersil PrismGT chip and are not supported by this driver. 247.Pp 248Revision v3 of the Netgear WG311 is based on a Marvell Libertas 24988W8335 and is not supported by this driver. 250.Sh BUGS 251There is no software retransmit; only hardware retransmit is used. 252.Pp 253The driver does not fully enable power-save operation of the chip; 254consequently power use is suboptimal. 255.Pp 256The driver honors the regulatory domain programmed into the EEPROM of a 257device and does not support overriding this setting. 258This is done to insure compliance with local regulatory agencies when 259operating as an access point. 260Unfortunately this also means that devices purchased for use in one locale 261may not be usable in another. 262Changes are planned to remove this restriction when operating in station mode. 263.Pp 264WPA is not supported for 5210 parts. 265.Pp 266Atheros' SuperG functionality is not supported. 267