1.\" $NetBSD: usbdi.9,v 1.37 2022/08/14 19:12:23 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.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" 28.\" Copyright (c) 1999, 2016 The NetBSD Foundation, Inc. 29.\" All rights reserved. 30.\" 31.\" This code is derived from software contributed to The NetBSD Foundation 32.\" by Lennart Augustsson and Nick Hudson. 33.\" 34.\" Redistribution and use in source and binary forms, with or without 35.\" modification, are permitted provided that the following conditions 36.\" are met: 37.\" 1. Redistributions of source code must retain the above copyright 38.\" notice, this list of conditions and the following disclaimer. 39.\" 2. Redistributions in binary form must reproduce the above copyright 40.\" notice, this list of conditions and the following disclaimer in the 41.\" documentation and/or other materials provided with the distribution. 42.\" 43.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 44.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 45.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 46.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 47.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 48.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 49.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 50.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 51.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 52.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 53.\" POSSIBILITY OF SUCH DAMAGE. 54.\" 55.Dd April 24, 2016 56.Dt USBDI 9 57.Os 58.Sh NAME 59.Nm usbdi 60.Nd USB device drivers interface 61.Sh SYNOPSIS 62.In dev/usb/usb.h 63.In dev/usb/usbdi.h 64.In dev/usb/usbdi_util.h 65.Ss Functions offered by usbdi.h 66.Ft usbd_status 67.Fn usbd_open_pipe "struct usbd_interface *iface" "uint8_t address" \ 68 "uint8_t flags" "struct usbd_pipe **pipe" 69.Ft usbd_status 70.Fn usbd_close_pipe "struct usbd_pipe *pipe" 71.Ft usbd_status 72.Fn usbd_transfer "struct usbd_xfer *xfer" 73.Ft struct usbd_xfer * 74.Fn usbd_setup_xfer "struct usbd_xfer *xfer" \ 75 "void *priv" "void *buffer" "uint32_t length" \ 76 "uint16_t flags" "uint32_t timeout" "usbd_callback" 77.Ft void 78.Fn usbd_setup_default_xfer "struct usbd_xfer *xfer" \ 79 "struct usbd_device *dev" "void *priv" \ 80 "uint32_t timeout" "usb_device_request_t *req" " void *buffer" \ 81 "uint32_t length" "uint16_t flags" "usbd_callback" 82.Ft void 83.Fn usbd_setup_isoc_xfer "struct usbd_xfer *xfer" \ 84 "void *priv" "uint16_t *frlengths" \ 85 "uint32_t nframes" "uint16_t flags" "usbd_callback" 86.Ft void 87.Fn usbd_get_xfer_status "struct usbd_xfer *xfer" "void **priv" \ 88 "void **buffer" "uint32_t *count" "usbd_status *status" 89.Ft usb_endpoint_descriptor_t * 90.Fn usbd_interface2endpoint_descriptor "struct usbd_interface *iface" \ 91 "uint8_t address" 92.Ft usbd_status 93.Fn usbd_abort_pipe "struct usbd_pipe *pipe" 94.Ft usbd_status 95.Fn usbd_abort_default_pipe "struct usbd_device *dev" 96.Ft usbd_status 97.Fn usbd_clear_endpoint_stall "struct usbd_pipe *pipe" 98.Ft usbd_status 99.Fn usbd_clear_endpoint_stall_async "struct usbd_pipe *pipe" 100.Ft void 101.Fn usbd_clear_endpoint_toggle "struct usbd_pipe *pipe" 102.Ft usbd_status 103.Fn usbd_endpoint_count "struct usbd_interface *dev" "uint8_t *count" 104.Ft usbd_status 105.Fn usbd_interface_count "struct usbd_device *dev" "uint8_t *count" 106.Ft usbd_status 107.Fn usbd_interface2device_handle "struct usbd_interface *iface" "struct usbd_device **dev" 108.Ft usbd_status 109.Fn usbd_device2interface_handle "struct usbd_device *dev" "uint8_t ifaceno" "struct usbd_interface **iface" 110.Pp 111.Ft struct usbd_device * 112.Fn usbd_pipe2device_handle "struct usbd_pipe *pipe" 113.Ft int 114.Fn usbd_create_xfer "struct usbd_pipe *pipe" "size_t len" \ 115"unsigned int flags" "unsigned int nframes" "struct usbd_xfer **xp" 116.Ft void 117.Fn usbd_destroy_xfer "struct usbd_xfer *xfer" 118.Ft void * 119.Fn usbd_get_buffer "struct usbd_xfer *xfer" 120.Ft usbd_status 121.Fn usbd_sync_transfer "struct usbd_xfer *req" 122.Ft usbd_status 123.Fn usbd_sync_transfer_sig "struct usbd_xfer *req" 124.Ft usbd_status 125.Fn usbd_open_pipe_intr "struct usbd_interface *iface" "uint8_t address" \ 126 "uint8_t flags" "struct usbd_pipe **pipe" \ 127 "void *priv" "void *buffer" \ 128 "uint32_t length" "usbd_callback callback" "int interval" 129.Ft usbd_status 130.Fn usbd_do_request "struct usbd_device *dev" "usb_device_request_t *req" \ 131 "void *data" 132.Ft usbd_status 133.Fn usbd_do_request_flags "struct usbd_device *dev" \ 134 "usb_device_request_t *req" "void *data" "uint16_t flags" "int *actlen" \ 135 "uint32_t timo" 136.Ft usb_interface_descriptor_t * 137.Fn usbd_get_interface_descriptor "struct usbd_interface *iface" 138.Ft usb_config_descriptor_t * 139.Fn usbd_get_config_descriptor "struct usbd_device *dev" 140.Ft usb_device_descriptor_t * 141.Fn usbd_get_device_descriptor "struct usbd_device *dev" 142.Ft usbd_status 143.Fn usbd_set_interface "struct usbd_interface *iface" "int altidx" 144.Ft int 145.Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno" 146.Ft usbd_status 147.\" unused, delete? 148.\" .Fn usbd_get_interface "struct usbd_interface *iface" "uint8_t *aiface" 149.\" .Ft void 150.Fn usbd_fill_deviceinfo "struct usbd_device *dev" "struct usb_device_info *di" 151.Ft int 152.Fn usbd_get_interface_altindex "struct usbd_interface *iface" 153.Ft usb_endpoint_descriptor_t * 154.Fn usbd_get_endpoint_descriptor "struct usbd_interface *dev" \ 155 "uint8_t address" 156.Ft usb_interface_descriptor_t * 157.Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" 158.Ft usb_endpoint_descriptor_t * 159.Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ 160 "int endptidx" 161.Ft void 162.Fn usbd_dopoll "struct usbd_interface *iface" 163.Ft void 164.Fn usbd_set_polling "struct usbd_device *iface" "int val" 165.Ft const char * 166.Fn usbd_errstr "usbd_status err" 167.Ft void 168.Fn usbd_add_dev_event "int type" "struct usbd_device *iface" 169.Ft void 170.Fn usbd_add_drv_event "int type" "struct usbd_device *iface" "device_t dv" 171.Ft char * 172.Fn usbd_devinfo_alloc "struct usbd_device *iface" "int showclass" 173.Ft void 174.Fn usbd_devinfo_free "char *str" 175.Ft const struct usbd_quirks * 176.Fn usbd_get_quirks "struct usbd_device *iface" 177.Ft usbd_status 178.Fn usbd_reload_device_desc "struct usbd_device *iface" 179.Ft int 180.Fn usbd_ratecheck "struct timeval *tv" 181.Ft usbd_status 182.Fn usbd_get_string "struct usbd_device *iface" "int si" "char *buf" 183.Ft usbd_status 184.Fn usbd_get_string0 "struct usbd_device *iface" "int si" "char *buf" \ 185 "int unicode" 186.Ft void 187.Fn usb_desc_iter_init "struct usbd_device *iface" "usbd_desc_iter_t *iter" 188.Ft const usb_descriptor_t * 189.Fn usb_desc_iter_next "usbd_desc_iter_t *iter" 190.Ft void 191.Fn usb_add_task "struct usbd_device *iface" "struct usb_task *task" \ 192 "int queue" 193.Ft void 194.Fn usb_rem_task "struct usbd_device *iface" "struct usb_task *task" 195.Ft void 196.Fn usb_init_task "struct usb_task *task" "void (*func)(void *)" \ 197 "void *arg" uint8_t flags 198.Ft const struct usb_devno * 199.Fn usb_lookup "const struct usb_devno *tbl" \ 200 "uint16_t vendor" "uint16_t product" 201.Ss Obsolete functions 202The following functions have been obsoleted from 203.Dv usbdi.h . 204.Ft void * 205.Fn usbd_alloc_buffer "struct usbd_xfer *xfer" "uint32_t size" 206.Ft void 207.Fn usbd_free_buffer "struct usbd_xfer *xfer" 208.Ss Utilities from usbdi_util.h 209Based on the routines in 210.Dv usbdi.h 211a number of utility functions have been defined that are accessible 212through 213.Dv usbdi_util.h . 214.Ft usbd_status 215.Fn usbd_get_desc "struct usbd_device *dev" "int type" "int index" \ 216 "int len" "void *desc" 217.Ft usbd_status 218.Fn usbd_get_config_desc "struct usbd_device *dev" "int confidx" \ 219 "usb_config_descriptor_t *d" 220.Ft usbd_status 221.Fn usbd_get_config_desc_full "struct usbd_device *" "int dev" "void *d" "int size" 222.Ft usbd_status 223.Fn usbd_get_device_desc "struct usbd_device *dev" \ 224 "usb_device_descriptor_t *d" 225.Ft usbd_status 226.Fn usbd_set_address "struct usbd_device *dev" "int addr" 227.Ft usbd_status 228.Fn usbd_get_port_status "struct usbd_device *dev" "int port" "usb_port_status_t *ps" 229.Ft usbd_status 230.Fn usbd_set_hub_feature "struct usbd_device *dev" "int sel" 231.Ft usbd_status 232.Fn usbd_clear_hub_feature "struct usbd_device *dev" "int sel" 233.Ft usbd_status 234.Fn usbd_set_port_feature "struct usbd_device *dev" "int port" "int sel" 235.Ft usbd_status 236.Fn usbd_clear_port_feature "struct usbd_device *dev" "int port" "int sel" 237.Ft usbd_status 238.Fn usbd_get_device_status "struct usbd_device *dev" "usb_status_t *st" 239.Ft usbd_status 240.Fn usbd_get_hub_status "struct usbd_device *dev" "usb_hub_status_t *st" 241.Ft usbd_status 242.Fn usbd_set_protocol "struct usbd_interface *dev" "int report" 243.Ft usbd_status 244.Fn usbd_get_report_descriptor "struct usbd_device *dev" "int ifcno" "int repid" "int size" "void *d" 245.Ft struct usb_hid_descriptor * 246.Fn usbd_get_hid_descriptor "struct usbd_interface *ifc" 247.Ft usbd_status 248.Fn usbd_set_report "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" 249.Ft usbd_status 250.Fn usbd_set_report_async "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" 251.Ft usbd_status 252.Fn usbd_get_report "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" 253.Ft usbd_status 254.Fn usbd_set_idle "struct usbd_interface *iface" "int duration" "int id" 255.Ft usbd_status 256.Fn usbd_alloc_report_desc "struct usbd_interface *ifc" "void **descp" \ 257 "int *sizep" "int mem" 258.\" private API between ugen(4) and usbdi(9) 259.\" .Ft usbd_status 260.\" .Fn usbd_get_config "struct usbd_device *dev" "uint8_t *conf" 261.Ft usbd_status 262.Fn usbd_get_string_desc "struct usbd_device *dev" "int sindex" "int langid" \ 263 "usb_string_descriptor_t *sdesc" 264.Ft void 265.Fn usbd_delay_ms "struct usbd_device *dev" "u_int ms" 266.Ft usbd_status 267.Fn usbd_set_config_no "struct usbd_device *dev" "int no" "int msg" 268.Ft usbd_status 269.Fn usbd_set_config_index "struct usbd_device *dev" "int index" "int msg" 270.Ft usbd_status 271.Fn usbd_bulk_transfer "struct usbd_xfer *xfer" "struct usbd_pipe *pipe" \ 272 "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" 273.Ft usbd_status 274.Fn usbd_intr_transfer "struct usbd_xfer *xfer" "struct usbd_pipe *pipe" \ 275 "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" 276.Ft void 277.Fn usb_detach_waitold "device_t dv" 278.Ft void 279.Fn usb_detach_wakeupold "device_t dv" 280.Ft void 281.Fn usb_detach_wait "device_t dv" "kcondvar_t *cv" "kmutex_t *lk" 282.Ft void 283.Fn usb_detach_broadcast "device_t dv" "kcondvar_t *cv" 284.Sh DESCRIPTION 285Device driver access to the USB bus centers around transfers. 286A transfer describes a communication with a USB device. 287A transfer is an abstract concept that can result in several 288physical packets being transferred to or from a device. 289A transfer is described by the 290.Va struct usbd_xfer * 291cookie. 292A pipe is a logical connection to a USB device. 293It is described by the 294.Va struct usbd_pipe * 295cookie. 296See the 297.Sx TRANSFERS 298and 299.Sx PIPES 300sections for more details. 301.Pp 302There are a number of functions to obtain a handle, descriptor 303or resource count: 304.Bl -tag -width 10n 305.It Fn usbd_device2interface_handle dev ifaceno iface 306Fills in 307.Fa iface 308with the 309.Ft struct usbd_interface * 310for the USB device 311.Fa dev 312on interface number 313.Fa ifaceno . 314.It Fn usbd_interface2device_handle iface dev 315Fills in 316.Fa dev 317with the 318.Ft struct usbd_device * 319pointer for interface 320.Fa iface . 321.\" usbd_pipe2device_handle is unused; remove from usbdi? 322.It Fn usbd_pipe2device_handle pipe 323Returns the 324.Ft struct usbd_device * 325associated with 326.Fa pipe . 327.It Fn usbd_interface2endpoint_descriptor iface address 328Returns the 329.Ft usb_endpoint_descriptor_t * 330for the particular interface 331.Fa iface 332at address 333.Fa address . 334.\" XXX describe what a .Ft usb_endpoint_descriptor_t is. 335.It Fn usbd_endpoint_count dev count 336.It Fn usbd_interface_count dev count 337Fills in 338.Fa count 339with the number of endpoint or interfaces the USB device 340.Fa dev 341has. 342.El 343.Pp 344Error handling and other return values are described in 345.Xr usbd_status 9 . 346.Pp 347Additional comments on particular functions: 348.Bl -tag -width 10n 349.It Fn usbd_errstr err 350Returns the string associated with 351.Fa err . 352.It Fn usbd_add_dev_event type iface 353The 354.Ar type 355must be one of 356.Dv USB_EVENT_CTRLR_ATTACH , 357.Dv USB_EVENT_CTRLR_DETACH , 358.Dv USB_EVENT_DEVICE_ATTACH 359and 360.Dv USB_EVENT_DEVICE_DETACH . 361.It Fn usbd_add_drv_event type iface dv 362The 363.Fa type 364must be one of 365.Dv USB_EVENT_DRIVER_ATTACH 366and 367.Dv USB_EVENT_DRIVER_DETACH . 368The 369.Fa dv 370corresponds with the 371.Ft device_t 372associated with the device attached or detached. 373.It Fn usb_lookup tbl vendor product 374Lookup a USB device. 375The returned 376.Va struct usb_devno 377pointer has these members: 378.Bl -item -offset offset -compact 379.It 380.Vt uint16_t ud_vendor ; 381.It 382.Vt uint16_t ud_product ; 383.El 384The 385.Dv USB_PRODUCT_ANY 386macro can be used to match any USB product by a particular vendor. 387.El 388.\" 389.\" XXX functions missing descriptions in usbdi.h XXX 390.\" 391.\" .Fn usbd_get_interface_descriptor "struct usbd_interface *iface" 392.\" .Fn usbd_get_config_descriptor "struct usbd_device *dev" 393.\" .Fn usbd_get_device_descriptor "struct usbd_device *dev" 394.\" .Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno" 395.\" unused, delete? 396.\" .Fn usbd_get_interface "struct usbd_interface *iface" "uint8_t *aiface" 397.\" .Fn usbd_fill_deviceinfo "struct usbd_device *dev" "struct usb_device_info *di" 398.\" .Fn usbd_get_interface_altindex "struct usbd_interface *iface" 399.\" .Fn usbd_get_endpoint_descriptor "struct usbd_interface *dev" \ 400.\" "uint8_t address" 401.\" .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" 402.\" .Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ 403.\" "int endptidx" 404.\" .Fn usbd_dopoll "struct usbd_interface *iface" 405.\" .Fn usbd_set_polling" struct usbd_device *iface" "int val" 406.\" 407.\" .Fn usbd_add_dev_event "int type" "struct usbd_device *iface" 408.\" .Fn usbd_add_drv_event "int type" "struct usbd_device *iface" "device_t dv" 409.\" 410.\" .Fn usbd_devinfo_alloc "struct usbd_device *iface" "int showclass" 411.\" .Fn usbd_devinfo_free "char *str" 412.\" 413.\" .Fn usbd_get_quirks "struct usbd_device *iface" 414.\" .Fn usbd_reload_device_desc "struct usbd_device *iface" 415.\" .Fn usbd_ratecheck "struct timeval *tv" 416.\" .Fn usbd_get_string "struct usbd_device *iface" "int si" "char *buf" 417.\" .Fn usbd_get_string0 "struct usbd_device *iface" "int" si "char *buf" \ 418.\" "int unicode" 419.\" 420.\" .Fn usb_desc_iter_init "struct usbd_device *iface" "usbd_desc_iter_t *iter" 421.\" .Fn usb_desc_iter_next "usbd_desc_iter_t *iter" 422.\" 423.\" XXX functions missing descriptions in usbdi.h XXX 424.\" 425.\" .Dv usbdi_util.h . 426.\" .Ft usbd_status 427.\" .Fn usbd_get_desc "struct usbd_device *dev" "int type" "int index" \ 428.\" "int len" "void *desc" 429.\" .Ft usbd_status 430.\" .Fn usbd_get_config_desc "struct usbd_device *dev" "int confidx" \ 431.\" "usb_config_descriptor_t *d" 432.\" .Ft usbd_status 433.\" .Fn usbd_get_config_desc_full "struct usbd_device *" "int dev" "void *d" "int size" 434.\" .Ft usbd_status 435.\" .Fn usbd_get_device_desc "struct usbd_device *dev" \ 436.\" "usb_device_descriptor_t *d" 437.\" .Ft usbd_status 438.\" .Fn usbd_set_address "struct usbd_device *dev" "int addr" 439.\" .Ft usbd_status 440.\" .Fn usbd_get_port_status "struct usbd_device *dev" "intp ort" "usb_port_status_t *ps" 441.\" .Ft usbd_status 442.\" .Fn usbd_set_hub_feature "struct usbd_device *dev" "int sel" 443.\" .Ft usbd_status 444.\" .Fn usbd_clear_hub_feature "struct usbd_device *dev" "int sel" 445.\" .Ft usbd_status 446.\" .Fn usbd_set_port_feature "struct usbd_device *dev" "int port" "int sel" 447.\" .Ft usbd_status 448.\" .Fn usbd_clear_port_feature "struct usbd_device *dev" "int port" "int sel" 449.\" .Ft usbd_status 450.\" .Fn usbd_get_device_status "struct usbd_device *dev" "usb_status_t *st" 451.\" .Ft usbd_status 452.\" .Fn usbd_get_hub_status "struct usbd_device *dev" "usb_hub_status_t *st" 453.\" .Ft usbd_status 454.\" .Fn usbd_set_protocol "struct usbd_interface *dev" "int report" 455.\" .Ft usbd_status 456.\" .Fn usbd_get_report_descriptor "struct usbd_device *dev" "int ifcno" "int repid" "int size" "void *d" 457.\" .Ft struct usb_hid_descriptor * 458.\" .Fn usbd_get_hid_descriptor "struct usbd_interface *ifc" 459.\" .Ft usbd_status 460.\" .Fn usbd_set_report "struct usbd_interface *iface" "nt type" "int id" "void *data" "int len" 461.\" .Ft usbd_status 462.\" .Fn usbd_set_report_async "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" 463.\" .Ft usbd_status 464.\" .Fn usbd_get_report "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" 465.\" .Ft usbd_status 466.\" .Fn usbd_set_idle "struct usbd_interface *iface" "int duration" "int id" 467.\" .Ft usbd_status 468.\" .Fn usbd_alloc_report_desc "struct usbd_interface *ifc" "void **descp" \ 469.\" "int *sizep" "int mem" 470.\" .Ft usbd_status 471.\" .Fn usbd_get_string_desc "struct usbd_device *dev" "int sindex" "int langid" \ 472.\" "usb_string_descriptor_t *sdesc" 473.\" .Ft void 474.\" .Fn usbd_delay_ms "struct usbd_device *dev" "u_int ms" 475.\" .Ft usbd_status 476.\" .Fn usbd_set_config_no "struct usbd_device *dev" "int no" "int msg" 477.\" .Ft usbd_status 478.\" .Fn usbd_set_config_index "struct usbd_device *dev" "int index" "int msg" 479.\" .Ft usbd_status 480.\" 481.Sh PIPES 482Pipes are created and destroyed by using the 483.Fn usbd_open_pipe , 484.Fn usbd_open_pipe_intr 485and 486.Fn usbd_close_pipe 487functions. 488The open functions take the interface handle 489.Fa iface , 490the 491.Fa address 492of this pipe and 493.Fa flags 494for this pipe which currently may be 0, or a combination of 495.Dv USBD_EXCLUSIVE_USE , 496to enable exclusive access to this interface and address, and 497.Dv USBD_MPSAFE , 498to allow running transfer callbacks on this pipe without first acquiring 499.Dv kernel_lock . 500The 501.Fn usbd_open_pipe_intr 502takes additional arguments 503.Fa priv 504to set the default private handle. 505.Fa buffer 506and 507.Fa len 508to describe the buffer to be used, 509.Fa callback 510for the function to call at interrupt time, and finally the 511.Fa interval 512for interrupts to be delivered in milliseconds. 513The 514.Fa interval 515may be set to 516.Dv USBD_DEFAULT_INTERVAL 517use the default interval, specified by the ep. description. 518It is common to have more than one pipe per device. 519.Sh TRANSFERS 520Transfers are created and destroyed with 521.Fn usbd_create_xfer 522and 523.Fn usbd_destroy_xfer , 524respectively, and are associated with a pipe at their creation time. 525The create function takes the pipe handle 526.Fa pipe , 527the length of the largest transfer possible 528.Fa len , 529possible transfer flags 530.Fa flags , 531the number of isochronous frames (or 0) in 532.Fa nframes . 533.Pp 534The data describing the transfer is filled by either 535.Fn usbd_setup_default_xfer 536for control pipe transfers, by 537.Fn usbd_setup_xfer 538for bulk and interrupt transfers, and by 539.Fn usbd_setup_isoc_xfer 540for isochronous transfers. 541Private data may be passed between setup and completion or status 542calls using the 543.Ft void *priv 544argument. 545.Pp 546Arguments to the setup functions include the newly allocated 547.Fa xfer , 548the private data 549.Fa priv , 550the 551.Fa timeout 552in milliseconds, 553for control, bulk and interrupt transfers 554.Fa buffer 555the data to transfer and its 556.Fa length 557and for isochronous transfers the frame length 558.Fa frlengths 559and number of frames 560.Fa nframes , 561and for default transfers a USB request structure 562.Fa req 563must be presented. 564See the 565.Sx INITIALISING USB REQUESTS 566section for more details on USB requests. 567.Pp 568The transfer specific 569.Fa flags 570that can be set are: 571.Bl -tag -width 10n 572.It Dv USBD_SYNCHRONOUS 573Wait for completion 574.It Dv USBD_SYNCHRONOUS_SIG 575When waiting for completion, allow signals to trigger wake up. 576.It Dv USBD_SHORT_XFER_OK 577Short reads are not an error 578.It Dv USBD_FORCE_SHORT_XFER 579Force last short packet on write 580.El 581.Pp 582The 583.Fn usbd_get_buffer 584function returns the current kernel address for the buffer suitable for 585transfer in 586.Fa xfer . 587.Pp 588The 589.Fn usbd_open_pipe , 590.Fn usbd_open_pipe_intr , 591.Fn usbd_close_pipe , 592.Fn usbd_alloc_xfer , 593and 594.Fn usbd_free_xfer 595can all sleep and should not be called from interrupt context as a result. 596.Pp 597Upon completion the 598.Fa callback 599function is called, which takes the completed 600.Fa xfer , 601the private data 602.Fa priv 603originally associated with this transfer, and 604.Fa status 605the status of this transfer. 606.Pp 607Transfers are initiated by calling 608.Fn usbd_transfer , 609and their results made be later obtained by calling 610.Fa usbd_get_xfer_status , 611which fills in the private data 612.Fa priv , 613original buffer location 614.Fa buffer , 615the length 616.Fa length , 617and the 618.Fa status 619of this request. 620.Pp 621The 622.Fn usbd_bulk_transfer 623and 624.Fn usbd_intr_transfer 625functions are used to transfer data in either an interrupt or 626bulk fashion, and are front-ends to the 627.Fn usbd_setup_xfer , 628.Fn usbd_transfer 629and 630.Fn usbd_get_xfer_status , 631as well as associated error handling. 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 719intended 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 initialised, 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