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