Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
USBDI(9)	       FreeBSD Kernel Developer's Manual	      USBDI(9)

NAME
     usb_fifo_alloc_buffer, usb_fifo_attach, usb_fifo_detach,
     usb_fifo_free_buffer, usb_fifo_get_data, usb_fifo_get_data_buffer,
     usb_fifo_get_data_error, usb_fifo_get_data_linear,
     usb_fifo_put_bytes_max, usb_fifo_put_data,	usb_fifo_put_data_buffer,
     usb_fifo_put_data_error, usb_fifo_put_data_linear,	usb_fifo_reset,
     usb_fifo_softc, usb_fifo_wakeup, usbd_do_request, usbd_do_request_flags,
     usbd_errstr, usbd_lookup_id_by_info, usbd_lookup_id_by_uaa,
     usbd_transfer_clear_stall,	usbd_transfer_drain, usbd_transfer_pending,
     usbd_transfer_poll, usbd_transfer_setup, usbd_transfer_start,
     usbd_transfer_stop, usbd_transfer_submit, usbd_transfer_unsetup,
     usbd_xfer_clr_flag, usbd_xfer_frame_data, usbd_xfer_frame_len,
     usbd_xfer_get_frame, usbd_xfer_get_priv, usbd_xfer_is_stalled,
     usbd_xfer_max_framelen, usbd_xfer_max_frames, usbd_xfer_max_len,
     usbd_xfer_set_flag, usbd_xfer_set_frame_data, usbd_xfer_set_frame_len,
     usbd_xfer_set_frame_offset, usbd_xfer_set_frames, usbd_xfer_set_interval,
     usbd_xfer_set_priv, usbd_xfer_set_stall, usbd_xfer_set_timeout,
     usbd_xfer_softc, usbd_xfer_state, usbd_xfer_status	-- Universal Serial
     Bus driver	programming interface

SYNOPSIS
     #include <dev/usb/usb.h>
     #include <dev/usb/usbdi.h>
     #include <dev/usb/usbdi_util.h>

     usb_error_t
     usbd_transfer_setup(struct	usb_device *udev, const	uint8_t	*ifaces,
	 struct	usb_xfer **pxfer, const	struct usb_config *setup_start,
	 uint16_t n_setup, void	*priv_sc, struct mtx *priv_mtx);

     void
     usbd_transfer_unsetup(struct usb_xfer **pxfer, uint16_t n_setup);

     void
     usbd_transfer_start(struct	usb_xfer *xfer);

     void
     usbd_transfer_stop(struct usb_xfer	*xfer);

     void
     usbd_transfer_drain(struct	usb_xfer *xfer);

DESCRIPTION
     The Universal Serial Bus (USB) driver programming interface provides USB
     peripheral	drivers	with a host controller independent API for controlling
     and communicating with USB	peripherals.  The usb module supports both USB
     Host and USB Device side mode.

USB TRANSFER MANAGEMENT	FUNCTIONS
     The USB standard defines four types of USB	transfers.  Control transfers,
     Bulk transfers, Interrupt transfers and Isochronous transfers.  All the
     transfer types are	managed	using the following five functions:

     usbd_transfer_setup() This	function will allocate memory for and ini-
     tialise an	array of USB transfers and all required	DMA memory.  This
     function can sleep	or block waiting for resources to become available.
     udev is a pointer to "struct usb_device".	ifaces is an array of inter-
     face index	numbers	to use.	 See "if_index".  pxfer	is a pointer to	an
     array of USB transfer pointers that are initialized to NULL, and then
     pointed to	allocated USB transfers.  setup_start is a pointer to an array
     of	USB config structures.	n_setup	is a number telling the	USB system how
     many USB transfers	should be setup.  priv_sc is the private softc
     pointer, which will be used to initialize "xfer->priv_sc".	 priv_mtx is
     the private mutex protecting the transfer structure and the softc.	 This
     pointer is	used to	initialize "xfer->priv_mtx".  This function returns
     zero upon success.	 A non-zero return value indicates failure.

     usbd_transfer_unsetup() This function will	release	the given USB trans-
     fers and all allocated resources associated with these USB	transfers.
     pxfer is a	pointer	to an array of USB transfer pointers, that may be
     NULL, that	should be freed	by the USB system.  n_setup is a number
     telling the USB system how	many USB transfers should be unsetup.  This
     function can sleep	waiting	for USB	transfers to complete.	This function
     is	NULL safe with regard to the USB transfer structure pointer.  It is
     not allowed to call this function from the	USB transfer callback.

     usbd_transfer_start() This	function will start the	USB transfer pointed
     to	by xfer, if not	already	started.  This function	is always non-blocking
     and must be called	with the so-called private USB mutex locked.  This
     function is NULL safe with	regard to the USB transfer structure pointer.

     usbd_transfer_stop() This function	will stop the USB transfer pointed to
     by	xfer, if not already stopped.  This function is	always non-blocking
     and must be called	with the so-called private USB mutex locked.  This
     function can return before	the USB	callback has been called.  This	func-
     tion is NULL safe with regard to the USB transfer structure pointer.  If
     the transfer was in progress, the callback	will called with
     "USB_ST_ERROR" and	"error = USB_ERR_CANCELLED".

     usbd_transfer_drain() This	function will stop an USB transfer, if not
     already stopped and wait for any additional USB hardware operations to
     complete.	Buffers	that are loaded	into DMA using
     "usbd_xfer_set_frame_data()" can safely be	freed after that this function
     has returned.  This function can block the	caller and will	not return
     before the	USB callback has been called.  This function is	NULL safe with
     regard to the USB transfer	structure pointer.

USB TRANSFER CALLBACK
     The USB callback has three	states.	 USB_ST_SETUP, USB_ST_TRANSFERRED and
     USB_ST_ERROR.  USB_ST_SETUP is the	initial	state.	After the callback has
     been called with this state it will always	be called back at a later
     stage in one of the other two states.  The	USB callback should not
     restart the USB transfer in case the error	cause is USB_ERR_CANCELLED.
     The USB callback is protected from	recursion.  That means one can start
     and stop whatever transfer	from the callback of another transfer one
     desires.  Also the	transfer that is currently called back.	 Recursion is
     handled like this that when the callback that wants to recurse returns it
     is	called one more	time.

     usbd_transfer_submit() This function should only be called	from within
     the USB callback and is used to start the USB hardware.  An USB transfer
     can have multiple frames consisting of one	or more	USB packets making up
     an	I/O vector for all USB transfer	types.

	   void
	   usb_default_callback(struct usb_xfer	*xfer, usb_error_t error)
	   {
		   int actlen;

		   usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL);

		   switch (USB_GET_STATE(xfer))	{
		   case	USB_ST_SETUP:
			   /*
			    * Setup xfer frame lengths/count and data
			    */
			   usbd_transfer_submit(xfer);
			   break;

		   case	USB_ST_TRANSFERRED:
			   /*
			    * Read usb frame data, if any.
			    * "actlen" has the total length for	all frames
			    * transferred.
			    */
			   break;

		   default: /* Error */
			   /*
			    * Print error message and clear stall
			    * for example.
			    */
			   break;
		   }
		   /*
		    * Here it is safe to do something without the private
		    * USB mutex	locked.
		    */
		   return;
	   }

USB CONTROL TRANSFERS
     An	USB control transfer has three parts.  First the SETUP packet, then
     DATA packet(s) and	then a STATUS packet.  The SETUP packet	is always
     pointed to	by frame 0 and the length is set by usbd_xfer_frame_len() also
     if	there should not be sent any SETUP packet!  If an USB control transfer
     has no DATA stage,	then the number	of frames should be set	to 1.  Else
     the default number	of frames is 2.

	   Example1: SETUP + STATUS
	    usbd_xfer_set_frames(xfer, 1);
	    usbd_xfer_set_frame_len(xfer, 0, 8);
	    usbd_transfer_submit(xfer);

	   Example2: SETUP + DATA + STATUS
	    usbd_xfer_set_frames(xfer, 2);
	    usbd_xfer_set_frame_len(xfer, 0, 8);
	    usbd_xfer_set_frame_len(xfer, 1, 1);
	    usbd_transfer_submit(xfer);

	   Example3: SETUP + DATA + STATUS - split
	   1st callback:
	    usbd_xfer_set_frames(xfer, 1);
	    usbd_xfer_set_frame_len(xfer, 0, 8);
	    usbd_transfer_submit(xfer);

	   2nd callback:
	    /* IMPORTANT: frbuffers[0] must still point	at the setup packet! */
	    usbd_xfer_set_frames(xfer, 2);
	    usbd_xfer_set_frame_len(xfer, 0, 0);
	    usbd_xfer_set_frame_len(xfer, 1, 1);
	    usbd_transfer_submit(xfer);

	   Example4: SETUP + STATUS - split
	   1st callback:
	    usbd_xfer_set_frames(xfer, 1);
	    usbd_xfer_set_frame_len(xfer, 0, 8);
	    usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS);
	    usbd_transfer_submit(xfer);

	   2nd callback:
	    usbd_xfer_set_frames(xfer, 1);
	    usbd_xfer_set_frame_len(xfer, 0, 0);
	    usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS);
	    usbd_transfer_submit(xfer);

USB TRANSFER CONFIG
     To	simply the search for endpoints	the usb	module defines a USB config
     structure where it	is possible to specify the characteristics of the
     wanted endpoint.

	   struct usb_config {
		   bufsize,
		   callback
		   direction,
		   endpoint,
		   frames,
		   index flags,
		   interval,
		   timeout,
		   type,
	   };

     type field	selects	the USB	pipe type.  Valid values are: UE_INTERRUPT,
     UE_CONTROL, UE_BULK, UE_ISOCHRONOUS.  The special value UE_BULK_INTR will
     select BULK and INTERRUPT pipes.  This field is mandatory.

     endpoint field selects the	USB endpoint number.  A	value of 0xFF, "-1" or
     "UE_ADDR_ANY" will	select the first matching endpoint.  This field	is
     mandatory.

     direction field selects the USB endpoint direction.  A value of
     "UE_DIR_ANY" will select the first	matching endpoint.  Else valid values
     are: "UE_DIR_IN" and "UE_DIR_OUT".	 "UE_DIR_IN" and "UE_DIR_OUT" can be
     binary OR'ed by "UE_DIR_SID" which	means that the direction will be
     swapped in	case of	USB_MODE_DEVICE.  Note that "UE_DIR_IN"	refers to the
     data transfer direction of	the "IN" tokens	and "UE_DIR_OUT" refers	to the
     data transfer direction of	the "OUT" tokens.  This	field is mandatory.

     interval field selects the	interrupt interval.  The value of this field
     is	given in milliseconds and is independent of device speed.  Depending
     on	the endpoint type, this	field has different meaning:

     UE_INTERRUPT    "0" use the default interrupt interval based on endpoint
		     descriptor.  "Else" use the given value for polling rate.

     UE_ISOCHRONOUS  "0" use default.  "Else" the value	is ignored.

     UE_BULK

     UE_CONTROL	     "0" no transfer pre-delay.	 "Else"	a delay	as given by
		     this field	in milliseconds	is inserted before the hard-
		     ware is started when "usbd_transfer_submit()" is called.

		     NOTE: The transfer	timeout, if any, is started after that
		     the pre-delay has elapsed!

     timeout field, if non-zero, will set the transfer timeout in millisec-
     onds.  If the "timeout" field is zero and the transfer type is
     ISOCHRONOUS a timeout of 250ms will be used.

     frames field sets the maximum number of frames.  If zero is specified it
     will yield	the following results:

     UE_BULK	   xfer->nframes = 1;

     UE_INTERRUPT  xfer->nframes = 1;

     UE_CONTROL	   xfer->nframes = 2;

     UE_ISOCHRONOUS
		   Not allowed.	 Will cause an error.

     ep_index field allows you to give a number, in case more endpoints	match
     the description, that selects which matching "ep_index" should be used.

     if_index field allows you to select which of the interface	numbers	in the
     "ifaces" array parameter passed to	"usbd_transfer_setup" that should be
     used when setting up the given USB	transfer.

     flags field has type "struct usb_xfer_flags" and allows one to set	ini-
     tial flags	an USB transfer.  Valid	flags are:

     force_short_xfer  This flag forces	the last transmitted USB packet	to be
		       short.  A short packet has a length of less than
		       "xfer->max_packet_size",	which derives from "wMaxPack-
		       etSize".	 This flag can be changed during operation.

     short_xfer_ok     This flag allows	the received transfer length,
		       "xfer->actlen" to be less than "xfer->sumlen" upon com-
		       pletion of a transfer.  This flag can be	changed	during
		       operation.

     short_frames_ok   This flag allows	the reception of multiple short	USB
		       frames.	This flag only has effect for BULK and INTER-
		       RUPT endpoints and if the number	of frames received is
		       greater than 1.	This flag can be changed during	opera-
		       tion.

     pipe_bof	       This flag causes	a failing USB transfer to remain first
		       in the PIPE queue except	in the case of "xfer->error"
		       equal to	"USB_ERR_CANCELLED".  No other USB transfers
		       in the affected PIPE queue will be started until
		       either:

		       1  The failing USB transfer is stopped using
			  "usbd_transfer_stop()".

		       2  The failing USB transfer performs a successful
			  transfer.
		       The purpose of this flag	is to avoid races when multi-
		       ple transfers are queued	for execution on an USB	end-
		       point, and the first executing transfer fails leading
		       to the need for clearing	of stall for example.  In this
		       case this flag is used to prevent the following USB
		       transfers from being executed at	the same time the
		       clear-stall command is executed on the USB control end-
		       point.  This flag can be	changed	during operation.

		       "BOF" is	short for "Block On Failure".

		       NOTE: This flag should be set on	all BULK and INTERRUPT
		       USB transfers which use an endpoint that	can be shared
		       between userland	and kernel.

     proxy_buffer      Setting this flag will cause that the total buffer size
		       will be rounded up to the nearest atomic	hardware
		       transfer	size.  The maximum data	length of any USB
		       transfer	is always stored in the
		       "xfer->max_data_length".	 For control transfers the USB
		       kernel will allocate additional space for the 8-bytes
		       of SETUP	header.	 These 8-bytes are not counted by the
		       "xfer->max_data_length" variable.  This flag cannot be
		       changed during operation.

     ext_buffer	       Setting this flag will cause that no data buffer	will
		       be allocated.  Instead the USB client must supply a
		       data buffer.  This flag cannot be changed during	opera-
		       tion.

     manual_status     Setting this flag prevents an USB STATUS	stage to be
		       appended	to the end of the USB control transfer.	 If no
		       control data is transferred this	flag must be cleared.
		       Else an error will be returned to the USB callback.
		       This flag is mostly useful for the USB device side.
		       This flag can be	changed	during operation.

     no_pipe_ok	       Setting this flag causes	the USB_ERR_NO_PIPE error to
		       be ignored.  This flag cannot be	changed	during opera-
		       tion.

     stall_pipe

		       Device Side Mode	 Setting this flag will	cause STALL
					 pids to be sent to the	endpoint
					 belonging to this transfer before the
					 transfer is started.  The transfer is
					 started at the	moment the host	issues
					 a clear-stall command on the STALL'ed
					 endpoint.  This flag can be changed
					 during	operation.

		       Host Side Mode	 Setting this flag will	cause a	clear-
					 stall control request to be executed
					 on the	endpoint before	the USB	trans-
					 fer is	started.

		       If this flag is changed outside the USB callback	func-
		       tion you	have to	use the	"usbd_xfer_set_stall()"	and
		       "usbd_transfer_clear_stall()" functions!	This flag is
		       automatically cleared after that	the stall or clear
		       stall has been executed.

     pre_scale_frames  If this flag is set the number of frames	specified is
		       assumed to give the buffering time in milliseconds
		       instead of frames.  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.  This option only has effect
		       for ISOCHRONOUS transfers.

     bufsize field sets	the total buffer size in bytes.	 If this field is
     zero, "wMaxPacketSize" will be used, multiplied by	the "frames" field if
     the transfer type is ISOCHRONOUS.	This is	useful for setting up inter-
     rupt pipes.  This field is	mandatory.

     NOTE: For control transfers "bufsize" includes the	length of the request
     structure.

     callback pointer sets the USB callback.  This field is mandatory.

USB LINUX COMPAT LAYER
     The usb module supports the Linux USB API.

SEE ALSO
     libusb(3),	usb(4),	usbconfig(8)

STANDARDS
     The usb module complies with the USB 2.0 standard.

HISTORY
     The usb module has	been inspired by the NetBSD USB	stack initially	writ-
     ten by Lennart Augustsson.	 The usb module	was written by Hans Petter
     Selasky <hselasky@FreeBSD.org>.

FreeBSD	11.1		       November	14, 2016		  FreeBSD 11.1

NAME | SYNOPSIS | DESCRIPTION | USB TRANSFER MANAGEMENT FUNCTIONS | USB TRANSFER CALLBACK | USB CONTROL TRANSFERS | USB TRANSFER CONFIG | USB LINUX COMPAT LAYER | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=usbdi&sektion=9&manpath=FreeBSD+11.1-RELEASE+and+Ports>

home | help