Deleted Added
sdiff udiff text old ( 192551 ) new ( 194860 )
full compact
usb.4 (192551) usb.4 (194860)
1.\" Copyright (c) 1997, 1998
2.\" Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.

--- 34 unchanged lines hidden (view full) ---

43.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
44.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
45.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
47.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
48.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
49.\" SUCH DAMAGE.
50.\"
1.\" Copyright (c) 1997, 1998
2.\" Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.

--- 34 unchanged lines hidden (view full) ---

43.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
44.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
45.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
47.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
48.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
49.\" SUCH DAMAGE.
50.\"
51.\" $FreeBSD: head/share/man/man4/usb.4 192551 2009-05-21 17:26:20Z thompsa $
51.\" $FreeBSD: head/share/man/man4/usb.4 194860 2009-06-24 17:01:17Z thompsa $
52.\"
53.Dd May 20, 2009
54.Dt USB 4
55.Os
56.Sh NAME
57.Nm usb
58.Nd Universal Serial Bus
59.Sh SYNOPSIS

--- 97 unchanged lines hidden (view full) ---

157.Tn USB
158bus proceeds in several steps:
159.Bl -enum
160.It
161Any interface specific driver can attach to the device.
162.It
163If none is found, generic interface class drivers can attach.
164.El
52.\"
53.Dd May 20, 2009
54.Dt USB 4
55.Os
56.Sh NAME
57.Nm usb
58.Nd Universal Serial Bus
59.Sh SYNOPSIS

--- 97 unchanged lines hidden (view full) ---

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

--- 24 unchanged lines hidden --- 		174.Xr aue 4 ,
175.Xr axe 4 ,
176.Xr cue 4 ,
177.Xr ehci 4 ,
178.Xr kue 4 ,
179.Xr ohci 4 ,
180.Xr pci 4 ,
181.Xr rue 4 ,

--- 24 unchanged lines hidden ---