Add USB man pages. More comming.

3 files changed, 392 insertions, 2 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index a333a5228c8..34811876895 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.72 1999/08/06 01:19:21 deraadt Exp $
+#	$OpenBSD: Makefile,v 1.73 1999/08/13 06:34:59 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,8 @@ 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 uk.4 unix.4 vnd.4 vr.4 wb.4 wd.4 we.4 xl.4 ym.4
+	tun.4 tx.4 udp.4 ugen.4 uhid.4 uk.4 unix.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
 MLINKS+=netintro.4 networking.4
diff --git a/share/man/man4/ugen.4 b/share/man/man4/ugen.4
new file mode 100644
index 00000000000..43fc0fb5b37
--- /dev/null
+++ b/share/man/man4/ugen.4
@@ -0,0 +1,274 @@
+.\"	$OpenBSD: ugen.4,v 1.1 1999/08/13 06:34:59 fgsch Exp $
+.\"	$NetBSD: ugen.4,v 1.7 1999/07/30 01:32:05 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 UGEN 4
+.Os
+.Sh NAME
+.Nm ugen
+.Nd USB generic device support
+.Sh SYNOPSIS
+.Cd "ugen* at uhub?"
+.Pp
+.Sh DESCRIPTION
+The
+.Nm
+driver provides support for all USB devices that do not have
+a special driver.  It supports access to all parts of the device,
+but not in a way that is as convenient as a special purpose driver.
+.Pp
+There can be up to 127 USB devices connected to a USB bus.
+Each USB device can have up to 16 endpoints.  Each of these endpoints
+will communicate in one of four different modes: control, isochronous,
+bulk, or interrupt.  Each of the endpoints will have a different
+device node.  The four least significant bits in the minor device
+number determines which endpoint the device accesses and the rest
+of the bits determines which USB device.
+.Pp
+If an endpoint address is used both for input and output the device
+can be opened for both read or write, but an
+.Xr open 2
+cannot specify
+.Dv O_RDWR
+mode; the endpoint must be opened once for each direction.
+.Pp
+To find out what endpoints that exist there are a series of
+.Xr ioctl 2
+operation on the control endpoint that returns the USB descriptors
+of the device, configurations, interfaces, and endpoints.
+.Pp
+The control transfer mode can only happen on the control endpoint
+which is always endpoint 0.  The control endpoint accepts request
+and may respond with an answer to such request.  Control request
+are issued by
+.Xr ioctl 2
+calls.  
+.\" .Pp
+.\" The isochronous transfer mode can be in or out depending on the
+.\" endpoint.  To perform IO on an isochronous endpoint
+.\" .Xr read 2
+.\" and
+.\" .Xr write 2
+.\" should be used.
+.\" Before any IO operations can take place the transfer rate in
+.\" bytes/second has to be set.  This is done with
+.\" .Xr ioctl 2
+.\" .Dv USB_SET_ISO_RATE .
+.\" Performing this call sets up a buffer corresponding to
+.\" about 1 second of data.
+.Pp
+The bulk transfer mode can be in or out depending on the
+endpoint.  To perform IO on a bulk endpoint
+.Xr read 2
+and
+.Xr write 2
+should be used.
+All IO operations on a bulk endpoint are unbuffered.
+.Pp
+The interrupt transfer mode can only be in.
+To perform input from an interrupt endpoint
+.Xr read 2
+should be used.  A moderate amount of buffering is done
+by the driver.
+.Pp
+The control endpoint (endpoint 0) handles the following
+.Xr ioctl 2
+calls:
+.Pp
+.Bl -tag -width indent -compact
+.It Dv USB_SET_SHORT_XFER (int)
+Allow short read transfer.  Normally a transfer from the device
+which is shorter than the request specified is reported as an
+error.
+.It Dv USB_GET_CONFIG (int)
+Get the device configuration number.
+.It Dv USB_SET_CONFIG (int)
+Set the device into the given configuration number.
+.br
+This operation can only be performed when the control endpoint
+is the sole open endpoint.
+.It Dv USB_GET_ALTINTERFACE (struct usb_alt_interface)
+Get the alternative setting number for the interface with the given
+index.
+The 
+.Dv config_index
+is ignored in this call.
+.Bd -literal
+struct usb_alt_interface {
+	int	config_index;
+	int	interface_index;
+	int	alt_no;
+};
+.Ed
+.It Dv USB_SET_ALTINTERFACE (struct usb_alt_interface)
+Set the alternative setting to the given number in the interface with the
+given index.
+The 
+.Dv config_index
+is ignored in this call.
+.br
+This operation can only be performed when no endpoints for the interface
+are open.
+.It Dv USB_GET_NO_ALT (struct usb_alt_interface)
+Return the number of different alternate settings in the
+.Dv alt_no
+field.
+.It Dv USB_GET_DEVICE_DESC (usb_device_descriptor_t)
+Return the device descriptor.
+.It Dv USB_GET_CONFIG_DESC (struct usb_config_desc)
+Return the descriptor for the configuration with the given index.
+For convenience the current configuration can be specified by
+.Dv USB_CURRENT_CONFIG_INDEX .
+.Bd -literal
+struct usb_config_desc {
+	int	config_index;
+	usb_config_descriptor_t desc;
+};
+.Ed
+.It Dv USB_GET_INTERFACE_DESC (struct usb_interface_desc)
+Return the interface descriptor for an interface specified by its
+configuration index, interface index, and alternative index.
+For convenience the current alternative can be specified by
+.Dv USB_CURRENT_ALT_INDEX .
+.Bd -literal
+struct usb_interface_desc {
+	int	config_index;
+	int	interface_index;
+	int	alt_index;
+	usb_interface_descriptor_t desc;
+};
+.Ed
+.It Dv USB_GET_ENDPOINT_DESC (struct usb_endpoint_desc)
+Return the endpoint descriptor for the endpoint specified by its
+configuration index, interface index, alternative index, and
+endpoint index.
+.Bd -literal
+struct usb_endpoint_desc {
+	int	config_index;
+	int	interface_index;
+	int	alt_index;
+	int	endpoint_index;
+	usb_endpoint_descriptor_t desc;
+};
+.Ed
+.It Dv USB_GET_FULL_DESC (struct usb_full_desc)
+Return all the descriptors for the given configuration.
+.Bd -literal
+struct usb_full_desc {
+	int	config_index;
+	u_int	size;
+	u_char	*data;
+};
+.Ed
+The 
+.Dv data
+field should point to a memory area of of the size given in the
+.Dv size
+field.  The proper size can be determined by first issuing a
+.Dv USB_GET_CONFIG_DESC
+and inspecting the
+.Dv wTotalLength
+field.
+.It Dv USB_GET_STRING_DESC (struct usb_string_desc)
+Get a string descriptor for the given language id and
+string index.
+.Bd -literal
+struct usb_string_desc {
+	int	string_index;
+	int	language_id;
+	usb_string_descriptor_t desc;
+};
+.Ed
+.It Dv USB_DO_REQUEST
+Send a USB request to the device on the control endpoint.
+Any data sent to/from the device is located at
+.Dv data .
+The size of the transferred data is determined from the
+.Dv request .
+The 
+.Dv addr
+field is ignored in this call.
+.Bd -literal
+struct usb_ctl_request {
+	int	addr;
+	usb_device_request_t request;
+	void	*data;
+};
+.Ed
+This is a dangerous operation in that it can perform arbitrary operations
+on the device.  Some of the most dangerous (e.g., changing the device
+address) are not allowed.
+.It Dv USB_GET_DEVICEINFO (struct usb_device_info)
+Get an information summary for the device.  This call will not
+issue any USB transactions.
+.El
+.Pp
+Note that there are two different ways of addressing configurations, interfaces, 
+alternatives, and endpoints: by index or by number.
+The index is the ordinal number (starting from 0) of the descriptor
+as presented by the device.  The number is the respective number of
+the entity as found in its descriptor.  Enumeration of descriptors
+use the index, getting and setting typically uses numbers.
+.Pp
+Example:
+All endpoints (except the control endpoint) for the current configuration
+can be found by iterating the
+.Dv interface_index
+from 0 to
+.Dv config_desc->bNumInterface-1
+and for each of these iterating the
+.Dv endpoint_index
+from 0 to
+.Dv interface_desc->bNumEndpoints .
+The 
+.Dv config_index
+should set to
+.Dv USB_CURRENT_CONFIG_INDEX
+and
+.Dv alt_index
+should be set to
+.Dv USB_CURRENT_ALT_INDEX .
+.Sh SEE ALSO
+.Xr usb 4
+.Sh HISTORY
+The
+.Nm
+driver
+appeared in
+.Ox 2.5 .
+.Sh BUGS
+The driver is not yet finished; there is no access to isochronous endpoints.
diff --git a/share/man/man4/uhid.4 b/share/man/man4/uhid.4
new file mode 100644
index 00000000000..be9bb902fed
--- /dev/null
+++ b/share/man/man4/uhid.4
@@ -0,0 +1,115 @@
+.\"	$OpenBSD: uhid.4,v 1.1 1999/08/13 06:34:59 fgsch Exp $
+.\"	$NetBSD: uhid.4,v 1.6 1999/05/11 21:05:09 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 UHID 4
+.Os
+.Sh NAME
+.Nm uhid
+.Nd USB generic HID support
+.Sh SYNOPSIS
+.Cd "uhid* at uhub?"
+.Pp
+.Sh DESCRIPTION
+The
+.Nm
+driver provides support for all HID (Human Interface Device) interfaces
+in USB devices that do not have a special driver.
+.Pp
+The device handles the following
+.Xr ioctl 2
+calls:
+.Pp
+.Bl -tag -width indent -compact
+.It Dv USB_GET_REPORT_DESC (struct usb_ctl_report_desc)
+Get the HID report descriptor.  Using
+this descriptor the exact layout and meaning of data to/from 
+the device can be found.  The report descriptor is delivered
+without any processing.
+.Bd -literal
+struct usb_ctl_report_desc {
+    int     size;
+    u_char  data[1024];	/* filled data size will vary */
+};
+.Ed
+.It Dv USB_SET_IMMED (int)
+Sets the device in a mode where each
+.Xr read 2
+will return the current value of the input report.  Normally
+a
+.Xr read 2
+will only return the data that the device reports on its
+interrupt pipe.  This call may fail if the device does not support
+this feature.
+.It Dv USB_GET_REPORT (struct usb_ctl_report)
+Get a report from the device without waiting for data on
+the interrupt pipe.  The 
+.Dv report
+field indicates which report is requested.  It should be
+.Dv UHID_INPUT_REPORT ,
+.Dv UHID_OUTPUT_REPORT ,
+or
+.Dv UHID_FEATURE_REPORT .
+This call may fail if the device does not support
+this feature.
+.Bd -literal
+struct usb_ctl_report {
+	int report;
+	u_char	data[1024];	/* filled data size will vary */
+};
+.Ed
+.El
+.Pp
+Use
+.Xr read 2
+to get data from the device.  Data should be read in chunks of the
+size prescribed by the report descriptor.
+.Pp
+Use
+.Xr write 2
+send data to the device.  Data should be written in chunks of the
+size prescribed by the report descriptor.
+.Sh SEE ALSO
+.Xr usb 3 ,
+.Xr usb 4 ,
+.Xr usbhidctl 1
+.Sh HISTORY
+The
+.Nm
+driver
+appeared in
+.Ox 2.5 .