1.\" 2.\" Copyright (c) 2005 Ian Dowse <iedowse@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.Dd November 14, 2016 26.Dt USBDI 9 27.Os 28.Sh NAME 29.Nm usb_fifo_alloc_buffer , 30.Nm usb_fifo_attach , 31.Nm usb_fifo_detach , 32.Nm usb_fifo_free_buffer , 33.Nm usb_fifo_get_data , 34.Nm usb_fifo_get_data_buffer , 35.Nm usb_fifo_get_data_error , 36.Nm usb_fifo_get_data_linear , 37.Nm usb_fifo_put_bytes_max , 38.Nm usb_fifo_put_data , 39.Nm usb_fifo_put_data_buffer , 40.Nm usb_fifo_put_data_error , 41.Nm usb_fifo_put_data_linear , 42.Nm usb_fifo_reset , 43.Nm usb_fifo_softc , 44.Nm usb_fifo_wakeup , 45.Nm usbd_do_request , 46.Nm usbd_do_request_flags , 47.Nm usbd_errstr , 48.Nm usbd_lookup_id_by_info , 49.Nm usbd_lookup_id_by_uaa , 50.Nm usbd_transfer_clear_stall , 51.Nm usbd_transfer_drain , 52.Nm usbd_transfer_pending , 53.Nm usbd_transfer_poll , 54.Nm usbd_transfer_setup , 55.Nm usbd_transfer_start , 56.Nm usbd_transfer_stop , 57.Nm usbd_transfer_submit , 58.Nm usbd_transfer_unsetup , 59.Nm usbd_xfer_clr_flag , 60.Nm usbd_xfer_frame_data , 61.Nm usbd_xfer_frame_len , 62.Nm usbd_xfer_get_frame , 63.Nm usbd_xfer_get_priv , 64.Nm usbd_xfer_is_stalled , 65.Nm usbd_xfer_max_framelen , 66.Nm usbd_xfer_max_frames , 67.Nm usbd_xfer_max_len , 68.Nm usbd_xfer_set_flag , 69.Nm usbd_xfer_set_frame_data , 70.Nm usbd_xfer_set_frame_len , 71.Nm usbd_xfer_set_frame_offset , 72.Nm usbd_xfer_set_frames , 73.Nm usbd_xfer_set_interval , 74.Nm usbd_xfer_set_priv , 75.Nm usbd_xfer_set_stall , 76.Nm usbd_xfer_set_timeout , 77.Nm usbd_xfer_softc , 78.Nm usbd_xfer_state , 79.Nm usbd_xfer_status 80.Nd Universal Serial Bus driver programming interface 81.Sh SYNOPSIS 82.In dev/usb/usb.h 83.In dev/usb/usbdi.h 84.In dev/usb/usbdi_util.h 85.Ft "usb_error_t" 86.Fo "usbd_transfer_setup" 87.Fa "struct usb_device *udev" 88.Fa "const uint8_t *ifaces" 89.Fa "struct usb_xfer **pxfer" 90.Fa "const struct usb_config *setup_start" 91.Fa "uint16_t n_setup" 92.Fa "void *priv_sc" 93.Fa "struct mtx *priv_mtx" 94.Fc 95.Ft "void" 96.Fo "usbd_transfer_unsetup" 97.Fa "struct usb_xfer **pxfer" 98.Fa "uint16_t n_setup" 99.Fc 100.Ft "void" 101.Fo "usbd_transfer_start" 102.Fa "struct usb_xfer *xfer" 103.Fc 104.Ft "void" 105.Fo "usbd_transfer_stop" 106.Fa "struct usb_xfer *xfer" 107.Fc 108.Ft "void" 109.Fo "usbd_transfer_drain" 110.Fa "struct usb_xfer *xfer" 111.Fc 112.Sh DESCRIPTION 113The Universal Serial Bus (USB) driver programming interface provides 114USB peripheral drivers with a host controller independent API for 115controlling and communicating with USB peripherals. 116The 117.Nm usb 118module supports both USB Host and USB Device side mode. 119.Sh USB TRANSFER MANAGEMENT FUNCTIONS 120The USB standard defines four types of USB transfers. 121. 122Control transfers, Bulk transfers, Interrupt transfers and Isochronous 123transfers. 124. 125All the transfer types are managed using the following five functions: 126. 127.Pp 128. 129.Fn usbd_transfer_setup 130This function will allocate memory for and initialise an array of USB 131transfers and all required DMA memory. 132. 133This function can sleep or block waiting for resources to become 134available. 135.Fa udev 136is a pointer to "struct usb_device". 137.Fa ifaces 138is an array of interface index numbers to use. 139See "if_index". 140.Fa pxfer 141is a pointer to an array of USB transfer pointers that are initialized 142to NULL, and then pointed to allocated USB transfers. 143.Fa setup_start 144is a pointer to an array of USB config structures. 145.Fa n_setup 146is a number telling the USB system how many USB transfers should be 147setup. 148.Fa priv_sc 149is the private softc pointer, which will be used to initialize 150"xfer->priv_sc". 151.Fa priv_mtx 152is the private mutex protecting the transfer structure and the 153softc. 154This pointer is used to initialize "xfer->priv_mtx". 155This function returns zero upon success. 156A non-zero return value indicates failure. 157. 158.Pp 159. 160.Fn usbd_transfer_unsetup 161This function will release the given USB transfers and all allocated 162resources associated with these USB transfers. 163.Fa pxfer 164is a pointer to an array of USB transfer pointers, that may be NULL, 165that should be freed by the USB system. 166.Fa n_setup 167is a number telling the USB system how many USB transfers should be 168unsetup. 169. 170This function can sleep waiting for USB transfers to complete. 171. 172This function is NULL safe with regard to the USB transfer structure 173pointer. 174. 175It is not allowed to call this function from the USB transfer 176callback. 177. 178.Pp 179. 180.Fn usbd_transfer_start 181This function will start the USB transfer pointed to by 182.Fa xfer , 183if not already started. 184. 185This function is always non-blocking and must be called with the 186so-called private USB mutex locked. 187. 188This function is NULL safe with regard to the USB transfer structure 189pointer. 190. 191.Pp 192. 193.Fn usbd_transfer_stop 194This function will stop the USB transfer pointed to by 195.Fa xfer , 196if not already stopped. 197. 198This function is always non-blocking and must be called with the 199so-called private USB mutex locked. 200. 201This function can return before the USB callback has been called. 202. 203This function is NULL safe with regard to the USB transfer structure 204pointer. 205. 206If the transfer was in progress, the callback will called with 207"USB_ST_ERROR" and "error = USB_ERR_CANCELLED". 208. 209.Pp 210. 211.Fn usbd_transfer_drain 212This function will stop an USB transfer, if not already stopped and 213wait for any additional USB hardware operations to complete. 214. 215Buffers that are loaded into DMA using "usbd_xfer_set_frame_data()" can 216safely be freed after that this function has returned. 217. 218This function can block the caller and will not return before the USB 219callback has been called. 220. 221This function is NULL safe with regard to the USB transfer structure 222pointer. 223. 224.Sh USB TRANSFER CALLBACK 225. 226The USB callback has three states. 227. 228USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. 229USB_ST_SETUP is the initial state. 230. 231After the callback has been called with this state it will always be 232called back at a later stage in one of the other two states. 233. 234The USB callback should not restart the USB transfer in case the error 235cause is USB_ERR_CANCELLED. 236. 237The USB callback is protected from recursion. 238. 239That means one can start and stop whatever transfer from the callback 240of another transfer one desires. 241. 242Also the transfer that is currently called back. 243. 244Recursion is handled like this that when the callback that wants to 245recurse returns it is called one more time. 246. 247. 248.Pp 249. 250.Fn usbd_transfer_submit 251This function should only be called from within the USB callback and 252is used to start the USB hardware. 253. 254An USB transfer can have multiple frames consisting of one or more USB 255packets making up an I/O vector for all USB transfer types. 256. 257.Bd -literal -offset indent 258void 259usb_default_callback(struct usb_xfer *xfer, usb_error_t error) 260{ 261 int actlen; 262 263 usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL); 264 265 switch (USB_GET_STATE(xfer)) { 266 case USB_ST_SETUP: 267 /* 268 * Setup xfer frame lengths/count and data 269 */ 270 usbd_transfer_submit(xfer); 271 break; 272 273 case USB_ST_TRANSFERRED: 274 /* 275 * Read usb frame data, if any. 276 * "actlen" has the total length for all frames 277 * transferred. 278 */ 279 break; 280 281 default: /* Error */ 282 /* 283 * Print error message and clear stall 284 * for example. 285 */ 286 break; 287 } 288 /* 289 * Here it is safe to do something without the private 290 * USB mutex locked. 291 */ 292 return; 293} 294.Ed 295. 296.Sh USB CONTROL TRANSFERS 297An USB control transfer has three parts. 298. 299First the SETUP packet, then DATA packet(s) and then a STATUS 300packet. 301. 302The SETUP packet is always pointed to by frame 0 and the 303length is set by 304.Fn usbd_xfer_frame_len 305also if there should not be 306sent any SETUP packet! 307If an USB control transfer has no DATA stage, 308then the number of frames should be set to 1. 309. 310Else the default number of frames is 2. 311. 312.Bd -literal -offset indent 313 314Example1: SETUP + STATUS 315 usbd_xfer_set_frames(xfer, 1); 316 usbd_xfer_set_frame_len(xfer, 0, 8); 317 usbd_transfer_submit(xfer); 318 319Example2: SETUP + DATA + STATUS 320 usbd_xfer_set_frames(xfer, 2); 321 usbd_xfer_set_frame_len(xfer, 0, 8); 322 usbd_xfer_set_frame_len(xfer, 1, 1); 323 usbd_transfer_submit(xfer); 324 325Example3: SETUP + DATA + STATUS - split 3261st callback: 327 usbd_xfer_set_frames(xfer, 1); 328 usbd_xfer_set_frame_len(xfer, 0, 8); 329 usbd_transfer_submit(xfer); 330 3312nd callback: 332 /* IMPORTANT: frbuffers[0] must still point at the setup packet! */ 333 usbd_xfer_set_frames(xfer, 2); 334 usbd_xfer_set_frame_len(xfer, 0, 0); 335 usbd_xfer_set_frame_len(xfer, 1, 1); 336 usbd_transfer_submit(xfer); 337 338Example4: SETUP + STATUS - split 3391st callback: 340 usbd_xfer_set_frames(xfer, 1); 341 usbd_xfer_set_frame_len(xfer, 0, 8); 342 usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS); 343 usbd_transfer_submit(xfer); 344 3452nd callback: 346 usbd_xfer_set_frames(xfer, 1); 347 usbd_xfer_set_frame_len(xfer, 0, 0); 348 usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS); 349 usbd_transfer_submit(xfer); 350 351.Ed 352.Sh USB TRANSFER CONFIG 353To simplify the search for endpoints the 354.Nm usb 355module defines a USB config structure where it is possible to specify 356the characteristics of the wanted endpoint. 357.Bd -literal -offset indent 358 359struct usb_config { 360 bufsize, 361 callback 362 direction, 363 endpoint, 364 frames, 365 index flags, 366 interval, 367 timeout, 368 type, 369}; 370 371.Ed 372. 373.Pp 374.Fa type 375field selects the USB pipe type. 376. 377Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK, 378UE_ISOCHRONOUS. 379. 380The special value UE_BULK_INTR will select BULK and INTERRUPT pipes. 381. 382This field is mandatory. 383. 384.Pp 385.Fa endpoint 386field selects the USB endpoint number. 387. 388A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching 389endpoint. 390. 391This field is mandatory. 392. 393.Pp 394.Fa direction 395field selects the USB endpoint direction. 396. 397A value of "UE_DIR_ANY" will select the first matching endpoint. 398. 399Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT". 400. 401"UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which 402means that the direction will be swapped in case of 403USB_MODE_DEVICE. 404. 405Note that "UE_DIR_IN" refers to the data transfer direction of the 406"IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of 407the "OUT" tokens. 408. 409This field is mandatory. 410. 411.Pp 412.Fa interval 413field selects the interrupt interval. 414. 415The value of this field is given in milliseconds and is independent of 416device speed. 417. 418Depending on the endpoint type, this field has different meaning: 419.Bl -tag -width "UE_ISOCHRONOUS" 420.It UE_INTERRUPT 421"0" use the default interrupt interval based on endpoint descriptor. 422"Else" use the given value for polling rate. 423.It UE_ISOCHRONOUS 424"0" use default. 425"Else" the value is ignored. 426.It UE_BULK 427.It UE_CONTROL 428"0" no transfer pre-delay. 429"Else" a delay as given by this field in 430milliseconds is inserted before the hardware is started when 431"usbd_transfer_submit()" is called. 432.Pp 433NOTE: The transfer timeout, if any, is started after that the 434pre-delay has elapsed! 435.El 436. 437.Pp 438.Fa timeout 439field, if non-zero, will set the transfer timeout in milliseconds. 440If the "timeout" field is zero and the transfer type is ISOCHRONOUS a 441timeout of 250ms will be used. 442. 443.Pp 444.Fa frames 445field sets the maximum number of frames. 446If zero is specified it will yield the following results: 447.Bl -tag -width "UE_INTERRUPT" 448.It UE_BULK 449xfer->nframes = 1; 450.It UE_INTERRUPT 451xfer->nframes = 1; 452.It UE_CONTROL 453xfer->nframes = 2; 454.It UE_ISOCHRONOUS 455Not allowed. 456Will cause an error. 457.El 458. 459.Pp 460.Fa ep_index 461field allows you to give a number, in case more endpoints match the 462description, that selects which matching "ep_index" should be used. 463. 464.Pp 465.Fa if_index 466field allows you to select which of the interface numbers in the 467"ifaces" array parameter passed to "usbd_transfer_setup" that should 468be used when setting up the given USB transfer. 469. 470.Pp 471.Fa flags 472field has type "struct usb_xfer_flags" and allows one to set initial 473flags an USB transfer. 474Valid flags are: 475.Bl -tag -width "force_short_xfer" 476.It force_short_xfer 477This flag forces the last transmitted USB packet to be short. 478A short packet has a length of less than "xfer->max_packet_size", which 479derives from "wMaxPacketSize". 480This flag can be changed during operation. 481.It short_xfer_ok 482This flag allows the received transfer length, "xfer->actlen" to be 483less than "xfer->sumlen" upon completion of a transfer. 484This flag can be changed during operation. 485.It short_frames_ok 486This flag allows the reception of multiple short USB frames. 487This flag 488only has effect for BULK and INTERRUPT endpoints and if the number of 489frames received is greater than 1. 490This flag can be changed during operation. 491.It pipe_bof 492This flag causes a failing USB transfer to remain first in the PIPE 493queue except in the case of "xfer->error" equal to 494"USB_ERR_CANCELLED". 495No other USB transfers in the affected PIPE queue 496will be started until either: 497.Bl -tag -width "X" 498.It 1 499The failing USB transfer is stopped using "usbd_transfer_stop()". 500.It 2 501The failing USB transfer performs a successful transfer. 502.El 503The purpose of this flag is to avoid races when multiple transfers are 504queued for execution on an USB endpoint, and the first executing 505transfer fails leading to the need for clearing of stall for 506example. 507. 508In this case this flag is used to prevent the following USB transfers 509from being executed at the same time the clear-stall command is 510executed on the USB control endpoint. 511. 512This flag can be changed during operation. 513.Pp 514"BOF" is short for "Block On Failure". 515.Pp 516NOTE: This flag should be set on all BULK and INTERRUPT USB transfers 517which use an endpoint that can be shared between userland and kernel. 518. 519. 520.It proxy_buffer 521Setting this flag will cause that the total buffer size will be 522rounded up to the nearest atomic hardware transfer size. 523. 524The maximum data length of any USB transfer is always stored in the 525"xfer->max_data_length". 526. 527For control transfers the USB kernel will allocate additional space 528for the 8-bytes of SETUP header. 529. 530These 8-bytes are not counted by the "xfer->max_data_length" 531variable. 532. 533This flag cannot be changed during operation. 534. 535. 536.It ext_buffer 537Setting this flag will cause that no data buffer will be 538allocated. 539. 540Instead the USB client must supply a data buffer. 541. 542This flag cannot be changed during operation. 543. 544. 545.It manual_status 546Setting this flag prevents an USB STATUS stage to be appended to the 547end of the USB control transfer. 548. 549If no control data is transferred this flag must be cleared. 550. 551Else an error will be returned to the USB callback. 552. 553This flag is mostly useful for the USB device side. 554. 555This flag can be changed during operation. 556. 557. 558.It no_pipe_ok 559Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. 560This flag cannot be changed during operation. 561. 562. 563.It stall_pipe 564.Bl -tag -width "Device Side Mode" 565.It Device Side Mode 566Setting this flag will cause STALL pids to be sent to the endpoint 567belonging to this transfer before the transfer is started. 568. 569The transfer is started at the moment the host issues a clear-stall 570command on the STALL'ed endpoint. 571. 572This flag can be changed during operation. 573.It Host Side Mode 574Setting this flag will cause a clear-stall control request to be 575executed on the endpoint before the USB transfer is started. 576.El 577.Pp 578If this flag is changed outside the USB callback function you have to 579use the "usbd_xfer_set_stall()" and "usbd_transfer_clear_stall()" 580functions! This flag is automatically cleared after that the stall or 581clear stall has been executed. 582. 583.It pre_scale_frames 584If this flag is set the number of frames specified is assumed to give the buffering time in milliseconds instead of frames. 585During transfer setup the frames field is pre scaled with the corresponding value for the endpoint and rounded to the nearest number of frames greater than zero. 586This option only has effect for ISOCHRONOUS transfers. 587.El 588.Pp 589.Fa bufsize 590field sets the total buffer size in bytes. 591. 592If this field is zero, "wMaxPacketSize" will be used, multiplied by 593the "frames" field if the transfer type is ISOCHRONOUS. 594. 595This is useful for setting up interrupt pipes. 596. 597This field is mandatory. 598.Pp 599NOTE: For control transfers "bufsize" includes the length of the 600request structure. 601. 602.Pp 603.Fa callback 604pointer sets the USB callback. 605This field is mandatory. 606. 607. 608.Sh USB LINUX COMPAT LAYER 609The 610.Nm usb 611module supports the Linux USB API. 612. 613. 614.Sh SEE ALSO 615.Xr libusb 3 , 616.Xr usb 4 , 617.Xr usbconfig 8 618.Sh STANDARDS 619The 620.Nm usb 621module complies with the USB 2.0 standard. 622.Sh HISTORY 623The 624.Nm usb 625module has been inspired by the NetBSD USB stack initially written by 626Lennart Augustsson. 627The 628.Nm usb 629module was written by 630.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . 631