1.\" $NetBSD: usbdi.9,v 1.26 2013/01/22 15:52:17 wiz Exp $ 2.\" 3.\" Copyright (c) 2012 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 24.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" 30.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 31.\" All rights reserved. 32.\" 33.\" This code is derived from software contributed to The NetBSD Foundation 34.\" by Lennart Augustsson. 35.\" 36.\" Redistribution and use in source and binary forms, with or without 37.\" modification, are permitted provided that the following conditions 38.\" are met: 39.\" 1. Redistributions of source code must retain the above copyright 40.\" notice, this list of conditions and the following disclaimer. 41.\" 2. Redistributions in binary form must reproduce the above copyright 42.\" notice, this list of conditions and the following disclaimer in the 43.\" documentation and/or other materials provided with the distribution. 44.\" 45.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 46.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 47.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 48.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 49.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 50.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 51.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 52.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 53.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 54.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 55.\" POSSIBILITY OF SUCH DAMAGE. 56.\" 57.Dd January 22, 2013 58.Dt USBDI 9 59.Os 60.Sh NAME 61.Nm usbdi 62.Nd USB device drivers interface 63.Sh SYNOPSIS 64.In dev/usb/usb.h 65.In dev/usb/usbdi.h 66.In dev/usb/usbdi_util.h 67.Ss Functions offered by usbdi.h 68.Ft usbd_status 69.Fn usbd_open_pipe "usbd_interface_handle iface" "uint8_t address" \ 70 "uint8_t flags" "usbd_pipe_handle *pipe" 71.Ft usbd_status 72.Fn usbd_close_pipe "usbd_pipe_handle pipe" 73.Ft usbd_status 74.Fn usbd_transfer "usbd_xfer_handle xfer" 75.Ft usbd_xfer_handle 76.Fn usbd_alloc_xfer "usbd_device_handle dev" 77.Ft usbd_status 78.Fn usbd_free_xfer "usbd_xfer_handle xfer" 79.Ft void 80.Fn usbd_setup_xfer "usbd_xfer_handle xfer" "usbd_pipe_handle pipe" \ 81 "usbd_private_handle priv" "void *buffer" "uint32_t length" \ 82 "uint16_t flags" "uint32_t timeout" "usbd_callback" 83.Ft void 84.Fn usbd_setup_default_xfer "usbd_xfer_handle xfer" \ 85 "usbd_device_handle dev" "usbd_private_handle priv" \ 86 "uint32_t timeout" "usb_device_request_t *req" " void *buffer" \ 87 "uint32_t length" "uint16_t flags" "usbd_callback" 88.Ft void 89.Fn usbd_setup_isoc_xfer "usbd_xfer_handle xfer" "usbd_pipe_handle pipe" \ 90 "usbd_private_handle priv" "uint16_t *frlengths" \ 91 "uint32_t nframes" "uint16_t flags" "usbd_callback" 92.Ft void 93.Fn usbd_get_xfer_status "usbd_xfer_handle xfer" "usbd_private_handle *priv" \ 94 "void **buffer" "uint32_t *count" "usbd_status *status" 95.Ft usb_endpoint_descriptor_t * 96.Fn usbd_interface2endpoint_descriptor "usbd_interface_handle iface" \ 97 "uint8_t address" 98.Ft usbd_status 99.Fn usbd_abort_pipe "usbd_pipe_handle pipe" 100.Ft usbd_status 101.Fn usbd_abort_default_pipe "usbd_device_handle dev" 102.Ft usbd_status 103.Fn usbd_clear_endpoint_stall "usbd_pipe_handle pipe" 104.Ft usbd_status 105.Fn usbd_clear_endpoint_stall_async "usbd_pipe_handle pipe" 106.Ft void 107.Fn usbd_clear_endpoint_toggle "usbd_pipe_handle pipe" 108.Ft usbd_status 109.Fn usbd_endpoint_count "usbd_interface_handle dev" "uint8_t *count" 110.Ft usbd_status 111.Fn usbd_interface_count "usbd_device_handle dev" "uint8_t *count" 112.Ft usbd_status 113.Fn usbd_interface2device_handle "usbd_interface_handle iface" "usbd_device_handle *dev" 114.Ft usbd_status 115.Fn usbd_device2interface_handle "usbd_device_handle dev" "uint8_t ifaceno" "usbd_interface_handle *iface" 116.Pp 117.Ft usbd_device_handle 118.Fn usbd_pipe2device_handle "usbd_pipe_handle pipe" 119.Ft void * 120.Fn usbd_alloc_buffer "usbd_xfer_handle req" "uint32_t size" 121.Ft void 122.Fn usbd_free_buffer "usbd_xfer_handle req" 123.Ft void * 124.Fn usbd_get_buffer "usbd_xfer_handle xfer" 125.Ft usbd_status 126.Fn usbd_sync_transfer "usbd_xfer_handle req" 127.Ft usbd_status 128.Fn usbd_sync_transfer_sig "usbd_xfer_handle req" 129.Ft usbd_status 130.Fn usbd_open_pipe_intr "usbd_interface_handle iface" "uint8_t address" \ 131 "uint8_t flags" "usbd_pipe_handle *pipe" \ 132 "usbd_private_handle priv" "void *buffer" \ 133 "uint32_t length" "usbd_callback callback" "int interval" 134.Ft usbd_status 135.Fn usbd_do_request "usbd_device_handle dev" "usb_device_request_t *req" \ 136 "void *data" 137.Ft usbd_status 138.Fn usbd_do_request_flags "usbd_device_handle dev" \ 139 "usb_device_request_t *req" "void *data" "uint16_t flags" "int *actlen" \ 140 "u_int32_t timo" 141.\" usbd_do_request_async() not used outside of usbdi* 142.Ft usb_interface_descriptor_t * 143.Fn usbd_get_interface_descriptor "usbd_interface_handle iface" 144.Ft usb_config_descriptor_t * 145.Fn usbd_get_config_descriptor "usbd_device_handle dev" 146.Ft usb_device_descriptor_t * 147.Fn usbd_get_device_descriptor "usbd_device_handle dev" 148.Ft usbd_status 149.Fn usbd_set_interface "usbd_interface_handle iface" "int altidx" 150.Ft int 151.Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno" 152.Ft usbd_status 153.Fn usbd_get_interface "usbd_interface_handle iface" "uint8_t *aiface" 154.Ft void 155.Fn usbd_fill_deviceinfo "usbd_device_handle dev" "struct usb_device_info *di" 156.Ft int 157.Fn usbd_get_interface_altindex "usbd_interface_handle iface" 158.Ft usb_endpoint_descriptor_t * 159.Fn usbd_get_endpoint_descriptor "usbd_interface_handle dev" \ 160 "u_int8_t address" 161.Ft usb_interface_descriptor_t * 162.Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" 163.Ft usb_endpoint_descriptor_t * 164.Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ 165 "int endptidx" 166.Ft void 167.Fn usbd_dopoll "usbd_interface_handle iface" 168.Ft void 169.Fn usbd_set_polling "usbd_device_handle iface" "int val" 170.Ft const char * 171.Fn usbd_errstr "usbd_status err" 172.Ft void 173.Fn usbd_add_dev_event "int type" "usbd_device_handle iface" 174.Ft void 175.Fn usbd_add_drv_event "int type" "usbd_device_handle iface" "device_t dv" 176.Ft char * 177.Fn usbd_devinfo_alloc "usbd_device_handle iface" "int showclass" 178.Ft void 179.Fn usbd_devinfo_free "char *str" 180.Ft const struct usbd_quirks * 181.Fn usbd_get_quirks "usbd_device_handle iface" 182.Ft usbd_status 183.Fn usbd_reload_device_desc "usbd_device_handle iface" 184.Ft int 185.Fn usbd_ratecheck "struct timeval *tv" 186.Ft usbd_status 187.Fn usbd_get_string "usbd_device_handle iface" "int si" "char *buf" 188.Ft usbd_status 189.Fn usbd_get_string0 "usbd_device_handle iface" "int" si "char *buf" \ 190 "int unicode" 191.Ft void 192.Fn usb_desc_iter_init "usbd_device_handle iface" "usbd_desc_iter_t *iter" 193.Ft const usb_descriptor_t * 194.Fn usb_desc_iter_next "usbd_desc_iter_t *iter" 195.Ft void 196.Fn usb_add_task "usbd_device_handle iface" "struct usb_task *task" \ 197 "int queue" 198.Ft void 199.Fn usb_rem_task "usbd_device_handle iface" "struct usb_task *task" 200.Ft void 201.Fn usb_init_task "struct usb_task *task" "void (*func)(void *)" \ 202 "void *arg" uint8_t flags 203.Ft const struct usb_devno * 204.Fn usb_lookup "const struct usb_devno *tbl" \ 205 "u_int16_t vendor" "u_int16_t product" 206.Ss Utilities from usbdi_util.h 207Based on the routines in 208.Dv usbdi.h 209a number of utility functions have been defined that are accessible 210through 211.Dv usbdi_util.h . 212.Ft usbd_status 213.Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \ 214 "int len" "void *desc" 215.Ft usbd_status 216.Fn usbd_get_config_desc "usbd_device_handle dev" "int confidx" \ 217 "usb_config_descriptor_t *d" 218.Ft usbd_status 219.Fn usbd_get_config_desc_full "usbd_device_handle" "int dev" "void *d" "int size" 220.Ft usbd_status 221.Fn usbd_get_device_desc "usbd_device_handle dev" \ 222 "usb_device_descriptor_t *d" 223.Ft usbd_status 224.Fn usbd_set_address "usbd_device_handle dev" "int addr" 225.Ft usbd_status 226.Fn usbd_get_port_status "usbd_device_handle dev" "intp ort" "usb_port_status_t *ps" 227.Ft usbd_status 228.Fn usbd_set_hub_feature "usbd_device_handle dev" "int sel" 229.Ft usbd_status 230.Fn usbd_clear_hub_feature "usbd_device_handle dev" "int sel" 231.Ft usbd_status 232.Fn usbd_set_port_feature "usbd_device_handle dev" "int port" "int sel" 233.Ft usbd_status 234.Fn usbd_clear_port_feature "usbd_device_handle dev" "int port" "int sel" 235.Ft usbd_status 236.Fn usbd_get_device_status "usbd_device_handle dev" "usb_status_t *st" 237.Ft usbd_status 238.Fn usbd_get_hub_status "usbd_device_handle dev" "usb_hub_status_t *st" 239.Ft usbd_status 240.Fn usbd_set_protocol "usbd_interface_handle dev" "int report" 241.Ft usbd_status 242.Fn usbd_get_report_descriptor "usbd_device_handle dev" "int ifcno" "int repid" "int size" "void *d" 243.Ft struct usb_hid_descriptor * 244.Fn usbd_get_hid_descriptor "usbd_interface_handle ifc" 245.Ft usbd_status 246.Fn usbd_set_report "usbd_interface_handle iface" "nt type" "int id" "void *data" "int len" 247.Ft usbd_status 248.Fn usbd_set_report_async "usbd_interface_handle iface" "int type" "int id" "void *data" "int len" 249.Ft usbd_status 250.Fn usbd_get_report "usbd_interface_handle iface" "int type" "int id" "void *data" "int len" 251.Ft usbd_status 252.Fn usbd_set_idle "usbd_interface_handle iface" "int duration" "int id" 253.Ft usbd_status 254.Fn usbd_alloc_report_desc "usbd_interface_handle ifc" "void **descp" \ 255 "int *sizep" "int mem" 256.Ft usbd_status 257.Fn usbd_get_config "usbd_device_handle dev" "uint8_t *conf" 258.Ft usbd_status 259.Fn usbd_get_string_desc "usbd_device_handle dev" "int sindex" "int langid" \ 260 "usb_string_descriptor_t *sdesc" 261.Ft void 262.Fn usbd_delay_ms "usbd_device_handle dev" "u_int ms" 263.Ft usbd_status 264.Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg" 265.Ft usbd_status 266.Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg" 267.Ft usbd_status 268.Fn usbd_bulk_transfer "usbd_xfer_handle xfer" "usbd_pipe_handle pipe" \ 269 "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" "char *lbl" 270.Ft usbd_status 271.Fn usbd_intr_transfer "usbd_xfer_handle xfer" "usbd_pipe_handle pipe" \ 272 "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" "char *lbl" 273.Ft void 274.Fn usb_detach_waitold "device_t dv" 275.Ft void 276.Fn usb_detach_wakeupold "device_t dv" 277.Ft void 278.Fn usb_detach_wait "device_t dv" "kcondvar_t *cv" "kmutex_t *lk" 279.Ft void 280.Fn usb_detach_broadcast "device_t dv" "kcondvar_t *cv" 281.Sh DESCRIPTION 282Device driver access to the USB bus centers around transfers. 283A transfer describes a communication with a USB device. 284A transfer is an abstract concept that can result in several 285physical packets being transferred to or from a device. 286A transfer is described by the 287.Va usbd_xfer_handle 288cookie. 289A pipe is a logical connection to a USB device. 290It is described by the 291.Va usbd_pipe_handle 292cookie. 293See the 294.Sx TRANSFERS 295and 296.Sx PIPES 297sections for more details. 298.Pp 299There are a number of functions to obtain a handle, descriptor 300of resource count: 301.Bl -tag -width 10n 302.It Fn usbd_device2interface_handle dev ifaceno iface 303Fills in 304.Fa iface 305with the 306.Ft usbd_interface_handle 307for the USB device 308.Fa dev 309on interface number 310.Fa ifaceno . 311.It Fn usbd_interface2device_handle iface dev 312Fills in 313.Fa dev 314with the 315.Ft usbd_device_handle 316pointer for interface 317.Fa iface . 318.\" usbd_pipe2device_handle is unused; remove from usbdi? 319.It Fn usbd_pipe2device_handle pipe 320Returns the 321.Ft usbd_device_handle 322associated with 323.Fa pipe . 324.It Fn usbd_interface2endpoint_descriptor iface address 325Returns the 326.Ft usb_endpoint_descriptor_t * 327for the particular interface 328.Fa iface 329at address 330.Fa address . 331.\" XXX describe what a .Ft usb_endpoint_descriptor_t is. 332.It Fn usbd_endpoint_count dev count 333.It Fn usbd_interface_count dev count 334Fills in 335.Fa count 336with the number of endpoint or interfaces the USB device 337.Fa dev 338has. 339.El 340.Pp 341Error handling and other return values are described in 342.Xr usbd_status 9 . 343.Pp 344Additional comments on particular functions: 345.Bl -tag -width 10n 346.It Fn usbd_errstr err 347Returns the string associated with 348.Fa err . 349.It Fn usbd_add_dev_event type iface 350The 351.Ar type 352must be one of 353.Dv USB_EVENT_CTRLR_ATTACH , 354.Dv USB_EVENT_CTRLR_DETACH , 355.Dv USB_EVENT_DEVICE_ATTACH 356and 357.Dv USB_EVENT_DEVICE_DETACH . 358.It Fn usbd_add_drv_event type iface dv 359The 360.Fa type 361must be one of 362.Dv USB_EVENT_DRIVER_ATTACH 363and 364.Dv USB_EVENT_DRIVER_DETACH . 365The 366.Fa dv 367corresponds with the 368.Ft device_t 369associated with the device attached or detached. 370.It Fn usb_lookup tbl vendor product 371Lookup a USB device. 372The returned 373.Va struct usb_devno 374pointer has these members: 375.Bl -item -offset offset -compact 376.It 377.Vt u_int16_t ud_vendor ; 378.It 379.Vt u_int16_t ud_product ; 380.El 381The 382.Dv USB_PRODUCT_ANY 383macro can be used to match any USB product by a particular vendor. 384.El 385.\" 386.\" XXX functions missing descriptions in usbdi.h XXX 387.\" 388.\" .Fn usbd_get_interface_descriptor "usbd_interface_handle iface" 389.\" .Fn usbd_get_config_descriptor "usbd_device_handle dev" 390.\" .Fn usbd_get_device_descriptor "usbd_device_handle dev" 391.\" .Fn usbd_set_interface "usbd_interface_handle iface" "int altidx" 392.\" .Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno" 393.\" .Fn usbd_get_interface "usbd_interface_handle iface" "uint8_t *aiface" 394.\" .Fn usbd_fill_deviceinfo "usbd_device_handle dev" "struct usb_device_info *di" 395.\" .Fn usbd_get_interface_altindex "usbd_interface_handle iface" 396.\" .Fn usbd_get_endpoint_descriptor "usbd_interface_handle dev" \ 397.\" "u_int8_t address" 398.\" .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" 399.\" .Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ 400.\" "int endptidx" 401.\" .Fn usbd_dopoll "usbd_interface_handle iface" 402.\" .Fn usbd_set_polling" usbd_device_handle iface" "int val" 403.\" 404.\" .Fn usbd_add_dev_event "int type" "usbd_device_handle iface" 405.\" .Fn usbd_add_drv_event "int type" "usbd_device_handle iface" "device_t dv" 406.\" 407.\" .Fn usbd_devinfo_alloc "usbd_device_handle iface" "int showclass" 408.\" .Fn usbd_devinfo_free "char *str" 409.\" 410.\" .Fn usbd_get_quirks "usbd_device_handle iface" 411.\" .Fn usbd_reload_device_desc "usbd_device_handle iface" 412.\" .Fn usbd_ratecheck "struct timeval *tv" 413.\" .Fn usbd_get_string "usbd_device_handle iface" "int si" "char *buf" 414.\" .Fn usbd_get_string0 "usbd_device_handle iface" "int" si "char *buf" \ 415.\" "int unicode" 416.\" 417.\" .Fn usb_desc_iter_init "usbd_device_handle iface" "usbd_desc_iter_t *iter" 418.\" .Fn usb_desc_iter_next "usbd_desc_iter_t *iter" 419.\" 420.\" XXX functions missing descriptions in usbdi.h XXX 421.\" 422.\" .Dv usbdi_util.h . 423.\" .Ft usbd_status 424.\" .Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \ 425.\" "int len" "void *desc" 426.\" .Ft usbd_status 427.\" .Fn usbd_get_config_desc "usbd_device_handle dev" "int confidx" \ 428.\" "usb_config_descriptor_t *d" 429.\" .Ft usbd_status 430.\" .Fn usbd_get_config_desc_full "usbd_device_handle" "int dev" "void *d" "int size" 431.\" .Ft usbd_status 432.\" .Fn usbd_get_device_desc "usbd_device_handle dev" \ 433.\" "usb_device_descriptor_t *d" 434.\" .Ft usbd_status 435.\" .Fn usbd_set_address "usbd_device_handle dev" "int addr" 436.\" .Ft usbd_status 437.\" .Fn usbd_get_port_status "usbd_device_handle dev" "intp ort" "usb_port_status_t *ps" 438.\" .Ft usbd_status 439.\" .Fn usbd_set_hub_feature "usbd_device_handle dev" "int sel" 440.\" .Ft usbd_status 441.\" .Fn usbd_clear_hub_feature "usbd_device_handle dev" "int sel" 442.\" .Ft usbd_status 443.\" .Fn usbd_set_port_feature "usbd_device_handle dev" "int port" "int sel" 444.\" .Ft usbd_status 445.\" .Fn usbd_clear_port_feature "usbd_device_handle dev" "int port" "int sel" 446.\" .Ft usbd_status 447.\" .Fn usbd_get_device_status "usbd_device_handle dev" "usb_status_t *st" 448.\" .Ft usbd_status 449.\" .Fn usbd_get_hub_status "usbd_device_handle dev" "usb_hub_status_t *st" 450.\" .Ft usbd_status 451.\" .Fn usbd_set_protocol "usbd_interface_handle dev" "int report" 452.\" .Ft usbd_status 453.\" .Fn usbd_get_report_descriptor "usbd_device_handle dev" "int ifcno" "int repid" "int size" "void *d" 454.\" .Ft struct usb_hid_descriptor * 455.\" .Fn usbd_get_hid_descriptor "usbd_interface_handle ifc" 456.\" .Ft usbd_status 457.\" .Fn usbd_set_report "usbd_interface_handle iface" "nt type" "int id" "void *data" "int len" 458.\" .Ft usbd_status 459.\" .Fn usbd_set_report_async "usbd_interface_handle iface" "int type" "int id" "void *data" "int len" 460.\" .Ft usbd_status 461.\" .Fn usbd_get_report "usbd_interface_handle iface" "int type" "int id" "void *data" "int len" 462.\" .Ft usbd_status 463.\" .Fn usbd_set_idle "usbd_interface_handle iface" "int duration" "int id" 464.\" .Ft usbd_status 465.\" .Fn usbd_alloc_report_desc "usbd_interface_handle ifc" "void **descp" \ 466.\" "int *sizep" "int mem" 467.\" .Ft usbd_status 468.\" .Fn usbd_get_config "usbd_device_handle dev" "uint8_t *conf" 469.\" .Ft usbd_status 470.\" .Fn usbd_get_string_desc "usbd_device_handle dev" "int sindex" "int langid" \ 471.\" "usb_string_descriptor_t *sdesc" 472.\" .Ft void 473.\" .Fn usbd_delay_ms "usbd_device_handle dev" "u_int ms" 474.\" .Ft usbd_status 475.\" .Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg" 476.\" .Ft usbd_status 477.\" .Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg" 478.\" .Ft usbd_status 479.\" 480.Sh PIPES 481Pipes are created and destroyed by using the 482.Fn usbd_open_pipe , 483.Fn usbd_open_pipe_intr 484and 485.Fn usbd_close_pipe 486functions. 487The open functions take the interface handle 488.Fa iface , 489the 490.Fa address 491of this pipe and 492.Fa flags 493for this pipe which currently may be 0, or a combination of 494.Dv USBD_EXCLUSIVE_USE , 495to enable exclusive access to this interface and address, and 496.Dv USBD_MPSAFE , 497to allow running transfer callbacks on this pipe without first acquiring 498.Dv kernel_lock . 499The 500.Fn usbd_open_pipe_intr 501takes additional arguments 502.Fa priv 503to set the default private handle. 504.Fa buffer 505and 506.Fa len 507to describe the buffer to be used, 508.Fa callback 509for the function to call at interrupt time, and finally the 510.Fa interval 511for interrupts to be delivered in milliseconds. 512The 513.Fa interval 514may be set to 515.Dv USBD_DEFAULT_INTERVAL 516use the default interval, specified by the ep. description. 517It is common to have more than one pipe per device. 518.Sh TRANSFERS 519Transfers are allocated and deallocated with 520.Fn usbd_alloc_xfer 521and 522.Fn usbd_free_xfer , 523respectively, and are associated with a pipe at their creation time. 524.Pp 525The data describing the transfer is filled by either 526.Fn usbd_setup_default_xfer 527for control pipe transfers, by 528.Fn usbd_setup_xfer 529for bulk and interrupt transfers, and by 530.Fn usbd_setup_isoc_xfer 531for isochronous transfers. 532Private data may be passed between setup and completion or status 533calls using the 534.Ft usbd_private_handle priv 535argument, which must be an integral type. 536.Pp 537Arguments to the setup functions include the newly allocated 538.Fa xfer , 539the 540.Fa pipe 541to associate this transfer with, 542the private data 543.Fa priv , 544the 545.Fa timeout 546in milliseconds, 547for control, bulk and interrupt transfers 548.Fa buffer 549the data to transfer and its 550.Fa length 551and for isochronous transfers the the frame length 552.Fa frlengths 553and number of frames 554.Fa nframes , 555and for default transfers a USB request structure 556.Fa req 557must be presented. 558See the 559.Sx INITIALISING USB REQUESTS 560section for more details on USB requests. 561.Pp 562The transfer specific 563.Fa flags 564that can be set are: 565.Bl -tag -width 10n 566.It Dv USBD_NO_COPY 567Do not copy data to DMA buffer 568.It Dv USBD_SYNCHRONOUS 569Wait for completion 570.It Dv USBD_SYNCHRONOUS_SIG 571When waiting for completion, allow signals to trigger wake up. 572.It Dv USBD_SHORT_XFER_OK 573Short reads are not an error 574.It Dv USBD_FORCE_SHORT_XFER 575Force last short packet on write 576.El 577.Pp 578To allocate buffers suitable for USB tranfers (i.e., DMA capable), the 579.Fn usbd_alloc_buffer 580function should be used on the specified 581.Fa xfer 582for 583.Fa size 584bytes of space. 585The 586.Fn usbd_free_buffer 587function can be used to free the buffer after use. 588The 589.Fn usbd_get_buffer 590function returns the current kernel address for the DMA-capable buffer 591in 592.Fa xfer . 593.Pp 594Upon completion the 595.Fa callback 596function is called, which takes the completed 597.Fa xfer , 598the private data 599.Fa priv 600originally assocated with this transfer, and 601.Fa status 602the status of this transfer. 603.Pp 604Transfers are initiated by calling 605.Fn usbd_transfer , 606and their results made be later obtained by calling 607.Fa usbd_get_xfer_status , 608which fills in the private data 609.Fa priv , 610original buffer location 611.Fa buffer , 612the length 613.Fa length , 614and the 615.Fa status 616of this request. 617.Pp 618The 619.Fn usbd_bulk_transfer 620and 621.Fn usbd_intr_transfer 622functions are used to transfer data in either an interrupt or 623bulk fashion, and are front-ends to the 624.Fn usbd_setup_xfer , 625.Fn usbd_transfer 626and 627.Fn usbd_get_xfer_status , 628as well as associated error handling. 629The 630.Fa lbl 631option is deprecated and will be removed. 632The 633.Fn usbd_sync_transfer 634is identical to 635.Fn usbd_transfer 636with the 637.Dv USBD_SYNCHRONOUS 638flag set. 639The 640.Fn usbd_sync_transfer_sig 641is identical to 642.Fn usbd_transfer 643with the 644.Dv USBD_SYNCHRONOUS 645and 646.Dv USBD_SYNCHRONOUS_SIG 647flags set. 648.Pp 649Transfers are aborted via this pipe with 650.Fn usbd_abort_pipe 651and 652.Fn usbd_abort_default_pipe . 653.Pp 654The 655.Fn usbd_clear_endpoint_stall 656and 657.Fn usbd_clear_endpoint_stall_async 658functions are used to clear endpoint halt in either a synchronous 659or asynchronous fashion. 660To clear the toggle state of an endpoint the 661.Fn usbd_clear_endpoint_toggle 662function should be used. 663.Pp 664A request is described by a 665.Va usb_device_request_t 666which must be initialised as necessary before calling either 667.Fn usbd_do_request 668or 669.Fn usbd_do_request_flags 670to submit the request. 671For both these functions 672.Fa dev 673is the handle of the USB device the request is for, 674.Fa req 675is the USB request, as described in the 676.Sx INITIALISING USB REQUESTS 677section, and then 678.Fa data 679is a buffer containing the data 680.\" (if any)???? 681for the request. 682For the 683.Fn usbd_do_request_flags 684function there are additional 685.Fa flags 686passed to the 687.Fa usbd_setup 688function, 689.Fa actlen 690a pointer to fill in with the actual length of this request, and 691.Fa timo , 692the number of milliseconds to wait before timing out this request. 693.Sh INITIALISING USB REQUESTS 694There are 5 members of a 695.Va usb_device_request_t 696that must be initialised: 697.Pp 698.Bl -item -offset offset -compact 699.It 700.Vt uByte bmRequestType ; 701.It 702.Vt uByte bRequest ; 703.It 704.Vt uWord wValue ; 705.It 706.Vt uWord wIndex ; 707.It 708.Vt uWord wLength ; 709.El 710.Pp 711The first two are normal byte values that may be simply assigned, 712but the last three must be initialised with the 713.Fn USETW 714macro. 715.Pp 716The 717.Fa bmRequestType 718holds the request type of this USB request, which describes the 719indended recipient of the request. 720.Pp 721This may be one of: 722.Bl -tag -width UT_WRITEXX -offset offset -compact 723.It Dv UT_WRITE 724.It Dv UT_READ 725.El 726.Pp 727with one of: 728.Bl -tag -width UT_STANDARDXX -offset offset -compact 729.It Dv UT_STANDARD 730.It Dv UT_CLASS 731.It Dv UT_VENDOR 732.El 733.Pp 734and with one of: 735.Bl -tag -width UT_INTERFACEXX -offset offset -compact 736.It Dv UT_DEVICE 737.It Dv UT_INTERFACE 738.It Dv UT_ENDPOINT 739.It Dv UT_OTHER 740.El 741.Pp 742These are also in combinations as: 743.Bl -tag -width UT_WRITE_VENDOR_INTERFACEXX -offset offset -compact 744.It Dv UT_READ_DEVICE 745.It Dv UT_READ_INTERFACE 746.It Dv UT_READ_ENDPOINT 747.It Dv UT_WRITE_DEVICE 748.It Dv UT_WRITE_INTERFACE 749.It Dv UT_WRITE_ENDPOINT 750.It Dv UT_READ_CLASS_DEVICE 751.It Dv UT_READ_CLASS_INTERFACE 752.It Dv UT_READ_CLASS_OTHER 753.It Dv UT_READ_CLASS_ENDPOINT 754.It Dv UT_WRITE_CLASS_DEVICE 755.It Dv UT_WRITE_CLASS_INTERFACE 756.It Dv UT_WRITE_CLASS_OTHER 757.It Dv UT_WRITE_CLASS_ENDPOINT 758.It Dv UT_READ_VENDOR_DEVICE 759.It Dv UT_READ_VENDOR_INTERFACE 760.It Dv UT_READ_VENDOR_OTHER 761.It Dv UT_READ_VENDOR_ENDPOINT 762.It Dv UT_WRITE_VENDOR_DEVICE 763.It Dv UT_WRITE_VENDOR_INTERFACE 764.It Dv UT_WRITE_VENDOR_OTHER 765.It Dv UT_WRITE_VENDOR_ENDPOINT 766.El 767.Pp 768The 769.Fa bRequest 770describes which request is being made. 771The available values are: 772.Bl -tag -width UR_GET_DESCRIPTORXX -offset offset -compact 773.It Dv UR_GET_STATUS 774.It Dv UR_CLEAR_FEATURE 775.It Dv UR_SET_FEATURE 776.It Dv UR_SET_ADDRESS 777.It Dv UR_GET_DESCRIPTOR 778.It Dv UR_SET_DESCRIPTOR 779.It Dv UR_GET_CONFIG 780.It Dv UR_SET_CONFIG 781.It Dv UR_GET_INTERFACE 782.It Dv UR_SET_INTERFACE 783.It Dv UR_SYNCH_FRAME 784.El 785.Pp 786The 787.Fa wValue , 788.Fa wIndex 789and 790.Fa wLength 791are device-specific values and must be initialised with the 792.Fn USETW 793macro. 794.Sh USB REQUEST TYPES AND STRUCTURES 795The 796.Dv UR_GET_STATUS 797request operates on a 798.Va usb_status_t 799structure, which has this member: 800.Bl -item -offset offset -compact 801.It 802.Vt uWord wStatus ; 803.El 804.Pp 805For device status requests the 806.Fa wStatus 807member may have either of these bit flags set: 808.Bl -tag -width UDS_REMOTE_WAKEUPXX -offset offset -compact 809.It Dv UDS_SELF_POWERED 810.It Dv UDS_REMOTE_WAKEUP 811.El 812.Pp 813For endpoint status requests the 814.Fa wStatus 815member may have this bit flag set: 816.Bl -tag -width UES_HALTXX -offset offset -compact 817.It Dv UES_HALT 818.El 819.Pp 820The 821.Dv UR_CLEAR_FEATURE 822and 823.Dv UR_SET_FEATURE 824requests clear or set special features on USB devices. 825The values for 826.Va wValue , 827.Va wIndex 828and 829.Va wLength 830depend upon the device and device type. 831.Pp 832The 833.Dv UR_SET_ADDRESS 834request sets the virtual USB address of a port using the 835.Va wValue . 836.Pp 837The 838.Dv UR_GET_DESCRIPTOR 839and 840.Dv UR_SET_DESCRIPTOR 841requests operate on a 842.Va usb_descriptor_t 843structure, which has these members: 844.Bl -item -offset offset -compact 845.It 846.Vt uByte bLength ; 847.It 848.Vt uByte bDescriptorType ; 849.El 850.Pp 851The 852.Fa bDescriptorType 853member may be one of the following values: 854.Bl -tag -width UDESC_OTHER_SPEED_CONFIGURATIONXX -offset offset -compact 855.It Dv UDESC_DEVICE 856.It Dv UDESC_CONFIG 857.It Dv UDESC_STRING 858.It Dv UDESC_INTERFACE 859.It Dv UDESC_ENDPOINT 860.It Dv UDESC_DEVICE_QUALIFIER 861.It Dv UDESC_OTHER_SPEED_CONFIGURATION 862.It Dv UDESC_INTERFACE_POWER 863.It Dv UDESC_OTG 864.It Dv UDESC_DEBUG 865.It Dv UDESC_INTERFACE_ASSOC 866.It Dv UDESC_CS_DEVICE 867.It Dv UDESC_CS_CONFIG 868.It Dv UDESC_CS_STRING 869.It Dv UDESC_CS_INTERFACE 870.It Dv UDESC_CS_ENDPOINT 871.It Dv UDESC_HUB 872.El 873.\".Pp 874.\" these have API front ends 875.\" .It Dv UR_GET_CONFIG 876.\" .It Dv UR_SET_CONFIG 877.\" .It Dv UR_GET_INTERFACE 878.\" .It Dv UR_SET_INTERFACE 879.\" this isn't supported 880.\" .It Dv UR_SYNCH_FRAME 881.Sh USB DEVICE DETACHMENT 882There are two functions available to ease the detach of active devices. 883Typically a reference count is maintained on syscall activity. 884When a USB device is to be detached, the reference count should be 885decremented and if it is greater or equal to zero, 886.Fn usb_detach_wait 887should be called on the 888.Ft dv 889associated with this USB device and, typically, a device-specific 890condition variable 891.Fa cv . 892and mutex 893.Fa lk 894protecting this reference count state. 895At the end of each syscall function, if the reference count is decremented 896to less than zero, then 897.Fn usb_detach_broadcast 898must be called on the 899.Ft dv 900and 901.Fa cv 902that is being waited on with 903.Fn usb_detach_wait . 904.Pp 905The are another pair of functions with similar functionality that do not 906use a condition variable or mutex and should be avoided in new code. 907The 908.Fn usb_detach_waitold 909function works like 910.Fn usb_detach_wait , 911and the 912.Fn usb_detach_wakeupold 913function works like 914.Fn usb_detach_broadcast . 915.\" XXX add an actual code example. 916.Sh USB TASK MANAGEMENT 917The USB stack provides a task management framework to execute tasks 918in a thread context at the soonest opportunity. 919Typically this is used by network drivers to handle periodic updates 920or status change requests, or other operations that need to run in 921a normal context. 922.Pp 923The 924.Fn usb_init_task 925function takes a pointer to a 926.Ft struct usb_task 927that will be initalised, a function to call for this task 928.Fa func , 929the argument to pass to 930.Fa func , 931.Fa arg , 932and the task flags 933.Fa flags . 934If the 935.Fa flags 936argument is 937.Dv USB_TASKQ_MPSAFE , 938the 939.Fa func 940function will be called without first acquiring 941.Dv kernel_lock . 942.Pp 943To invoke the task callback the 944.Fn usb_add_task 945function should be called with the 946.Fa iface 947associated with this device, the task structure 948.Fa task , 949and the 950.Fa queue 951to run against, either 952.Dv USB_TASKQ_HC 953for operations initiated by host controllers or 954.Dv USB_TASKQ_DRIVER 955for operations initiated by USB drivers. 956.Pp 957To deschedule a potentially running task the 958.Fn usb_rem_task 959function should be called. 960.Pp 961The driver using these facilities is expected to provide the 962necessary serialisation between 963.Fn usb_init_task , 964.Fn usb_add_task 965and 966.Fn usb_rem_task 967for each specific 968.Ft struct usb_task . 969.Sh SEE ALSO 970.Xr usb 4 , 971.Xr usbd_status 9 972.Sh HISTORY 973This 974.Nm 975interface first appeared in 976.Nx 1.4 . 977The interface is based on an early definition from the OpenUSBDI group 978within the USB organisation. 979Right after this definition the OpenUSBDI development got closed for open 980source developers, so this interface has not followed the further changes. 981The OpenUSBDI specification is now available again, but looks different. 982.Sh BUGS 983This manual is under development, so its biggest shortcoming is 984incompleteness. 985