diff options
Diffstat (limited to 'share/man/man4/ugen.4')
| -rw-r--r-- | share/man/man4/ugen.4 | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/share/man/man4/ugen.4 b/share/man/man4/ugen.4 new file mode 100644 index 0000000..875abb4 --- /dev/null +++ b/share/man/man4/ugen.4 @@ -0,0 +1,311 @@ +.\" $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. +.\" +.\" 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 May 16, 2014 +.Dt UGEN 4 +.Os +.Sh NAME +.Nm ugen +.Nd USB generic device support +.Sh SYNOPSIS +.Nm +is integrated into the +.Xr usb 4 +kernel module. +.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 determine which endpoint the device accesses, and the rest +of the bits determine 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 which endpoints exist, there are a series of +.Xr ioctl 2 +operations on the control endpoint that return 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 a request +and may respond with an answer to such a request. +Control requests +are issued by +.Xr ioctl 2 +calls. +.\" .Pp +.\" The isochronous transfer mode can be in or out depending on the +.\" endpoint. +.\" To perform I/O on an isochronous endpoint +.\" .Xr read 2 +.\" and +.\" .Xr write 2 +.\" should be used. +.\" Before any I/O 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 I/O on a bulk endpoint +.Xr read 2 +and +.Xr write 2 +should be used. +All I/O operations on a bulk endpoint are unbuffered. +.Pp +The interrupt transfer mode can be in or out depending on the +endpoint. +To perform I/O on an interrupt endpoint +.Xr read 2 +and +.Xr write 2 +should be used. +A moderate amount of buffering is done +by the driver. +.Pp +All endpoints handle the following +.Xr ioctl 2 +calls: +.Bl -tag -width indent +.It Dv USB_SET_SHORT_XFER Pq Vt 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 Pq Vt 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: +.Bl -tag -width indent +.It Dv USB_GET_CONFIG Pq Vt int +Get the device configuration number. +.It Dv USB_SET_CONFIG Pq Vt int +Set the device into the given configuration number. +.Pp +This operation can only be performed when the control endpoint +is the sole open endpoint. +.It Dv USB_GET_ALTINTERFACE Pq Vt "struct usb_alt_interface" +Get the alternative setting number for the interface with the given +index. +The +.Va uai_config_index +is ignored in this call. +.Bd -literal +struct usb_alt_interface { + int uai_config_index; + int uai_interface_index; + int uai_alt_no; +}; +.Ed +.It Dv USB_SET_ALTINTERFACE Pq Vt "struct usb_alt_interface" +Set the alternative setting to the given number in the interface with the +given index. +The +.Va uai_config_index +is ignored in this call. +.Pp +This operation can only be performed when no endpoints for the interface +are open. +.It Dv USB_GET_NO_ALT Pq Vt "struct usb_alt_interface" +Return the number of different alternate settings in the +.Va uai_alt_no +field. +.It Dv USB_GET_DEVICE_DESC Pq Vt usb_device_descriptor_t +Return the device descriptor. +.It Dv USB_GET_CONFIG_DESC Pq Vt "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 ucd_config_index; + usb_config_descriptor_t ucd_desc; +}; +.Ed +.It Dv USB_GET_INTERFACE_DESC Pq Vt "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 uid_config_index; + int uid_interface_index; + int uid_alt_index; + usb_interface_descriptor_t uid_desc; +}; +.Ed +.It Dv USB_GET_ENDPOINT_DESC Pq Vt "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 ued_config_index; + int ued_interface_index; + int ued_alt_index; + int ued_endpoint_index; + usb_endpoint_descriptor_t ued_desc; +}; +.Ed +.It Dv USB_GET_FULL_DESC Pq Vt "struct usb_full_desc" +Return all the descriptors for the given configuration. +.Bd -literal +struct usb_full_desc { + int ufd_config_index; + u_int ufd_size; + u_char *ufd_data; +}; +.Ed +The +.Va ufd_data +field should point to a memory area of the size given in the +.Va ufd_size +field. +The proper size can be determined by first issuing a +.Dv USB_GET_CONFIG_DESC +and inspecting the +.Va wTotalLength +field. +.It Dv USB_GET_STRING_DESC Pq Vt "struct usb_string_desc" +Get a string descriptor for the given language ID and +string index. +.Bd -literal +struct usb_string_desc { + int usd_string_index; + int usd_language_id; + usb_string_descriptor_t usd_desc; +}; +.Ed +.It Dv USB_DO_REQUEST Pq Vt "struct usb_ctl_request" +Send a USB request to the device on the control endpoint. +Any data sent to/from the device is located at +.Va ucr_data . +The size of the transferred data is determined from the +.Va ucr_request . +The +.Va ucr_addr +field is ignored in this call. +The +.Va ucr_flags +field can be used to flag that the request is allowed to +be shorter than the requested size, and +.Va ucr_actlen +will contain the actual size on completion. +.Bd -literal +struct usb_ctl_request { + int ucr_addr; + usb_device_request_t ucr_request; + void *ucr_data; + int ucr_flags; +#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ + int ucr_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 Pq Vt "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 +uses 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 +.Va interface_index +from 0 to +.Va config_desc->bNumInterface Ns \-1 +and for each of these, iterating the +.Va endpoint_index +from 0 to +.Va interface_desc->bNumEndpoints . +The +.Va config_index +should be set to +.Dv USB_CURRENT_CONFIG_INDEX +and +.Va alt_index +should be set to +.Dv USB_CURRENT_ALT_INDEX . +.Sh FILES +.Bl -tag -width ".Pa /dev/ugen Ns Ar N Ns Pa \&. Ns Ar E" -compact +.It Pa /dev/ugen Ns Ar N Ns Pa \&. Ns Ar E +Endpoint +.Ar E +of device +.Ar 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. |
