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