1.\" $NetBSD: ugen.4,v 1.15 2002/02/13 08:17:50 ross 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.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 only be in. 97To perform input from an interrupt endpoint 98.Xr read 2 99should be used. A moderate amount of buffering is done 100by the driver. 101.Pp 102All endpoints handle the following 103.Xr ioctl 2 104calls: 105.Pp 106.Bl -tag -width indent -compact 107.It Dv USB_SET_SHORT_XFER (int) 108Allow short read transfer. Normally a transfer from the device 109which is shorter than the request specified is reported as an 110error. 111.It Dv USB_SET_TIMEOUT (int) 112Set the timeout on the device operations, the time is specified 113in milliseconds. The value 0 is used to indicate that there is 114no timeout. 115.El 116.Pp 117The control endpoint (endpoint 0) handles the following 118.Xr ioctl 2 119calls: 120.Pp 121.Bl -tag -width indent -compact 122.It Dv USB_GET_CONFIG (int) 123Get the device configuration number. 124.It Dv USB_SET_CONFIG (int) 125Set the device into the given configuration number. 126.br 127This operation can only be performed when the control endpoint 128is the sole open endpoint. 129.It Dv USB_GET_ALTINTERFACE (struct usb_alt_interface) 130Get the alternative setting number for the interface with the given 131index. 132The 133.Dv config_index 134is ignored in this call. 135.Bd -literal 136struct usb_alt_interface { 137 int config_index; 138 int interface_index; 139 int alt_no; 140}; 141.Ed 142.It Dv USB_SET_ALTINTERFACE (struct usb_alt_interface) 143Set the alternative setting to the given number in the interface with the 144given index. 145The 146.Dv config_index 147is ignored in this call. 148.br 149This operation can only be performed when no endpoints for the interface 150are open. 151.It Dv USB_GET_NO_ALT (struct usb_alt_interface) 152Return the number of different alternate settings in the 153.Dv alt_no 154field. 155.It Dv USB_GET_DEVICE_DESC (usb_device_descriptor_t) 156Return the device descriptor. 157.It Dv USB_GET_CONFIG_DESC (struct usb_config_desc) 158Return the descriptor for the configuration with the given index. 159For convenience the current configuration can be specified by 160.Dv USB_CURRENT_CONFIG_INDEX . 161.Bd -literal 162struct usb_config_desc { 163 int config_index; 164 usb_config_descriptor_t desc; 165}; 166.Ed 167.It Dv USB_GET_INTERFACE_DESC (struct usb_interface_desc) 168Return the interface descriptor for an interface specified by its 169configuration index, interface index, and alternative index. 170For convenience the current alternative can be specified by 171.Dv USB_CURRENT_ALT_INDEX . 172.Bd -literal 173struct usb_interface_desc { 174 int config_index; 175 int interface_index; 176 int alt_index; 177 usb_interface_descriptor_t desc; 178}; 179.Ed 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.It Dv USB_GET_FULL_DESC (struct usb_full_desc) 194Return all the descriptors for the given configuration. 195.Bd -literal 196struct usb_full_desc { 197 int config_index; 198 u_int size; 199 u_char *data; 200}; 201.Ed 202The 203.Dv data 204field should point to a memory area of of the size given in the 205.Dv size 206field. The proper size can be determined by first issuing a 207.Dv USB_GET_CONFIG_DESC 208and inspecting the 209.Dv wTotalLength 210field. 211.It Dv USB_GET_STRING_DESC (struct usb_string_desc) 212Get a string descriptor for the given language id and 213string index. 214.Bd -literal 215struct usb_string_desc { 216 int string_index; 217 int language_id; 218 usb_string_descriptor_t desc; 219}; 220.Ed 221.It Dv USB_DO_REQUEST 222Send a USB request to the device on the control endpoint. 223Any data sent to/from the device is located at 224.Dv data . 225The size of the transferred data is determined from the 226.Dv request . 227The 228.Dv addr 229field is ignored in this call. 230The 231.Dv flags 232field can be used to flag that the request is allowed to 233be shorter than the requested size, and the 234.Dv actlen 235will contain the actual size on completion. 236.Bd -literal 237struct usb_ctl_request { 238 int addr; 239 usb_device_request_t request; 240 void *data; 241 int flags; 242#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ 243 int actlen; /* actual length transferred */ 244}; 245.Ed 246This is a dangerous operation in that it can perform arbitrary operations 247on the device. Some of the most dangerous (e.g., changing the device 248address) are not allowed. 249.It Dv USB_GET_DEVICEINFO (struct usb_device_info) 250Get an information summary for the device. This call will not 251issue any USB transactions. 252.El 253.Pp 254Note that there are two different ways of addressing configurations, interfaces, 255alternatives, and endpoints: by index or by number. 256The index is the ordinal number (starting from 0) of the descriptor 257as presented by the device. The number is the respective number of 258the entity as found in its descriptor. Enumeration of descriptors 259use the index, getting and setting typically uses numbers. 260.Pp 261Example: 262All endpoints (except the control endpoint) for the current configuration 263can be found by iterating the 264.Dv interface_index 265from 0 to 266.Dv config_desc-\*[Gt]bNumInterface-1 267and for each of these iterating the 268.Dv endpoint_index 269from 0 to 270.Dv interface_desc-\*[Gt]bNumEndpoints . 271The 272.Dv config_index 273should set to 274.Dv USB_CURRENT_CONFIG_INDEX 275and 276.Dv alt_index 277should be set to 278.Dv USB_CURRENT_ALT_INDEX . 279.Sh FILES 280.Bl -tag -width Pa 281.It Pa /dev/ugenN.EE 282Endpoint 283.Pa EE 284of device 285.Pa N . 286.El 287.Sh SEE ALSO 288.Xr usb 4 289.Sh HISTORY 290The 291.Nm 292driver 293appeared in 294.Nx 1.4 . 295.\" .Sh BUGS 296.\" The driver is not yet finished; there is no access to isochronous endpoints. 297