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