share/man/man4/ugen.4

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