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