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