More USB manpages.

2 files changed, 334 insertions, 2 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 34811876895..65bcb524c21 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.73 1999/08/13 06:34:59 fgsch Exp $
+#	$OpenBSD: Makefile,v 1.74 1999/08/13 06:52:43 fgsch Exp $
 #	$NetBSD: Makefile,v 1.22.4.2 1996/07/18 00:51:10 jtc Exp $
 
 MAN=	atalk.4 atapiscsi.4 audio.4 adv.4 ahc.4 bpf.4 bridge.4 ccd.4 cd.4 \
@@ -10,7 +10,7 @@ MAN=	atalk.4 atapiscsi.4 audio.4 adv.4 ahc.4 bpf.4 bridge.4 ccd.4 cd.4 \
 	opl.4 options.4 pciide.4 pcmcia.4 pn.4 pty.4 qsphy.4 raid.4 random.4 \
 	rl.4 rln.4 rlphy.4 route.4 scsi.4 sd.4 sl.4 sm.4 spp.4 sppp.4 sqphy.4 \
 	ss.4 st.4 sv.4 tb.4 tcp.4 termios.4 ti.4 tl.4 tlphy.4 tty.4 tp.4 \
-	tun.4 tx.4 udp.4 ugen.4 uhid.4 uk.4 unix.4 vnd.4 vr.4 wb.4 wd.4 \
+	tun.4 tx.4 udp.4 ugen.4 uhid.4 uk.4 unix.4 usb.4 vnd.4 vr.4 wb.4 wd.4 \
 	we.4 xl.4 ym.4
 
 MLINKS+=fd.4 stderr.4 fd.4 stdin.4 fd.4 stdout.4
diff --git a/share/man/man4/usb.4 b/share/man/man4/usb.4
new file mode 100644
index 00000000000..81192ef0489
--- /dev/null
+++ b/share/man/man4/usb.4
@@ -0,0 +1,332 @@
+.\"	$OpenBSD: usb.4,v 1.1 1999/08/13 06:52:43 fgsch Exp $
+.\"	$NetBSD: usb.4,v 1.15 1999/07/29 14:20:32 augustss Exp $
+.\"
+.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Lennart Augustsson.
+.\"
+.\" 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.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 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 DAMAGE.
+.\"
+.Dd July 12, 1998
+.Dt USB 4
+.Os
+.Sh NAME
+.Nm usb
+.Nd Universal Serial Bus driver
+.Sh SYNOPSIS
+.Cd "uhci*   at pci? function ?"
+.Cd "ohci*   at pci? function ?"
+.Cd "usb*    at uhci?"
+.Cd "usb*    at ohci?"
+.Cd "uhub*   at usb?"
+.Cd "uhub*   at uhub? port ? configuration ? interface ? vendor ? product ? release ?"
+.Cd "XX*     at uhub? port ? configuration ? interface ? vendor ? product ? release ?"
+.Pp
+.Cd "#include <dev/usb/usb.h>"
+.Cd "#include <dev/usb/usbhid.h>"
+.Sh INTRODUCTION
+.Ox
+provides machine-independent bus support and drivers for
+.Tn USB
+devices.
+.Pp
+The
+.Ox
+.Nm
+driver has three layers (like
+.Xr scsi 4
+and
+.Xr pcmcia 4 ):
+the controller, the bus, and the device layer.
+The controller attaches to a physical bus (like
+.Xr pci 4 ).
+The
+.Tn USB
+bus attaches to the controller and the root hub attaches
+to the controller.
+Further devices, which may include further hubs,
+attach to other hubs.
+The attachment forms the same tree structure as the physical
+.Tn USB
+device tree.
+For each
+.Tn USB
+device there may be additional drivers attached to it.
+.Pp
+The
+.Cm uhub
+device controls
+.Tn USB
+hubs and must always be present since there is at least a root hub in any
+.Tn USB
+system.
+.Pp
+.Sh INTRODUCTION TO USB
+The
+.Tn USB
+is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
+Each
+.Tn USB
+has a host controller that is the master of the bus;
+all other devices on the bus only speak when spoken to.
+.Pp
+There can be up to 127 devices (apart from the host controller)
+on a bus, each with its own address.
+The addresses are assigned
+dynamically by the host when each device is attached to the bus.
+.Pp
+Within each device there can be up to 16 endpoints.
+Each endpoint
+is individually addressed and the addresses are static.
+Each of these endpoints will communicate in one of four different modes:
+control, isochronous, bulk, or interrupt.
+A device always has at least one endpoint.
+This endpoint has address 0 and is a control
+endpoint and is used to give commands to and extract basic data,
+such as descriptors, from the device.
+Each endpoint, except the control endpoint, is unidirectional.
+.Pp
+The endpoints in a device are grouped into interfaces.
+An interface is a logical unit within a device; e.g.
+a compound device with both a keyboard and a trackball would present
+one interface for each.
+An interface can sometimes be set into different modes,
+called alternate settings, which affects how it operates.
+Different alternate settings can have different endpoints
+within it.
+.Pp
+A device may operate in different configurations.
+Depending on the
+configuration the device may present different sets of endpoints
+and interfaces.
+.Pp
+Each device located on a hub has several
+.Xr config 8
+locators:
+.Bl -tag -compact -width xxxxxxx
+.It Cd port
+this is the number of the port on closest upstream hub.
+.It Cd configuration
+this is the configuration the device must be in for this driver to attach.
+This locator does not set the configuration; it is iterated by the bus
+enumeration.
+.It Cd interface
+this is the interface number within a device that an interface driver
+attaches to.
+.It Cd vendor
+this is the 16 bit vendor id of the device.
+.It Cd product
+this is the 16 bit product id of the device.
+.It Cd release
+this is the 16 bit release (revision) number of the device.
+.El
+The first locator can be used to pin down a particular device
+according to its physical position in the device tree.
+The last three locators can be used to pin down a particular
+device according to what device it actually is.
+.Pp
+The bus enumeration of the
+.Tn USB
+bus proceeds in several steps:
+.Bl -enum
+.It
+Any device specific driver can to attach to the device.
+.It
+If none is found, any device class specific driver can attach.
+.It
+If none is found, all configurations are iterated over.
+For each configuration all the interface are iterated over and interface
+drivers can attach.
+If any interface driver attached in a certain
+configuration the iteration over configurations is stopped.
+.It
+If still no drivers have been found, the generic
+.Tn USB
+driver can attach.
+.El
+.Sh USB CONTROLLER INTERFACE
+Use the following to get access to the
+.Tn USB
+specific structurs and defines.
+.Bd -literal
+#include <sys/dev/usb.h>
+.Ed
+.Pp
+The
+.Pa /dev/usbN
+can be opened and a few operations can be performed on it.
+The
+.Xr poll 2
+system call will say that I/O is possible on the controller device when a
+.Tn USB
+device has been connected or disconnected to the bus.
+.Pp
+The following
+.Xr ioctl 2
+commands are supported on the controller device:
+.Bl -tag -width xxxxxx
+.\" .It Dv USB_DISCOVER
+.\" This command will cause a complete bus discovery to be initiated.
+.\" If any devices attached or detached from the bus they will be
+.\" processed during this command.
+.\" This is the only way that new devices are found on the bus.
+.It Dv USB_DEVICEINFO Fa "struct usb_device_info"
+This command can be used to retrieve some information about a device
+on the bus.
+The
+.Va addr
+field should be filled before the call and the other fields will
+be filled by information about the device on that address.
+Should no such device exist an error is reported.
+.Bd -literal
+struct usb_device_info {
+	uByte	addr;		/* device address */
+	char	product[USB_MAX_STRING_LEN];
+	char	vendor[USB_MAX_STRING_LEN];
+	char	release[8];
+	uByte	class;
+	uByte	config;
+	uByte	lowspeed;
+	int	power;
+	int	nports;
+	uByte	ports[16];
+#define USB_PORT_ENABLED 0xff
+#define USB_PORT_SUSPENDED 0xfe
+#define USB_PORT_POWERED 0xfd
+#define USB_PORT_DISABLED 0xfc
+};
+.Ed
+.Pp
+The
+.Va product ,
+.Va vendor ,
+and
+.Va release
+fields contain self-explanatory descriptions of the device.
+.Pp
+The
+.Va class
+field contains the device class.
+.Pp
+The
+.Va config
+field shows the current configuration of the device.
+.Pp
+The
+.Va lowspeed
+field
+is set if the device is a
+.Tn USB
+low speed device.
+.Pp
+The
+.Va power
+field shows the power consumption in milli-amps drawn at 5 volts,
+or zero if the device is self powered.
+.Pp
+If the device is a hub the
+.Va nports
+field is non-zero and the
+.Va ports
+field contains the addresses of the connected devices.
+If no device is connected to a port one of the
+.Va USB_PORT_*
+values indicates its status.
+.It Dv USB_DEVICESTATS Fa "struct usb_device_stats"
+This command retrieves statistics about the controller.
+.Bd -literal
+struct usb_device_stats {
+	u_long	requests[4];
+};
+.Ed
+.Pp
+The
+.Va requests
+field is indexed by the transfer kind, i.e.
+.Va UE_* ,
+and indicates how many transfers of each kind that has been completed
+by the controller.
+.It Dv USB_REQUEST Fa "struct usb_ctl_request"
+This command can be used to execute arbitrary requests on the control pipe.
+This is
+.Em DANGEROUS
+and should be used with great care since it
+can destroy the bus integrity.
+.El
+.Pp
+The include file
+.Aq Pa dev/usb/usb.h
+contains definitions for the types used by the various
+.Xr ioctl 2
+calls.
+The naming convention of the fields for the various
+.Tn USB
+descriptors exactly follows the naming in the
+.Tn USB
+specification.
+Byte sized fields can be accessed directly, but word (16 bit)
+sized fields must be access by the
+.Fn UGETW field
+and
+.Fn USETW field value
+macros to handle byte order and alignment properly.
+.Pp
+The include file
+.Aq Pa dev/usb/usbhid.h
+similarly contains the definitions for
+Human Interface Devices
+.Pq Tn HID .
+.Sh BUGS
+There should be a serial number locator, but
+.Ox
+does not have string valued locators.
+.Sh SEE ALSO
+The 
+.Tn USB 
+specifications can be found at
+.Dv http://www.usb.org/developers/docs.htm .
+.Pp
+.Xr pci 4 ,
+.\".Xr uaudio 4 ,
+.Xr ugen 4 ,
+.Xr uhid 4 ,
+.\".Xr ukbd 4 ,
+.\".Xr ulpt 4 ,
+.\".Xr ums 4 ,
+.Xr usb 3 ,
+.Xr usbd 8 ,
+.Xr usbdevs 8
+.Sh HISTORY
+The
+.Nm
+driver
+appeared in
+.Ox 2.5 .