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