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

FreeBSD Manual Pages

  
 
  

home | help
USBDI(9)		   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  pro-
       gramming	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  con-
       trolling	 and  communicating with USB peripherals.  The usb module sup-
       ports both USB Host and USB Device side mode.

USB TRANSFER MANAGEMENT	FUNCTIONS
       The USB standard	defines	four types of USB transfers.   Control	trans-
       fers,  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 ar-
       ray of USB config structures.  n_setup is a number telling the USB sys-
       tem  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 func-
       tion 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-block-
       ing  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-block-
       ing and must be called with the so-called  private  USB	mutex  locked.
       This function can return	before the USB callback	has been called.  This
       function	 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	 func-
       tion has	returned.  This	function can block the caller and will not re-
       turn  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 call-
       back 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_CAN-
       CELLED.	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 re-
       curse 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	trans-
       fer can have multiple frames consisting of one or more USB packets mak-
       ing 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  simplify the	search for endpoints the usb module defines a USB con-
       fig 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  val-
       ues  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  end-
		       point  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 ISOCHRO-
       NOUS 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	"wMax-
			 PacketSize".	This flag can be changed during	opera-
			 tion.

       short_xfer_ok	 This  flag  allows  the  received  transfer   length,
			 "xfer->actlen"	 to  be	 less than "xfer->sumlen" upon
			 completion 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  IN-
			 TERRUPT  endpoints  and  if  the number of frames re-
			 ceived	is greater than	1.  This flag can  be  changed
			 during	operation.

       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  mul-
			 tiple	transfers  are	queued for execution on	an USB
			 endpoint, and	the  first  executing  transfer	 fails
			 leading  to  the need for clearing of stall for exam-
			 ple.  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 endpoint.	 This flag can be changed dur-
			 ing operation.

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

			 NOTE: This flag should	be set on all BULK and	INTER-
			 RUPT  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 hard-
			 ware 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 op-
			 eration.

       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 de-
			 vice side.  This flag can be  changed	during	opera-
			 tion.

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

       stall_pipe

			 Device	Side Mode  Setting  this flag will cause STALL
					   pids	to be sent to the endpoint be-
					   longing 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 transfer	is started.

			 If  this  flag	 is  changed  outside the USB callback
			 function 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  ef-
			 fect 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 in-
       terrupt pipes.  This field is mandatory.

       NOTE:  For  control  transfers "bufsize"	includes the length of the re-
       quest 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
       written	by  Lennart  Augustsson.   The	usb module was written by Hans
       Petter Selasky <hselasky@FreeBSD.org>.

FreeBSD	13.2		       November	14, 2016		      USBDI(9)

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://man.freebsd.org/cgi/man.cgi?query=usbdi&sektion=9&manpath=FreeBSD+14.2-RELEASE+and+Ports>

home | help