1.\" $NetBSD: ugen.4,v 1.12 2000/09/08 01:11:15 augustss 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.Dd July 12, 1998 38.Dt UGEN 4 39.Os 40.Sh NAME 41.Nm ugen 42.Nd USB generic device support 43.Sh SYNOPSIS 44.Cd "ugen* at uhub?" 45.Pp 46.Sh DESCRIPTION 47The 48.Nm 49driver provides support for all USB devices that do not have 50a special driver. It supports access to all parts of the device, 51but not in a way that is as convenient as a special purpose driver. 52.Pp 53There can be up to 127 USB devices connected to a USB bus. 54Each USB device can have up to 16 endpoints. Each of these endpoints 55will communicate in one of four different modes: control, isochronous, 56bulk, or interrupt. Each of the endpoints will have a different 57device node. The four least significant bits in the minor device 58number determines which endpoint the device accesses and the rest 59of the bits determines which USB device. 60.Pp 61If an endpoint address is used both for input and output the device 62can be opened for both read or write. 63.Pp 64To find out what endpoints that exist there are a series of 65.Xr ioctl 2 66operation on the control endpoint that returns the USB descriptors 67of the device, configurations, interfaces, and endpoints. 68.Pp 69The control transfer mode can only happen on the control endpoint 70which is always endpoint 0. The control endpoint accepts request 71and may respond with an answer to such request. Control request 72are issued by 73.Xr ioctl 2 74calls. 75.\" .Pp 76.\" The isochronous transfer mode can be in or out depending on the 77.\" endpoint. To perform IO on an isochronous endpoint 78.\" .Xr read 2 79.\" and 80.\" .Xr write 2 81.\" should be used. 82.\" Before any IO operations can take place the transfer rate in 83.\" bytes/second has to be set. This is done with 84.\" .Xr ioctl 2 85.\" .Dv USB_SET_ISO_RATE . 86.\" Performing this call sets up a buffer corresponding to 87.\" about 1 second of data. 88.Pp 89The bulk transfer mode can be in or out depending on the 90endpoint. To perform IO on a bulk endpoint 91.Xr read 2 92and 93.Xr write 2 94should be used. 95All IO operations on a bulk endpoint are unbuffered. 96.Pp 97The interrupt transfer mode can only be in. 98To perform input from an interrupt endpoint 99.Xr read 2 100should be used. A moderate amount of buffering is done 101by the driver. 102.Pp 103All endpoints handle the following 104.Xr ioctl 2 105calls: 106.Pp 107.Bl -tag -width indent -compact 108.It Dv USB_SET_SHORT_XFER (int) 109Allow short read transfer. Normally a transfer from the device 110which is shorter than the request specified is reported as an 111error. 112.It Dv USB_SET_TIMEOUT (int) 113Set the timeout on the device operations, the time is specified 114in milliseconds. The value 0 is used to indicate that there is 115no timeout. 116.El 117.Pp 118The control endpoint (endpoint 0) handles the following 119.Xr ioctl 2 120calls: 121.Pp 122.Bl -tag -width indent -compact 123.It Dv USB_GET_CONFIG (int) 124Get the device configuration number. 125.It Dv USB_SET_CONFIG (int) 126Set the device into the given configuration number. 127.br 128This operation can only be performed when the control endpoint 129is the sole open endpoint. 130.It Dv USB_GET_ALTINTERFACE (struct usb_alt_interface) 131Get the alternative setting number for the interface with the given 132index. 133The 134.Dv config_index 135is ignored in this call. 136.Bd -literal 137struct usb_alt_interface { 138 int config_index; 139 int interface_index; 140 int alt_no; 141}; 142.Ed 143.It Dv USB_SET_ALTINTERFACE (struct usb_alt_interface) 144Set the alternative setting to the given number in the interface with the 145given index. 146The 147.Dv config_index 148is ignored in this call. 149.br 150This operation can only be performed when no endpoints for the interface 151are open. 152.It Dv USB_GET_NO_ALT (struct usb_alt_interface) 153Return the number of different alternate settings in the 154.Dv alt_no 155field. 156.It Dv USB_GET_DEVICE_DESC (usb_device_descriptor_t) 157Return the device descriptor. 158.It Dv USB_GET_CONFIG_DESC (struct usb_config_desc) 159Return the descriptor for the configuration with the given index. 160For convenience the current configuration can be specified by 161.Dv USB_CURRENT_CONFIG_INDEX . 162.Bd -literal 163struct usb_config_desc { 164 int config_index; 165 usb_config_descriptor_t desc; 166}; 167.Ed 168.It Dv USB_GET_INTERFACE_DESC (struct usb_interface_desc) 169Return the interface descriptor for an interface specified by its 170configuration index, interface index, and alternative index. 171For convenience the current alternative can be specified by 172.Dv USB_CURRENT_ALT_INDEX . 173.Bd -literal 174struct usb_interface_desc { 175 int config_index; 176 int interface_index; 177 int alt_index; 178 usb_interface_descriptor_t desc; 179}; 180.Ed 181.It Dv USB_GET_ENDPOINT_DESC (struct usb_endpoint_desc) 182Return the endpoint descriptor for the endpoint specified by its 183configuration index, interface index, alternative index, and 184endpoint index. 185.Bd -literal 186struct usb_endpoint_desc { 187 int config_index; 188 int interface_index; 189 int alt_index; 190 int endpoint_index; 191 usb_endpoint_descriptor_t desc; 192}; 193.Ed 194.It Dv USB_GET_FULL_DESC (struct usb_full_desc) 195Return all the descriptors for the given configuration. 196.Bd -literal 197struct usb_full_desc { 198 int config_index; 199 u_int size; 200 u_char *data; 201}; 202.Ed 203The 204.Dv data 205field should point to a memory area of of the size given in the 206.Dv size 207field. The proper size can be determined by first issuing a 208.Dv USB_GET_CONFIG_DESC 209and inspecting the 210.Dv wTotalLength 211field. 212.It Dv USB_GET_STRING_DESC (struct usb_string_desc) 213Get a string descriptor for the given language id and 214string index. 215.Bd -literal 216struct usb_string_desc { 217 int string_index; 218 int language_id; 219 usb_string_descriptor_t desc; 220}; 221.Ed 222.It Dv USB_DO_REQUEST 223Send a USB request to the device on the control endpoint. 224Any data sent to/from the device is located at 225.Dv data . 226The size of the transferred data is determined from the 227.Dv request . 228The 229.Dv addr 230field is ignored in this call. 231The 232.Dv flags 233field can be used to flag that the request is allowed to 234be shorter than the requested size, and the 235.Dv actlen 236will contain the actual size on completion. 237.Bd -literal 238struct usb_ctl_request { 239 int addr; 240 usb_device_request_t request; 241 void *data; 242 int flags; 243#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ 244 int actlen; /* actual length transferred */ 245}; 246.Ed 247This is a dangerous operation in that it can perform arbitrary operations 248on the device. Some of the most dangerous (e.g., changing the device 249address) are not allowed. 250.It Dv USB_GET_DEVICEINFO (struct usb_device_info) 251Get an information summary for the device. This call will not 252issue any USB transactions. 253.El 254.Pp 255Note that there are two different ways of addressing configurations, interfaces, 256alternatives, and endpoints: by index or by number. 257The index is the ordinal number (starting from 0) of the descriptor 258as presented by the device. The number is the respective number of 259the entity as found in its descriptor. Enumeration of descriptors 260use the index, getting and setting typically uses numbers. 261.Pp 262Example: 263All endpoints (except the control endpoint) for the current configuration 264can be found by iterating the 265.Dv interface_index 266from 0 to 267.Dv config_desc->bNumInterface-1 268and for each of these iterating the 269.Dv endpoint_index 270from 0 to 271.Dv interface_desc->bNumEndpoints . 272The 273.Dv config_index 274should set to 275.Dv USB_CURRENT_CONFIG_INDEX 276and 277.Dv alt_index 278should be set to 279.Dv USB_CURRENT_ALT_INDEX . 280.Sh FILES 281.Bl -tag -width Pa 282.It Pa /dev/ugenN.EE 283Endpoint 284.Pa EE 285of device 286.Pa N . 287.El 288.Sh SEE ALSO 289.Xr usb 4 290.Sh HISTORY 291The 292.Nm 293driver 294appeared in 295.Nx 1.4 . 296.\" .Sh BUGS 297.\" The driver is not yet finished; there is no access to isochronous endpoints. 298