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