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