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