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