share/man/man4/ath.4

   1 .\"     $NetBSD: ath.4,v 1.26 2009/07/22 19:42:15 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2002, 2003 Sam Leffler, Errno Consulting
   4 .\" All rights reserved.
   5 .\""
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer,
  11 .\"    without modification.
  12 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  13 .\"    similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any
  14 .\"    redistribution must be conditioned upon including a substantially
  15 .\"    similar Disclaimer requirement for further binary redistribution.
  16 .\" 3. Neither the names of the above-listed copyright holders nor the names
  17 .\"    of any contributors may be used to endorse or promote products derived
  18 .\"    from this software without specific prior written permission.
  19 .\"
  20 .\" NO WARRANTY
  21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY
  24 .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
  25 .\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY,
  26 .\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  27 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  28 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  29 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  30 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  31 .\" THE POSSIBILITY OF SUCH DAMAGES.
  32 .\"
  33 .\"
  34 .\" Note: This man page was taken by Perry Metzger almost entirely
  35 .\" from the "ath" and "ath_hal" man pages in FreeBSD. I claim no
  36 .\" copyright because there was nearly no original work performed in
  37 .\" doing so. Maintainers should check the FreeBSD originals for
  38 .\" updates against the following two revisions and incorporate them
  39 .\" if needed:
  40 .\"
  41 .\" $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ath.4,v 1.16 2004/02/18 08:30:08 maxim Exp $
  42 .\" parts from $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ath_hal.4,v 1.7 2004/01/07 20:49:51 blackend Exp $
  43 .\"
  44 .Dd July 22, 2009
  45 .Dt ATH 4
  46 .Os
  47 .Sh NAME
  48 .Nm ath
  49 .Nd Atheros IEEE 802.11 driver
  50 .Sh SYNOPSIS
  51 .Cd "ath* at pci? dev ? function ?"
  52 .Cd "ath* at cardbus? function ?"
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 driver provides support for wireless network adapters based on
  57 the Atheros AR2413, AR2417, AR5210, AR5211, AR5212, AR5213, AR5413,
  58 AR5416, AR5424, AR9160, AR9280, and AR9285 chips.
  59 Chip-specific support is provided by the Atheros Hardware Access Layer
  60 (HAL).
  61 .Pp
  62 Supported features include 802.11 and 802.3 frames, power management, BSS,
  63 IBSS, and host-based access point operation modes.
  64 All host/device interaction is via DMA.
  65 .Pp
  66 The
  67 .Nm
  68 driver encapsulates all IP and ARP traffic as 802.11 frames, however
  69 it can receive either 802.11 or 802.3 frames.
  70 Transmit speed and operating mode is selectable
  71 depending on your hardware.
  72 .Pp
  73 AR5210-based devices support 802.11a operation with transmit speeds
  74 of 6 Mbps, 9 Mbps, 12 Mbps, 18 Mbps, 24 Mbps, 36 Mbps, 48 Mbps, and 54 Mbps.
  75 .Pp
  76 AR5211-based devices support 802.11a and 802.11b operation with transmit
  77 speeds as above for 802.11a operation and
  78 1Mbps, 2Mbps, 5.5 Mbps and 11Mbps for 802.11b operation.
  79 .Pp
  80 AR5212-based and AR5213-based devices support 802.11a, 802.11b, and
  81 802.11g operation with transmit speeds appropriate to each.
  82 .Pp
  83 All chips also support an Atheros Turbo Mode (TM) that operates in the
  84 802.11a frequency range with 2x the transmit speeds.
  85 (This mode is, however, only interoperable with other Atheros-based devices.)
  86 .Pp
  87 The actual transmit speed used is dependent on signal quality and the
  88 .Dq rate control
  89 algorithm employed by the driver.
  90 All chips support WEP encryption.
  91 AR5211 and AR5212 support the AES, TKIP, and Michael cryptographic
  92 operations required for WPA but at this time the driver does not support them.
  93 To enable encryption, use
  94 .Xr ifconfig 8 .
  95 .Pp
  96 By default, the
  97 .Nm
  98 driver configures the card for BSS operation (aka infrastructure
  99 mode).
 100 This mode requires the use of an access point (base station).
 101 .Pp
 102 The
 103 .Nm
 104 driver also supports the standard IBSS point-to-point mode
 105 where stations can communicate amongst themselves without the
 106 aid of an access point.
 107 .Pp
 108 The driver may also be configured to operate in hostap mode.
 109 In this mode a host may function as an access point (base station).
 110 Access points are different than operating in IBSS mode.
 111 They operate in BSS mode.
 112 They allow for easier roaming and bridge all Ethernet traffic such
 113 that machines connected via an access point appear to be on the local
 114 Ethernet segment.
 115 .Pp
 116 The mode of operation is chosen by specifying the appropriate mediaopt
 117 value to ifconfig.
 118 The
 119 .Fl m
 120 flag to ifconfig will list the available options.
 121 .Pp
 122 For more information on configuring this device, see
 123 .Xr ifconfig 8 .
 124 .Pp
 125 Devices supported by the
 126 .Nm
 127 driver come in either CardBus or mini-PCI packages.
 128 Wireless cards in CardBus slots may be inserted and ejected on the fly.
 129 .Pp
 130 The following cards are among those supported by the
 131 .Nm
 132 driver:
 133 .Pp
 134 .Bl -column -compact "Samsung SWL-5200N" "AR5212" "CardBus" "a/b/g"
 135 .It Em "Card    Chip    Bus     Standard"
 136 .It 3Com 3CRPAG175      AR5212  CardBus a/b/g
 137 .It Airlink AWLH4030    AR5212  PCI     b/g
 138 .It Aztech WL830PC      AR5212  CardBus b/g
 139 .It Belkin F6D3000      AR5212  PCI     a/b/g
 140 .It D-Link DWL-A520     AR5210  PCI     a
 141 .It D-Link DWL-A650     AR5210  CardBus a
 142 .It D-Link DWL-AB650    AR5211  CardBus a/b
 143 .It D-Link DWL-AG520    AR5212  PCI     a/b/g
 144 .It D-Link DWL-AG650    AR5212  CardBus a/b/g
 145 .It D-Link DWL-AG660    AR521?  CardBus a/b/g
 146 .It D-Link DWL-G520     AR5212  PCI     b/g
 147 .It D-Link DWL-G650B    AR5212  CardBus b/g
 148 .It Elecom LD-WL54      AR5211  CardBus a
 149 .It Elecom LD-WL54AG    AR5212  CardBus a/b/g
 150 .It Fujitsu E5454       AR5212  CardBus a/b/g
 151 .It Fujitsu E5454       AR5212  CardBus a/b/g
 152 .It Fujitsu FMV-JW481   AR5212  CardBus a/b/g
 153 .It HP NC4000   AR5212  PCI     a/b/g
 154 .It I/O Data WN-A54     AR5212  CardBus a
 155 .It I/O Data WN-AB      AR5212  CardBus a/b
 156 .It I/O Data WN-AG      AR5212  CardBus a/b/g
 157 .It Linksys WMP55AG     AR5212  PCI     a/b/g
 158 .It Linksys WPC51AB     AR5211  CardBus a/b
 159 .It Linksys WPC55AG     AR5212  CardBus a/b/g
 160 .It NEC PA-WL/54AG      AR5212  CardBus a/b/g
 161 .It Netgear WAB501      AR5211  CardBus a/b
 162 .It Netgear WAG311      AR5212  PCI     a/b/g
 163 .It Netgear WAG511      AR5212  CardBus a/b/g
 164 .It Netgear WG311       AR5212  PCI     b/g
 165 .It Netgear WG511T      AR5212  CardBus b/g
 166 .It Orinoco 8470WD      AR5212  CardBus a/b/g
 167 .It Orinoco 8480        AR5212  CardBus a/b/g
 168 .It Planex GW-NS54AG    AR5212  CardBus a/b/g
 169 .It Proxim Skyline 4030 AR5210  CardBus a
 170 .It Proxim Skyline 4032 AR5210  PCI     a
 171 .It Samsung SWL-5200N   AR5212  CardBus a/b/g
 172 .It SMC SMC2735W        AR5210  CardBus a
 173 .It Sony PCWA-C300S     AR5212  CardBus b/g
 174 .It Sony PCWA-C500      AR5210  CardBus a
 175 .It Sony PCWA-C700      AR5212  CardBus a/b
 176 .It Ubiquiti SRC        AR5213  CardBus a/b/g
 177 .El
 178 .Pp
 179 An up to date list can be found at
 180 .Pa http://customerproducts.atheros.com/customerproducts .
 181 .Sh DIAGNOSTICS
 182 .Bl -diag
 183 .It "ath%d: unable to attach hardware; HAL status %u"
 184 The Atheros Hardware Access Layer was unable to configure the hardware
 185 as requested.
 186 The status code is explained in the HAL include file
 187 .Pa contrib/sys/dev/ic/athhal.h .
 188 .It "ath%d: failed to allocate descriptors: %d"
 189 The driver was unable to allocate contiguous memory for the transmit
 190 and receive descriptors.
 191 This usually indicates system memory is scarce and/or fragmented.
 192 .It "ath%d: unable to setup a data xmit queue!"
 193 The request to the HAL to setup the transmit queue for normal
 194 data frames failed.
 195 This should not happen.
 196 .It "ath%d: unable to setup a beacon xmit queue!"
 197 The request to the HAL to setup the transmit queue for 802.11 beacon frames
 198 failed.
 199 This should not happen.
 200 .It "ath%d: 802.11 address: %s"
 201 The MAC address programmed in the EEPROM is displayed.
 202 .It "ath%d: hardware error; resetting"
 203 An unrecoverable error in the hardware occurred.
 204 Errors of this sort include unrecoverable DMA errors.
 205 The driver will reset the hardware and continue.
 206 .It "ath%d: rx FIFO overrun; resetting"
 207 The receive FIFO in the hardware overflowed before the data could be
 208 transferred to the host.
 209 This typically occurs because the hardware ran short of receive
 210 descriptors and had no place to transfer received data.
 211 The driver will reset the hardware and continue.
 212 .It "ath%d: unable to reset hardware; hal status %u"
 213 The Atheros Hardware Access Layer was unable to reset the hardware
 214 as requested.
 215 The status code is explained in the HAL include file
 216 .Pa contrib/sys/dev/ic/athhal.h .
 217 This should not happen.
 218 .It "ath%d: unable to start recv logic"
 219 The driver was unable to restart frame reception.
 220 This should not happen.
 221 .It "ath%d: device timeout"
 222 A frame dispatched to the hardware for transmission did not complete in time.
 223 The driver will reset the hardware and continue.
 224 This should not happen.
 225 .It "ath%d: bogus xmit rate 0x%x"
 226 An invalid transmit rate was specified for an outgoing frame.
 227 The frame is discarded.
 228 This should not happen.
 229 .It "ath%d: ath_chan_set: unable to reset channel %u (%u MHz)"
 230 The Atheros Hardware Access Layer was unable to reset the hardware
 231 when switching channels during scanning.
 232 This should not happen.
 233 .It "ath%d: unable to allocate channel table"
 234 The driver was unable to allocate memory for the table used to hold
 235 the set of available channels.
 236 .It "ath%d: unable to collect channel list from hal"
 237 A problem occurred while querying the HAL to find the set of available
 238 channels for the device.
 239 This should not happen.
 240 .It "ath%d: %s: %dM -\*[Gt] %dM (%d ok, %d err, %d retr)"
 241 The driver's rate control algorithm changed the current rate for transmitting
 242 frames.
 243 This message is temporarily enabled for normal use to help in diagnosing
 244 and improving the rate control algorithm.
 245 The message indicates the new and old transmit rates and the statistics
 246 it used to decide on this change.
 247 .It "ath%d: failed to enable memory mapping"
 248 The driver was unable to enable memory-mapped I/O to the PCI device registers.
 249 This should not happen.
 250 .It "ath%d: failed to enable bus mastering"
 251 The driver was unable to enable the device as a PCI bus master for doing DMA.
 252 This should not happen.
 253 .It "ath%d: cannot map register space"
 254 The driver was unable to map the device registers into the host address space.
 255 This should not happen.
 256 .It "ath%d: could not map interrupt"
 257 The driver was unable to allocate an IRQ for the device interrupt.
 258 This should not happen.
 259 .It "ath%d: could not establish interrupt"
 260 The driver was unable to install the device interrupt handler.
 261 This should not happen.
 262 .El
 263 .Sh SEE ALSO
 264 .Xr arp 4 ,
 265 .Xr cardbus 4 ,
 266 .Xr ifmedia 4 ,
 267 .Xr netintro 4 ,
 268 .Xr pci 4 ,
 269 .Xr ifconfig 8
 270 .Sh HISTORY
 271 The
 272 .Nm
 273 device driver first appeared in
 274 .Fx 5.2 .
 275 It was ported to
 276 .Nx 2.0 .
 277 .Sh AUTHORS
 278 .An -nosplit
 279 The
 280 .Nm
 281 driver was originally written by
 282 .An Sam Leffler ,
 283 and was ported to
 284 .Nx
 285 by
 286 .An David Young .
 287 .Sh CAVEATS
 288 Different regulatory domains have different default channels for adhoc
 289 mode.
 290 See
 291 .Xr ifconfig 8
 292 for information on how to change the channel.
 293 Different regulatory domains may not be able to communicate with each
 294 other with 802.11a as different regulatory domains do not necessarily
 295 have overlapping channels.
 296 .Pp
 297 Revision A1 of the D-LINK DWL-G520 and DWL-G650 are based on an
 298 Intersil PrismGT chip and are not supported by this driver.
 299 .Pp
 300 Revision v2 of the Netgear WG311 is based on a Texas Instruments ACX111
 301 and is not supported by this driver.
 302 .Pp
 303 Revision v3 of the Netgear WG311 is based on a Marvell Libertas
 304 88W8335 and is not supported by this driver.
 305 .Sh BUGS
 306 Performance in lossy environments is suboptimal.
 307 The algorithm used to select the rate for transmitted packets is
 308 very simplistic.
 309 There is no software retransmit; only hardware retransmit is used.
 310 Contributors are encouraged to replace the existing rate control algorithm
 311 with a better one (hint: all the information needed is available to the driver).
 312 .Pp
 313 The driver does not fully enable power-save operation of the chip;
 314 consequently power use is suboptimal.