1.\" $NetBSD: ugen.4,v 1.13 2001/09/11 22:52:54 wiz Exp $ 2.\" 3.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Lennart Augustsson. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" $FreeBSD$ 38.\" 39.Dd July 12, 1998 40.Dt UGEN 4 41.Os 42.Sh NAME 43.Nm ugen 44.Nd USB generic device support 45.Sh SYNOPSIS 46.Cd "device ugen" 47.Sh DESCRIPTION 48The 49.Nm 50driver provides support for all USB devices that do not have 51a special driver. 52It supports access to all parts of the device, 53but not in a way that is as convenient as a special purpose driver. 54.Pp 55There can be up to 127 USB devices connected to a USB bus. 56Each USB device can have up to 16 endpoints. 57Each of these endpoints 58will communicate in one of four different modes: control, isochronous, 59bulk, or interrupt. 60Each of the endpoints will have a different 61device node. 62The four least significant bits in the minor device 63number determines which endpoint the device accesses and the rest 64of the bits determines which USB device. 65.Pp 66If an endpoint address is used both for input and output the device 67can be opened for both read or write. 68.Pp 69To find out what endpoints that exist there are a series of 70.Xr ioctl 2 71operation on the control endpoint that returns the USB descriptors 72of the device, configurations, interfaces, and endpoints. 73.Pp 74The control transfer mode can only happen on the control endpoint 75which is always endpoint 0. 76The control endpoint accepts request 77and may respond with an answer to such request. 78Control request 79are issued by 80.Xr ioctl 2 81calls. 82.\" .Pp 83.\" The isochronous transfer mode can be in or out depending on the 84.\" endpoint. 85.\" To perform I/O on an isochronous endpoint 86.\" .Xr read 2 87.\" and 88.\" .Xr write 2 89.\" should be used. 90.\" Before any I/O operations can take place the transfer rate in 91.\" bytes/second has to be set. 92.\" This is done with 93.\" .Xr ioctl 2 94.\" .Dv USB_SET_ISO_RATE . 95.\" Performing this call sets up a buffer corresponding to 96.\" about 1 second of data. 97.Pp 98The bulk transfer mode can be in or out depending on the 99endpoint. 100To perform I/O on a bulk endpoint 101.Xr read 2 102and 103.Xr write 2 104should be used. 105All I/O operations on a bulk endpoint are unbuffered. 106.Pp 107The interrupt transfer mode can only be in. 108To perform input from an interrupt endpoint 109.Xr read 2 110should be used. 111A moderate amount of buffering is done 112by the driver. 113.Pp 114All endpoints handle the following 115.Xr ioctl 2 116calls: 117.Bl -tag -width indent 118.It Dv USB_SET_SHORT_XFER Pq Vt int 119Allow short read transfer. 120Normally a transfer from the device 121which is shorter than the request specified is reported as an 122error. 123.It Dv USB_SET_TIMEOUT Pq Vt int 124Set the timeout on the device operations, the time is specified 125in milliseconds. 126The value 0 is used to indicate that there is 127no timeout. 128.El 129.Pp 130The control endpoint (endpoint 0) handles the following 131.Xr ioctl 2 132calls: 133.Bl -tag -width indent 134.It Dv USB_GET_CONFIG Pq Vt int 135Get the device configuration number. 136.It Dv USB_SET_CONFIG Pq Vt int 137Set the device into the given configuration number. 138.Pp 139This operation can only be performed when the control endpoint 140is the sole open endpoint. 141.It Dv USB_GET_ALTINTERFACE Pq Vt "struct usb_alt_interface" 142Get the alternative setting number for the interface with the given 143index. 144The 145.Va config_index 146is ignored in this call. 147.Bd -literal 148struct usb_alt_interface { 149 int config_index; 150 int interface_index; 151 int alt_no; 152}; 153.Ed 154.It Dv USB_SET_ALTINTERFACE Pq Vt "struct usb_alt_interface" 155Set the alternative setting to the given number in the interface with the 156given index. 157The 158.Va config_index 159is ignored in this call. 160.Pp 161This operation can only be performed when no endpoints for the interface 162are open. 163.It Dv USB_GET_NO_ALT Pq Vt "struct usb_alt_interface" 164Return the number of different alternate settings in the 165.Va alt_no 166field. 167.It Dv USB_GET_DEVICE_DESC Pq Vt usb_device_descriptor_t 168Return the device descriptor. 169.It Dv USB_GET_CONFIG_DESC Pq Vt "struct usb_config_desc" 170Return the descriptor for the configuration with the given index. 171For convenience the current configuration can be specified by 172.Dv USB_CURRENT_CONFIG_INDEX . 173.Bd -literal 174struct usb_config_desc { 175 int config_index; 176 usb_config_descriptor_t desc; 177}; 178.Ed 179.It Dv USB_GET_INTERFACE_DESC Pq Vt "struct usb_interface_desc" 180Return the interface descriptor for an interface specified by its 181configuration index, interface index, and alternative index. 182For convenience the current alternative can be specified by 183.Dv USB_CURRENT_ALT_INDEX . 184.Bd -literal 185struct usb_interface_desc { 186 int config_index; 187 int interface_index; 188 int alt_index; 189 usb_interface_descriptor_t desc; 190}; 191.Ed 192.It Dv USB_GET_ENDPOINT_DESC Pq Vt "struct usb_endpoint_desc" 193Return the endpoint descriptor for the endpoint specified by its 194configuration index, interface index, alternative index, and 195endpoint index. 196.Bd -literal 197struct usb_endpoint_desc { 198 int config_index; 199 int interface_index; 200 int alt_index; 201 int endpoint_index; 202 usb_endpoint_descriptor_t desc; 203}; 204.Ed 205.It Dv USB_GET_FULL_DESC Pq Vt "struct usb_full_desc" 206Return all the descriptors for the given configuration. 207.Bd -literal 208struct usb_full_desc { 209 int config_index; 210 u_int size; 211 u_char *data; 212}; 213.Ed 214The 215.Va data 216field should point to a memory area of the size given in the 217.Va size 218field. 219The proper size can be determined by first issuing a 220.Dv USB_GET_CONFIG_DESC 221and inspecting the 222.Va wTotalLength 223field. 224.It Dv USB_GET_STRING_DESC Pq Vt "struct usb_string_desc" 225Get a string descriptor for the given language ID and 226string index. 227.Bd -literal 228struct usb_string_desc { 229 int string_index; 230 int language_id; 231 usb_string_descriptor_t desc; 232}; 233.Ed 234.It Dv USB_DO_REQUEST Pq Vt "struct usb_ctl_request" 235Send a USB request to the device on the control endpoint. 236Any data sent to/from the device is located at 237.Va data . 238The size of the transferred data is determined from the 239.Va request . 240The 241.Va addr 242field is ignored in this call. 243The 244.Va flags 245field can be used to flag that the request is allowed to 246be shorter than the requested size, and the 247.Va actlen 248will contain the actual size on completion. 249.Bd -literal 250struct usb_ctl_request { 251 int addr; 252 usb_device_request_t request; 253 void *data; 254 int flags; 255#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ 256 int actlen; /* actual length transferred */ 257}; 258.Ed 259This is a dangerous operation in that it can perform arbitrary operations 260on the device. 261Some of the most dangerous (e.g., changing the device 262address) are not allowed. 263.It Dv USB_GET_DEVICEINFO Pq Vt "struct usb_device_info" 264Get an information summary for the device. 265This call will not 266issue any USB transactions. 267.El 268.Pp 269Note that there are two different ways of addressing configurations, interfaces, 270alternatives, and endpoints: by index or by number. 271The index is the ordinal number (starting from 0) of the descriptor 272as presented by the device. 273The number is the respective number of 274the entity as found in its descriptor. 275Enumeration of descriptors 276use the index, getting and setting typically uses numbers. 277.Pp 278Example: 279all endpoints (except the control endpoint) for the current configuration 280can be found by iterating the 281.Va interface_index 282from 0 to 283.Va config_desc->bNumInterface Ns \-1 284and for each of these iterating the 285.Va endpoint_index 286from 0 to 287.Va interface_desc->bNumEndpoints . 288The 289.Va config_index 290should set to 291.Dv USB_CURRENT_CONFIG_INDEX 292and 293.Va alt_index 294should be set to 295.Dv USB_CURRENT_ALT_INDEX . 296.Sh FILES 297.Bl -tag -width ".Pa /dev/ugen Ns Ar N Ns Pa \&. Ns Ar EE" -compact 298.It Pa /dev/ugen Ns Ar N Ns Pa \&. Ns Ar EE 299Endpoint 300.Ar EE 301of device 302.Ar N . 303.El 304.Sh SEE ALSO 305.Xr usb 4 306.Sh HISTORY 307The 308.Nm 309driver 310appeared in 311.Nx 1.4 . 312.\" .Sh BUGS 313.\" The driver is not yet finished; there is no access to isochronous endpoints. 314