Bring in the ugen manual page from NetBSD.

1 files changed, 298 insertions, 0 deletions

diff --git a/share/man/man4/ugen.4 b/share/man/man4/ugen.4
new file mode 100644
index 0000000..7320fdb
--- /dev/null
+++ b/share/man/man4/ugen.4
@@ -0,0 +1,298 @@
+.\" $NetBSD: ugen.4,v 1.13 2001/09/11 22:52:54 wiz 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd July 12, 1998
+.Dt UGEN 4
+.Os
+.Sh NAME
+.Nm ugen
+.Nd USB generic device support
+.Sh SYNOPSIS
+.Cd "device ugen"
+.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.
+.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
+All endpoints handle 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_SET_TIMEOUT (int)
+Set the timeout on the device operations, the time is specified
+in milliseconds.  The value 0 is used to indicate that there is
+no timeout.
+.El
+.Pp
+The control endpoint (endpoint 0) handles the following
+.Xr ioctl 2
+calls:
+.Pp
+.Bl -tag -width indent -compact
+.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.
+The
+.Dv flags
+field can be used to flag that the request is allowed to
+be shorter than the requested size, and the
+.Dv actlen
+will contain the actual size on completion.
+.Bd -literal
+struct usb_ctl_request {
+	int	addr;
+	usb_device_request_t request;
+	void	*data;
+	int	flags;
+#define USBD_SHORT_XFER_OK	0x04	/* allow short reads */
+	int	actlen;		/* actual length transferred */
+};
+.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 FILES
+.Bl -tag -width Pa
+.It Pa /dev/ugenN.EE
+Endpoint
+.Pa EE
+of device
+.Pa N .
+.El
+.Sh SEE ALSO
+.Xr usb 4
+.Sh HISTORY
+The
+.Nm
+driver
+appeared in
+.Nx 1.4 .
+.\" .Sh BUGS
+.\" The driver is not yet finished; there is no access to isochronous endpoints.