1.\" $NetBSD: usbdi.9,v 1.30 2015/06/29 16:20:14 skrll 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 June 29, 2015 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.\" unused, delete? 154.\" .Fn usbd_get_interface "usbd_interface_handle iface" "uint8_t *aiface" 155.\" .Ft void 156.Fn usbd_fill_deviceinfo "usbd_device_handle dev" "struct usb_device_info *di" 157.Ft int 158.Fn usbd_get_interface_altindex "usbd_interface_handle iface" 159.Ft usb_endpoint_descriptor_t * 160.Fn usbd_get_endpoint_descriptor "usbd_interface_handle dev" \ 161 "u_int8_t address" 162.Ft usb_interface_descriptor_t * 163.Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" 164.Ft usb_endpoint_descriptor_t * 165.Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ 166 "int endptidx" 167.Ft void 168.Fn usbd_dopoll "usbd_interface_handle iface" 169.Ft void 170.Fn usbd_set_polling "usbd_device_handle iface" "int val" 171.Ft const char * 172.Fn usbd_errstr "usbd_status err" 173.Ft void 174.Fn usbd_add_dev_event "int type" "usbd_device_handle iface" 175.Ft void 176.Fn usbd_add_drv_event "int type" "usbd_device_handle iface" "device_t dv" 177.Ft char * 178.Fn usbd_devinfo_alloc "usbd_device_handle iface" "int showclass" 179.Ft void 180.Fn usbd_devinfo_free "char *str" 181.Ft const struct usbd_quirks * 182.Fn usbd_get_quirks "usbd_device_handle iface" 183.Ft usbd_status 184.Fn usbd_reload_device_desc "usbd_device_handle iface" 185.Ft int 186.Fn usbd_ratecheck "struct timeval *tv" 187.Ft usbd_status 188.Fn usbd_get_string "usbd_device_handle iface" "int si" "char *buf" 189.Ft usbd_status 190.Fn usbd_get_string0 "usbd_device_handle iface" "int si" "char *buf" \ 191 "int unicode" 192.Ft void 193.Fn usb_desc_iter_init "usbd_device_handle iface" "usbd_desc_iter_t *iter" 194.Ft const usb_descriptor_t * 195.Fn usb_desc_iter_next "usbd_desc_iter_t *iter" 196.Ft void 197.Fn usb_add_task "usbd_device_handle iface" "struct usb_task *task" \ 198 "int queue" 199.Ft void 200.Fn usb_rem_task "usbd_device_handle iface" "struct usb_task *task" 201.Ft void 202.Fn usb_init_task "struct usb_task *task" "void (*func)(void *)" \ 203 "void *arg" uint8_t flags 204.Ft const struct usb_devno * 205.Fn usb_lookup "const struct usb_devno *tbl" \ 206 "u_int16_t vendor" "u_int16_t product" 207.Ss Utilities from usbdi_util.h 208Based on the routines in 209.Dv usbdi.h 210a number of utility functions have been defined that are accessible 211through 212.Dv usbdi_util.h . 213.Ft usbd_status 214.Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \ 215 "int len" "void *desc" 216.Ft usbd_status 217.Fn usbd_get_config_desc "usbd_device_handle dev" "int confidx" \ 218 "usb_config_descriptor_t *d" 219.Ft usbd_status 220.Fn usbd_get_config_desc_full "usbd_device_handle" "int dev" "void *d" "int size" 221.Ft usbd_status 222.Fn usbd_get_device_desc "usbd_device_handle dev" \ 223 "usb_device_descriptor_t *d" 224.Ft usbd_status 225.Fn usbd_set_address "usbd_device_handle dev" "int addr" 226.Ft usbd_status 227.Fn usbd_get_port_status "usbd_device_handle dev" "int port" "usb_port_status_t *ps" 228.Ft usbd_status 229.Fn usbd_set_hub_feature "usbd_device_handle dev" "int sel" 230.Ft usbd_status 231.Fn usbd_clear_hub_feature "usbd_device_handle dev" "int sel" 232.Ft usbd_status 233.Fn usbd_set_port_feature "usbd_device_handle dev" "int port" "int sel" 234.Ft usbd_status 235.Fn usbd_clear_port_feature "usbd_device_handle dev" "int port" "int sel" 236.Ft usbd_status 237.Fn usbd_get_device_status "usbd_device_handle dev" "usb_status_t *st" 238.Ft usbd_status 239.Fn usbd_get_hub_status "usbd_device_handle dev" "usb_hub_status_t *st" 240.Ft usbd_status 241.Fn usbd_set_protocol "usbd_interface_handle dev" "int report" 242.Ft usbd_status 243.Fn usbd_get_report_descriptor "usbd_device_handle dev" "int ifcno" "int repid" "int size" "void *d" 244.Ft struct usb_hid_descriptor * 245.Fn usbd_get_hid_descriptor "usbd_interface_handle ifc" 246.Ft usbd_status 247.Fn usbd_set_report "usbd_interface_handle iface" "int type" "int id" "void *data" "int len" 248.Ft usbd_status 249.Fn usbd_set_report_async "usbd_interface_handle iface" "int type" "int id" "void *data" "int len" 250.Ft usbd_status 251.Fn usbd_get_report "usbd_interface_handle iface" "int type" "int id" "void *data" "int len" 252.Ft usbd_status 253.Fn usbd_set_idle "usbd_interface_handle iface" "int duration" "int id" 254.Ft usbd_status 255.Fn usbd_alloc_report_desc "usbd_interface_handle ifc" "void **descp" \ 256 "int *sizep" "int mem" 257.\" private API between ugen(4) and usbdi(9) 258.\" .Ft usbd_status 259.\" .Fn usbd_get_config "usbd_device_handle dev" "uint8_t *conf" 260.Ft usbd_status 261.Fn usbd_get_string_desc "usbd_device_handle dev" "int sindex" "int langid" \ 262 "usb_string_descriptor_t *sdesc" 263.Ft void 264.Fn usbd_delay_ms "usbd_device_handle dev" "u_int ms" 265.Ft usbd_status 266.Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg" 267.Ft usbd_status 268.Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg" 269.Ft usbd_status 270.Fn usbd_bulk_transfer "usbd_xfer_handle xfer" "usbd_pipe_handle pipe" \ 271 "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" "char *lbl" 272.Ft usbd_status 273.Fn usbd_intr_transfer "usbd_xfer_handle xfer" "usbd_pipe_handle pipe" \ 274 "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" "char *lbl" 275.Ft void 276.Fn usb_detach_waitold "device_t dv" 277.Ft void 278.Fn usb_detach_wakeupold "device_t dv" 279.Ft void 280.Fn usb_detach_wait "device_t dv" "kcondvar_t *cv" "kmutex_t *lk" 281.Ft void 282.Fn usb_detach_broadcast "device_t dv" "kcondvar_t *cv" 283.Sh DESCRIPTION 284Device driver access to the USB bus centers around transfers. 285A transfer describes a communication with a USB device. 286A transfer is an abstract concept that can result in several 287physical packets being transferred to or from a device. 288A transfer is described by the 289.Va usbd_xfer_handle 290cookie. 291A pipe is a logical connection to a USB device. 292It is described by the 293.Va usbd_pipe_handle 294cookie. 295See the 296.Sx TRANSFERS 297and 298.Sx PIPES 299sections for more details. 300.Pp 301There are a number of functions to obtain a handle, descriptor 302of resource count: 303.Bl -tag -width 10n 304.It Fn usbd_device2interface_handle dev ifaceno iface 305Fills in 306.Fa iface 307with the 308.Ft usbd_interface_handle 309for the USB device 310.Fa dev 311on interface number 312.Fa ifaceno . 313.It Fn usbd_interface2device_handle iface dev 314Fills in 315.Fa dev 316with the 317.Ft usbd_device_handle 318pointer for interface 319.Fa iface . 320.\" usbd_pipe2device_handle is unused; remove from usbdi? 321.It Fn usbd_pipe2device_handle pipe 322Returns the 323.Ft usbd_device_handle 324associated with 325.Fa pipe . 326.It Fn usbd_interface2endpoint_descriptor iface address 327Returns the 328.Ft usb_endpoint_descriptor_t * 329for the particular interface 330.Fa iface 331at address 332.Fa address . 333.\" XXX describe what a .Ft usb_endpoint_descriptor_t is. 334.It Fn usbd_endpoint_count dev count 335.It Fn usbd_interface_count dev count 336Fills in 337.Fa count 338with the number of endpoint or interfaces the USB device 339.Fa dev 340has. 341.El 342.Pp 343Error handling and other return values are described in 344.Xr usbd_status 9 . 345.Pp 346Additional comments on particular functions: 347.Bl -tag -width 10n 348.It Fn usbd_errstr err 349Returns the string associated with 350.Fa err . 351.It Fn usbd_add_dev_event type iface 352The 353.Ar type 354must be one of 355.Dv USB_EVENT_CTRLR_ATTACH , 356.Dv USB_EVENT_CTRLR_DETACH , 357.Dv USB_EVENT_DEVICE_ATTACH 358and 359.Dv USB_EVENT_DEVICE_DETACH . 360.It Fn usbd_add_drv_event type iface dv 361The 362.Fa type 363must be one of 364.Dv USB_EVENT_DRIVER_ATTACH 365and 366.Dv USB_EVENT_DRIVER_DETACH . 367The 368.Fa dv 369corresponds with the 370.Ft device_t 371associated with the device attached or detached. 372.It Fn usb_lookup tbl vendor product 373Lookup a USB device. 374The returned 375.Va struct usb_devno 376pointer has these members: 377.Bl -item -offset offset -compact 378.It 379.Vt u_int16_t ud_vendor ; 380.It 381.Vt u_int16_t ud_product ; 382.El 383The 384.Dv USB_PRODUCT_ANY 385macro can be used to match any USB product by a particular vendor. 386.El 387.\" 388.\" XXX functions missing descriptions in usbdi.h XXX 389.\" 390.\" .Fn usbd_get_interface_descriptor "usbd_interface_handle iface" 391.\" .Fn usbd_get_config_descriptor "usbd_device_handle dev" 392.\" .Fn usbd_get_device_descriptor "usbd_device_handle dev" 393.\" .Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno" 394.\" unused, delete? 395.\" .Fn usbd_get_interface "usbd_interface_handle iface" "uint8_t *aiface" 396.\" .Fn usbd_fill_deviceinfo "usbd_device_handle dev" "struct usb_device_info *di" 397.\" .Fn usbd_get_interface_altindex "usbd_interface_handle iface" 398.\" .Fn usbd_get_endpoint_descriptor "usbd_interface_handle dev" \ 399.\" "u_int8_t address" 400.\" .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" 401.\" .Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ 402.\" "int endptidx" 403.\" .Fn usbd_dopoll "usbd_interface_handle iface" 404.\" .Fn usbd_set_polling" usbd_device_handle iface" "int val" 405.\" 406.\" .Fn usbd_add_dev_event "int type" "usbd_device_handle iface" 407.\" .Fn usbd_add_drv_event "int type" "usbd_device_handle iface" "device_t dv" 408.\" 409.\" .Fn usbd_devinfo_alloc "usbd_device_handle iface" "int showclass" 410.\" .Fn usbd_devinfo_free "char *str" 411.\" 412.\" .Fn usbd_get_quirks "usbd_device_handle iface" 413.\" .Fn usbd_reload_device_desc "usbd_device_handle iface" 414.\" .Fn usbd_ratecheck "struct timeval *tv" 415.\" .Fn usbd_get_string "usbd_device_handle iface" "int si" "char *buf" 416.\" .Fn usbd_get_string0 "usbd_device_handle iface" "int" si "char *buf" \ 417.\" "int unicode" 418.\" 419.\" .Fn usb_desc_iter_init "usbd_device_handle iface" "usbd_desc_iter_t *iter" 420.\" .Fn usb_desc_iter_next "usbd_desc_iter_t *iter" 421.\" 422.\" XXX functions missing descriptions in usbdi.h XXX 423.\" 424.\" .Dv usbdi_util.h . 425.\" .Ft usbd_status 426.\" .Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \ 427.\" "int len" "void *desc" 428.\" .Ft usbd_status 429.\" .Fn usbd_get_config_desc "usbd_device_handle dev" "int confidx" \ 430.\" "usb_config_descriptor_t *d" 431.\" .Ft usbd_status 432.\" .Fn usbd_get_config_desc_full "usbd_device_handle" "int dev" "void *d" "int size" 433.\" .Ft usbd_status 434.\" .Fn usbd_get_device_desc "usbd_device_handle dev" \ 435.\" "usb_device_descriptor_t *d" 436.\" .Ft usbd_status 437.\" .Fn usbd_set_address "usbd_device_handle dev" "int addr" 438.\" .Ft usbd_status 439.\" .Fn usbd_get_port_status "usbd_device_handle dev" "intp ort" "usb_port_status_t *ps" 440.\" .Ft usbd_status 441.\" .Fn usbd_set_hub_feature "usbd_device_handle dev" "int sel" 442.\" .Ft usbd_status 443.\" .Fn usbd_clear_hub_feature "usbd_device_handle dev" "int sel" 444.\" .Ft usbd_status 445.\" .Fn usbd_set_port_feature "usbd_device_handle dev" "int port" "int sel" 446.\" .Ft usbd_status 447.\" .Fn usbd_clear_port_feature "usbd_device_handle dev" "int port" "int sel" 448.\" .Ft usbd_status 449.\" .Fn usbd_get_device_status "usbd_device_handle dev" "usb_status_t *st" 450.\" .Ft usbd_status 451.\" .Fn usbd_get_hub_status "usbd_device_handle dev" "usb_hub_status_t *st" 452.\" .Ft usbd_status 453.\" .Fn usbd_set_protocol "usbd_interface_handle dev" "int report" 454.\" .Ft usbd_status 455.\" .Fn usbd_get_report_descriptor "usbd_device_handle dev" "int ifcno" "int repid" "int size" "void *d" 456.\" .Ft struct usb_hid_descriptor * 457.\" .Fn usbd_get_hid_descriptor "usbd_interface_handle ifc" 458.\" .Ft usbd_status 459.\" .Fn usbd_set_report "usbd_interface_handle iface" "nt type" "int id" "void *data" "int len" 460.\" .Ft usbd_status 461.\" .Fn usbd_set_report_async "usbd_interface_handle iface" "int type" "int id" "void *data" "int len" 462.\" .Ft usbd_status 463.\" .Fn usbd_get_report "usbd_interface_handle iface" "int type" "int id" "void *data" "int len" 464.\" .Ft usbd_status 465.\" .Fn usbd_set_idle "usbd_interface_handle iface" "int duration" "int id" 466.\" .Ft usbd_status 467.\" .Fn usbd_alloc_report_desc "usbd_interface_handle ifc" "void **descp" \ 468.\" "int *sizep" "int mem" 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 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.\" these have API front ends 780.\" .It Dv UR_GET_CONFIG 781.\" api usbd_get_config() (ugen private) 782.\" .It Dv UR_SET_CONFIG 783.\" static api usbd_set_config() (usb_subr private) 784.\" .It Dv UR_GET_INTERFACE 785.\" .It Dv UR_SET_INTERFACE 786.\" this isn't supported 787.\" .It Dv UR_SYNCH_FRAME 788.El 789.Pp 790The 791.Fa wValue , 792.Fa wIndex 793and 794.Fa wLength 795are device-specific values and must be initialised with the 796.Fn USETW 797macro. 798.Sh USB REQUEST TYPES AND STRUCTURES 799The 800.Dv UR_GET_STATUS 801request operates on a 802.Va usb_status_t 803structure, which has this member: 804.Bl -item -offset offset -compact 805.It 806.Vt uWord wStatus ; 807.El 808.Pp 809For device status requests the 810.Fa wStatus 811member may have either of these bit flags set: 812.Bl -tag -width UDS_REMOTE_WAKEUPXX -offset offset -compact 813.It Dv UDS_SELF_POWERED 814.It Dv UDS_REMOTE_WAKEUP 815.El 816.Pp 817For endpoint status requests the 818.Fa wStatus 819member may have this bit flag set: 820.Bl -tag -width UES_HALTXX -offset offset -compact 821.It Dv UES_HALT 822.El 823.Pp 824The 825.Dv UR_CLEAR_FEATURE 826and 827.Dv UR_SET_FEATURE 828requests clear or set special features on USB devices. 829The values for 830.Va wValue , 831.Va wIndex 832and 833.Va wLength 834depend upon the device and device type. 835.Pp 836The 837.Dv UR_SET_ADDRESS 838request sets the virtual USB address of a port using the 839.Va wValue . 840.Pp 841The 842.Dv UR_GET_DESCRIPTOR 843and 844.Dv UR_SET_DESCRIPTOR 845requests operate on a 846.Va usb_descriptor_t 847structure, which has these members: 848.Bl -item -offset offset -compact 849.It 850.Vt uByte bLength ; 851.It 852.Vt uByte bDescriptorType ; 853.El 854.Pp 855The 856.Fa bDescriptorType 857member may be one of the following values: 858.Bl -tag -width UDESC_OTHER_SPEED_CONFIGURATIONXX -offset offset -compact 859.It Dv UDESC_DEVICE 860.It Dv UDESC_CONFIG 861.It Dv UDESC_STRING 862.It Dv UDESC_INTERFACE 863.It Dv UDESC_ENDPOINT 864.It Dv UDESC_DEVICE_QUALIFIER 865.It Dv UDESC_OTHER_SPEED_CONFIGURATION 866.It Dv UDESC_INTERFACE_POWER 867.It Dv UDESC_OTG 868.It Dv UDESC_DEBUG 869.It Dv UDESC_INTERFACE_ASSOC 870.It Dv UDESC_CS_DEVICE 871.It Dv UDESC_CS_CONFIG 872.It Dv UDESC_CS_STRING 873.It Dv UDESC_CS_INTERFACE 874.It Dv UDESC_CS_ENDPOINT 875.It Dv UDESC_HUB 876.El 877.Pp 878The 879.\" XXXMRG is the below even remotely valid? 880.Fn usbd_set_interface 881function can be used to change the index used for transfers on this 882interface as obtained via 883.Fn usbd_device2interface_handle . 884.Sh USB DEVICE DETACHMENT 885There are two functions available to ease the detach of active devices. 886Typically a reference count is maintained on syscall activity. 887When a USB device is to be detached, the reference count should be 888decremented and if it is greater or equal to zero, 889.Fn usb_detach_wait 890should be called on the 891.Ft dv 892associated with this USB device and, typically, a device-specific 893condition variable 894.Fa cv . 895and mutex 896.Fa lk 897protecting this reference count state. 898At the end of each syscall function, if the reference count is decremented 899to less than zero, then 900.Fn usb_detach_broadcast 901must be called on the 902.Ft dv 903and 904.Fa cv 905that is being waited on with 906.Fn usb_detach_wait . 907.Pp 908The are another pair of functions with similar functionality that do not 909use a condition variable or mutex and should be avoided in new code. 910The 911.Fn usb_detach_waitold 912function works like 913.Fn usb_detach_wait , 914and the 915.Fn usb_detach_wakeupold 916function works like 917.Fn usb_detach_broadcast . 918.\" XXX add an actual code example. 919.Sh USB TASK MANAGEMENT 920The USB stack provides a task management framework to execute tasks 921in a thread context at the soonest opportunity. 922Typically this is used by network drivers to handle periodic updates 923or status change requests, or other operations that need to run in 924a normal context. 925.Pp 926The 927.Fn usb_init_task 928function takes a pointer to a 929.Ft struct usb_task 930that will be initalised, a function to call for this task 931.Fa func , 932the argument to pass to 933.Fa func , 934.Fa arg , 935and the task flags 936.Fa flags . 937If the 938.Fa flags 939argument is 940.Dv USB_TASKQ_MPSAFE , 941the 942.Fa func 943function will be called without first acquiring 944.Dv kernel_lock . 945.Pp 946To invoke the task callback the 947.Fn usb_add_task 948function should be called with the 949.Fa iface 950associated with this device, the task structure 951.Fa task , 952and the 953.Fa queue 954to run against, either 955.Dv USB_TASKQ_HC 956for operations initiated by host controllers or 957.Dv USB_TASKQ_DRIVER 958for operations initiated by USB drivers. 959.Pp 960To deschedule a potentially running task the 961.Fn usb_rem_task 962function should be called. 963.Pp 964The driver using these facilities is expected to provide the 965necessary serialisation between 966.Fn usb_init_task , 967.Fn usb_add_task 968and 969.Fn usb_rem_task 970for each specific 971.Ft struct usb_task . 972.Sh SEE ALSO 973.Xr usb 4 , 974.Xr usbd_status 9 975.Sh HISTORY 976This 977.Nm 978interface first appeared in 979.Nx 1.4 . 980The interface is based on an early definition from the OpenUSBDI group 981within the USB organisation. 982Right after this definition the OpenUSBDI development got closed for open 983source developers, so this interface has not followed the further changes. 984The OpenUSBDI specification is now available again, but looks different. 985.Sh BUGS 986This manual is under development, so its biggest shortcoming is 987incompleteness. 988