share/man/man9/usbdi.9

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