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