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