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