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.3 2008/11/23 21:55:52 swildner 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.Fn 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 945is not NULL. 946Finally, the transfer status is stored in 947.Fa *status 948if 949.Fa status 950is not NULL. 951.Pp 952The 953.Fn usbd_clear_endpoint_stall 954function clears an endpoint stall condition synchronously, i.e.\& 955it sleeps waiting for the stall clear request to complete. 956The function 957.Fn usbd_clear_endpoint_stall_async 958performs the same function asynchronously, but it provides no 959way to determine when the request completed, or whether it was 960successful. 961The 962.Fn usbd_clear_endpoint_toggle 963function instructs the host controller driver to reset the toggle bit 964on a pipe. 965This is used when manually clearing an endpoint stall using a 966control pipe request, in order to ensure that the host controller 967driver and the USB device restart with the same toggle value. 968.Pp 969Normally the USB subsystem maps and copies data to and from 970DMA-capable memory each time a transfer is performed. 971The function 972.Fn usbd_alloc_buffer 973allocates a permanent DMA-capable buffer associated with the 974transfer to avoid this overhead. 975The return value is the virtual address of the buffer. 976Any time that 977.Fn usbd_setup_xfer 978is called on the transfer with the 979.Dv USBD_NO_COPY 980flag enabled, the allocated buffer will be used directly and 981the 982.Fa buffer 983argument passed to 984.Fn usbd_setup_xfer 985will be ignored. 986The 987.Fn usbd_get_buffer 988function returns a pointer to the virtual address of a buffer previously 989allocated by 990.Fn usbd_alloc_buffer . 991Finally, 992.Fn usbd_free_buffer 993deallocates the buffer. 994.Pp 995The 996.Fn usbd_errstr 997function converts a status code into a string for display. 998.Pp 999The function 1000.Fn usbd_set_polling 1001enables or disables polling mode. 1002In polling mode, all operations will busy-wait for the device to 1003respond, so its use is effectively limited to boot time and kernel 1004debuggers. 1005It is important to match up calls that enable and disable polling 1006mode, because the implementation just increments a polling reference 1007count when 1008.Fa on 1009is non-zero and decrements it when 1010.Fa on 1011is zero. 1012The 1013.Fn usbd_dopoll 1014causes the host controller driver to poll for any activity. 1015This should only be used when polling mode is enabled. 1016.Pp 1017The 1018.Fn usbd_ratecheck 1019function is used to limit the rate at which error messages are 1020printed to approximately once per second. 1021The 1022.Fa last 1023argument should point at a persistent 1024.Vt "struct timeval" . 1025A value of 1 will be returned if a message should be printed, but if 1026.Fn usbd_ratecheck 1027has already been called with the same 1028.Vt "struct timeval" 1029parameter in the last second then 0 is returned and the error message 1030should be suppressed. 1031.Pp 1032The functions 1033.Fn usb_detach_wait 1034and 1035.Fn usb_detach_wakeup 1036are used to wait for references to drain before completing the 1037detachment of a device. 1038The 1039.Fn usb_detach_wait 1040function will wait up to 60 seconds to receive a signal from 1041.Fn usb_detach_wait . 1042.Ss "USB Descriptors" 1043The USB specification defines a number of standard descriptors by 1044which USB devices report their attributes. 1045These descriptors are fixed-format structures that all USB devices 1046make available through USB control pipe requests. 1047.Pp 1048Every USB device has exactly one USB device descriptor. 1049The USB subsystem retrieves this automatically when a device is 1050attached, and a copy of the descriptor is kept in memory. 1051The 1052.Fn usbd_get_device_descriptor 1053function returns a pointer to the descriptor. 1054The device descriptor structure is defined in 1055.In bus/usb/usb.h 1056as follows: 1057.Bd -literal 1058typedef struct { 1059 uByte bLength; 1060 uByte bDescriptorType; 1061 uWord bcdUSB; 1062#define UD_USB_2_0 0x0200 1063#define UD_IS_USB2(d) (UGETW((d)->bcdUSB) >= UD_USB_2_0) 1064 uByte bDeviceClass; 1065 uByte bDeviceSubClass; 1066 uByte bDeviceProtocol; 1067 uByte bMaxPacketSize; 1068 /* The fields below are not part of the initial descriptor. */ 1069 uWord idVendor; 1070 uWord idProduct; 1071 uWord bcdDevice; 1072 uByte iManufacturer; 1073 uByte iProduct; 1074 uByte iSerialNumber; 1075 uByte bNumConfigurations; 1076} UPACKED usb_device_descriptor_t; 1077#define USB_DEVICE_DESCRIPTOR_SIZE 18 1078.Ed 1079.Pp 1080USB devices have at least one configuration descriptor. 1081The 1082.Fa bNumConfigurations 1083field of the device descriptor specifies the number of configuration 1084descriptors that a device supports. 1085The 1086.Fn usbd_get_config_desc 1087function retrieves a particular configuration descriptor from the device 1088and the 1089.Fn usbd_get_config_desc_full 1090function retrieves a full 1091.Fa wTotalLength 1092length configuration descriptor, which includes all related interface 1093and endpoint descriptors. 1094Only one configuration may be active at a time. 1095The 1096.Fn usbd_set_config_index 1097function activates a specified configuration. 1098The configuration descriptor structure is defined in 1099.In bus/usb/usb.h 1100as follows: 1101.Bd -literal 1102typedef struct { 1103 uByte bLength; 1104 uByte bDescriptorType; 1105 uWord wTotalLength; 1106 uByte bNumInterface; 1107 uByte bConfigurationValue; 1108 uByte iConfiguration; 1109 uByte bmAttributes; 1110#define UC_BUS_POWERED 0x80 1111#define UC_SELF_POWERED 0x40 1112#define UC_REMOTE_WAKEUP 0x20 1113 uByte bMaxPower; /* max current in 2 mA units */ 1114#define UC_POWER_FACTOR 2 1115} UPACKED usb_config_descriptor_t; 1116#define USB_CONFIG_DESCRIPTOR_SIZE 9 1117.Ed 1118.Pp 1119Each device configuration provides one or more interfaces. 1120The 1121.Fa bNumInterface 1122field of the configuration descriptor specifies the number of 1123interfaces associated with a device configuration. 1124Interfaces are described by an interface descriptor, which is defined in 1125.In bus/usb/usb.h 1126as follows: 1127.Bd -literal 1128typedef struct { 1129 uByte bLength; 1130 uByte bDescriptorType; 1131 uByte bInterfaceNumber; 1132 uByte bAlternateSetting; 1133 uByte bNumEndpoints; 1134 uByte bInterfaceClass; 1135 uByte bInterfaceSubClass; 1136 uByte bInterfaceProtocol; 1137 uByte iInterface; 1138} UPACKED usb_interface_descriptor_t; 1139#define USB_INTERFACE_DESCRIPTOR_SIZE 9 1140.Ed 1141.Pp 1142Configurations may also have alternate interfaces with the same 1143.Fa bInterfaceNumber 1144but different 1145.Fa bAlternateSetting 1146values. 1147These alternate interface settings may be selected by passing a 1148non-zero 1149.Fa altidx 1150parameter to 1151.Fn usbd_set_interface . 1152.Pp 1153Interfaces have zero or more endpoints, and each endpoint has an 1154endpoint descriptor. 1155Note that endpoint zero, which is always present, does not have an 1156endpoint descriptor, and it is never included in the 1157.Fa bNumEndpoints 1158count of endpoints. 1159The endpoint descriptor is defined in 1160.In bus/usb/usb.h 1161as follows: 1162.Bd -literal 1163typedef struct { 1164 uByte bLength; 1165 uByte bDescriptorType; 1166 uByte bEndpointAddress; 1167#define UE_GET_DIR(a) ((a) & 0x80) 1168#define UE_SET_DIR(a,d) ((a) | (((d)&1) << 7)) 1169#define UE_DIR_IN 0x80 1170#define UE_DIR_OUT 0x00 1171#define UE_ADDR 0x0f 1172#define UE_GET_ADDR(a) ((a) & UE_ADDR) 1173 uByte bmAttributes; 1174#define UE_XFERTYPE 0x03 1175#define UE_CONTROL 0x00 1176#define UE_ISOCHRONOUS 0x01 1177#define UE_BULK 0x02 1178#define UE_INTERRUPT 0x03 1179#define UE_GET_XFERTYPE(a) ((a) & UE_XFERTYPE) 1180#define UE_ISO_TYPE 0x0c 1181#define UE_ISO_ASYNC 0x04 1182#define UE_ISO_ADAPT 0x08 1183#define UE_ISO_SYNC 0x0c 1184#define UE_GET_ISO_TYPE(a) ((a) & UE_ISO_TYPE) 1185 uWord wMaxPacketSize; 1186 uByte bInterval; 1187} UPACKED usb_endpoint_descriptor_t; 1188#define USB_ENDPOINT_DESCRIPTOR_SIZE 7 1189.Ed 1190.Sh RETURN VALUES 1191Many functions return a 1192.Vt usbd_status 1193type to indicate the outcome of the operation. 1194If the operation completed successfully then 1195.Dv USBD_NORMAL_COMPLETION 1196is returned. 1197Operations that have been started but not yet completed will return 1198.Dv USBD_IN_PROGRESS . 1199Other errors usually indicate a problem. 1200Error codes can be converted to strings using 1201.Fn usbd_errstr . 1202.Sh ERRORS 1203.Bl -tag -width ".Er USBD_PENDING_REQUESTS" 1204.It Bq Er USBD_PENDING_REQUESTS 1205A pipe could not be closed because there are active requests. 1206.It Bq Er USBD_NOT_STARTED 1207The transfer has not yet been started. 1208.It Bq Er USBD_INVAL 1209An invalid value was supplied. 1210.It Bq Er USBD_NOMEM 1211An attempt to allocate memory failed. 1212.It Bq Er USBD_CANCELLED 1213The transfer was aborted. 1214.It Bq Er USBD_BAD_ADDRESS 1215The specified endpoint address was not found. 1216.It Bq Er USBD_IN_USE 1217The endpoint is already in use, or the configuration cannot be changed 1218because some of its endpoints are in use. 1219.It Bq Er USBD_NO_ADDR 1220No free USB devices addresses were found to assign to the device. 1221.It Bq Er USBD_SET_ADDR_FAILED 1222The device address could not be set. 1223.It Bq Er USBD_NO_POWER 1224Insufficient power was available for the device. 1225.It Bq Er USBD_TOO_DEEP 1226Too many levels of chained hubs were found. 1227.It Bq Er USBD_IOERROR 1228There was an error communicating with the device. 1229.It Bq Er USBD_NOT_CONFIGURED 1230An operation that requires an active configuration was attempted while 1231the device was in an unconfigured state. 1232.It Bq Er USBD_TIMEOUT 1233A transfer timed out. 1234.It Bq Er USBD_SHORT_XFER 1235A transfer that disallowed short data lengths completed with less than 1236the requested length transferred. 1237.It Bq Er USBD_STALLED 1238A transfer failed because the pipe is stalled. 1239.It Bq Er USBD_INTERRUPTED 1240An interruptible operation caught a signal. 1241.El 1242.Sh SEE ALSO 1243.Xr usb 4 1244.Sh HISTORY 1245The USB driver interface first appeared in 1246.Fx 3.0 . 1247.Sh AUTHORS 1248The USB driver was written by 1249.An Lennart Augustsson 1250for the 1251.Nx 1252project. 1253.Pp 1254.An -nosplit 1255This manual page was written by 1256.An Ian Dowse Aq iedowse@FreeBSD.org . 1257