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$ 33.\"/ 34.Dd September 5, 2005 35.Dt ATH 4 36.Os 37.Sh NAME 38.Nm ath 39.Nd "Atheros IEEE 802.11 wireless network driver" 40.Sh SYNOPSIS 41To compile support for the 42.Nm 43driver into your kernel, place 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 53.Nm 54driver at boot time, place the following lines in 55.Xr loader.conf 5 : 56.Bd -literal -offset indent 57if_ath_load="YES" 58.Ed 59.Sh DESCRIPTION 60The 61.Nm 62driver provides support for wireless network adapters based on 63the Atheros AR5210, AR5211, and AR5212 programming api's. 64These api's are used by a wide variety of chips; all chips with 65a PCI and/or CardBus interface are supported. 66Chip-specific support is provided by the Atheros Hardware Access Layer 67(HAL), that is packaged separately. 68.Pp 69Supported features include 802.11 and 802.3 frames, power management, BSS, 70IBSS, and host-based access point operation modes. 71All host/device interaction is via DMA. 72.Pp 73The 74.Nm 75driver encapsulates all IP and ARP traffic as 802.11 frames, however 76it can receive either 802.11 or 802.3 frames. 77Transmit speed and operating mode is selectable 78and depends on the specific chipset. 79AR5210-based devices support 802.11a operation with transmit speeds 80of 6 Mbps, 9 Mbps, 12 Mbps, 18 Mbps, 24 Mbps, 36 Mbps, 48 Mbps, and 54 Mbps. 81AR5211-based devices support 802.11a and 802.11b operation with transmit 82speeds as above for 802.11a operation and 831Mbps, 2Mbps, 5.5 Mbps and 11Mbps for 802.11b operation. 84AR5212-based devices support 802.11a, 802.11b, and 802.11g operation 85with transmit speeds appropriate to each. 86Most chips also support an Atheros Turbo Mode (TM) that operates in 87the 5Ghz frequency range with 2x the transmit speeds. 88Some chips also support Turbo mode in the 2.4Ghz range with 802.11g 89though this support is not presently available due to regulatory requirements. 90(Note that Turbo modes are, however, 91only interoperable with other Atheros-based devices.) 92The actual transmit speed used is dependent on signal quality and the 93.Dq "rate control" 94algorithm employed by the driver. 95All chips support WEP encryption. 96The AR5212 has hardware support for the AES-CCM, TKIP, and Michael cryptographic 97operations required for WPA. 98To enable encryption, use 99.Xr ifconfig 8 100as shown below. 101.Pp 102By default, the 103.Nm 104driver configures the card for BSS operation (aka infrastructure 105mode). 106This mode requires the use of an access point (base station). 107.Pp 108The 109.Nm 110driver also supports the standard IBSS point-to-point mode 111where stations can communicate amongst themselves without the 112aid of an access point. 113.Pp 114The driver may also be configured to operate in hostap mode. 115In this mode a host may function as an access point (base station). 116Access points are different than operating in IBSS mode. 117They operate in BSS mode. 118They allow for easier roaming and bridge all Ethernet traffic such 119that machines connected via an access point appear to be on the local 120Ethernet segment. 121.Pp 122For more information on configuring this device, see 123.Xr ifconfig 8 . 124.Pp 125Devices supported by the 126.Nm 127driver come in either Cardbus or mini-PCI packages. 128Wireless cards in Cardbus slots may be inserted and ejected on the fly. 129.Sh HARDWARE 130The following cards are among those supported by the 131.Nm 132driver: 133.Pp 134.Bl -column -compact "Samsung SWL-5200N" "AR5212" "Cardbus" "a/b/g" 135.It Em "Card Chip Bus Standard" 136.It "Aztech WL830PC AR5212 CardBus b/g" 137.It "Cisco AIR-CB21AG AR5115 Cardbus a/b/g" 138.It "Cisco AIR-PI21AG AR5115 PCI a/b/g" 139.It "D-Link DWL-A650 AR5210 CardBus a" 140.It "D-Link DWL-AB650 AR5211 CardBus a/b" 141.It "D-Link DWL-A520 AR5210 PCI a" 142.It "D-Link DWL-AG520 AR5212 PCI a/b/g" 143.It "D-Link DWL-AG650 AR5212 CardBus a/b/g" 144.It "D-Link DWL-G520B AR5212 PCI b/g" 145.It "D-Link DWL-G650B AR5212 CardBus b/g" 146.It "Elecom LD-WL54AG AR5212 Cardbus a/b/g" 147.It "Elecom LD-WL54 AR5211 Cardbus a" 148.It "Fujitsu E5454 AR5212 Cardbus a/b/g" 149.It "Fujitsu FMV-JW481 AR5212 Cardbus a/b/g" 150.It "Fujitsu E5454 AR5212 Cardbus a/b/g" 151.It "HP NC4000 AR5212 PCI a/b/g" 152.It "I/O Data WN-AB AR5212 CardBus a/b" 153.It "I/O Data WN-AG AR5212 CardBus a/b/g" 154.It "I/O Data WN-A54 AR5212 CardBus a" 155.It "Linksys WMP55AG AR5212 PCI a/b/g" 156.It "Linksys WPC51AB AR5211 CardBus a/b" 157.It "Linksys WPC55AG AR5212 CardBus a/b/g" 158.It "NEC PA-WL/54AG AR5212 CardBus a/b/g" 159.It "Netgear WAG311 AR5212 PCI a/b/g" 160.It "Netgear WAB501 AR5211 CardBus a/b" 161.It "Netgear WAG511 AR5212 CardBus a/b/g" 162.It "Netgear WG311T AR5212 PCI b/g" 163.It "Netgear WG511T AR5212 CardBus b/g" 164.It "Orinoco 8480 AR5212 CardBus a/b/g" 165.It "Orinoco 8470WD AR5212 CardBus a/b/g" 166.It "Proxim Skyline 4030 AR5210 CardBus a" 167.It "Proxim Skyline 4032 AR5210 PCI a" 168.It "Samsung SWL-5200N AR5212 CardBus a/b/g" 169.It "SMC SMC2536W-AG AR5212 CardBus a/b/g" 170.It "SMC SMC2735W AR5210 CardBus a" 171.It "Sony PCWA-C700 AR5212 Cardbus a/b" 172.It "Sony PCWA-C300S AR5212 Cardbus b/g" 173.It "Sony PCWA-C500 AR5210 Cardbus a" 174.It "3Com 3CRPAG175 AR5212 CardBus a/b/g" 175.El 176.Pp 177An up to date list can be found at 178.Pa http://customerproducts.atheros.com/customerproducts . 179.Sh EXAMPLES 180Join an existing BSS network (ie: connect to an access point): 181.Pp 182.Dl "ifconfig ath0 inet 192.168.0.20 netmask 0xffffff00" 183.Pp 184Join a specific BSS network with network name 185.Dq Li my_net : 186.Pp 187.Dl "ifconfig ath0 inet 192.168.0.20 netmask 0xffffff00 ssid my_net" 188.Pp 189Join a specific BSS network with WEP encryption: 190.Bd -literal -offset indent 191ifconfig ath0 inet 192.168.0.20 netmask 0xffffff00 ssid my_net \e 192 wepmode on wepkey 0x8736639624 193.Ed 194.Pp 195Join/create an 802.11b IBSS network with network name 196.Dq Li my_net : 197.Bd -literal -offset indent 198ifconfig ath0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e 199 mode 11b mediaopt adhoc 200.Ed 201.Pp 202Create an 802.11g host-based access point: 203.Bd -literal -offset indent 204ifconfig ath0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e 205 mode 11g mediaopt hostap 206.Ed 207.Pp 208Create an 802.11a host-based access point with WEP enabled: 209.Bd -literal -offset indent 210ifconfig ath0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e 211 wepmode on wepkey 0x1234567890 mode 11a mediaopt hostap 212.Ed 213.Pp 214Create a host-based wireless bridge to fxp0: 215.Bd -literal -offset indent 216Add BRIDGE to the kernel config. 217ifconfig ath0 inet up ssid my_ap media DS/11Mbps mediaopt hostap 218sysctl net.link.ether.bridge.enable=1 219sysctl net.link.ether.bridge.config="ath0 fxp0" 220sysctl net.inet.ip.check_interface=0 221.Ed 222.Pp 223This will give you the same functionality as an access point. 224.Sh DIAGNOSTICS 225.Bl -diag 226.It "ath%d: unable to attach hardware; HAL status %u" 227The Atheros Hardware Access Layer was unable to configure the hardware 228as requested. 229The status code is explained in the HAL include file 230.Pa sys/contrib/dev/ath/ah.h . 231.It "ath%d: failed to allocate descriptors: %d" 232The driver was unable to allocate contiguous memory for the transmit 233and receive descriptors. 234This usually indicates system memory is scarce and/or fragmented. 235.It "ath%d: unable to setup a data xmit queue!" 236The request to the HAL to set up the transmit queue for normal 237data frames failed. 238This should not happen. 239.It "ath%d: unable to setup a beacon xmit queue!" 240The request to the HAL to set up the transmit queue for 802.11 beacon frames 241frames failed. 242This should not happen. 243.It "ath%d: 802.11 address: %s" 244The MAC address programmed in the EEPROM is displayed. 245.It "ath%d: hardware error; resetting" 246An unrecoverable error in the hardware occurred. 247Errors of this sort include unrecoverable DMA errors. 248The driver will reset the hardware and continue. 249.It "ath%d: rx FIFO overrun; resetting" 250The receive FIFO in the hardware overflowed before the data could be 251transferred to the host. 252This typically occurs because the hardware ran short of receive 253descriptors and had no place to transfer received data. 254The driver will reset the hardware and continue. 255.It "ath%d: unable to reset hardware; hal status %u" 256The Atheros Hardware Access Layer was unable to reset the hardware 257as requested. 258The status code is explained in the HAL include file 259.Pa sys/contrib/dev/ath/ah.h . 260This should not happen. 261.It "ath%d: unable to start recv logic" 262The driver was unable to restart frame reception. 263This should not happen. 264.It "ath%d: device timeout" 265A frame dispatched to the hardware for transmission did not complete in time. 266The driver will reset the hardware and continue. 267This should not happen. 268.It "ath%d: bogus xmit rate 0x%x" 269An invalid transmit rate was specified for an outgoing frame. 270The frame is discarded. 271This should not happen. 272.It "ath%d: ath_chan_set: unable to reset channel %u (%u Mhz)" 273The Atheros Hardware Access Layer was unable to reset the hardware 274when switching channels during scanning. 275This should not happen. 276.It "ath%d: unable to allocate channel table" 277The driver was unable to allocate memory for the table used to hold 278the set of available channels. 279.It "ath%d: unable to collect channel list from hal" 280A problem occurred while querying the HAL to find the set of available 281channels for the device. 282This should not happen. 283.It "ath%d: failed to enable memory mapping" 284The driver was unable to enable memory-mapped I/O to the PCI device registers. 285This should not happen. 286.It "ath%d: failed to enable bus mastering" 287The driver was unable to enable the device as a PCI bus master for doing DMA. 288This should not happen. 289.It "ath%d: cannot map register space" 290The driver was unable to map the device registers into the host address space. 291This should not happen. 292.It "ath%d: could not map interrupt" 293The driver was unable to allocate an IRQ for the device interrupt. 294This should not happen. 295.It "ath%d: could not establish interrupt" 296The driver was unable to install the device interrupt handler. 297This should not happen. 298.El 299.Sh SEE ALSO 300.Xr an 4 , 301.Xr arp 4 , 302.Xr ath_hal 4 , 303.Xr card 4 , 304.Xr netintro 4 , 305.Xr pcic 4 , 306.Xr wi 4 , 307.Xr wlan 4 , 308.Xr ifconfig 8 , 309.Xr wicontrol 8 310.Sh HISTORY 311The 312.Nm 313device driver first appeared in 314.Fx 5.2 . 315.Sh CAVEATS 316Different regulatory domains have different default channels for adhoc 317mode. 318See 319.Xr ifconfig 8 320for information on how to change the channel. 321See 322.Xr wicontrol 8 323for information on different regulatory domains. 324Different regulatory domains may not be able to communicate with each 325other with 802.11a as different regulatory domains do not necessarily 326have overlapping channels. 327.Pp 328Revision A1 of the D-LINK DWL-G520 and DWL-G650 are based on an 329Intersil PrismGT chip and are not supported by this driver. 330.Sh BUGS 331There is no software retransmit; only hardware retransmit is used. 332.Pp 333The driver does not fully enable power-save operation of the chip; 334consequently power use is suboptimal. 335.Pp 336The driver honors the regulatory domain programmed into the EEPROM of a 337device and does not support overriding this setting. 338This is done to insure compliance with local regulatory agencies when 339operating as an access point. 340Unfortunately this also means that devices purchased for use in one locale 341may not be usable in another. 342Changes are planned to remove this restriction when operating in station mode. 343.Pp 344WPA is not supported for 5210 parts. 345.Pp 346Atheros' SuperG functionality is not supported. 347