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