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