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