1.\"- 2.\" Copyright (c) 2002, 2003 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$ 33.\"/ 34.Dd June 23, 2003 35.Dt ATH 4 36.Os 37.Sh NAME 38.Nm ath 39.Nd "Atheros IEEE 802.11 driver" 40.Sh SYNOPSIS 41.Cd "device ath" 42.Sh DESCRIPTION 43The 44.Nm 45driver provides support for wireless network adapters based on 46the Atheros AR5210, AR5211, and AR5212 chips. 47Chip-specific support is provided by the Atheros Hardware Access Layer 48(HAL), that is packaged separately. 49.Pp 50Supported features include 802.11 and 802.3 frames, power management, BSS, 51IBSS, and host-based access point operation modes. 52All host/device interaction is via DMA. 53.Pp 54The 55.Nm 56driver encapsulates all IP and ARP traffic as 802.11 frames, however 57it can receive either 802.11 or 802.3 frames. 58Transmit speed and operating mode is selectable 59depending on your hardware. 60AR5210-based devices support 802.11a operation with trasmit speeds 61of 6 Mbps, 9 Mbps, 12 Mbps, 18 Mbps, 24 Mbps, 36 Mbps, 48 Mbps, and 54 Mbps. 62AR5211-based devices support 802.11a and 802.11b operation with transmit 63speeds as above for 802.11a operation and 641Mbps, 2Mbps, 5.5 Mbps and 11Mbps for 802.11b operation. 65AR5212-based devices support 802.11a, 802.11b, and 802.11g operation 66with transmit speeds appropriate to each. 67All chips also support an Atheros Turbo Mode (TM) that operates in the 802.11a frequency range with 2x the transmit speeds. 68(This mode is, however, only interoperable with other Atheros-based devices.) 69The actual transmit speed used is dependent on signal quality and the 70``rate control'' algorithm employed by the driver. 71All chips support WEP encryption. 72AR5211 and AR5212 support the AES, TKIP, and Michael cryptographic 73operations required for WPA but at this time the driver does support them. 74To enable encryption, use 75.Xr ifconfig 8 76as shown below. 77.Pp 78By default, the 79.Nm 80driver configures the card for BSS operation (aka infrastructure 81mode). 82This mode requires the use of an access point (base station). 83.Pp 84The 85.Nm 86driver also supports the standard IBSS point-to-point mode 87where stations can communicate amongst themselves without the 88aid of an access point. 89.Pp 90The driver may also be configured to operate in hostap mode. 91In this mode a host may function as an access point (base station). 92Access points are different than operating in IBSS mode. 93They operate in BSS mode. 94They allow for easier roaming and bridge all ethernet traffic such 95that machines connected via an access point appear to be on the local 96ethernet segment. 97.Pp 98For more information on configuring this device, see 99.Xr ifconfig 8 . 100.Pp 101Devices supported by the 102.Nm 103driver come in either Cardbus or mini-PCI packages. 104Wireless cards in Cardbus slots may be inserted and ejected on the fly. 105.Pp 106The following cards are among those supported by the 107.Nm 108driver: 109.Pp 110.Bl -column -compact "D-Link DWL-AG650" "AR5212" "Cardbus" 111.Em "Card Chip Bus" 112D-Link DWL-AB650 AR5211 Cardbus 113D-Link DWL-AG520 AR5212 Cardbus 114D-Link DWL-AG650 AR5212 PCI 115Linksys WMP55AG AR5212 Cardbus 116Linksys WPC51AB AR5211 Cardbus 117Linksys WPC55AG AR5212 PCI 118Netgear WAB501 AR5211 Cardbus 119Netgear WAG511 AR5212 Cardbus 120.El 121.Sh EXAMPLES 122Join an existing BSS network (ie: connect to an access point): 123.Pp 124.Dl "ifconfig ath0 inet 192.168.0.20 netmask 0xffffff00" 125.Pp 126Join a specific BSS network with network name 127.Dq Li my_net : 128.Pp 129.Dl "ifconfig ath0 inet 192.168.0.20 netmask 0xffffff00 ssid my_net" 130.Pp 131Join a specific BSS network with WEP encryption: 132.Bd -literal -offset indent 133ifconfig ath0 inet 192.168.0.20 netmask 0xffffff00 ssid my_net \e 134 wepmode on wepkey 0x8736639624 135.Ed 136.Pp 137Join/create an 802.11b IBSS network with network name 138.Dq Li my_net : 139.Bd -literal -offset indent 140ifconfig ath0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e 141 mode 11b mediaopt adhoc 142.Ed 143.Pp 144Create an 802.11g host-based access point: 145.Bd -literal -offset indent 146ifconfig ath0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e 147 mode 11g mediaopt hostap 148.Ed 149.Pp 150Create an 802.11a host-based access point with WEP enabled: 151.Bd -literal -offset indent 152ifconfig ath0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e 153 wepmode on wepkey 0x1234567890 mode 11a mediaopt hostap 154.Ed 155.Pp 156Create a host-based wireless bridge to fxp0: 157.Bd -literal -offset indent 158Add BRIDGE to the kernel config. 159ifconfig ath0 inet up ssid my_ap media DS/11Mbps mediaopt hostap 160sysctl net.link.ether.bridge=1 161sysctl net.link.ether.bridge_cfg="ath0 fxp0" 162sysctl net.inet.ip.forwarding=1 163.Ed 164.Pp 165This will give you the same functionality as an access point. 166.Sh DIAGNOSTICS 167.Bl -diag 168.It "ath%d: unable to attach hardware; HAL status %u" 169The Atheros Hardware Access Layer was unable to configure the hardware 170as requested. 171The status code is explained in the HAL include file 172.Pa sys/contrib/dev/ath/ah.h . 173.It "ath%d: failed to allocate descriptors: %d" 174The driver was unable to allocate contiguous memory for the transmit 175ad receive descriptors. 176This usually indicates system memory is scarce and/or fragmented. 177.It "ath%d: unable to setup a data xmit queue!" 178The request to the HAL to setup the transmit queue for normal 179data frames failed. 180This should not happen. 181.It "ath%d: unable to setup a beacon xmit queue!" 182The request to the HAL to setup the transmit queue for 802.11 beacon frames 183frames failed. 184This should not happen. 185.It "ath%d: 802.11 address: %s" 186The MAC address programmed in the EEPROM is displayed. 187.It "ath%d: hardware error; resetting" 188A nunrecoverable error in the hardware occurred. 189Errors of this sort include unrecoverable DMA errors. 190The driver will reset the hardware and continue. 191.It "ath%d: rx FIFO overrun; resetting" 192The receive FIFO in the hardware overflowed before the data could be 193transferred to the host. 194This typically occurs because the hardware ran short of receive 195descriptors and had no place to transfer received data. 196The driver will reset the hardware and continue. 197.It "ath%d: unable to reset hardware; hal status %u" 198The Atheros Hardware Access Layer was unable to reset the hardware 199as requested. 200The status code is explained in the HAL include file 201.Pa sys/contrib/dev/ath/ah.h . 202This should not happen. 203.It "ath%d: unable to start recv logic" 204The driver was unable to restart frame reception. 205This should not happen. 206.It "ath%d: device timeout" 207A frame dispatched to the hardware for transmission did not complete in time. 208The driver will reset the hardware and continue. 209This should not hapen. 210.It "ath%d: bogus xmit rate 0x%x" 211An invalid transmit rate was specified for an outgoing frame. 212The frame is discarded. 213This should not happen. 214.It "ath%d: ath_chan_set: unable to reset channel %u (%u Mhz)" 215The Atheros Hardware Access Layer was unable to reset the hardware 216when switching channels during scanning. 217This should not happen. 218.It "ath%d: unable to allocate channel table" 219The driver was unable to allocate memory for the table used to hold 220the set of available channels. 221.It "ath%d: unable to collect channel list from hal" 222A problem occurred while querying the HAL to find the set of available 223channels for the device. 224This should not happen. 225.It "ath%d: %s: %dM -> %dM (%d ok, %d err, %d retr)" 226The driver's rate control algorithm changed the current rate for transmitting 227frames. 228This message is temporarily enabled for normal use to help in diagnosing 229and improving the rate control algorithm. 230The message indicates the new and old transmit rates and the statistics 231it used to decide on this change. 232.It "ath%d: failed to enable memory mapping" 233The driver was unable to enable memory-mapped I/O to the PCI device registers. 234This should not happen. 235.It "ath%d: failed to enable bus mastering" 236The driver was unable to enable the device as a PCI bus master for doing DMA. 237This should not happen. 238.It "ath%d: cannot map register space" 239The driver was unable to map the device registers into the host address space. 240This should not happen. 241.It "ath%d: could not map interrupt" 242The driver was unable to allocate an IRQ for the device interrupt. 243This should not happen. 244.It "ath%d: could not establish interrupt" 245The driver was unable to install the device interrupt handler. 246This should not happen. 247.El 248.Sh SEE ALSO 249.Xr an 4 , 250.Xr arp 4 , 251.Xr ath_hal 4, 252.Xr card 4 , 253.Xr netintro 4 , 254.Xr pcic 4 , 255.Xr wi 4 , 256.Xr wlan 4 , 257.Xr ifconfig 8 , 258.Xr wicontrol 8 259.Re 260.Sh HISTORY 261The 262.Nm 263device driver first appeared in 264.Fx 5.2 . 265.Sh CAVEATS 266Different regulatory domains have different default channels for adhoc 267mode. 268See 269.Xr ifconfig 8 270for information on how to change the channel. 271See 272.Xr wicontrol 8 273for information on different regulatory domains. 274.Pp 275802.11g support is little tested and may have interoperabity problems. 276The software is known to function with an Atheros 11g access point but 277interoperability may be problematic until vendors update firmware in 278existing 11g products. 279If you encounter problems using an 11g access point you should be able 280to workaround incompatibilities by locking the driver to 11b mode. 281Alternatively, most 11g compatibility issues are in the 802.11 layer 282and you may be able to workaround issues by modifying the 283.Xr wlan 4 284module. 285.Pp 286Atheros Turbo mode is untested. 287.Sh BUGS 288.Pp 289Roaming mode is broken. 290If you lose your access point by going out of 291range the driver does not automaticaly re-associate. 292.Pp 293Adhoc mode is untested and possibly/probably broken. 294.Pp 295Performance in lossy environments is suboptimal. 296The algorithm used to select the rate for transmitted packets is 297very simplistic. 298There is no software retransmit; only hardware retransmit is used. 299Contributors are encouraged to replace the existing rate control algorithm 300with a better one (hint: all the information needed is availble to the driver). 301.Pp 302General performance is suboptimal. 303The Atheros hardware is known to be capable of transfer rates of 23-34 Mb/s 304(or more) in 11a and 11g modes using their NDIS (aka Windows) driver. 305Results with this driver are mixed and seem to vary significantly. 306.Pp 307It has been observed that getting a DHCP address sometimes requires 308multiple tries. 309This seems to happen only with AR5211 and AR5212 parts and mostly 310in a noisy environment (i.e. one where many access points are found). 311This problem is specific to the driver and not the hardware. 312.Pp 313The driver does not fully enable power-save operation of the chip; 314consequently power use is suboptimal. 315