diff options
Diffstat (limited to 'share/man/man4/ugen.4')
-rw-r--r-- | share/man/man4/ugen.4 | 298 |
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. |