diff options
Diffstat (limited to 'static/openbsd/man4/ath.4')
| -rw-r--r-- | static/openbsd/man4/ath.4 | 353 |
1 files changed, 353 insertions, 0 deletions
diff --git a/static/openbsd/man4/ath.4 b/static/openbsd/man4/ath.4 new file mode 100644 index 00000000..76642ff3 --- /dev/null +++ b/static/openbsd/man4/ath.4 @@ -0,0 +1,353 @@ +.\" $OpenBSD: ath.4,v 1.70 2025/03/27 10:21:53 jmc Exp $ +.\" $NetBSD: ath.4,v 1.5 2004/07/03 16:58:18 mycroft Exp $ +.\" +.\" Copyright (c) 2002, 2003 Sam Leffler, Errno Consulting +.\" All rights reserved. +.\"" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any +.\" redistribution must be conditioned upon including a substantially +.\" similar Disclaimer requirement for further binary redistribution. +.\" 3. Neither the names of the above-listed copyright holders nor the names +.\" of any contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, +.\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGES. +.\" +.\" +.\" Note: This man page was taken by Perry Metzger almost entirely +.\" from the "ath" and "ath_hal" man pages in FreeBSD. I claim no +.\" copyright because there was nearly no original work performed in +.\" doing so. Maintainers should check the FreeBSD originals for +.\" updates against the following two revisions and incorporate them +.\" if needed: +.\" +.\" $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ath.4,v 1.16 2004/02/18 08:30:08 maxim Exp $ +.\" parts from $FreeBSD: /repoman/r/ncvs/src/share/man/man4/ath_hal.4,v 1.7 2004/01/07 20:49:51 blackend Exp $ +.\" +.Dd $Mdocdate: March 27 2025 $ +.Dt ATH 4 +.Os +.Sh NAME +.Nm ath +.Nd Atheros IEEE 802.11a/b/g wireless network device with GPIO +.Sh SYNOPSIS +.Cd "ath* at pci? dev ? function ?" +.Cd "ath* at cardbus? dev ? function ?" +.Cd "gpio* at ath?" +.Sh DESCRIPTION +The +.Nm +driver provides support for wireless network devices based on +the Atheros AR5210, AR5211, and AR5212 chips. +.Pp +All host/device interaction is via DMA. +The +.Nm +driver encapsulates all IP and ARP traffic as 802.11 frames, though +it can receive either 802.11 or 802.3 frames. +Transmit speed and operating mode is selectable and +depends on the specific chipset. +.Pp +Support for the various devices is as follows: +.Bl -tag -width "ARxxxx" +.It AR5210 +These devices support 802.11a operation with transmit speeds +of 6 Mbps, 9 Mbps, 12 Mbps, 18 Mbps, 24 Mbps, 36 Mbps, 48 Mbps, and 54 Mbps. +.It AR5211 +These devices support 802.11a and 802.11b operation with +transmit speeds as above for 802.11a and +1Mbps, 2Mbps, 5.5 Mbps, and 11Mbps for 802.11b operation. +.It AR5212 +These devices support 802.11a, 802.11b, and 802.11g operation with +transmit speeds as above for 802.11a, 802.11b, and 802.11g operation +(802.11g speeds are the same as for 802.11a speeds). +.El +.Pp +The actual transmit speed used is dependent on signal quality and the +.Dq rate control +algorithm employed by the driver. +.Pp +These are the modes the +.Nm +driver can operate in: +.Bl -tag -width "IBSS-masterXX" +.It BSS mode +Also known as +.Em infrastructure +mode, this is used when associating with an access point, through +which all traffic passes. +This mode is the default. +.It IBSS mode +Also known as +.Em IEEE ad-hoc +mode or +.Em peer-to-peer +mode. +This is the standardized method of operating without an access point. +Stations associate with a service set. +However, actual connections between stations are peer-to-peer. +.It Host AP +In this mode the adapter acts as an access point (base station) +for other cards. +.It monitor mode +In this mode the driver is able to receive packets without +associating with an access point. +This disables the internal receive filter and enables the card to +capture packets from networks which it wouldn't normally have access to, +or to scan for access points. +.El +.Pp +The +.Nm +driver can be configured to use +Wired Equivalent Privacy (WEP) or +Wi-Fi Protected Access (WPA1 and WPA2). +WPA2 is currently the most secure encryption standard for wireless networks +supported by +.Ox . +It is strongly recommended that neither WEP nor WPA1 +are used as the sole mechanism to secure wireless communication, +due to serious weaknesses. +WPA1 is disabled by default and may be enabled using the option +.Qq Cm wpaprotos Ar wpa1,wpa2 . +For standard WPA networks which use pre-shared keys (PSK), +keys are configured using the +.Qq Cm wpakey +option. +WPA-Enterprise networks require use of the wpa_supplicant package. +.Pp +AR5211 and AR5212 support the AES, TKIP, and Michael cryptographic +operations required for WPA in hardware but at this time the driver +does not support them. +.Pp +The +.Nm +driver can be configured at runtime with +.Xr ifconfig 8 +or on boot with +.Xr hostname.if 5 . +.Sh HARDWARE +Devices supported by the +.Nm +driver come in either CardBus or Mini PCI packages. +Wireless cards in CardBus slots may be inserted and ejected on the fly. +.Pp +The following cards are among those supported by the +.Nm +driver: +.Bl -column "Proxim Skyline 4030" "AR5212" "Mini PCI" "Standard" -offset 6n +.It Em Card Ta Em Chip Ta Em Bus Ta Em Standard +.It "3Com 3CRPAG175" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "Aztech WL830PC" Ta AR5212 Ta CardBus Ta b/g +.It "Cisco AIR-CB21AG" Ta AR5212 Ta CardBus Ta a/b/g +.It "D-Link DWL-A650" Ta AR5210 Ta CardBus Ta a +.It "D-Link DWL-AB650" Ta AR5211 Ta CardBus Ta a/b +.It "D-Link DWL-A520" Ta AR5210 Ta PCI Ta a +.\"It "D-Link DWL-AG520" Ta AR5212 Ta PCI Ta a/b/g +.\"It "D-Link DWL-AG650" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "D-Link DWL-G520" Ta AR5212 Ta PCI Ta b/g +.\"It "D-Link DWL-G650B" Ta AR5212 Ta CardBus Ta b/g +.\"It "Elecom LD-WL54AG" Ta AR5212 Ta CardBus Ta a/b/g +.It "Elecom LD-WL54" Ta AR5211 Ta CardBus Ta a +.\"It "Fujitsu E5454" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "Fujitsu FMV-JW481" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "Fujitsu E5454" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "HP NC4000" Ta AR5212 Ta PCI Ta a/b/g +.It "IBM 11ABG WL LAN" Ta AR5212 Ta Mini PCI Ta a/b/g +.\"It "I/O Data WN-AB" Ta AR5212 Ta CardBus Ta a/b +.\"It "I/O Data WN-AG" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "I/O Data WN-A54" Ta AR5212 Ta CardBus Ta a +.\"It "Linksys WMP55AG" Ta AR5212 Ta PCI Ta a/b/g +.It "Linksys WPC51AB" Ta AR5211 Ta CardBus Ta a/b +.\"It "Linksys WPC55AG" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "NEC PA-WL/54AG" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "Netgear WAG311" Ta AR5212 Ta PCI Ta a/b/g +.It "Netgear WAB501" Ta AR5211 Ta CardBus Ta a/b +.\"It "Netgear WAG511" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "Netgear WG311 rev1" Ta AR5212 Ta PCI Ta b/g +.\"It "Netgear WG511T" Ta AR5212 Ta CardBus Ta b/g +.\"It "Orinoco 8480" Ta AR5212 Ta CardBus Ta a/b/g +.\"It "Orinoco 8470WD" Ta AR5212 Ta CardBus Ta a/b/g +.It "Planet WL-3560" Ta AR5211 Ta CardBus Ta a/b/g +.It "Proxim Skyline 4030" Ta AR5210 Ta CardBus Ta a +.It "Proxim Skyline 4032" Ta AR5210 Ta PCI Ta a +.\"It "Samsung SWL-5200N" Ta AR5212 Ta CardBus Ta a/b/g +.It "Senao NL-5354MP" Ta AR5212 Ta Mini PCI Ta a/b/g +.It "SMC SMC2735W" Ta AR5210 Ta CardBus Ta a +.\"It "Sony PCWA-C700" Ta AR5212 Ta CardBus Ta a/b +.\"It "Sony PCWA-C300S" Ta AR5212 Ta CardBus Ta b/g +.It "Sony PCWA-C500" Ta AR5210 Ta CardBus Ta a +.It "Wistron CM9" Ta AR5212 Ta Mini PCI Ta a/b/g +.El +.Sh EXAMPLES +The following example scans for available networks: +.Pp +.Dl # ifconfig ath0 scan +.Pp +The following +.Xr hostname.if 5 +example configures ath0 to join network +.Dq mynwid , +using WPA key +.Dq mywpakey , +obtaining an IP address using DHCP: +.Bd -literal -offset indent +nwid mynwid wpakey mywpakey +inet autoconf +.Ed +.Pp +The following +.Xr hostname.if 5 +example creates a host-based access point on boot: +.Bd -literal -offset indent +mediaopt hostap +nwid mynwid wpakey mywpakey +inet 192.168.1.1 255.255.255.0 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "ath0: unable to attach hardware; HAL status N" +The Hardware Access Layer was unable to configure the hardware +as requested. +The status code is explained in the HAL include file +.Pa sys/dev/ic/ar5xxx.h . +.It "ath0: failed to allocate descriptors: N" +The driver was unable to allocate contiguous memory for the transmit +and receive descriptors. +This usually indicates system memory is scarce and/or fragmented. +.It "ath0: unable to setup a data xmit queue!" +The request to the HAL to set up the transmit queue for normal +data frames failed. +This should not happen. +.It "ath0: unable to setup a beacon xmit queue!" +The request to the HAL to set up the transmit queue for 802.11 beacon frames +failed. +This should not happen. +.It "ath0: hardware error; resetting" +An unrecoverable error in the hardware occurred. +Errors of this sort include unrecoverable DMA errors. +The driver will reset the hardware and continue. +.It "ath0: rx FIFO overrun; resetting" +The receive FIFO in the hardware overflowed before the data could be +transferred to the host. +This typically occurs because the hardware ran short of receive +descriptors and had no place to transfer received data. +The driver will reset the hardware and continue. +.It "ath0: unable to reset hardware; hal status N" +The Hardware Access Layer was unable to reset the hardware +as requested. +The status code is explained in the HAL include file +.Pa /sys/dev/ic/ar5xxx.h . +This should not happen. +.It "ath0: unable to initialize the key cache" +The driver was unable to initialize the hardware key cache. +This should not happen. +.It "ath0: unable to start recv logic" +The driver was unable to restart frame reception. +This should not happen. +.It "ath0: device timeout" +A frame dispatched to the hardware for transmission did not complete in time. +The driver will reset the hardware and continue. +This should not happen. +.It "ath0: bogus xmit rate 0xNNNN" +An invalid transmit rate was specified for an outgoing frame. +The frame is discarded. +This should not happen. +.It "ath0: ath_chan_set: unable to reset channel N (X MHz)" +The Hardware Access Layer was unable to reset the hardware +when switching channels during scanning. +This should not happen. +.It "ath0: unable to allocate channel table" +The driver was unable to allocate memory for the table used to hold +the set of available channels. +.It "ath0: unable to collect channel list from hal" +A problem occurred while querying the HAL to find the set of available +channels for the device. +This should not happen. +.It "ath0: failed to enable memory mapping" +The driver was unable to enable memory-mapped I/O to the PCI device registers. +This should not happen. +.It "ath0: failed to enable bus mastering" +The driver was unable to enable the device as a PCI bus master for doing DMA. +This should not happen. +.It "ath0: cannot map register space" +The driver was unable to map the device registers into the host address space. +This should not happen. +.It "ath0: could not map interrupt" +The driver was unable to allocate an IRQ for the device interrupt. +This should not happen. +.It "ath0: could not establish interrupt" +The driver was unable to install the device interrupt handler. +This should not happen. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr cardbus 4 , +.Xr gpio 4 , +.Xr ifmedia 4 , +.Xr intro 4 , +.Xr netintro 4 , +.Xr pci 4 , +.Xr hostname.if 5 , +.Xr gpioctl 8 , +.Xr hostapd 8 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.2 +using a binary-only HAL module which was ported to +.Nx 2.0 . +The driver using a free HAL-replacement first appeared in +.Ox 3.7 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Sam Leffler , +and was ported to +.Ox +by +.An Reyk Floeter Aq Mt reyk@openbsd.org +who also wrote a free replacement of the binary-only HAL. +.Sh CAVEATS +Different regulatory domains may not be able to communicate with each +other with 802.11a as different regulatory domains do not necessarily +have overlapping channels. +.Pp +Host AP mode doesn't support power saving. +Clients attempting to use power saving mode may experience significant +packet loss (disabling power saving on the client will fix this). +.Sh BUGS +Performance in lossy environments is suboptimal. +The algorithm used to select the rate for transmitted packets is +very simplistic. +There is no software retransmit; only hardware retransmit is used. +Contributors are encouraged to replace the existing rate control algorithm +with a better one. +.Pp +The driver does not fully enable power-save operation of the chip; +consequently power use is suboptimal. +.Pp +Operation in the 2GHz band is restricted to 11b mode because the driver +does not support running the hardware in 11g mode. |