share/man/man9/usbdi.9

   1 .\"
   2 .\" Copyright (c) 2005 Ian Dowse <iedowse@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\"     $FreeBSD$
  27 .Dd December 30, 2005
  28 .Os
  29 .Dt USBDI 9
  30 .Sh NAME
  31 .Nm usb_detach_wait ,
  32 .Nm usb_detach_wakeup ,
  33 .Nm usb_find_desc ,
  34 .Nm usbd_abort_default_pipe ,
  35 .Nm usbd_abort_pipe ,
  36 .Nm usbd_alloc_buffer ,
  37 .Nm usbd_alloc_xfer ,
  38 .Nm usbd_bulk_transfer ,
  39 .Nm usbd_clear_endpoint_stall ,
  40 .Nm usbd_clear_endpoint_stall_async ,
  41 .Nm usbd_clear_endpoint_toggle ,
  42 .Nm usbd_close_pipe ,
  43 .Nm usbd_device2interface_handle ,
  44 .Nm usbd_devinfo ,
  45 .Nm usbd_do_request ,
  46 .Nm usbd_do_request_async ,
  47 .Nm usbd_do_request_flags ,
  48 .Nm usbd_do_request_flags_pipe ,
  49 .Nm usbd_dopoll ,
  50 .Nm usbd_endpoint_count ,
  51 .Nm usbd_errstr ,
  52 .Nm usbd_fill_deviceinfo ,
  53 .Nm usbd_find_edesc ,
  54 .Nm usbd_find_idesc ,
  55 .Nm usbd_free_buffer ,
  56 .Nm usbd_free_xfer ,
  57 .Nm usbd_get_buffer ,
  58 .Nm usbd_get_config ,
  59 .Nm usbd_get_config_desc ,
  60 .Nm usbd_get_config_desc_full ,
  61 .Nm usbd_get_config_descriptor ,
  62 .Nm usbd_get_device_descriptor ,
  63 .Nm usbd_get_endpoint_descriptor ,
  64 .Nm usbd_get_interface_altindex ,
  65 .Nm usbd_get_interface_descriptor ,
  66 .Nm usbd_get_no_alts ,
  67 .Nm usbd_get_quirks ,
  68 .Nm usbd_get_speed ,
  69 .Nm usbd_get_string ,
  70 .Nm usbd_get_string_desc ,
  71 .Nm usbd_get_xfer_status ,
  72 .Nm usbd_interface2device_handle ,
  73 .Nm usbd_interface2endpoint_descriptor ,
  74 .Nm usbd_interface_count ,
  75 .Nm usbd_intr_transfer ,
  76 .Nm usbd_open_pipe ,
  77 .Nm usbd_open_pipe_intr ,
  78 .Nm usbd_pipe2device_handle ,
  79 .Nm usbd_ratecheck ,
  80 .Nm usbd_set_config_index ,
  81 .Nm usbd_set_config_no ,
  82 .Nm usbd_set_interface ,
  83 .Nm usbd_set_polling ,
  84 .Nm usbd_setup_default_xfer ,
  85 .Nm usbd_setup_isoc_xfer ,
  86 .Nm usbd_setup_xfer ,
  87 .Nm usbd_sync_transfer ,
  88 .Nm usbd_transfer
  89 .Nd Universal Serial Bus driver programming interface
  90 .Sh SYNOPSIS
  91 .In dev/usb/usb.h
  92 .In dev/usb/usbdi.h
  93 .In dev/usb/usbdi_util.h
  94 .Pp
  95 .Ft void
  96 .Fn usb_detach_wait "device_ptr_t dv"
  97 .Ft void
  98 .Fn usb_detach_wakeup "device_ptr_t dv"
  99 .Ft "const usb_descriptor_t *"
 100 .Fn usb_find_desc "usbd_device_handle dev" "int type" "int subtype"
 101 .Ft usbd_status
 102 .Fn usbd_abort_default_pipe "usbd_device_handle dev"
 103 .Ft usbd_status
 104 .Fn usbd_abort_pipe "usbd_pipe_handle pipe"
 105 .Ft "void *"
 106 .Fn usbd_alloc_buffer "usbd_xfer_handle xfer" "u_int32_t size"
 107 .Ft usbd_xfer_handle
 108 .Fn usbd_alloc_xfer "usbd_device_handle dev"
 109 .Ft usbd_status
 110 .Fo usbd_bulk_transfer
 111 .Fa "usbd_xfer_handle xfer"
 112 .Fa "usbd_pipe_handle pipe"
 113 .Fa "u_int16_t flags"
 114 .Fa "u_int32_t timeout"
 115 .Fa "void *buf"
 116 .Fa "u_int32_t *size"
 117 .Fa "char *lbl"
 118 .Fc
 119 .Ft usbd_status
 120 .Fn usbd_clear_endpoint_stall "usbd_pipe_handle pipe"
 121 .Ft usbd_status
 122 .Fn usbd_clear_endpoint_stall_async "usbd_pipe_handle"
 123 .Ft void
 124 .Fn usbd_clear_endpoint_toggle "usbd_pipe_handle pipe"
 125 .Ft usbd_status
 126 .Fn usbd_close_pipe "usbd_pipe_handle pipe"
 127 .Ft usbd_status
 128 .Fo usbd_device2interface_handle
 129 .Fa "usbd_device_handle dev"
 130 .Fa "u_int8_t ifaceno"
 131 .Fa "usbd_interface_handle *iface"
 132 .Fc
 133 .Ft void
 134 .Fn usbd_devinfo "usbd_device_handle dev" "int showclass" "char *cp"
 135 .Ft usbd_status
 136 .Fo usbd_do_request
 137 .Fa "usbd_device_handle dev"
 138 .Fa "usb_device_request_t *req"
 139 .Fa "void *data"
 140 .Fc
 141 .Ft usbd_status
 142 .Fo usbd_do_request_async
 143 .Fa "usbd_device_handle dev"
 144 .Fa "usb_device_request_t *req"
 145 .Fa "void *data"
 146 .Fc
 147 .Ft usbd_status
 148 .Fo usbd_do_request_flags
 149 .Fa "usbd_device_handle dev"
 150 .Fa "usb_device_request_t *req"
 151 .Fa "void *data"
 152 .Fa "u_int16_t flags"
 153 .Fa "int *actlen"
 154 .Fa "u_int32_t timo"
 155 .Fc
 156 .Ft usbd_status
 157 .Fo usbd_do_request_flags_pipe
 158 .Fa "usbd_device_handle dev"
 159 .Fa "usbd_pipe_handle pipe"
 160 .Fa "usb_device_request_t *req"
 161 .Fa "void *data"
 162 .Fa "u_int16_t flags"
 163 .Fa "int *actlen"
 164 .Fa "u_int32_t timeout"
 165 .Fc
 166 .Ft void
 167 .Fn usbd_dopoll "usbd_interface_handle iface"
 168 .Ft usbd_status
 169 .Fn usbd_endpoint_count "usbd_interface_handle iface" "u_int8_t *count"
 170 .Ft "const char *"
 171 .Fn usbd_errstr "usbd_status err"
 172 .Ft void
 173 .Fo usbd_fill_deviceinfo
 174 .Fa "usbd_device_handle dev"
 175 .Fa "struct usb_device_info *di"
 176 .Fa "int usedev"
 177 .Fc
 178 .Ft "usb_endpoint_descriptor_t *"
 179 .Fo usbd_find_edesc
 180 .Fa "usb_config_descriptor_t *cd"
 181 .Fa "int ifaceidx"
 182 .Fa "int altidx"
 183 .Fa "int endptidx"
 184 .Fc
 185 .Ft "usb_interface_descriptor_t *"
 186 .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx"
 187 .Ft void
 188 .Fn usbd_free_buffer "usbd_xfer_handle xfer"
 189 .Ft usbd_status
 190 .Fn usbd_free_xfer "usbd_xfer_handle xfer"
 191 .Ft "void *"
 192 .Fn usbd_get_buffer "usbd_xfer_handle xfer"
 193 .Ft usbd_status
 194 .Fn usbd_get_config "usbd_device_handle dev" "u_int8_t *conf"
 195 .Ft usbd_status
 196 .Fo usbd_get_config_desc
 197 .Fa "usbd_device_handle dev"
 198 .Fa "int confidx"
 199 .Fa "usb_config_descriptor_t *d"
 200 .Fc
 201 .Ft usbd_status
 202 .Fo usbd_get_config_desc_full
 203 .Fa "usbd_device_handle dev"
 204 .Fa "int conf"
 205 .Fa "void *d"
 206 .Fa "int size"
 207 .Fc
 208 .Ft "usb_config_descriptor_t *"
 209 .Fn usbd_get_config_descriptor "usbd_device_handle dev"
 210 .Ft "usb_device_descriptor_t *"
 211 .Fn usbd_get_device_descriptor "usbd_device_handle dev"
 212 .Ft "usb_endpoint_descriptor_t *"
 213 .Fo usbd_get_endpoint_descriptor
 214 .Fa "usbd_interface_handle iface"
 215 .Fa "u_int8_t address"
 216 .Fc
 217 .Ft int
 218 .Fn usbd_get_interface_altindex "usbd_interface_handle iface"
 219 .Ft "usb_interface_descriptor_t *"
 220 .Fn usbd_get_interface_descriptor "usbd_interface_handle iface"
 221 .Ft int
 222 .Fn usbd_get_no_alts "usb_config_descriptor_t *cdesc" "int ifaceno"
 223 .Ft "const struct usbd_quirks *"
 224 .Fn usbd_get_quirks "usbd_device_handle dev"
 225 .Ft int
 226 .Fn usbd_get_speed "usbd_device_handle dev"
 227 .Ft usbd_status
 228 .Fn usbd_get_string "usbd_device_handle dev" "int si" "char *buf"
 229 .Ft usbd_status
 230 .Fo usbd_get_string_desc
 231 .Fa "usbd_device_handle dev"
 232 .Fa "int sindex"
 233 .Fa "int langid"
 234 .Fa "usb_string_descriptor_t *sdesc"
 235 .Fa "int *sizep"
 236 .Fc
 237 .Ft void
 238 .Fo usbd_get_xfer_status
 239 .Fa "usbd_xfer_handle xfer"
 240 .Fa "usbd_private_handle *priv"
 241 .Fa "void **buffer"
 242 .Fa "u_int32_t *count"
 243 .Fa "usbd_status *status"
 244 .Fc
 245 .Ft void
 246 .Fo usbd_interface2device_handle
 247 .Fa "usbd_interface_handle iface"
 248 .Fa "usbd_device_handle *dev"
 249 .Fc
 250 .Ft "usb_endpoint_descriptor_t *"
 251 .Fo usbd_interface2endpoint_descriptor
 252 .Fa "usbd_interface_handle iface"
 253 .Fa "u_int8_t index"
 254 .Fc
 255 .Ft usbd_status
 256 .Fn usbd_interface_count "usbd_device_handle dev" "u_int8_t *count"
 257 .Ft usbd_status
 258 .Fo usbd_intr_transfer
 259 .Fa "usbd_xfer_handle xfer"
 260 .Fa "usbd_pipe_handle pipe"
 261 .Fa "u_int16_t flags"
 262 .Fa "u_int32_t timeout"
 263 .Fa "void *buf"
 264 .Fa "u_int32_t *size"
 265 .Fa "char *lbl"
 266 .Fc
 267 .Ft usbd_status
 268 .Fo usbd_open_pipe
 269 .Fa "usbd_interface_handle iface"
 270 .Fa "u_int8_t address"
 271 .Fa "u_int8_t flags"
 272 .Fa "usbd_pipe_handle *pipe"
 273 .Fc
 274 .Ft usbd_status
 275 .Fo usbd_open_pipe_intr
 276 .Fa "usbd_interface_handle iface"
 277 .Fa "u_int8_t address"
 278 .Fa "u_int8_t flags"
 279 .Fa "usbd_pipe_handle *pipe"
 280 .Fa "usbd_private_handle priv"
 281 .Fa "void *buffer"
 282 .Fa "u_int32_t len"
 283 .Fa "usbd_callback cb"
 284 .Fa "int ival"
 285 .Fc
 286 .Ft usbd_device_handle
 287 .Fn usbd_pipe2device_handle "usbd_pipe_handle pipe"
 288 .Ft int
 289 .Fn usbd_ratecheck "struct timeval *last"
 290 .Ft usbd_status
 291 .Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg"
 292 .Ft usbd_status
 293 .Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg"
 294 .Ft usbd_status
 295 .Fn usbd_set_interface "usbd_interface_handle iface" "int altidx"
 296 .Ft void
 297 .Fn usbd_set_polling "usbd_device_handle dev" "int on"
 298 .Ft void
 299 .Fo usbd_setup_default_xfer
 300 .Fa "usbd_xfer_handle xfer"
 301 .Fa "usbd_device_handle dev"
 302 .Fa "usbd_private_handle priv"
 303 .Fa "u_int32_t timeout"
 304 .Fa "usb_device_request_t *req"
 305 .Fa "void *buffer"
 306 .Fa "u_int32_t length"
 307 .Fa "u_int16_t flags"
 308 .Fa "usbd_callback callback"
 309 .Fc
 310 .Ft void
 311 .Fo usbd_setup_isoc_xfer
 312 .Fa "usbd_xfer_handle xfer"
 313 .Fa "usbd_pipe_handle pipe"
 314 .Fa "usbd_private_handle priv"
 315 .Fa "u_int16_t *frlengths"
 316 .Fa "u_int32_t nframes"
 317 .Fa "u_int16_t flags"
 318 .Fa "usbd_callback callback"
 319 .Fc
 320 .Ft void
 321 .Fo usbd_setup_xfer
 322 .Fa "usbd_xfer_handle xfer"
 323 .Fa "usbd_pipe_handle pipe"
 324 .Fa "usbd_private_handle priv"
 325 .Fa "void *buffer"
 326 .Fa "u_int32_t length"
 327 .Fa "u_int16_t flags"
 328 .Fa "u_int32_t timeout"
 329 .Fa "usbd_callback callback"
 330 .Fc
 331 .Ft usbd_status
 332 .Fn usbd_sync_transfer "usbd_xfer_handle xfer"
 333 .Ft usbd_status
 334 .Fn usbd_transfer "usbd_xfer_handle xfer"
 335 .Sh DESCRIPTION
 336 The Universal Serial Bus (USB) driver programming interface provides
 337 USB peripheral drivers with a host controller independent API for
 338 controlling and communicating with USB peripherals.
 339 .Pp
 340 Typically, drivers will first use some combination of the functions
 341 .Fn usbd_set_config_no ,
 342 .Fn usbd_get_config_descriptor ,
 343 .Fn usbd_set_interface ,
 344 .Fn usbd_get_interface_descriptor ,
 345 .Fn usbd_device2interface_handle ,
 346 .Fn usbd_endpoint_count
 347 and
 348 .Fn usbd_interface2endpoint_descriptor
 349 to query the device's properties and prepare it for use.
 350 Drivers can then perform requests on the USB control pipe using
 351 .Fn usbd_do_request ,
 352 they can open pipes using the functions
 353 .Fn usbd_open_pipe
 354 and
 355 .Fn usbd_open_pipe_intr ,
 356 and perform transfers over these pipes using
 357 .Fn usbd_alloc_xfer ,
 358 .Fn usbd_setup_xfer
 359 and
 360 .Fn usbd_transfer .
 361 Finally, the functions
 362 .Fn usbd_abort_pipe ,
 363 .Fn usbd_close_pipe
 364 and
 365 .Fn usbd_free_xfer
 366 are used to cancel outstanding transfers, close open pipes and deallocate
 367 transfer structures.
 368 .Pp
 369 The
 370 .Fn usbd_get_device_descriptor
 371 function returns a pointer to the USB device descriptor for
 372 .Fa dev .
 373 See
 374 .Sx "USB Descriptors"
 375 below for information about the USB device descriptor.
 376 .Pp
 377 The
 378 .Fn usbd_get_config_desc
 379 function retrieves the specified configuration descriptor from the device.
 380 The
 381 .Fa confidx
 382 parameter specifies the configuration descriptor index, which must be less
 383 than the
 384 .Fa bNumConfigurations
 385 value in the device descriptor.
 386 The function
 387 .Fn usbd_get_config_desc_full
 388 retrieves a full configuration descriptor, which has all related interface
 389 and endpoint descriptors appended to a normal configuration descriptor.
 390 The parameter
 391 .Fa d
 392 should point to memory that is at least
 393 .Fa size
 394 bytes in length, and this should be at least as long as the
 395 .Fa wTotalLength
 396 value from the configuration descriptor.
 397 See
 398 .Sx "USB Descriptors"
 399 below for information about the USB configuration descriptor.
 400 .Pp
 401 The
 402 .Fn usbd_get_config
 403 function retrieves the current configuration number from the device, i.e.\&
 404 the
 405 .Fa bConfigurationValue
 406 value from the configuration that is active.
 407 If the device is unconfigured then
 408 .Dv USB_UNCONFIG_NO
 409 is returned.
 410 The current configuration can be changed by calling either
 411 .Fn usbd_set_config_index
 412 or
 413 .Fn usbd_set_config_no .
 414 The difference between these functions is that
 415 .Fn usbd_set_config_index
 416 accepts a configuration index number that is less than the
 417 .Fa bNumConfigurations
 418 value from the device descriptor, whereas
 419 .Fn usbd_set_config_no
 420 requires the
 421 .Fa bConfigurationValue
 422 value of the desired configuration to be provided instead.
 423 To unconfigure the device, supply a configuration index of
 424 .Dv USB_UNCONFIG_INDEX
 425 to
 426 .Fn usbd_set_config_index ,
 427 or else specify a configuration number of
 428 .Dv USB_UNCONFIG_NO
 429 to
 430 .Fn usbd_set_config_no .
 431 .Pp
 432 The
 433 .Fn usbd_get_config_descriptor
 434 function returns a pointer to an in-memory copy of the full configuration
 435 descriptor of the configuration that is currently active.
 436 The returned pointer remains valid until the device configuration
 437 is changed using
 438 .Fn usbd_set_config_index
 439 or
 440 .Fn usbd_set_config_no .
 441 If the device is unconfigured then
 442 .Dv NULL
 443 is returned instead.
 444 .Pp
 445 The function
 446 .Fn usbd_interface_count
 447 returns the number of interfaces available in the current device
 448 configuration.
 449 The
 450 .Fn usbd_get_no_alts
 451 function determines the number of alternate interfaces in a full
 452 configuration descriptor by counting the interface descriptors with
 453 .Fa bInterfaceNumber
 454 equal to
 455 .Fa ifaceno
 456 (the count includes alternate index zero).
 457 The
 458 .Fn usbd_find_idesc
 459 function locates an interface descriptor within a full configuration
 460 descriptor.
 461 The
 462 .Fa ifaceidx
 463 parameter specifies the interface index number, which should be less than
 464 the number of interfaces in the configuration descriptor (i.e.\& the value
 465 returned by
 466 .Fn usbd_interface_count
 467 or the
 468 .Fa bNumInterface
 469 field from the configuration descriptor).
 470 An alternate interface can be specified using a non-zero
 471 .Fa altidx ,
 472 which should be less than the value returned by
 473 .Fn usbd_get_no_alts .
 474 The return value is a pointer to the requested interface descriptor
 475 within the full configuration descriptor, or
 476 .Dv NULL
 477 if the specified interface descriptor does not exist.
 478 Note that the
 479 .Fa altidx
 480 parameter specifies the alternate setting by index number starting
 481 at zero; it is not the alternate setting number defined in the
 482 interface descriptor.
 483 .Pp
 484 The function
 485 .Fn usbd_find_edesc
 486 locates an endpoint descriptor within a full configuration descriptor.
 487 The
 488 .Fa ifaceidx
 489 and
 490 .Fa altidx
 491 parameters are the same as described for
 492 .Fn usbd_find_idesc ,
 493 and the
 494 .Fa endptidx
 495 parameter is an endpoint index number that should be less than the
 496 .Fa bNumEndpoints
 497 field in the interface descriptor.
 498 The return value is a pointer to the requested endpoint descriptor
 499 within the full configuration descriptor, or
 500 .Dv NULL
 501 if the specified endpoint descriptor does not exist.
 502 Note that the
 503 .Fa altidx
 504 and
 505 .Fa endptidx
 506 parameters are index numbers starting at zero; they are not the
 507 alternate setting and endpoint address defined in the descriptors.
 508 .Pp
 509 The
 510 .Fn usbd_get_speed
 511 function returns the device speed.
 512 This can be
 513 .Dv USB_SPEED_LOW ,
 514 .Dv USB_SPEED_FULL
 515 or
 516 .Dv USB_SPEED_HIGH .
 517 .Pp
 518 USB devices optionally support string descriptors, which can be
 519 retrieved using the
 520 .Fn usbd_get_string
 521 or
 522 .Fn usbd_get_string_desc
 523 functions.
 524 Device, configuration and interface descriptors reference strings by
 525 an index number that can be supplied to these functions.
 526 The
 527 .Fn usbd_get_string
 528 function should be used unless a non-default language is required.
 529 It requires that
 530 .Fa buf
 531 points to a buffer of at least
 532 .Dv USB_MAX_STRING_LEN
 533 bytes in size.
 534 The
 535 .Fa si
 536 parameter specified which string to retrieve.
 537 .Pp
 538 The
 539 .Fn usb_find_desc
 540 function searches through the in-memory full configuration descriptor
 541 for the active configuration and finds the first descriptor that has a
 542 .Fa bDescriptorType
 543 equal to
 544 .Fa type ,
 545 and if
 546 .Fa subtype
 547 is not equal to
 548 .Dv USBD_SUBTYPE_ANY ,
 549 the descriptor must also have a
 550 .Fa bDescriptorSubtype
 551 equal to
 552 .Fa subtype .
 553 If found, then a pointer to the descriptor is returned.
 554 Otherwise,
 555 .Fn usb_find_desc
 556 returns
 557 .Dv NULL .
 558 The returned pointer is valid until the device configuration is changed using
 559 .Fn usbd_set_config_index
 560 or
 561 .Fn usbd_set_config_no .
 562 .Pp
 563 The USB driver interface uses opaque interface handles to refer to
 564 configuration interfaces.
 565 These handles remain valid until the device configuration is changed using
 566 .Fn usbd_set_config_index
 567 or
 568 .Fn usbd_set_config_no .
 569 The
 570 .Fn usbd_device2interface_handle
 571 function retrieves an interface handle.
 572 The
 573 .Fa ifaceno
 574 parameter is an interface index number starting at zero.
 575 If the device is configured and the specified interface exists, then
 576 .Dv USBD_NORMAL_COMPLETION
 577 is returned and the interface handle is stored in
 578 .Fa *iface .
 579 Otherwise an error code is returned and
 580 .Fa *iface
 581 is not changed.
 582 The
 583 .Fn usbd_interface2device_handle
 584 function retrieves the device handle from an interface handle.
 585 This is just for convenience to save passing around the device
 586 handle as well as the interface handle.
 587 The
 588 .Fn usbd_set_interface
 589 function changes the alternate setting number for an interface to
 590 the alternate setting identified by the zero-based index number
 591 .Fa altidx .
 592 This operation invalidates any existing endpoints on this
 593 interface and their descriptors.
 594 The
 595 .Fn usbd_get_interface_altindex
 596 function returns the current alternative setting index as was
 597 specified when calling
 598 .Fn usbd_set_interface .
 599 The
 600 .Fn usbd_endpoint_count
 601 function retrieves the number of endpoints associated with the
 602 specified interface.
 603 The
 604 .Fn usbd_interface2endpoint_descriptor
 605 function returns a pointer to an in-memory endpoint descriptor for
 606 the endpoint that has an index number of
 607 .Fa index .
 608 This pointer remains valid until the configuration or alternate setting
 609 number are changed.
 610 The function
 611 .Fn usbd_get_endpoint_descriptor
 612 is like
 613 .Fn usbd_interface2endpoint_descriptor
 614 but it accepts a
 615 .Fa bEndpointAddress
 616 address value instead of an index.
 617 .Pp
 618 The
 619 .Fn usbd_fill_deviceinfo
 620 function fills out a
 621 .Vt usb_device_info
 622 structure with information about the device.
 623 The vendor and product names come from the device itself, falling back to
 624 a table lookup or just providing the IDs in hexadecimal.
 625 If
 626 .Fa usedev
 627 is zero then
 628 .Fn usbd_fill_deviceinfo
 629 will not attempt to retrieve the vendor and product names from the
 630 device.
 631 The usb_device_info structure is defined in
 632 .In dev/usb/usb.h
 633 as follows:
 634 .Bd -literal
 635 struct usb_device_info {
 636         u_int8_t        udi_bus;
 637         u_int8_t        udi_addr;       /* device address */
 638         usb_event_cookie_t udi_cookie;
 639         char            udi_product[USB_MAX_STRING_LEN];
 640         char            udi_vendor[USB_MAX_STRING_LEN];
 641         char            udi_release[8];
 642         u_int16_t       udi_productNo;
 643         u_int16_t       udi_vendorNo;
 644         u_int16_t       udi_releaseNo;
 645         u_int8_t        udi_class;
 646         u_int8_t        udi_subclass;
 647         u_int8_t        udi_protocol;
 648         u_int8_t        udi_config;
 649         u_int8_t        udi_speed;
 650 #define USB_SPEED_LOW  1
 651 #define USB_SPEED_FULL 2
 652 #define USB_SPEED_HIGH 3
 653         int             udi_power;      /* power consumption in mA */
 654         int             udi_nports;
 655         char            udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
 656         /* hub only: addresses of devices on ports */
 657         u_int8_t        udi_ports[16];
 658 #define USB_PORT_ENABLED 0xff
 659 #define USB_PORT_SUSPENDED 0xfe
 660 #define USB_PORT_POWERED 0xfd
 661 }
 662 .Ed
 663 .Pp
 664 The
 665 .Fn usbd_devinfo
 666 function generates a string description of the USB device.
 667 The
 668 .Fa cp
 669 argument should point to a 1024-byte buffer (XXX the maximum length
 670 is approximately 320 chars, but there is no sanity checking and everything uses
 671 1024-character buffers).
 672 Device class information is included if the
 673 .Fa showclass
 674 parameter is non-zero.
 675 .Pp
 676 The
 677 .Fn usbd_get_quirks
 678 function returns information from a table of devices that require
 679 special workarounds in order to function correctly.
 680 The returned structure is defined in
 681 .In dev/usb/usb_quirks.h
 682 as follows:
 683 .Bd -literal
 684 struct usbd_quirks {
 685         u_int32_t uq_flags;     /* Device problems */
 686 };
 687 .Ed
 688 .Pp
 689 See
 690 .In dev/usb/usb_quirks.h
 691 for a list of all currently defined quirks.
 692 .Pp
 693 USB control requests are performed via
 694 .Vt usb_device_request_t
 695 structures, defined in
 696 .In dev/usb/usb.h
 697 as follows:
 698 .Bd -literal
 699 typedef struct {
 700         uByte           bmRequestType;
 701         uByte           bRequest;
 702         uWord           wValue;
 703         uWord           wIndex;
 704         uWord           wLength;
 705 } UPACKED usb_device_request_t;
 706 .Ed
 707 .Pp
 708 The
 709 .Fn usbd_do_request
 710 function performs a single request synchronously.
 711 The
 712 .Fa req
 713 parameter should point to a properly initialized
 714 .Vt usb_device_request_t ,
 715 and when the
 716 .Fa wLength
 717 field is non-zero,
 718 .Fa data
 719 should point at a buffer that is at least
 720 .Fa wLength
 721 bytes in length.
 722 The request timeout is set to 5 seconds, so the operation will fail
 723 with
 724 .Er USBD_TIMEOUT
 725 if the device does not respond within that time.
 726 The
 727 .Fn usbd_do_request_async
 728 function is like
 729 .Fn usbd_do_request ,
 730 but it does not wait for the request to complete before returning.
 731 This routine does not block so it can be used from contexts where
 732 sleeping is not allowed.
 733 Note that there is no notification mechanism to report when the
 734 operation completed nor is there a way to determine whether the
 735 request succeeded, so this function is of limited use.
 736 See
 737 .Fn usbd_setup_default_xfer
 738 and
 739 .Fn usbd_transfer
 740 for a way to invoke an asynchronous callback upon completion of
 741 a control request.
 742 The
 743 .Fn usbd_do_request_flags
 744 function is like
 745 .Fn usbd_do_request ,
 746 but additional flags can be specified, the timeout is configurable,
 747 and the actual number of bytes transferred is made available to the
 748 caller.
 749 The
 750 .Fn usbd_do_request_flags_pipe
 751 function uses a specified pipe instead of the default pipe.
 752 .Pp
 753 The function
 754 .Fn usbd_open_pipe
 755 creates a pipe connected to a specified endpoint on a specified interface.
 756 The parameter
 757 .Fa address
 758 should be the
 759 .Fa bEndpointAddress
 760 value from one of this interface's endpoint descriptors.
 761 If
 762 .Fa flags
 763 contains
 764 .Dv USBD_EXCLUSIVE_USE
 765 then the operation will only succeed if there are no open pipes
 766 already connected to the specified endpoint.
 767 The
 768 .Fn usbd_open_pipe_intr
 769 function creates an interrupt pipe connected to the specified endpoint.
 770 The parameter
 771 .Fa address
 772 should be the
 773 .Fa bEndpointAddress
 774 value from one of this interface's endpoint descriptors.
 775 The
 776 .Fa flags
 777 parameter is passed to
 778 .Fn usbd_setup_xfer .
 779 The
 780 .Fa buffer
 781 and
 782 .Fa len
 783 parameters define a buffer that is to be used for the interrupt transfers.
 784 The callback to be invoked each time a transfer completes is specified by
 785 .Fa cb ,
 786 and
 787 .Fa priv
 788 is an argument to be passed to the callback function.
 789 The
 790 .Fa ival
 791 parameter specifies the maximum acceptable interval between transfers;
 792 in practice the transfers may occur more frequently.
 793 The function
 794 .Fn usbd_pipe2device_handle
 795 returns the device associated with the specified
 796 .Fa pipe .
 797 .Pp
 798 The
 799 .Fn usbd_abort_pipe
 800 function aborts all active or waiting transfers on the specified pipe.
 801 Each transfer is aborted with a
 802 .Dv USBD_CANCELLED
 803 status; callback routines must detect this error code to ensure that
 804 they do not attempt to initiate a new transfer in response to one being
 805 aborted.
 806 This routine blocks while it is waiting for the hardware to complete
 807 processing of aborted transfers, so it is only safe to call it in
 808 contexts where sleeping is allowed.
 809 The function
 810 .Fn usbd_abort_default_pipe
 811 aborts all active or waiting transfers on the default pipe.
 812 Like
 813 .Fn usbd_abort_pipe ,
 814 it blocks waiting for the hardware processing to complete.
 815 .Pp
 816 When a pipe has no active or waiting transfers, the pipe may be closed
 817 using the
 818 .Fn usbd_close_pipe
 819 function.
 820 Once a pipe is closed, its pipe handle becomes invalid and may no longer
 821 be used.
 822 .Pp
 823 USB transfer handles are allocated using the function
 824 .Fn usbd_alloc_xfer
 825 and may be freed using
 826 .Fn usbd_free_xfer .
 827 .Pp
 828 The function
 829 .Fn usbd_setup_xfer
 830 initializes a transfer handle with the details of a transfer to or from
 831 a USB device.
 832 The
 833 .Fa xfer
 834 parameter specifies the transfer handle to initialize,
 835 .Fa pipe
 836 specifies the pipe on which the transfer is to take place, and
 837 .Fa priv
 838 is an argument that will be passed to callback function.
 839 The arguments
 840 .Fa buffer
 841 and
 842 .Fa length
 843 define the data buffer for the transfer.
 844 If
 845 .Fa length
 846 is zero then the
 847 .Fa buffer
 848 may be
 849 .Dv NULL .
 850 The
 851 .Fa flags
 852 parameter may contain the following flags:
 853 .Bl -tag -width ".Dv USBD_FORCE_SHORT_XFER"
 854 .It Dv USBD_NO_COPY
 855 This is used in association with
 856 .Fn usbd_alloc_buffer
 857 and
 858 .Fn usbd_free_buffer
 859 to use a dedicated DMA-capable buffer for the transfer.
 860 .It Dv USBD_SYNCHRONOUS
 861 Wait for the transfer to compete in
 862 .Fn usbd_transfer .
 863 .It Dv USBD_SHORT_XFER_OK
 864 Permit transfers shorter than the requested data length.
 865 .It Dv USBD_FORCE_SHORT_XFER
 866 Force a short transfer at the end of a write operation to let the
 867 device know that the transfer has ended.
 868 .El
 869 .Pp
 870 The
 871 .Fa timeout
 872 parameter specifies a timeout for the transfer in milliseconds.
 873 A value of
 874 .Dv USBD_NO_TIMEOUT
 875 indicates that no timeout should be configured.
 876 The parameter
 877 .Fa callback
 878 specifies the function to call when the transfer completes.
 879 Note that
 880 .Fn usbd_setup_xfer
 881 does not actually initiate the transfer.
 882 The
 883 .Fn usbd_setup_default_xfer
 884 initializes a control transfer for the default pipe.
 885 The
 886 .Fa req
 887 parameter should point at a completed
 888 .Vt usb_device_request_t
 889 structure.
 890 The function
 891 .Fa usbd_setup_isoc_xfer
 892 initializes a transfer for an isochronous pipe.
 893 .Pp
 894 The function
 895 .Fn usbd_transfer
 896 initiates a transfer.
 897 Normally it returns
 898 .Dv USBD_IN_PROGRESS
 899 to indicate that the transfer has been queued.
 900 If the USB stack is operating in polling mode, or if the transfer
 901 is synchronous, then
 902 .Dv USBD_NORMAL_COMPLETION
 903 may be returned.
 904 Other return values indicate that the transfer could not be
 905 initiated due to an error.
 906 The
 907 .Fn usbd_sync_transfer
 908 function executes a transfer synchronously.
 909 It will sleep waiting for the transfer to complete and then return
 910 the transfer status.
 911 Note that if the transfer has a callback routine, this will be
 912 invoked before
 913 .Fn usbd_sync_transfer
 914 returns.
 915 .Pp
 916 The
 917 .Fn usbd_intr_transfer
 918 and
 919 .Fn usbd_bulk_transfer
 920 functions set up a transfer and wait synchronously for it to complete
 921 but they allows signals to interrupt the wait.
 922 They returns
 923 .Dv USBD_INTERRUPTED
 924 if the transfer was interrupted by a signal.
 925 XXX these two functions are identical apart from their names.
 926 .Pp
 927 The function
 928 .Fn usbd_get_xfer_status
 929 retrieves various information from a completed transfer.
 930 If the
 931 .Fa priv
 932 parameter is not NULL then the callback private argument is
 933 stored in
 934 .Fa *priv .
 935 If
 936 .Fa buffer
 937 is not NULL then the transfer buffer pointer is stored in
 938 .Fa *buffer .
 939 The actual number of bytes transferred is stored in
 940 .Fa *count
 941 if
 942 .Fa count is not NULL.
 943 Finally, the transfer status is stored in
 944 .Fa *status
 945 if
 946 .Fa status
 947 is not NULL.
 948 .Pp
 949 The
 950 .Fn usbd_clear_endpoint_stall
 951 function clears an endpoint stall condition synchronously, i.e.\&
 952 it sleeps waiting for the stall clear request to complete.
 953 The function
 954 .Fn usbd_clear_endpoint_stall_async
 955 performs the same function asynchronously, but it provides no
 956 way to determine when the request completed, or whether it was
 957 successful.
 958 The
 959 .Fn usbd_clear_endpoint_toggle
 960 function instructs the host controller driver to reset the toggle bit
 961 on a pipe.
 962 This is used when manually clearing an endpoint stall using a
 963 control pipe request, in order to ensure that the host controller
 964 driver and the USB device restart with the same toggle value.
 965 .Pp
 966 Normally the USB subsystem maps and copies data to and from
 967 DMA-capable memory each time a transfer is performed.
 968 The function
 969 .Fn usbd_alloc_buffer
 970 allocates a permanent DMA-capable buffer associated with the
 971 transfer to avoid this overhead.
 972 The return value is the virtual address of the buffer.
 973 Any time that
 974 .Fn usbd_setup_xfer
 975 is called on the transfer with the
 976 .Dv USBD_NO_COPY
 977 flag enabled, the allocated buffer will be used directly and
 978 the
 979 .Fa buffer
 980 argument passed to
 981 .Fn usbd_setup_xfer
 982 will be ignored.
 983 The
 984 .Fn usbd_get_buffer
 985 function returns a pointer to the virtual address of a buffer previously
 986 allocated by
 987 .Fn usbd_alloc_buffer .
 988 Finally,
 989 .Fn usbd_free_buffer
 990 deallocates the buffer.
 991 .Pp
 992 The
 993 .Fn usbd_errstr
 994 function converts a status code into a string for display.
 995 .Pp
 996 The function
 997 .Fn usbd_set_polling
 998 enables or disables polling mode.
 999 In polling mode, all operations will busy-wait for the device to
1000 respond, so its use is effectively limited to boot time and kernel
1001 debuggers.
1002 It is important to match up calls that enable and disable polling
1003 mode, because the implementation just increments a polling reference
1004 count when
1005 .Fa on
1006 is non-zero and decrements it when
1007 .Fa on
1008 is zero.
1009 The
1010 .Fn usbd_dopoll
1011 causes the host controller driver to poll for any activity.
1012 This should only be used when polling mode is enabled.
1013 .Pp
1014 The
1015 .Fn usbd_ratecheck
1016 function is used to limit the rate at which error messages are
1017 printed to approximately once per second.
1018 The
1019 .Fa last
1020 argument should point at a persistent
1021 .Vt "struct timeval" .
1022 A value of 1 will be returned if a message should be printed, but if
1023 .Fn usbd_ratecheck
1024 has already been called with the same
1025 .Vt "struct timeval"
1026 parameter in the last second then 0 is returned and the error message
1027 should be suppressed.
1028 .Pp
1029 The functions
1030 .Fn usb_detach_wait
1031 and
1032 .Fn usb_detach_wakeup
1033 are used to wait for references to drain before completing the
1034 detachment of a device.
1035 The
1036 .Fn usb_detach_wait
1037 function will wait up to 60 seconds to receive a signal from
1038 .Fn usb_detach_wait .
1039 .Ss "USB Descriptors"
1040 The USB specification defines a number of standard descriptors by
1041 which USB devices report their attributes.
1042 These descriptors are fixed-format structures that all USB devices
1043 make available through USB control pipe requests.
1044 .Pp
1045 Every USB device has exactly one USB device descriptor.
1046 The USB subsystem retrieves this automatically when a device is
1047 attached, and a copy of the descriptor is kept in memory.
1048 The
1049 .Fn usbd_get_device_descriptor
1050 function returns a pointer to the descriptor.
1051 The device descriptor structure is defined in
1052 .In dev/usb/usb.h
1053 as follows:
1054 .Bd -literal
1055 typedef struct {
1056         uByte           bLength;
1057         uByte           bDescriptorType;
1058         uWord           bcdUSB;
1059 #define UD_USB_2_0              0x0200
1060 #define UD_IS_USB2(d) (UGETW((d)->bcdUSB) >= UD_USB_2_0)
1061         uByte           bDeviceClass;
1062         uByte           bDeviceSubClass;
1063         uByte           bDeviceProtocol;
1064         uByte           bMaxPacketSize;
1065         /* The fields below are not part of the initial descriptor. */
1066         uWord           idVendor;
1067         uWord           idProduct;
1068         uWord           bcdDevice;
1069         uByte           iManufacturer;
1070         uByte           iProduct;
1071         uByte           iSerialNumber;
1072         uByte           bNumConfigurations;
1073 } UPACKED usb_device_descriptor_t;
1074 #define USB_DEVICE_DESCRIPTOR_SIZE 18
1075 .Ed
1076 .Pp
1077 USB devices have at least one configuration descriptor.
1078 The
1079 .Fa bNumConfigurations
1080 field of the device descriptor specifies the number of configuration
1081 descriptors that a device supports.
1082 The
1083 .Fn usbd_get_config_desc
1084 function retrieves a particular configuration descriptor from the device
1085 and the
1086 .Fn usbd_get_config_desc_full
1087 function retrieves a full
1088 .Fa wTotalLength
1089 length configuration descriptor, which includes all related interface
1090 and endpoint descriptors.
1091 Only one configuration may be active at a time.
1092 The
1093 .Fn usbd_set_config_index
1094 function activates a specified configuration.
1095 The configuration descriptor structure is defined in
1096 .In dev/usb/usb.h
1097 as follows:
1098 .Bd -literal
1099 typedef struct {
1100         uByte           bLength;
1101         uByte           bDescriptorType;
1102         uWord           wTotalLength;
1103         uByte           bNumInterface;
1104         uByte           bConfigurationValue;
1105         uByte           iConfiguration;
1106         uByte           bmAttributes;
1107 #define UC_BUS_POWERED          0x80
1108 #define UC_SELF_POWERED         0x40
1109 #define UC_REMOTE_WAKEUP        0x20
1110         uByte           bMaxPower; /* max current in 2 mA units */
1111 #define UC_POWER_FACTOR 2
1112 } UPACKED usb_config_descriptor_t;
1113 #define USB_CONFIG_DESCRIPTOR_SIZE 9
1114 .Ed
1115 .Pp
1116 Each device configuration provides one or more interfaces.
1117 The
1118 .Fa bNumInterface
1119 field of the configuration descriptor specifies the number of
1120 interfaces associated with a device configuration.
1121 Interfaces are described by an interface descriptor, which is defined in
1122 .In dev/usb/usb.h
1123 as follows:
1124 .Bd -literal
1125 typedef struct {
1126         uByte           bLength;
1127         uByte           bDescriptorType;
1128         uByte           bInterfaceNumber;
1129         uByte           bAlternateSetting;
1130         uByte           bNumEndpoints;
1131         uByte           bInterfaceClass;
1132         uByte           bInterfaceSubClass;
1133         uByte           bInterfaceProtocol;
1134         uByte           iInterface;
1135 } UPACKED usb_interface_descriptor_t;
1136 #define USB_INTERFACE_DESCRIPTOR_SIZE 9
1137 .Ed
1138 .Pp
1139 Configurations may also have alternate interfaces with the same
1140 .Fa bInterfaceNumber
1141 but different
1142 .Fa bAlternateSetting
1143 values.
1144 These alternate interface settings may be selected by passing a
1145 non-zero
1146 .Fa altidx
1147 parameter to
1148 .Fn usbd_set_interface .
1149 .Pp
1150 Interfaces have zero or more endpoints, and each endpoint has an
1151 endpoint descriptor.
1152 Note that endpoint zero, which is always present, does not have an
1153 endpoint descriptor, and it is never included in the
1154 .Fa bNumEndpoints
1155 count of endpoints.
1156 The endpoint descriptor is defined in
1157 .In dev/usb/usb.h
1158 as follows:
1159 .Bd -literal
1160 typedef struct {
1161         uByte           bLength;
1162         uByte           bDescriptorType;
1163         uByte           bEndpointAddress;
1164 #define UE_GET_DIR(a)   ((a) & 0x80)
1165 #define UE_SET_DIR(a,d) ((a) | (((d)&1) << 7))
1166 #define UE_DIR_IN       0x80
1167 #define UE_DIR_OUT      0x00
1168 #define UE_ADDR         0x0f
1169 #define UE_GET_ADDR(a)  ((a) & UE_ADDR)
1170         uByte           bmAttributes;
1171 #define UE_XFERTYPE     0x03
1172 #define  UE_CONTROL     0x00
1173 #define  UE_ISOCHRONOUS 0x01
1174 #define  UE_BULK        0x02
1175 #define  UE_INTERRUPT   0x03
1176 #define UE_GET_XFERTYPE(a)      ((a) & UE_XFERTYPE)
1177 #define UE_ISO_TYPE     0x0c
1178 #define  UE_ISO_ASYNC   0x04
1179 #define  UE_ISO_ADAPT   0x08
1180 #define  UE_ISO_SYNC    0x0c
1181 #define UE_GET_ISO_TYPE(a)      ((a) & UE_ISO_TYPE)
1182         uWord           wMaxPacketSize;
1183         uByte           bInterval;
1184 } UPACKED usb_endpoint_descriptor_t;
1185 #define USB_ENDPOINT_DESCRIPTOR_SIZE 7
1186 .Ed
1187 .Sh RETURN VALUES
1188 Many functions return a
1189 .Vt usbd_status
1190 type to indicate the outcome of the operation.
1191 If the operation completed successfully then
1192 .Dv USBD_NORMAL_COMPLETION
1193 is returned.
1194 Operations that have been started but not yet completed will return
1195 .Dv USBD_IN_PROGRESS .
1196 Other errors usually indicate a problem.
1197 Error codes can be converted to strings using
1198 .Fn usbd_errstr .
1199 .Sh ERRORS
1200 .Bl -tag -width ".Er USBD_PENDING_REQUESTS"
1201 .It Bq Er USBD_PENDING_REQUESTS
1202 A pipe could not be closed because there are active requests.
1203 .It Bq Er USBD_NOT_STARTED
1204 The transfer has not yet been started.
1205 .It Bq Er USBD_INVAL
1206 An invalid value was supplied.
1207 .It Bq Er USBD_NOMEM
1208 An attempt to allocate memory failed.
1209 .It Bq Er USBD_CANCELLED
1210 The transfer was aborted.
1211 .It Bq Er USBD_BAD_ADDRESS
1212 The specified endpoint address was not found.
1213 .It Bq Er USBD_IN_USE
1214 The endpoint is already in use, or the configuration cannot be changed
1215 because some of its endpoints are in use.
1216 .It Bq Er USBD_NO_ADDR
1217 No free USB devices addresses were found to assign to the device.
1218 .It Bq Er USBD_SET_ADDR_FAILED
1219 The device address could not be set.
1220 .It Bq Er USBD_NO_POWER
1221 Insufficient power was available for the device.
1222 .It Bq Er USBD_TOO_DEEP
1223 Too many levels of chained hubs were found.
1224 .It Bq Er USBD_IOERROR
1225 There was an error communicating with the device.
1226 .It Bq Er USBD_NOT_CONFIGURED
1227 An operation that requires an active configuration was attempted while
1228 the device was in an unconfigured state.
1229 .It Bq Er USBD_TIMEOUT
1230 A transfer timed out.
1231 .It Bq Er USBD_SHORT_XFER
1232 A transfer that disallowed short data lengths completed with less than
1233 the requested length transferred.
1234 .It Bq Er USBD_STALLED
1235 A transfer failed because the pipe is stalled.
1236 .It Bq Er USBD_INTERRUPTED
1237 An interruptible operation caught a signal.
1238 .El
1239 .Sh SEE ALSO
1240 .Xr usb 4
1241 .Sh HISTORY
1242 The USB driver interface first appeared in
1243 .Fx 3.0 .
1244 .Sh AUTHORS
1245 The USB driver was written by
1246 .An Lennart Augustsson
1247 for the
1248 .Nx
1249 project.
1250 .Pp
1251 .An -nosplit
1252 This manual page was written by
1253 .An Ian Dowse Aq iedowse@FreeBSD.org .