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