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