2 .\" Copyright (c) 2005 Ian Dowse <iedowse@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
31 .Nm usb_fifo_alloc_buffer ,
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 ,
48 .Nm usbd_do_request_flags ,
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 ,
82 .Nd Universal Serial Bus driver programming interface
86 .In dev/usb/usbdi_util.h
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.
93 module supports both USB Host and USB Device side mode.
95 .Sh USB KERNEL PROGRAMMING
96 Here is a list of commonly used functions:
100 .Fo "usbd_transfer_setup"
113 .Fo "usbd_transfer_unsetup"
121 .Fo "usbd_transfer_start"
128 .Fo "usbd_transfer_stop"
135 .Fo "usbd_transfer_drain"
141 .Sh USB TRANSFER MANAGEMENT FUNCTIONS
142 The USB standard defines four types of USB transfers.
144 Control transfers, Bulk transfers, Interrupt transfers and Isochronous
147 All the transfer types are managed using the following five functions:
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.
155 This function can sleep or block waiting for resources to become
158 is a pointer to "struct usb_device".
160 is an array of interface index numbers to use. See "if_index".
162 is a pointer to an array of USB transfer pointers that are initialized
163 to NULL, and then pointed to allocated USB transfers.
165 is a pointer to an array of USB config structures.
167 is a number telling the USB system how many USB transfers should be
170 is the private softc pointer, which will be used to initialize
173 is the private mutex protecting the transfer structure and the
174 softc. This pointer is used to initialize "xfer->priv_mtx".
175 This function returns
176 zero upon success. A non-zero return value indicates failure.
180 .Fn usbd_transfer_unsetup
181 This function will release the given USB transfers and all allocated
182 resources associated with these USB transfers.
184 is a pointer to an array of USB transfer pointers, that may be NULL,
185 that should be freed by the USB system.
187 is a number telling the USB system how many USB transfers should be
190 This function can sleep waiting for USB transfers to complete.
192 This function is NULL safe with regard to the USB transfer structure
195 It is not allowed to call this function from the USB transfer
200 .Fn usbd_transfer_start
201 This function will start the USB transfer pointed to by
203 if not already started.
205 This function is always non-blocking and must be called with the
206 so-called private USB mutex locked.
208 This function is NULL safe with regard to the USB transfer structure
213 .Fn usbd_transfer_stop
214 This function will stop the USB transfer pointed to by
216 if not already stopped.
218 This function is always non-blocking and must be called with the
219 so-called private USB mutex locked.
221 This function can return before the USB callback has been called.
223 This function is NULL safe with regard to the USB transfer structure
226 If the transfer was in progress, the callback will called with
227 "USB_ST_ERROR" and "error = USB_ERR_CANCELLED".
231 .Fn usbd_transfer_drain
232 This function will stop an USB transfer, if not already stopped and
233 wait for any additional USB hardware operations to complete.
235 Buffers that are loaded into DMA using "usbd_xfer_set_frame_data()" can
236 safely be freed after that this function has returned.
238 This function can block the caller and will not return before the USB
239 callback has been called.
241 This function is NULL safe with regard to the USB transfer structure
244 .Sh USB TRANSFER CALLBACK
246 The USB callback has three states.
248 USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the
251 After the callback has been called with this state it will always be
252 called back at a later stage in one of the other two states.
254 The USB callback should not restart the USB transfer in case the error
255 cause is USB_ERR_CANCELLED.
257 The USB callback is protected from recursion.
259 That means one can start and stop whatever transfer from the callback
260 of another transfer one desires.
262 Also the transfer that is currently called back.
264 Recursion is handled like this that when the callback that wants to
265 recurse returns it is called one more time.
270 .Fn usbd_transfer_submit
271 This function should only be called from within the USB callback and
272 is used to start the USB hardware.
274 An USB transfer can have multiple frames consisting of one or more USB
275 packets making up an I/O vector for all USB transfer types.
277 .Bd -literal -offset indent
279 usb_default_callback(struct usb_xfer *xfer, usb_error_t error)
283 usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL);
285 switch (USB_GET_STATE(xfer)) {
288 * Setup xfer frame lengths/count and data
290 usbd_transfer_submit(xfer);
293 case USB_ST_TRANSFERRED:
295 * Read usb frame data, if any.
296 * "actlen" has the total length for all frames
303 * Print error message and clear stall
309 * Here it is safe to do something without the private
316 .Sh USB CONTROL TRANSFERS
317 An USB control transfer has three parts.
319 First the SETUP packet, then DATA packet(s) and then a STATUS
322 The SETUP packet is always pointed to by frame 0 and the
324 .Fn usbd_xfer_frame_len
325 also if there should not be
326 sent any SETUP packet! If an USB control transfer has no DATA stage,
327 then the number of frames should be set to 1.
329 Else the default number of frames is 2.
331 .Bd -literal -offset indent
333 Example1: SETUP + STATUS
334 usbd_xfer_set_frames(xfer, 1);
335 usbd_xfer_set_frame_len(xfer, 0, 8);
336 usbd_transfer_submit(xfer);
338 Example2: 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);
344 Example3: SETUP + DATA + STATUS - split
346 usbd_xfer_set_frames(xfer, 1);
347 usbd_xfer_set_frame_len(xfer, 0, 8);
348 usbd_transfer_submit(xfer);
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);
357 Example4: SETUP + STATUS - split
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);
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);
371 .Sh USB TRANSFER CONFIG
372 To simply the search for endpoints the
374 module defines a USB config structure where it is possible to specify
375 the characteristics of the wanted endpoint.
376 .Bd -literal -offset indent
394 field selects the USB pipe type.
396 Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK,
399 The special value UE_BULK_INTR will select BULK and INTERRUPT pipes.
401 This field is mandatory.
405 field selects the USB endpoint number.
407 A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching
410 This field is mandatory.
414 field selects the USB endpoint direction.
416 A value of "UE_DIR_ANY" will select the first matching endpoint.
418 Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT".
420 "UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which
421 means that the direction will be swapped in case of
424 Note 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
428 This field is mandatory.
432 field selects the interrupt interval.
434 The value of this field is given in milliseconds and is independent of
437 Depending on the endpoint type, this field has different meaning:
438 .Bl -tag -width "UE_ISOCHRONOUS"
440 "0" use the default interrupt interval based on endpoint descriptor.
441 "Else" use the given value for polling rate.
443 "0" use default. "Else" the value is ignored.
446 "0" no transfer pre-delay. "Else" a delay as given by this field in
447 milliseconds is inserted before the hardware is started when
448 "usbd_transfer_submit()" is called.
450 NOTE: The transfer timeout, if any, is started after that the
451 pre-delay has elapsed!
456 field, if non-zero, will set the transfer timeout in milliseconds. If
457 the "timeout" field is zero and the transfer type is ISOCHRONOUS a
458 timeout of 250ms will be used.
462 field sets the maximum number of frames. If zero is specified it will
463 yield the following results:
464 .Bl -tag -width "UE_INTERRUPT"
472 Not allowed. Will cause an error.
477 field allows you to give a number, in case more endpoints match the
478 description, that selects which matching "ep_index" should be used.
482 field allows you to select which of the interface numbers in the
483 "ifaces" array parameter passed to "usbd_transfer_setup" that should
484 be used when setting up the given USB transfer.
488 field has type "struct usb_xfer_flags" and allows one to set initial
489 flags an USB transfer. Valid flags are:
490 .Bl -tag -width "force_short_xfer"
492 This flag forces the last transmitted USB packet to be short. A short
493 packet has a length of less than "xfer->max_packet_size", which
494 derives from "wMaxPacketSize". This flag can be changed during
497 This flag allows the received transfer length, "xfer->actlen" to be
498 less than "xfer->sumlen" upon completion of a transfer. This flag can
499 be changed during operation.
501 This flag allows the reception of multiple short USB frames. This flag
502 only has effect for BULK and INTERRUPT endpoints and if the number of
503 frames received is greater than 1. This flag can be changed during
506 This flag causes a failing USB transfer to remain first in the PIPE
507 queue except in the case of "xfer->error" equal to
508 "USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue
509 will be started until either:
512 The failing USB transfer is stopped using "usbd_transfer_stop()".
514 The failing USB transfer performs a successful transfer.
516 The purpose of this flag is to avoid races when multiple transfers are
517 queued for execution on an USB endpoint, and the first executing
518 transfer fails leading to the need for clearing of stall for
521 In this case this flag is used to prevent the following USB transfers
522 from being executed at the same time the clear-stall command is
523 executed on the USB control endpoint.
525 This flag can be changed during operation.
527 "BOF" is short for "Block On Failure".
529 NOTE: This flag should be set on all BULK and INTERRUPT USB transfers
530 which use an endpoint that can be shared between userland and kernel.
534 Setting this flag will cause that the total buffer size will be
535 rounded up to the nearest atomic hardware transfer size.
537 The maximum data length of any USB transfer is always stored in the
538 "xfer->max_data_length".
540 For control transfers the USB kernel will allocate additional space
541 for the 8-bytes of SETUP header.
543 These 8-bytes are not counted by the "xfer->max_data_length"
546 This flag can not be changed during operation.
550 Setting this flag will cause that no data buffer will be
553 Instead the USB client must supply a data buffer.
555 This flag can not be changed during operation.
559 Setting this flag prevents an USB STATUS stage to be appended to the
560 end of the USB control transfer.
562 If no control data is transferred this flag must be cleared.
564 Else an error will be returned to the USB callback.
566 This flag is mostly useful for the USB device side.
568 This flag can be changed during operation.
572 Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This
573 flag can not be changed during operation.
577 .Bl -tag -width "Device Side Mode"
579 Setting this flag will cause STALL pids to be sent to the endpoint
580 belonging to this transfer before the transfer is started.
582 The transfer is started at the moment the host issues a clear-stall
583 command on the STALL'ed endpoint.
585 This flag can be changed during operation.
587 Setting this flag will cause a clear-stall control request to be
588 executed on the endpoint before the USB transfer is started.
591 If this flag is changed outside the USB callback function you have to
592 use the "usbd_xfer_set_stall()" and "usbd_transfer_clear_stall()"
593 functions! This flag is automatically cleared after that the stall or
594 clear stall has been executed.
597 If this flag is set the number of frames specified is assumed to give the buffering time in milliseconds instead of frames.
598 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.
599 This option only has effect for ISOCHRONOUS transfers.
603 field sets the total buffer size in bytes.
605 If this field is zero, "wMaxPacketSize" will be used, multiplied by
606 the "frames" field if the transfer type is ISOCHRONOUS.
608 This is useful for setting up interrupt pipes.
610 This field is mandatory.
612 NOTE: For control transfers "bufsize" includes the length of the
617 pointer sets the USB callback. This field is mandatory.
620 .Sh USB LINUX COMPAT LAYER
623 module supports the Linux USB API.
633 module complies with the USB 2.0 standard.
637 module has been inspired by the NetBSD USB stack initially written by
638 Lennart Augustsson. The
640 module was written by
641 .An Hans Petter Selasky Aq hselasky@FreeBSD.org .