Add initial man page for bwi(4). Points to the firmware package.

OK jsg@

4 files changed, 306 insertions, 5 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 110351ba6f0..f1b7208a1f4 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.428 2007/09/09 00:20:31 deraadt Exp $
+#	$OpenBSD: Makefile,v 1.429 2007/09/15 06:50:04 mglocker Exp $
 
 MAN=	aac.4 ac97.4 acphy.4 \
 	acpi.4 acpiac.4 acpibat.4 acpibtn.4 acpicpu.4 acpidock.4 \
@@ -11,6 +11,7 @@ MAN=	aac.4 ac97.4 acphy.4 \
 	auich.4 autri.4 auixp.4 auvia.4 awi.4 axe.4 az.4 azalia.4 \
 	bce.4 bge.4 bha.4 \
 	bio.4 bktr.4 bluetooth.4 bmtphy.4 bnx.4 boca.4 bpf.4 brgphy.4 bridge.4 \
+	bwi.4 \
 	cac.4 cas.4 cardbus.4 carp.4 ccd.4 cd.4 cdce.4 cdcef.4 che.4 cfxga.4 \
 	ch.4 ciphy.4 ciss.4 clcs.4 clct.4 cmpci.4 cnw.4 \
 	com.4 crypto.4 cue.4 cy.4 cz.4 dc.4 dcphy.4 ddb.4 de.4 dpt.4 \
diff --git a/share/man/man4/bwi.4 b/share/man/man4/bwi.4
new file mode 100644
index 00000000000..ad288d045fa
--- /dev/null
+++ b/share/man/man4/bwi.4
@@ -0,0 +1,296 @@
+.\" $OpenBSD: bwi.4,v 1.1 2007/09/15 06:50:04 mglocker Exp $
+.\"
+.\" Copyright (c) 2007 Marcus Glocker <mglocker@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $docdate$
+.Os
+.Dt BWI 4
+.Sh NAME
+.Nm bwi
+.Nd Broadcom IEEE 802.11b/g wireless network device
+.Sh SYNOPSIS
+.Cd "bwi* at cardbus?"
+.Cd "bwi* at pci?"
+.Sh DESCRIPTION
+The
+.Nm
+driver provides support for Broadcom AirForce based
+PCI/Cardbus network adapters.
+.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 driver 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
+.\" .Nm
+.\" supports hardware WEP.
+.\" Wired Equivalent Privacy (WEP) is the de facto encryption standard
+.\" for wireless networks.
+.\" It can be typically configured in one of three modes:
+.\" no encryption; 40-bit encryption; or 104-bit encryption.
+.\" Unfortunately, due to serious weaknesses in WEP protocol
+.\" it is strongly recommended that it not be used as the
+.\" sole mechanism to secure wireless communication.
+.\" WEP is not enabled by default.
+.\" .Pp
+The transmit speed is user-selectable or can be adapted automatically by the
+driver depending on the received signal strength and on the number of hardware
+transmission retries.
+.Sh CONFIGURATION
+The
+.Nm
+driver can be configured at runtime with
+.Xr ifconfig 8
+or on boot with
+.Xr hostname.if 5
+using the following parameters:
+.Bl -tag -width Ds
+.It Cm bssid Ar bssid
+Set the desired BSSID.
+.It Fl bssid
+Unset the desired BSSID.
+The interface will automatically select a BSSID in this mode, which is
+the default.
+.It Cm chan Ar n
+Set the channel (radio frequency) to be used by the driver based on
+the given channel ID
+.Ar n .
+.It Fl chan
+Unset the desired channel to be used by the driver.
+The driver will automatically select a channel in this mode, which is
+the default.
+.It Cm media Ar media
+The
+.Nm
+driver supports the following
+.Ar media
+types:
+.Pp
+.Bl -tag -width autoselect -compact
+.It Cm autoselect
+Enable autoselection of the media type and options.
+.It Cm DS1
+Set 802.11b DS 1Mbps operation.
+.It Cm DS2
+Set 802.11b DS 2Mbps operation.
+.It Cm DS5
+Set 802.11b DS 5.5Mbps operation.
+.It Cm DS11
+Set 802.11b DS 11Mbps operation.
+.It Cm OFDM6
+Set 802.11g OFDM 6Mbps operation.
+.It Cm OFDM9
+Set 802.11g OFDM 9Mbps operation.
+.It Cm OFDM12
+Set 802.11g OFDM 12Mbps operation.
+.It Cm OFDM18
+Set 802.11g OFDM 18Mbps operation.
+.It Cm OFDM24
+Set 802.11g OFDM 24Mbps operation.
+.It Cm OFDM36
+Set 802.11g OFDM 36Mbps operation.
+.It Cm OFDM48
+Set 802.11g OFDM 48Mbps operation.
+.It Cm OFDM54
+Set 802.11g OFDM 54Mbps operation.
+.El
+.It Cm mediaopt Ar opts
+The
+.Nm
+driver supports the following media options:
+.Pp
+.Bl -tag -width monitor -compact
+.It Cm hostap
+Select Host AP operation.
+.It Cm ibss
+Select IBSS operation.
+.\".It Cm monitor
+.\"Select monitor mode.
+.El
+.It Fl mediaopt Ar opts
+Disable the specified media options on the driver and return it to the
+default mode of operation (BSS).
+.It Cm mode Ar mode
+The
+.Nm
+driver supports the following modes:
+.Pp
+.Bl -tag -width 11b -compact
+.It Cm 11b
+Force 802.11b operation.
+.It Cm 11g
+Force 802.11g operation.
+.El
+.It Cm nwid Ar id
+Set the network ID.
+The
+.Ar id
+can either be any text string up to 32 characters in length,
+or a series of hexadecimal digits up to 64 digits.
+An empty
+.Ar id
+string allows the interface to connect to any available access points.
+By default the
+.Nm
+driver uses an empty string.
+Note that network ID is synonymous with Extended Service Set ID (ESSID).
+.It Fl nwid
+Set the network ID to the empty string to allow the interface to connect
+to any available access point.
+.It Cm nwkey Ar key
+Enable WEP encryption using the specified
+.Ar key .
+The
+.Ar key
+can either be a string, a series of hexadecimal digits (preceded by
+.Sq 0x ) ,
+or a set of keys of the form
+.Dq n:k1,k2,k3,k4 ,
+where
+.Sq n
+specifies which of the keys will be used for transmitted packets,
+and the four keys,
+.Dq k1
+through
+.Dq k4 ,
+are configured as WEP keys.
+If a set of keys is specified, a comma
+.Pq Sq \&,
+within the key must be escaped with a backslash.
+Note that if multiple keys are used, their order must be the same within
+the network.
+.Nm
+is capable of using both 40-bit (5 characters or 10 hexadecimal digits)
+or 104-bit (13 characters or 26 hexadecimal digits) keys.
+.It Fl nwkey
+Disable WEP encryption.
+This is the default mode of operation.
+.El
+.Sh FILES
+The driver needs a firmware file which is loaded when an interface is
+brought up:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It Pa /etc/firmware/bwi-airforce
+.El
+.\".Pp
+.\"These firmware files are not free because Marvell refuses
+.\"to grant distribution rights.
+.\"As a result, even though
+.\".Ox
+.\"includes the driver, the firmware files cannot be included and
+.\"users have to download these files on their own.
+.Pp
+A prepackaged version of the firmware, designed to be used with
+.Xr pkg_add 1 ,
+can be found at:
+.Bd -literal -offset indent
+http://www.nazgul.ch/bwi/bwi-firmware-1.0.tgz
+.Ed
+.Sh HARDWARE
+The following cards are among those supported by the
+.Nm
+driver:
+.Pp
+.Bl -column -compact "Microcom Travelcard" "MALO111" "CardBus" "a/b/g" -offset 6n
+.Em "Card	Chip	Bus	Standard"
+Linksys WPC54G Ver 3	BCM4318	PCI	b/g
+?	BCM4306	PCI	b/g
+.El
+.Sh EXAMPLES
+The following
+.Xr hostname.if 5
+example configures bwi0 to join whatever network is available on boot,
+using WEP key
+.Dq 0x1deadbeef1 ,
+channel 11, obtaining an IP address using DHCP:
+.Bd -literal -offset indent
+dhcp NONE NONE NONE nwkey 0x1deadbeef1 chan 11
+.Ed
+.Pp
+The following
+.Xr hostname.if 5
+example creates a host-based access point on boot:
+.Bd -literal -offset indent
+inet 192.168.1.1 255.255.255.0 NONE media autoselect \e
+	mediaopt hostap nwid my_net chan 11
+.Ed
+.Pp
+Configure bwi0 for WEP, using hex key
+.Dq 0x1deadbeef1 :
+.Bd -literal -offset indent
+# ifconfig bwi0 nwkey 0x1deadbeef1
+.Ed
+.Pp
+Return bwi0 to its default settings:
+.Bd -literal -offset indent
+# ifconfig bwi0 -bssid -chan media autoselect \e
+	nwid "" -nwkey
+.Ed
+.Pp
+Join an existing BSS network,
+.Dq my_net :
+.Bd -literal -offset indent
+# ifconfig bwi0 192.168.1.1 netmask 0xffffff00 nwid my_net
+.Ed
+.Sh SEE ALSO
+.Xr arp 4 ,
+.Xr cardbus 4 ,
+.Xr ifmedia 4 ,
+.Xr intro 4 ,
+.Xr netintro 4 ,
+.Xr pci 4 ,
+.Xr hostname.if 5 ,
+.Xr hostapd 8 ,
+.Xr ifconfig 8
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Ox 4.3 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+driver was written for DragonFlyBSD by Sepherosa Ziehau and ported to OpenBSD
+by
+.An Jonathan Gray
+and
+.An Marcus Glocker .
diff --git a/share/man/man4/cardbus.4 b/share/man/man4/cardbus.4
index 772338c3eee..3eca38fc27f 100644
--- a/share/man/man4/cardbus.4
+++ b/share/man/man4/cardbus.4
@@ -1,4 +1,4 @@
-.\" $OpenBSD: cardbus.4,v 1.56 2007/05/31 19:19:49 jmc Exp $
+.\" $OpenBSD: cardbus.4,v 1.57 2007/09/15 06:50:04 mglocker Exp $
 .\" $NetBSD: cardbus.4,v 1.4 2000/02/02 19:57:17 augustss Exp $
 .\"
 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
@@ -35,7 +35,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: May 31 2007 $
+.Dd $Mdocdate: September 15 2007 $
 .Dt CARDBUS 4
 .Os
 .Sh NAME
@@ -75,6 +75,8 @@ TI ACX100/ACX111 IEEE 802.11a/b/g wireless network device
 Atheros IEEE 802.11a/b/g wireless network device
 .It Xr atw 4
 ADMtek ADM8211 IEEE 802.11b wireless network device
+.It Xr bwi 4
+Broadcom IEEE 802.11b/g wireless network device
 .It Xr malo 4
 Marvell Libertas IEEE 802.11b/g wireless network device
 .It Xr pgt 4
diff --git a/share/man/man4/pci.4 b/share/man/man4/pci.4
index 32c5377523e..753a68033cb 100644
--- a/share/man/man4/pci.4
+++ b/share/man/man4/pci.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pci.4,v 1.227 2007/09/07 14:06:11 jmc Exp $
+.\"	$OpenBSD: pci.4,v 1.228 2007/09/15 06:50:05 mglocker Exp $
 .\"	$NetBSD: pci.4,v 1.29 2000/04/01 00:32:23 tsarna Exp $
 .\"
 .\" Copyright (c) 2000 Theo de Raadt.  All rights reserved.
@@ -31,7 +31,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 7 2007 $
+.Dd $Mdocdate: September 15 2007 $
 .Dt PCI 4
 .Os
 .Sh NAME
@@ -253,6 +253,8 @@ Aironet Communications 4500/4800 IEEE 802.11FH/b wireless network device
 Atheros IEEE 802.11a/b/g wireless network device
 .It Xr atw 4
 ADMtek ADM8211 IEEE 802.11b wireless network device
+.It Xr bwi 4
+Broadcom IEEE 802.11b/g wireless network device
 .It Xr ipw 4
 Intel PRO/Wireless 2100 IEEE 802.11b wireless network device
 .It Xr iwi 4