Move programming info from usb(4) to usbdi(9) and update for the usb stack

changeover. Needs much more content still.

4 files changed, 673 insertions, 1779 deletions

diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc
index 4bfe840..4588a4d 100644
--- a/ObsoleteFiles.inc
+++ b/ObsoleteFiles.inc
@@ -14,6 +14,53 @@
 # The file is partitioned: OLD_FILES first, then OLD_LIBS and OLD_DIRS last.
 #
 
+# 20090624: update usbdi(9)
+OLD_FILES+=usr/share/man/man9/usbd_abort_default_pipe.9
+OLD_FILES+=usr/share/man/man9/usbd_abort_pipe.9
+OLD_FILES+=usr/share/man/man9/usbd_alloc_buffer.9
+OLD_FILES+=usr/share/man/man9/usbd_alloc_xfer.9
+OLD_FILES+=usr/share/man/man9/usbd_clear_endpoint_stall.9
+OLD_FILES+=usr/share/man/man9/usbd_clear_endpoint_stall_async.9
+OLD_FILES+=usr/share/man/man9/usbd_clear_endpoint_toggle.9
+OLD_FILES+=usr/share/man/man9/usbd_close_pipe.9
+OLD_FILES+=usr/share/man/man9/usbd_device2interface_handle.9
+OLD_FILES+=usr/share/man/man9/usbd_do_request_async.9
+OLD_FILES+=usr/share/man/man9/usbd_do_request_flags_pipe.9
+OLD_FILES+=usr/share/man/man9/usbd_endpoint_count.9
+OLD_FILES+=usr/share/man/man9/usbd_find_edesc.9
+OLD_FILES+=usr/share/man/man9/usbd_find_idesc.9
+OLD_FILES+=usr/share/man/man9/usbd_free_buffer.9
+OLD_FILES+=usr/share/man/man9/usbd_free_xfer.9
+OLD_FILES+=usr/share/man/man9/usbd_get_buffer.9
+OLD_FILES+=usr/share/man/man9/usbd_get_config.9
+OLD_FILES+=usr/share/man/man9/usbd_get_config_desc.9
+OLD_FILES+=usr/share/man/man9/usbd_get_config_desc_full.9
+OLD_FILES+=usr/share/man/man9/usbd_get_config_descriptor.9
+OLD_FILES+=usr/share/man/man9/usbd_get_device_descriptor.9
+OLD_FILES+=usr/share/man/man9/usbd_get_endpoint_descriptor.9
+OLD_FILES+=usr/share/man/man9/usbd_get_interface_altindex.9
+OLD_FILES+=usr/share/man/man9/usbd_get_interface_descriptor.9
+OLD_FILES+=usr/share/man/man9/usbd_get_no_alts.9
+OLD_FILES+=usr/share/man/man9/usbd_get_quirks.9
+OLD_FILES+=usr/share/man/man9/usbd_get_speed.9
+OLD_FILES+=usr/share/man/man9/usbd_get_string.9
+OLD_FILES+=usr/share/man/man9/usbd_get_string_desc.9
+OLD_FILES+=usr/share/man/man9/usbd_get_xfer_status.9
+OLD_FILES+=usr/share/man/man9/usbd_interface2device_handle.9
+OLD_FILES+=usr/share/man/man9/usbd_interface2endpoint_descriptor.9
+OLD_FILES+=usr/share/man/man9/usbd_interface_count.9
+OLD_FILES+=usr/share/man/man9/usbd_open_pipe.9
+OLD_FILES+=usr/share/man/man9/usbd_open_pipe_intr.9
+OLD_FILES+=usr/share/man/man9/usbd_pipe2device_handle.9
+OLD_FILES+=usr/share/man/man9/usbd_set_config_index.9
+OLD_FILES+=usr/share/man/man9/usbd_set_config_no.9
+OLD_FILES+=usr/share/man/man9/usbd_set_interface.9
+OLD_FILES+=usr/share/man/man9/usbd_setup_default_xfer.9
+OLD_FILES+=usr/share/man/man9/usbd_setup_isoc_xfer.9
+OLD_FILES+=usr/share/man/man9/usbd_setup_xfer.9
+OLD_FILES+=usr/share/man/man9/usbd_sync_transfer.9
+OLD_FILES+=usr/share/man/man9/usbd_transfer.9
+OLD_FILES+=usr/share/man/man9/usb_find_desc.9
 # 20090605: removal of clists
 OLD_FILES+=usr/include/sys/clist.h
 # 20090602: removal of window(1)
diff --git a/share/man/man4/usb.4 b/share/man/man4/usb.4
index 4fcfd96..e2b236a 100644
--- a/share/man/man4/usb.4
+++ b/share/man/man4/usb.4
@@ -162,548 +162,6 @@ Any interface specific driver can attach to the device.
 .It
 If none is found, generic interface class drivers can attach.
 .El
-.Sh USB KERNEL PROGRAMMING
-Here is a list of commonly used functions:
-.Pp
-.
-.Ft "usb2_error_t"
-.Fo "usb2_transfer_setup"
-.Fa "udev"
-.Fa "ifaces"
-.Fa "pxfer"
-.Fa "setup_start"
-.Fa "n_setup"
-.Fa "priv_sc"
-.Fa "priv_mtx"
-.Fc
-.
-.Pp
-.
-.Ft "void"
-.Fo "usb2_transfer_unsetup"
-.Fa "pxfer"
-.Fa "n_setup"
-.Fc
-.
-.Pp
-.
-.Ft "void"
-.Fo "usb2_transfer_start"
-.Fa "xfer"
-.Fc
-.
-.Pp
-.
-.Ft "void"
-.Fo "usb2_transfer_stop"
-.Fa "xfer"
-.Fc
-.
-.Pp
-.
-.Ft "void"
-.Fo "usb2_transfer_drain"
-.Fa "xfer"
-.Fc
-.
-.
-.Sh DESCRIPTION
-The
-.Nm
-module implements the core functionality of the USB standard and many
-helper functions to make USB device driver programming easier and more
-safe.
-.
-The
-.Nm
-module supports both USB Host and USB Device side mode!
-.
-.Sh 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:
-.
-.Pp
-.
-.Fn usb2_transfer_setup
-This function will allocate memory for and initialise an array of USB
-transfers and all required DMA memory.
-.
-This function can sleep or block waiting for resources to become
-available.
-.Fa udev
-is a pointer to "struct usb2_device".
-.Fa ifaces
-is an array of interface index numbers to use. See "if_index".
-.Fa pxfer
-is a pointer to an array of USB transfer pointers that are initialized
-to NULL, and then pointed to allocated USB transfers.
-.Fa setup_start
-is a pointer to an array of USB config structures.
-.Fa n_setup
-is a number telling the USB system how many USB transfers should be
-setup.
-.Fa priv_sc
-is the private softc pointer, which will be used to initialize
-"xfer->priv_sc".
-.Fa 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.
-.
-.Pp
-.
-.Fn usb2_transfer_unsetup
-This function will release the given USB transfers and all allocated
-resources associated with these USB transfers. 
-.Fa pxfer
-is a pointer to an array of USB transfer pointers, that may be NULL,
-that should be freed by the USB system.
-.Fa 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.
-.
-.Pp
-.
-.Fn usb2_transfer_start
-This function will start the USB transfer pointed to by
-.Fa 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.
-.
-.Pp
-.
-.Fn usb2_transfer_stop
-This function will stop the USB transfer pointed to by
-.Fa 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 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 "xfer->error = USB_ERR_CANCELLED".
-.
-.Pp
-.
-.Fn usb2_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 "usb2_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.
-.
-.Sh 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.
-.
-In the USB_ST_ERROR state the "error" field of the USB transfer
-structure is set to the error cause.
-.
-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.
-.
-.
-.Pp
-.
-.Fn usb2_start_hardware
-This function should only be called from within the USB callback and
-is used to start the USB hardware.
-.
-Typical parameters that should be set in the USB transfer structure
-before this function is called are "frlengths[]", "nframes" and
-"frbuffers[]".
-.
-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.
-.
-After the USB transfer is complete "frlengths[]" is updated to the
-actual USB transfer length for the given frame.
-.Bd -literal -offset indent
-void
-usb2_default_callback(struct usb2_xfer *xfer)
-{
-	switch (USB_GET_STATE(xfer)) {
-	case USB_ST_SETUP: 
-		/*
-		 * Setup xfer->frlengths[], xfer->nframes
-		 * and write data to xfer->frbuffers[], if any
-		 */
-		usb2_start_hardware(xfer);
-		break;
-
-	case USB_ST_TRANSFERRED: 
-		/* 
-		 * Read	data from xfer->frbuffers[], if any.
-		 * "xfer->frlengths[]" should now have been
-		 * updated to the actual length.
-		 */
-		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;
-}
-.Ed
-.
-.Sh 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 "xfer->frbuffers[0]" and the
-length is stored in "xfer->frlengths[0]" also if there should not be
-sent any SETUP packet! If an USB control transfer has no DATA stage,
-then "xfer->nframes" should be set to 1.
-.
-Else the default value is "xfer->nframes" equal to 2.
-.
-.Bd -literal -offset indent
-
-Example1: SETUP + STATUS
- xfer->nframes = 1;
- xfer->frlenghts[0] = 8;
- usb2_start_hardware(xfer);
-
-Example2: SETUP + DATA + STATUS
- xfer->nframes = 2;
- xfer->frlenghts[0] = 8;
- xfer->frlenghts[1] = 1;
- usb2_start_hardware(xfer);
-
-Example3: SETUP + DATA + STATUS - split
-1st callback:
- xfer->nframes = 1;
- xfer->frlenghts[0] = 8;
- usb2_start_hardware(xfer);
-
-2nd callback:
- /* IMPORTANT: frbuffers[0] must still point at the setup packet! */
- xfer->nframes = 2;
- xfer->frlenghts[0] = 0;
- xfer->frlenghts[1] = 1;
- usb2_start_hardware(xfer);
-
-Example4: SETUP + STATUS - split
-1st callback:
- xfer->nframes = 1;
- xfer->frlenghts[0] = 8;
- xfer->flags.manual_status = 1;
- usb2_start_hardware(xfer);
-
-2nd callback:
- xfer->nframes = 1;
- xfer->frlenghts[0] = 0;
- xfer->flags.manual_status = 0;
- usb2_start_hardware(xfer);
-
-.Ed
-.Sh USB TRANSFER CONFIG
-To simply the search for endpoints the
-.Nm
-module defines a USB config structure where it is possible to specify
-the characteristics of the wanted endpoint.
-.Bd -literal -offset indent
-
-struct usb2_config { 
-	bufsize,
-	callback
-	direction,
-	endpoint,
-	frames,
-	index flags,
-	interval,
-	timeout,
-	type,
-};
-
-.Ed
-.
-.Pp
-.Fa 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.
-.
-.Pp
-.Fa 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.
-.
-.Pp
-.Fa 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.
-.
-.Pp
-.Fa 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:
-.Bl -tag
-.It UE_INTERRUPT
-"0" use the default interrupt interval based on endpoint descriptor.
-"Else" use the given value for polling rate.
-.It UE_ISOCHRONOUS
-"0" use default. "Else" the value is ignored.
-.It UE_BULK
-.It UE_CONTROL
-"0" no transfer pre-delay. "Else" a delay as given by this field in
-milliseconds is inserted before the hardware is started when
-"usb2_start_hardware()" is called.
-.Pp
-NOTE: The transfer timeout, if any, is started after that the
-pre-delay has elapsed!
-.El
-.
-.Pp
-.Fa timeout
-field, if non-zero, will set the transfer timeout in milliseconds. If
-the "timeout" field is zero and the transfer type is ISOCHRONOUS a
-timeout of 250ms will be used.
-.
-.Pp
-.Fa frames
-field sets the maximum number of frames. If zero is specified it will
-yield the following results:
-.Bl -tag
-.It UE_BULK
-xfer->nframes = 1;
-.It UE_INTERRUPT
-xfer->nframes = 1;
-.It UE_CONTROL
-xfer->nframes = 2;
-.It UE_ISOCHRONOUS
-Not allowed. Will cause an error.
-.El
-.
-.Pp
-.Fa 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.
-.
-.Pp
-.Fa if_index
-field allows you to select which of the interface numbers in the
-"ifaces" array parameter passed to "usb2_transfer_setup" that should
-be used when setting up the given USB transfer.
-.
-.Pp
-.Fa flags
-field has type "struct usb2_xfer_flags" and allows one to set initial
-flags an USB transfer. Valid flags are:
-.Bl -tag
-.It 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 "wMaxPacketSize". This flag can be changed during
-operation.
-.It 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.
-.It short_frames_ok
-This flag allows the reception of multiple short USB frames. This flag
-only has effect for BULK and INTERRUPT endpoints and if the number of
-frames received is greater than 1. This flag can be changed during
-operation.
-.It 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:
-.Bl -tag
-.It 1
-The failing USB transfer is stopped using "usb2_transfer_stop()".
-.It 2
-The failing USB transfer performs a successful transfer.
-.El
-The purpose of this flag is to avoid races when multiple transfers are
-queued for execution on an USB endpoint, 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 endpoint.
-.
-This flag can be changed during operation.
-.Pp
-"BOF" is short for "Block On Failure"
-.Pp
-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.
-.
-.
-.It 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 can not be changed during operation.
-.
-.
-.It 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 can not be changed during operation.
-.
-.
-.It 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.
-.
-.
-.It no_pipe_ok
-Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This
-flag can not be changed during operation.
-.
-.
-.It stall_pipe
-.Bl -tag
-.It 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.
-.It 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.
-.El
-.Pp
-If this flag is changed outside the USB callback function you have to
-use the "usb2_transfer_set_stall()" and "usb2_transfer_clear_stall()"
-functions! This flag is automatically cleared after that the stall or
-clear stall has been executed.
-.
-.El
-.Pp
-.Fa 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 interrupt pipes.
-.
-This field is mandatory.
-.Pp
-NOTE: For control transfers "bufsize" includes the length of the
-request structure.
-.
-.Pp
-.Fa callback
-pointer sets the USB callback. This field is mandatory.
-.
-.
-.Sh USB LINUX COMPAT LAYER
-The
-.Nm
-module supports the Linux USB API.
-.
-.
-.
 .Sh SEE ALSO
 The
 .Tn USB
@@ -712,6 +170,7 @@ specifications can be found at:
 .D1 Pa http://www.usb.org/developers/docs/
 .Pp
 .Xr libusb 3 ,
+.Xr usbdi 4 ,
 .Xr aue 4 ,
 .Xr axe 4 ,
 .Xr cue 4 ,
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 2ad85ce..d7a611c 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1210,55 +1210,58 @@ MLINKS+=uidinfo.9 uifind.9 \
 	uidinfo.9 uihashinit.9 \
 	uidinfo.9 uihold.9
 MLINKS+=uio.9 uiomove.9
-MLINKS+=usbdi.9 usbd_abort_default_pipe.9 \
-	usbdi.9 usbd_abort_pipe.9 \
-	usbdi.9 usbd_alloc_buffer.9 \
-	usbdi.9 usbd_alloc_xfer.9 \
-	usbdi.9 usbd_clear_endpoint_stall.9 \
-	usbdi.9 usbd_clear_endpoint_stall_async.9 \
-	usbdi.9 usbd_clear_endpoint_toggle.9 \
-	usbdi.9 usbd_close_pipe.9 \
-	usbdi.9 usbd_device2interface_handle.9 \
+MLINKS+=usbdi.9 usb_fifo_alloc_buffer.9 \
+	usbdi.9 usb_fifo_attach.9 \
+	usbdi.9 usb_fifo_detach.9 \
+	usbdi.9 usb_fifo_free_buffer.9 \
+	usbdi.9 usb_fifo_get_data.9 \
+	usbdi.9 usb_fifo_get_data_buffer.9 \
+	usbdi.9 usb_fifo_get_data_error.9 \
+	usbdi.9 usb_fifo_get_data_linear.9 \
+	usbdi.9 usb_fifo_put_bytes_max.9 \
+	usbdi.9 usb_fifo_put_data.9 \
+	usbdi.9 usb_fifo_put_data_buffer.9 \
+	usbdi.9 usb_fifo_put_data_error.9 \
+	usbdi.9 usb_fifo_put_data_linear.9 \
+	usbdi.9 usb_fifo_reset.9 \
+	usbdi.9 usb_fifo_softc.9 \
+	usbdi.9 usb_fifo_wakeup.9 \
 	usbdi.9 usbd_do_request.9 \
-	usbdi.9 usbd_do_request_async.9 \
 	usbdi.9 usbd_do_request_flags.9 \
-	usbdi.9 usbd_do_request_flags_pipe.9 \
-	usbdi.9 usbd_endpoint_count.9 \
 	usbdi.9 usbd_errstr.9 \
-	usbdi.9 usbd_find_edesc.9 \
-	usbdi.9 usbd_find_idesc.9 \
-	usbdi.9 usbd_free_buffer.9 \
-	usbdi.9 usbd_free_xfer.9 \
-	usbdi.9 usbd_get_buffer.9 \
-	usbdi.9 usbd_get_config.9 \
-	usbdi.9 usbd_get_config_desc.9 \
-	usbdi.9 usbd_get_config_desc_full.9 \
-	usbdi.9 usbd_get_config_descriptor.9 \
-	usbdi.9 usbd_get_device_descriptor.9 \
-	usbdi.9 usbd_get_endpoint_descriptor.9 \
-	usbdi.9 usbd_get_interface_altindex.9 \
-	usbdi.9 usbd_get_interface_descriptor.9 \
-	usbdi.9 usbd_get_no_alts.9 \
-	usbdi.9 usbd_get_quirks.9 \
-	usbdi.9 usbd_get_speed.9 \
-	usbdi.9 usbd_get_string.9 \
-	usbdi.9 usbd_get_string_desc.9 \
-	usbdi.9 usbd_get_xfer_status.9 \
-	usbdi.9 usbd_interface2device_handle.9 \
-	usbdi.9 usbd_interface2endpoint_descriptor.9 \
-	usbdi.9 usbd_interface_count.9 \
-	usbdi.9 usbd_open_pipe.9 \
-	usbdi.9 usbd_open_pipe_intr.9 \
-	usbdi.9 usbd_pipe2device_handle.9 \
-	usbdi.9 usbd_set_config_index.9 \
-	usbdi.9 usbd_set_config_no.9 \
-	usbdi.9 usbd_set_interface.9 \
-	usbdi.9 usbd_setup_default_xfer.9 \
-	usbdi.9 usbd_setup_isoc_xfer.9 \
-	usbdi.9 usbd_setup_xfer.9 \
-	usbdi.9 usbd_sync_transfer.9 \
-	usbdi.9 usbd_transfer.9 \
-	usbdi.9 usb_find_desc.9
+	usbdi.9 usbd_lookup_id_by_info.9 \
+	usbdi.9 usbd_lookup_id_by_uaa.9 \
+	usbdi.9 usbd_transfer_clear_stall.9 \
+	usbdi.9 usbd_transfer_drain.9 \
+	usbdi.9 usbd_transfer_pending.9 \
+	usbdi.9 usbd_transfer_poll.9 \
+	usbdi.9 usbd_transfer_setup.9 \
+	usbdi.9 usbd_transfer_start.9 \
+	usbdi.9 usbd_transfer_stop.9 \
+	usbdi.9 usbd_transfer_submit.9 \
+	usbdi.9 usbd_transfer_unsetup.9 \
+	usbdi.9 usbd_xfer_clr_flag.9 \
+	usbdi.9 usbd_xfer_frame_data.9 \
+	usbdi.9 usbd_xfer_frame_len.9 \
+	usbdi.9 usbd_xfer_get_frame.9 \
+	usbdi.9 usbd_xfer_get_priv.9 \
+	usbdi.9 usbd_xfer_is_stalled.9 \
+	usbdi.9 usbd_xfer_max_framelen.9 \
+	usbdi.9 usbd_xfer_max_frames.9 \
+	usbdi.9 usbd_xfer_max_len.9 \
+	usbdi.9 usbd_xfer_set_flag.9 \
+	usbdi.9 usbd_xfer_set_frame_data.9 \
+	usbdi.9 usbd_xfer_set_frame_len.9 \
+	usbdi.9 usbd_xfer_set_frame_offset.9 \
+	usbdi.9 usbd_xfer_set_frames.9 \
+	usbdi.9 usbd_xfer_set_interval.9 \
+	usbdi.9 usbd_xfer_set_priv.9 \
+	usbdi.9 usbd_xfer_set_stall.9 \
+	usbdi.9 usbd_xfer_set_timeout.9 \
+	usbdi.9 usbd_xfer_softc.9 \
+	usbdi.9 usbd_xfer_state.9 \
+	usbdi.9 usbd_xfer_state.9 \
+	usbdi.9 usbd_xfer_status.9
 MLINKS+=vcount.9 count_dev.9
 MLINKS+=vfsconf.9 vfs_modevent.9 \
 	vfsconf.9 vfs_register.9 \
diff --git a/share/man/man9/usbdi.9 b/share/man/man9/usbdi.9
index 582754f..d58e599 100644
--- a/share/man/man9/usbdi.9
+++ b/share/man/man9/usbdi.9
@@ -24,1230 +24,615 @@
 .\" SUCH DAMAGE.
 .\"
 .\"	$FreeBSD$
-.Dd December 30, 2005
+.Dd June 24, 2009
 .Os
 .Dt USBDI 9
 .Sh NAME
-.Nm usb_detach_wait ,
-.Nm usb_detach_wakeup ,
-.Nm usb_find_desc ,
-.Nm usbd_abort_default_pipe ,
-.Nm usbd_abort_pipe ,
-.Nm usbd_alloc_buffer ,
-.Nm usbd_alloc_xfer ,
-.Nm usbd_bulk_transfer ,
-.Nm usbd_clear_endpoint_stall ,
-.Nm usbd_clear_endpoint_stall_async ,
-.Nm usbd_clear_endpoint_toggle ,
-.Nm usbd_close_pipe ,
-.Nm usbd_device2interface_handle ,
-.Nm usbd_devinfo ,
+.Nm usb_fifo_alloc_buffer ,
+.Nm usb_fifo_attach ,
+.Nm usb_fifo_detach ,
+.Nm usb_fifo_free_buffer ,
+.Nm usb_fifo_get_data ,
+.Nm usb_fifo_get_data_buffer ,
+.Nm usb_fifo_get_data_error ,
+.Nm usb_fifo_get_data_linear ,
+.Nm usb_fifo_put_bytes_max ,
+.Nm usb_fifo_put_data ,
+.Nm usb_fifo_put_data_buffer ,
+.Nm usb_fifo_put_data_error ,
+.Nm usb_fifo_put_data_linear ,
+.Nm usb_fifo_reset ,
+.Nm usb_fifo_softc ,
+.Nm usb_fifo_wakeup ,
 .Nm usbd_do_request ,
-.Nm usbd_do_request_async ,
 .Nm usbd_do_request_flags ,
-.Nm usbd_do_request_flags_pipe ,
-.Nm usbd_dopoll ,
-.Nm usbd_endpoint_count ,
 .Nm usbd_errstr ,
-.Nm usbd_fill_deviceinfo ,
-.Nm usbd_find_edesc ,
-.Nm usbd_find_idesc ,
-.Nm usbd_free_buffer ,
-.Nm usbd_free_xfer ,
-.Nm usbd_get_buffer ,
-.Nm usbd_get_config ,
-.Nm usbd_get_config_desc ,
-.Nm usbd_get_config_desc_full ,
-.Nm usbd_get_config_descriptor ,
-.Nm usbd_get_device_descriptor ,
-.Nm usbd_get_endpoint_descriptor ,
-.Nm usbd_get_interface_altindex ,
-.Nm usbd_get_interface_descriptor ,
-.Nm usbd_get_no_alts ,
-.Nm usbd_get_quirks ,
-.Nm usbd_get_speed ,
-.Nm usbd_get_string ,
-.Nm usbd_get_string_desc ,
-.Nm usbd_get_xfer_status ,
-.Nm usbd_interface2device_handle ,
-.Nm usbd_interface2endpoint_descriptor ,
-.Nm usbd_interface_count ,
-.Nm usbd_intr_transfer ,
-.Nm usbd_open_pipe ,
-.Nm usbd_open_pipe_intr ,
-.Nm usbd_pipe2device_handle ,
-.Nm usbd_ratecheck ,
-.Nm usbd_set_config_index ,
-.Nm usbd_set_config_no ,
-.Nm usbd_set_interface ,
-.Nm usbd_set_polling ,
-.Nm usbd_setup_default_xfer ,
-.Nm usbd_setup_isoc_xfer ,
-.Nm usbd_setup_xfer ,
-.Nm usbd_sync_transfer ,
-.Nm usbd_transfer
+.Nm usbd_lookup_id_by_info ,
+.Nm usbd_lookup_id_by_uaa ,
+.Nm usbd_transfer_clear_stall ,
+.Nm usbd_transfer_drain ,
+.Nm usbd_transfer_pending ,
+.Nm usbd_transfer_poll ,
+.Nm usbd_transfer_setup ,
+.Nm usbd_transfer_start ,
+.Nm usbd_transfer_stop ,
+.Nm usbd_transfer_submit ,
+.Nm usbd_transfer_unsetup ,
+.Nm usbd_xfer_clr_flag ,
+.Nm usbd_xfer_frame_data ,
+.Nm usbd_xfer_frame_len ,
+.Nm usbd_xfer_get_frame ,
+.Nm usbd_xfer_get_priv ,
+.Nm usbd_xfer_is_stalled ,
+.Nm usbd_xfer_max_framelen ,
+.Nm usbd_xfer_max_frames ,
+.Nm usbd_xfer_max_len ,
+.Nm usbd_xfer_set_flag ,
+.Nm usbd_xfer_set_frame_data ,
+.Nm usbd_xfer_set_frame_len ,
+.Nm usbd_xfer_set_frame_offset ,
+.Nm usbd_xfer_set_frames ,
+.Nm usbd_xfer_set_interval ,
+.Nm usbd_xfer_set_priv ,
+.Nm usbd_xfer_set_stall ,
+.Nm usbd_xfer_set_timeout ,
+.Nm usbd_xfer_softc ,
+.Nm usbd_xfer_state ,
+.Nm usbd_xfer_state ,
+.Nm usbd_xfer_status
 .Nd Universal Serial Bus driver programming interface
 .Sh SYNOPSIS
 .In dev/usb/usb.h
 .In dev/usb/usbdi.h
 .In dev/usb/usbdi_util.h
-.Pp
-.Ft void
-.Fn usb_detach_wait "device_ptr_t dv"
-.Ft void
-.Fn usb_detach_wakeup "device_ptr_t dv"
-.Ft "const usb_descriptor_t *"
-.Fn usb_find_desc "usbd_device_handle dev" "int type" "int subtype"
-.Ft usbd_status
-.Fn usbd_abort_default_pipe "usbd_device_handle dev"
-.Ft usbd_status
-.Fn usbd_abort_pipe "usbd_pipe_handle pipe"
-.Ft "void *"
-.Fn usbd_alloc_buffer "usbd_xfer_handle xfer" "u_int32_t size"
-.Ft usbd_xfer_handle
-.Fn usbd_alloc_xfer "usbd_device_handle dev"
-.Ft usbd_status
-.Fo usbd_bulk_transfer
-.Fa "usbd_xfer_handle xfer"
-.Fa "usbd_pipe_handle pipe"
-.Fa "u_int16_t flags"
-.Fa "u_int32_t timeout"
-.Fa "void *buf"
-.Fa "u_int32_t *size"
-.Fa "char *lbl"
-.Fc
-.Ft usbd_status
-.Fn usbd_clear_endpoint_stall "usbd_pipe_handle pipe"
-.Ft usbd_status
-.Fn usbd_clear_endpoint_stall_async "usbd_pipe_handle"
-.Ft void
-.Fn usbd_clear_endpoint_toggle "usbd_pipe_handle pipe"
-.Ft usbd_status
-.Fn usbd_close_pipe "usbd_pipe_handle pipe"
-.Ft usbd_status
-.Fo usbd_device2interface_handle
-.Fa "usbd_device_handle dev"
-.Fa "u_int8_t ifaceno"
-.Fa "usbd_interface_handle *iface"
-.Fc
-.Ft void
-.Fn usbd_devinfo "usbd_device_handle dev" "int showclass" "char *cp"
-.Ft usbd_status
-.Fo usbd_do_request
-.Fa "usbd_device_handle dev"
-.Fa "usb_device_request_t *req"
-.Fa "void *data"
-.Fc
-.Ft usbd_status
-.Fo usbd_do_request_async
-.Fa "usbd_device_handle dev"
-.Fa "usb_device_request_t *req"
-.Fa "void *data"
-.Fc
-.Ft usbd_status
-.Fo usbd_do_request_flags
-.Fa "usbd_device_handle dev"
-.Fa "usb_device_request_t *req"
-.Fa "void *data"
-.Fa "u_int16_t flags"
-.Fa "int *actlen"
-.Fa "u_int32_t timo"
-.Fc
-.Ft usbd_status
-.Fo usbd_do_request_flags_pipe
-.Fa "usbd_device_handle dev"
-.Fa "usbd_pipe_handle pipe"
-.Fa "usb_device_request_t *req"
-.Fa "void *data"
-.Fa "u_int16_t flags"
-.Fa "int *actlen"
-.Fa "u_int32_t timeout"
-.Fc
-.Ft void
-.Fn usbd_dopoll "usbd_interface_handle iface"
-.Ft usbd_status
-.Fn usbd_endpoint_count "usbd_interface_handle iface" "u_int8_t *count"
-.Ft "const char *"
-.Fn usbd_errstr "usbd_status err"
-.Ft void
-.Fo usbd_fill_deviceinfo
-.Fa "usbd_device_handle dev"
-.Fa "struct usb_device_info *di"
-.Fa "int usedev"
-.Fc
-.Ft "usb_endpoint_descriptor_t *"
-.Fo usbd_find_edesc
-.Fa "usb_config_descriptor_t *cd"
-.Fa "int ifaceidx"
-.Fa "int altidx"
-.Fa "int endptidx"
-.Fc
-.Ft "usb_interface_descriptor_t *"
-.Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx"
-.Ft void
-.Fn usbd_free_buffer "usbd_xfer_handle xfer"
-.Ft usbd_status
-.Fn usbd_free_xfer "usbd_xfer_handle xfer"
-.Ft "void *"
-.Fn usbd_get_buffer "usbd_xfer_handle xfer"
-.Ft usbd_status
-.Fn usbd_get_config "usbd_device_handle dev" "u_int8_t *conf"
-.Ft usbd_status
-.Fo usbd_get_config_desc
-.Fa "usbd_device_handle dev"
-.Fa "int confidx"
-.Fa "usb_config_descriptor_t *d"
-.Fc
-.Ft usbd_status
-.Fo usbd_get_config_desc_full
-.Fa "usbd_device_handle dev"
-.Fa "int conf"
-.Fa "void *d"
-.Fa "int size"
-.Fc
-.Ft "usb_config_descriptor_t *"
-.Fn usbd_get_config_descriptor "usbd_device_handle dev"
-.Ft "usb_device_descriptor_t *"
-.Fn usbd_get_device_descriptor "usbd_device_handle dev"
-.Ft "usb_endpoint_descriptor_t *"
-.Fo usbd_get_endpoint_descriptor
-.Fa "usbd_interface_handle iface"
-.Fa "u_int8_t address"
-.Fc
-.Ft int
-.Fn usbd_get_interface_altindex "usbd_interface_handle iface"
-.Ft "usb_interface_descriptor_t *"
-.Fn usbd_get_interface_descriptor "usbd_interface_handle iface"
-.Ft int
-.Fn usbd_get_no_alts "usb_config_descriptor_t *cdesc" "int ifaceno"
-.Ft "const struct usbd_quirks *"
-.Fn usbd_get_quirks "usbd_device_handle dev"
-.Ft int
-.Fn usbd_get_speed "usbd_device_handle dev"
-.Ft usbd_status
-.Fn usbd_get_string "usbd_device_handle dev" "int si" "char *buf"
-.Ft usbd_status
-.Fo usbd_get_string_desc
-.Fa "usbd_device_handle dev"
-.Fa "int sindex"
-.Fa "int langid"
-.Fa "usb_string_descriptor_t *sdesc"
-.Fa "int *sizep"
-.Fc
-.Ft void
-.Fo usbd_get_xfer_status
-.Fa "usbd_xfer_handle xfer"
-.Fa "usbd_private_handle *priv"
-.Fa "void **buffer"
-.Fa "u_int32_t *count"
-.Fa "usbd_status *status"
-.Fc
-.Ft void
-.Fo usbd_interface2device_handle
-.Fa "usbd_interface_handle iface"
-.Fa "usbd_device_handle *dev"
-.Fc
-.Ft "usb_endpoint_descriptor_t *"
-.Fo usbd_interface2endpoint_descriptor
-.Fa "usbd_interface_handle iface"
-.Fa "u_int8_t index"
-.Fc
-.Ft usbd_status
-.Fn usbd_interface_count "usbd_device_handle dev" "u_int8_t *count"
-.Ft usbd_status
-.Fo usbd_intr_transfer
-.Fa "usbd_xfer_handle xfer"
-.Fa "usbd_pipe_handle pipe"
-.Fa "u_int16_t flags"
-.Fa "u_int32_t timeout"
-.Fa "void *buf"
-.Fa "u_int32_t *size"
-.Fa "char *lbl"
-.Fc
-.Ft usbd_status
-.Fo usbd_open_pipe
-.Fa "usbd_interface_handle iface"
-.Fa "u_int8_t address"
-.Fa "u_int8_t flags"
-.Fa "usbd_pipe_handle *pipe"
-.Fc
-.Ft usbd_status
-.Fo usbd_open_pipe_intr
-.Fa "usbd_interface_handle iface"
-.Fa "u_int8_t address"
-.Fa "u_int8_t flags"
-.Fa "usbd_pipe_handle *pipe"
-.Fa "usbd_private_handle priv"
-.Fa "void *buffer"
-.Fa "u_int32_t len"
-.Fa "usbd_callback cb"
-.Fa "int ival"
-.Fc
-.Ft usbd_device_handle
-.Fn usbd_pipe2device_handle "usbd_pipe_handle pipe"
-.Ft int
-.Fn usbd_ratecheck "struct timeval *last"
-.Ft usbd_status
-.Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg"
-.Ft usbd_status
-.Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg"
-.Ft usbd_status
-.Fn usbd_set_interface "usbd_interface_handle iface" "int altidx"
-.Ft void
-.Fn usbd_set_polling "usbd_device_handle dev" "int on"
-.Ft void
-.Fo usbd_setup_default_xfer
-.Fa "usbd_xfer_handle xfer"
-.Fa "usbd_device_handle dev"
-.Fa "usbd_private_handle priv"
-.Fa "u_int32_t timeout"
-.Fa "usb_device_request_t *req"
-.Fa "void *buffer"
-.Fa "u_int32_t length"
-.Fa "u_int16_t flags"
-.Fa "usbd_callback callback"
-.Fc
-.Ft void
-.Fo usbd_setup_isoc_xfer
-.Fa "usbd_xfer_handle xfer"
-.Fa "usbd_pipe_handle pipe"
-.Fa "usbd_private_handle priv"
-.Fa "u_int16_t *frlengths"
-.Fa "u_int32_t nframes"
-.Fa "u_int16_t flags"
-.Fa "usbd_callback callback"
-.Fc
-.Ft void
-.Fo usbd_setup_xfer
-.Fa "usbd_xfer_handle xfer"
-.Fa "usbd_pipe_handle pipe"
-.Fa "usbd_private_handle priv"
-.Fa "void *buffer"
-.Fa "u_int32_t length"
-.Fa "u_int16_t flags"
-.Fa "u_int32_t timeout"
-.Fa "usbd_callback callback"
-.Fc
-.Ft usbd_status
-.Fn usbd_sync_transfer "usbd_xfer_handle xfer"
-.Ft usbd_status
-.Fn usbd_transfer "usbd_xfer_handle xfer"
 .Sh 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.
-.Pp
-Typically, drivers will first use some combination of the functions
-.Fn usbd_set_config_no ,
-.Fn usbd_get_config_descriptor ,
-.Fn usbd_set_interface ,
-.Fn usbd_get_interface_descriptor ,
-.Fn usbd_device2interface_handle ,
-.Fn usbd_endpoint_count
-and
-.Fn usbd_interface2endpoint_descriptor
-to query the device's properties and prepare it for use.
-Drivers can then perform requests on the USB control pipe using
-.Fn usbd_do_request ,
-they can open pipes using the functions
-.Fn usbd_open_pipe
-and
-.Fn usbd_open_pipe_intr ,
-and perform transfers over these pipes using
-.Fn usbd_alloc_xfer ,
-.Fn usbd_setup_xfer
-and
-.Fn usbd_transfer .
-Finally, the functions
-.Fn usbd_abort_pipe ,
-.Fn usbd_close_pipe
-and
-.Fn usbd_free_xfer
-are used to cancel outstanding transfers, close open pipes and deallocate
-transfer structures.
-.Pp
-The
-.Fn usbd_get_device_descriptor
-function returns a pointer to the USB device descriptor for
-.Fa dev .
-See
-.Sx "USB Descriptors"
-below for information about the USB device descriptor.
-.Pp
-The
-.Fn usbd_get_config_desc
-function retrieves the specified configuration descriptor from the device.
-The
-.Fa confidx
-parameter specifies the configuration descriptor index, which must be less
-than the
-.Fa bNumConfigurations
-value in the device descriptor.
-The function
-.Fn usbd_get_config_desc_full
-retrieves a full configuration descriptor, which has all related interface
-and endpoint descriptors appended to a normal configuration descriptor.
-The parameter
-.Fa d
-should point to memory that is at least
-.Fa size
-bytes in length, and this should be at least as long as the
-.Fa wTotalLength
-value from the configuration descriptor.
-See
-.Sx "USB Descriptors"
-below for information about the USB configuration descriptor.
-.Pp
-The
-.Fn usbd_get_config
-function retrieves the current configuration number from the device, i.e.\&
-the
-.Fa bConfigurationValue
-value from the configuration that is active.
-If the device is unconfigured then
-.Dv USB_UNCONFIG_NO
-is returned.
-The current configuration can be changed by calling either
-.Fn usbd_set_config_index
-or
-.Fn usbd_set_config_no .
-The difference between these functions is that
-.Fn usbd_set_config_index
-accepts a configuration index number that is less than the
-.Fa bNumConfigurations
-value from the device descriptor, whereas
-.Fn usbd_set_config_no
-requires the
-.Fa bConfigurationValue
-value of the desired configuration to be provided instead.
-To unconfigure the device, supply a configuration index of
-.Dv USB_UNCONFIG_INDEX
-to
-.Fn usbd_set_config_index ,
-or else specify a configuration number of
-.Dv USB_UNCONFIG_NO
-to
-.Fn usbd_set_config_no .
-.Pp
-The
-.Fn usbd_get_config_descriptor
-function returns a pointer to an in-memory copy of the full configuration
-descriptor of the configuration that is currently active.
-The returned pointer remains valid until the device configuration
-is changed using
-.Fn usbd_set_config_index
-or
-.Fn usbd_set_config_no .
-If the device is unconfigured then
-.Dv NULL
-is returned instead.
-.Pp
-The function
-.Fn usbd_interface_count
-returns the number of interfaces available in the current device
-configuration.
 The
-.Fn usbd_get_no_alts
-function determines the number of alternate interfaces in a full
-configuration descriptor by counting the interface descriptors with
-.Fa bInterfaceNumber
-equal to
-.Fa ifaceno
-(the count includes alternate index zero).
-The
-.Fn usbd_find_idesc
-function locates an interface descriptor within a full configuration
-descriptor.
-The
-.Fa ifaceidx
-parameter specifies the interface index number, which should be less than
-the number of interfaces in the configuration descriptor (i.e.\& the value
-returned by
-.Fn usbd_interface_count
-or the
-.Fa bNumInterface
-field from the configuration descriptor).
-An alternate interface can be specified using a non-zero
-.Fa altidx ,
-which should be less than the value returned by
-.Fn usbd_get_no_alts .
-The return value is a pointer to the requested interface descriptor
-within the full configuration descriptor, or
-.Dv NULL
-if the specified interface descriptor does not exist.
-Note that the
-.Fa altidx
-parameter specifies the alternate setting by index number starting
-at zero; it is not the alternate setting number defined in the
-interface descriptor.
-.Pp
-The function
-.Fn usbd_find_edesc
-locates an endpoint descriptor within a full configuration descriptor.
-The
-.Fa ifaceidx
-and
-.Fa altidx
-parameters are the same as described for
-.Fn usbd_find_idesc ,
-and the
-.Fa endptidx
-parameter is an endpoint index number that should be less than the
-.Fa bNumEndpoints
-field in the interface descriptor.
-The return value is a pointer to the requested endpoint descriptor
-within the full configuration descriptor, or
-.Dv NULL
-if the specified endpoint descriptor does not exist.
-Note that the
-.Fa altidx
-and
-.Fa endptidx
-parameters are index numbers starting at zero; they are not the
-alternate setting and endpoint address defined in the descriptors.
-.Pp
-The
-.Fn usbd_get_speed
-function returns the device speed.
-This can be
-.Dv USB_SPEED_LOW ,
-.Dv USB_SPEED_FULL
-or
-.Dv USB_SPEED_HIGH .
+.Nm usb
+module supports both USB Host and USB Device side mode.
+.
+.Sh USB KERNEL PROGRAMMING
+Here is a list of commonly used functions:
+.Pp
+.
+.Ft "usb_error_t"
+.Fo "usbd_transfer_setup"
+.Fa "udev"
+.Fa "ifaces"
+.Fa "pxfer"
+.Fa "setup_start"
+.Fa "n_setup"
+.Fa "priv_sc"
+.Fa "priv_mtx"
+.Fc
+.
 .Pp
-USB devices optionally support string descriptors, which can be
-retrieved using the
-.Fn usbd_get_string
-or
-.Fn usbd_get_string_desc
-functions.
-Device, configuration and interface descriptors reference strings by
-an index number that can be supplied to these functions.
-The
-.Fn usbd_get_string
-function should be used unless a non-default language is required.
-It requires that
-.Fa buf
-points to a buffer of at least
-.Dv USB_MAX_STRING_LEN
-bytes in size.
-The
-.Fa si
-parameter specified which string to retrieve.
+.
+.Ft "void"
+.Fo "usbd_transfer_unsetup"
+.Fa "pxfer"
+.Fa "n_setup"
+.Fc
+.
 .Pp
-The
-.Fn usb_find_desc
-function searches through the in-memory full configuration descriptor
-for the active configuration and finds the first descriptor that has a
-.Fa bDescriptorType
-equal to
-.Fa type ,
-and if
-.Fa subtype
-is not equal to
-.Dv USBD_SUBTYPE_ANY ,
-the descriptor must also have a
-.Fa bDescriptorSubtype
-equal to
-.Fa subtype .
-If found, then a pointer to the descriptor is returned.
-Otherwise,
-.Fn usb_find_desc
-returns
-.Dv NULL .
-The returned pointer is valid until the device configuration is changed using
-.Fn usbd_set_config_index
-or
-.Fn usbd_set_config_no .
+.
+.Ft "void"
+.Fo "usbd_transfer_start"
+.Fa "xfer"
+.Fc
+.
 .Pp
-The USB driver interface uses opaque interface handles to refer to
-configuration interfaces.
-These handles remain valid until the device configuration is changed using
-.Fn usbd_set_config_index
-or
-.Fn usbd_set_config_no .
-The
-.Fn usbd_device2interface_handle
-function retrieves an interface handle.
-The
-.Fa ifaceno
-parameter is an interface index number starting at zero.
-If the device is configured and the specified interface exists, then
-.Dv USBD_NORMAL_COMPLETION
-is returned and the interface handle is stored in
-.Fa *iface .
-Otherwise an error code is returned and
-.Fa *iface
-is not changed.
-The
-.Fn usbd_interface2device_handle
-function retrieves the device handle from an interface handle.
-This is just for convenience to save passing around the device
-handle as well as the interface handle.
-The
-.Fn usbd_set_interface
-function changes the alternate setting number for an interface to
-the alternate setting identified by the zero-based index number
-.Fa altidx .
-This operation invalidates any existing endpoints on this
-interface and their descriptors.
-The
-.Fn usbd_get_interface_altindex
-function returns the current alternative setting index as was
-specified when calling
-.Fn usbd_set_interface .
-The
-.Fn usbd_endpoint_count
-function retrieves the number of endpoints associated with the
-specified interface.
-The
-.Fn usbd_interface2endpoint_descriptor
-function returns a pointer to an in-memory endpoint descriptor for
-the endpoint that has an index number of
-.Fa index .
-This pointer remains valid until the configuration or alternate setting
-number are changed.
-The function
-.Fn usbd_get_endpoint_descriptor
-is like
-.Fn usbd_interface2endpoint_descriptor
-but it accepts a
-.Fa bEndpointAddress
-address value instead of an index.
+.
+.Ft "void"
+.Fo "usbd_transfer_stop"
+.Fa "xfer"
+.Fc
+.
 .Pp
-The
-.Fn usbd_fill_deviceinfo
-function fills out a
-.Vt usb_device_info
-structure with information about the device.
-The vendor and product names come from the device itself, falling back to
-a table lookup or just providing the IDs in hexadecimal.
-If
-.Fa usedev
-is zero then
-.Fn usbd_fill_deviceinfo
-will not attempt to retrieve the vendor and product names from the
-device.
-The usb_device_info structure is defined in
-.In dev/usb/usb.h
-as follows:
-.Bd -literal
-struct usb_device_info {
-	u_int8_t	udi_bus;
-	u_int8_t	udi_addr;	/* device address */
-	usb_event_cookie_t udi_cookie;
-	char		udi_product[USB_MAX_STRING_LEN];
-	char		udi_vendor[USB_MAX_STRING_LEN];
-	char		udi_release[8];
-	u_int16_t	udi_productNo;
-	u_int16_t	udi_vendorNo;
-	u_int16_t	udi_releaseNo;
-	u_int8_t	udi_class;
-	u_int8_t	udi_subclass;
-	u_int8_t	udi_protocol;
-	u_int8_t	udi_config;
-	u_int8_t	udi_speed;
-#define USB_SPEED_LOW  1
-#define USB_SPEED_FULL 2
-#define USB_SPEED_HIGH 3
-	int		udi_power;	/* power consumption in mA */
-	int		udi_nports;
-	char		udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
-	/* hub only: addresses of devices on ports */
-	u_int8_t	udi_ports[16];
-#define USB_PORT_ENABLED 0xff
-#define USB_PORT_SUSPENDED 0xfe
-#define USB_PORT_POWERED 0xfd
+.
+.Ft "void"
+.Fo "usbd_transfer_drain"
+.Fa "xfer"
+.Fc
+.
+.
+.
+.Sh 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:
+.
+.Pp
+.
+.Fn usbd_transfer_setup
+This function will allocate memory for and initialise an array of USB
+transfers and all required DMA memory.
+.
+This function can sleep or block waiting for resources to become
+available.
+.Fa udev
+is a pointer to "struct usb_device".
+.Fa ifaces
+is an array of interface index numbers to use. See "if_index".
+.Fa pxfer
+is a pointer to an array of USB transfer pointers that are initialized
+to NULL, and then pointed to allocated USB transfers.
+.Fa setup_start
+is a pointer to an array of USB config structures.
+.Fa n_setup
+is a number telling the USB system how many USB transfers should be
+setup.
+.Fa priv_sc
+is the private softc pointer, which will be used to initialize
+"xfer->priv_sc".
+.Fa 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.
+.
+.Pp
+.
+.Fn usbd_transfer_unsetup
+This function will release the given USB transfers and all allocated
+resources associated with these USB transfers. 
+.Fa pxfer
+is a pointer to an array of USB transfer pointers, that may be NULL,
+that should be freed by the USB system.
+.Fa 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.
+.
+.Pp
+.
+.Fn usbd_transfer_start
+This function will start the USB transfer pointed to by
+.Fa 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.
+.
+.Pp
+.
+.Fn usbd_transfer_stop
+This function will stop the USB transfer pointed to by
+.Fa 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 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".
+.
+.Pp
+.
+.Fn 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.
+.
+.Sh 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.
+.
+.
+.Pp
+.
+.Fn 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.
+.
+.Bd -literal -offset indent
+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
+		 * transfered.
+		 */
+		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;
 }
 .Ed
-.Pp
-The
-.Fn usbd_devinfo
-function generates a string description of the USB device.
-The
-.Fa cp
-argument should point to a 1024-byte buffer (XXX the maximum length
-is approximately 320 chars, but there is no sanity checking and everything uses
-1024-character buffers).
-Device class information is included if the
-.Fa showclass
-parameter is non-zero.
-.Pp
-The
-.Fn usbd_get_quirks
-function returns information from a table of devices that require
-special workarounds in order to function correctly.
-The returned structure is defined in
-.In dev/usb/usb_quirks.h
-as follows:
-.Bd -literal
-struct usbd_quirks {
-	u_int32_t uq_flags;	/* Device problems */
-};
+.
+.Sh 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 
+.Fn 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.
+.
+.Bd -literal -offset indent
+
+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);
+
 .Ed
-.Pp
-See
-.In dev/usb/usb_quirks.h
-for a list of all currently defined quirks.
-.Pp
-USB control requests are performed via
-.Vt usb_device_request_t
-structures, defined in
-.In dev/usb/usb.h
-as follows:
-.Bd -literal
-typedef struct {
-	uByte		bmRequestType;
-	uByte		bRequest;
-	uWord		wValue;
-	uWord		wIndex;
-	uWord		wLength;
-} UPACKED usb_device_request_t;
+.Sh USB TRANSFER CONFIG
+To simply the search for endpoints the
+.Nm usb
+module defines a USB config structure where it is possible to specify
+the characteristics of the wanted endpoint.
+.Bd -literal -offset indent
+
+struct usb_config { 
+	bufsize,
+	callback
+	direction,
+	endpoint,
+	frames,
+	index flags,
+	interval,
+	timeout,
+	type,
+};
+
 .Ed
-.Pp
-The
-.Fn usbd_do_request
-function performs a single request synchronously.
-The
-.Fa req
-parameter should point to a properly initialized
-.Vt usb_device_request_t ,
-and when the
-.Fa wLength
-field is non-zero,
-.Fa data
-should point at a buffer that is at least
-.Fa wLength
-bytes in length.
-The request timeout is set to 5 seconds, so the operation will fail
-with
-.Er USBD_TIMEOUT
-if the device does not respond within that time.
-The
-.Fn usbd_do_request_async
-function is like
-.Fn usbd_do_request ,
-but it does not wait for the request to complete before returning.
-This routine does not block so it can be used from contexts where
-sleeping is not allowed.
-Note that there is no notification mechanism to report when the
-operation completed nor is there a way to determine whether the
-request succeeded, so this function is of limited use.
-See
-.Fn usbd_setup_default_xfer
-and
-.Fn usbd_transfer
-for a way to invoke an asynchronous callback upon completion of
-a control request.
-The
-.Fn usbd_do_request_flags
-function is like
-.Fn usbd_do_request ,
-but additional flags can be specified, the timeout is configurable,
-and the actual number of bytes transferred is made available to the
-caller.
-The
-.Fn usbd_do_request_flags_pipe
-function uses a specified pipe instead of the default pipe.
-.Pp
-The function
-.Fn usbd_open_pipe
-creates a pipe connected to a specified endpoint on a specified interface.
-The parameter
-.Fa address
-should be the
-.Fa bEndpointAddress
-value from one of this interface's endpoint descriptors.
-If
-.Fa flags
-contains
-.Dv USBD_EXCLUSIVE_USE
-then the operation will only succeed if there are no open pipes
-already connected to the specified endpoint.
-The
-.Fn usbd_open_pipe_intr
-function creates an interrupt pipe connected to the specified endpoint.
-The parameter
-.Fa address
-should be the
-.Fa bEndpointAddress
-value from one of this interface's endpoint descriptors.
-The
-.Fa flags
-parameter is passed to
-.Fn usbd_setup_xfer .
-The
-.Fa buffer
-and
-.Fa len
-parameters define a buffer that is to be used for the interrupt transfers.
-The callback to be invoked each time a transfer completes is specified by
-.Fa cb ,
-and
-.Fa priv
-is an argument to be passed to the callback function.
-The
-.Fa ival
-parameter specifies the maximum acceptable interval between transfers;
-in practice the transfers may occur more frequently.
-The function
-.Fn usbd_pipe2device_handle
-returns the device associated with the specified
-.Fa pipe .
-.Pp
-The
-.Fn usbd_abort_pipe
-function aborts all active or waiting transfers on the specified pipe.
-Each transfer is aborted with a
-.Dv USBD_CANCELLED
-status; callback routines must detect this error code to ensure that
-they do not attempt to initiate a new transfer in response to one being
-aborted.
-This routine blocks while it is waiting for the hardware to complete
-processing of aborted transfers, so it is only safe to call it in
-contexts where sleeping is allowed.
-The function
-.Fn usbd_abort_default_pipe
-aborts all active or waiting transfers on the default pipe.
-Like
-.Fn usbd_abort_pipe ,
-it blocks waiting for the hardware processing to complete.
-.Pp
-When a pipe has no active or waiting transfers, the pipe may be closed
-using the
-.Fn usbd_close_pipe
-function.
-Once a pipe is closed, its pipe handle becomes invalid and may no longer
-be used.
-.Pp
-USB transfer handles are allocated using the function
-.Fn usbd_alloc_xfer
-and may be freed using
-.Fn usbd_free_xfer .
-.Pp
-The function
-.Fn usbd_setup_xfer
-initializes a transfer handle with the details of a transfer to or from
-a USB device.
-The
-.Fa xfer
-parameter specifies the transfer handle to initialize,
-.Fa pipe
-specifies the pipe on which the transfer is to take place, and
-.Fa priv
-is an argument that will be passed to callback function.
-The arguments
-.Fa buffer
-and
-.Fa length
-define the data buffer for the transfer.
-If
-.Fa length
-is zero then the
-.Fa buffer
-may be
-.Dv NULL .
-The
-.Fa flags
-parameter may contain the following flags:
-.Bl -tag -width ".Dv USBD_FORCE_SHORT_XFER"
-.It Dv USBD_NO_COPY
-This is used in association with
-.Fn usbd_alloc_buffer
-and
-.Fn usbd_free_buffer
-to use a dedicated DMA-capable buffer for the transfer.
-.It Dv USBD_SYNCHRONOUS
-Wait for the transfer to compete in
-.Fn usbd_transfer .
-.It Dv USBD_SHORT_XFER_OK
-Permit transfers shorter than the requested data length.
-.It Dv USBD_FORCE_SHORT_XFER
-Force a short transfer at the end of a write operation to let the
-device know that the transfer has ended.
+.
+.Pp
+.Fa 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.
+.
+.Pp
+.Fa 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.
+.
+.Pp
+.Fa 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.
+.
+.Pp
+.Fa 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:
+.Bl -tag
+.It UE_INTERRUPT
+"0" use the default interrupt interval based on endpoint descriptor.
+"Else" use the given value for polling rate.
+.It UE_ISOCHRONOUS
+"0" use default. "Else" the value is ignored.
+.It UE_BULK
+.It UE_CONTROL
+"0" no transfer pre-delay. "Else" a delay as given by this field in
+milliseconds is inserted before the hardware is started when
+"usbd_transfer_submit()" is called.
+.Pp
+NOTE: The transfer timeout, if any, is started after that the
+pre-delay has elapsed!
 .El
+.
 .Pp
-The
 .Fa timeout
-parameter specifies a timeout for the transfer in milliseconds.
-A value of
-.Dv USBD_NO_TIMEOUT
-indicates that no timeout should be configured.
-The parameter
-.Fa callback
-specifies the function to call when the transfer completes.
-Note that
-.Fn usbd_setup_xfer
-does not actually initiate the transfer.
-The
-.Fn usbd_setup_default_xfer
-initializes a control transfer for the default pipe.
-The
-.Fa req
-parameter should point at a completed
-.Vt usb_device_request_t
-structure.
-The function
-.Fa usbd_setup_isoc_xfer
-initializes a transfer for an isochronous pipe.
-.Pp
-The function
-.Fn usbd_transfer
-initiates a transfer.
-Normally it returns
-.Dv USBD_IN_PROGRESS
-to indicate that the transfer has been queued.
-If the USB stack is operating in polling mode, or if the transfer
-is synchronous, then
-.Dv USBD_NORMAL_COMPLETION
-may be returned.
-Other return values indicate that the transfer could not be
-initiated due to an error.
-The
-.Fn usbd_sync_transfer
-function executes a transfer synchronously.
-It will sleep waiting for the transfer to complete and then return
-the transfer status.
-Note that if the transfer has a callback routine, this will be
-invoked before
-.Fn usbd_sync_transfer
-returns.
-.Pp
-The
-.Fn usbd_intr_transfer
-and
-.Fn usbd_bulk_transfer
-functions set up a transfer and wait synchronously for it to complete
-but they allows signals to interrupt the wait.
-They returns
-.Dv USBD_INTERRUPTED
-if the transfer was interrupted by a signal.
-XXX these two functions are identical apart from their names.
-.Pp
-The function
-.Fn usbd_get_xfer_status
-retrieves various information from a completed transfer.
-If the
-.Fa priv
-parameter is not NULL then the callback private argument is
-stored in
-.Fa *priv .
-If
-.Fa buffer
-is not NULL then the transfer buffer pointer is stored in
-.Fa *buffer .
-The actual number of bytes transferred is stored in
-.Fa *count
-if
-.Fa count is not NULL.
-Finally, the transfer status is stored in
-.Fa *status
-if
-.Fa status
-is not NULL.
-.Pp
-The
-.Fn usbd_clear_endpoint_stall
-function clears an endpoint stall condition synchronously, i.e.\&
-it sleeps waiting for the stall clear request to complete.
-The function
-.Fn usbd_clear_endpoint_stall_async
-performs the same function asynchronously, but it provides no
-way to determine when the request completed, or whether it was
-successful.
-The
-.Fn usbd_clear_endpoint_toggle
-function instructs the host controller driver to reset the toggle bit
-on a pipe.
-This is used when manually clearing an endpoint stall using a
-control pipe request, in order to ensure that the host controller
-driver and the USB device restart with the same toggle value.
-.Pp
-Normally the USB subsystem maps and copies data to and from
-DMA-capable memory each time a transfer is performed.
-The function
-.Fn usbd_alloc_buffer
-allocates a permanent DMA-capable buffer associated with the
-transfer to avoid this overhead.
-The return value is the virtual address of the buffer.
-Any time that
-.Fn usbd_setup_xfer
-is called on the transfer with the
-.Dv USBD_NO_COPY
-flag enabled, the allocated buffer will be used directly and
-the
-.Fa buffer
-argument passed to
-.Fn usbd_setup_xfer
-will be ignored.
-The
-.Fn usbd_get_buffer
-function returns a pointer to the virtual address of a buffer previously
-allocated by
-.Fn usbd_alloc_buffer .
-Finally,
-.Fn usbd_free_buffer
-deallocates the buffer.
-.Pp
-The
-.Fn usbd_errstr
-function converts a status code into a string for display.
-.Pp
-The function
-.Fn usbd_set_polling
-enables or disables polling mode.
-In polling mode, all operations will busy-wait for the device to
-respond, so its use is effectively limited to boot time and kernel
-debuggers.
-It is important to match up calls that enable and disable polling
-mode, because the implementation just increments a polling reference
-count when
-.Fa on
-is non-zero and decrements it when
-.Fa on
-is zero.
-The
-.Fn usbd_dopoll
-causes the host controller driver to poll for any activity.
-This should only be used when polling mode is enabled.
+field, if non-zero, will set the transfer timeout in milliseconds. If
+the "timeout" field is zero and the transfer type is ISOCHRONOUS a
+timeout of 250ms will be used.
+.
+.Pp
+.Fa frames
+field sets the maximum number of frames. If zero is specified it will
+yield the following results:
+.Bl -tag
+.It UE_BULK
+xfer->nframes = 1;
+.It UE_INTERRUPT
+xfer->nframes = 1;
+.It UE_CONTROL
+xfer->nframes = 2;
+.It UE_ISOCHRONOUS
+Not allowed. Will cause an error.
+.El
+.
 .Pp
-The
-.Fn usbd_ratecheck
-function is used to limit the rate at which error messages are
-printed to approximately once per second.
-The
-.Fa last
-argument should point at a persistent
-.Vt "struct timeval" .
-A value of 1 will be returned if a message should be printed, but if
-.Fn usbd_ratecheck
-has already been called with the same
-.Vt "struct timeval"
-parameter in the last second then 0 is returned and the error message
-should be suppressed.
+.Fa 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.
+.
 .Pp
-The functions
-.Fn usb_detach_wait
-and
-.Fn usb_detach_wakeup
-are used to wait for references to drain before completing the
-detachment of a device.
-The
-.Fn usb_detach_wait
-function will wait up to 60 seconds to receive a signal from
-.Fn usb_detach_wait .
-.Ss "USB Descriptors"
-The USB specification defines a number of standard descriptors by
-which USB devices report their attributes.
-These descriptors are fixed-format structures that all USB devices
-make available through USB control pipe requests.
+.Fa 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.
+.
 .Pp
-Every USB device has exactly one USB device descriptor.
-The USB subsystem retrieves this automatically when a device is
-attached, and a copy of the descriptor is kept in memory.
-The
-.Fn usbd_get_device_descriptor
-function returns a pointer to the descriptor.
-The device descriptor structure is defined in
-.In dev/usb/usb.h
-as follows:
-.Bd -literal
-typedef struct {
-	uByte		bLength;
-	uByte		bDescriptorType;
-	uWord		bcdUSB;
-#define UD_USB_2_0		0x0200
-#define UD_IS_USB2(d) (UGETW((d)->bcdUSB) >= UD_USB_2_0)
-	uByte		bDeviceClass;
-	uByte		bDeviceSubClass;
-	uByte		bDeviceProtocol;
-	uByte		bMaxPacketSize;
-	/* The fields below are not part of the initial descriptor. */
-	uWord		idVendor;
-	uWord		idProduct;
-	uWord		bcdDevice;
-	uByte		iManufacturer;
-	uByte		iProduct;
-	uByte		iSerialNumber;
-	uByte		bNumConfigurations;
-} UPACKED usb_device_descriptor_t;
-#define USB_DEVICE_DESCRIPTOR_SIZE 18
-.Ed
+.Fa flags
+field has type "struct usb_xfer_flags" and allows one to set initial
+flags an USB transfer. Valid flags are:
+.Bl -tag
+.It 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 "wMaxPacketSize". This flag can be changed during
+operation.
+.It 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.
+.It short_frames_ok
+This flag allows the reception of multiple short USB frames. This flag
+only has effect for BULK and INTERRUPT endpoints and if the number of
+frames received is greater than 1. This flag can be changed during
+operation.
+.It 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:
+.Bl -tag
+.It 1
+The failing USB transfer is stopped using "usbd_transfer_stop()".
+.It 2
+The failing USB transfer performs a successful transfer.
+.El
+The purpose of this flag is to avoid races when multiple transfers are
+queued for execution on an USB endpoint, 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 endpoint.
+.
+This flag can be changed during operation.
+.Pp
+"BOF" is short for "Block On Failure"
+.Pp
+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.
+.
+.
+.It 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 can not be changed during operation.
+.
+.
+.It 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 can not be changed during operation.
+.
+.
+.It 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.
+.
+.
+.It no_pipe_ok
+Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This
+flag can not be changed during operation.
+.
+.
+.It stall_pipe
+.Bl -tag
+.It 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.
+.It 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.
+.El
 .Pp
-USB devices have at least one configuration descriptor.
-The
-.Fa bNumConfigurations
-field of the device descriptor specifies the number of configuration
-descriptors that a device supports.
-The
-.Fn usbd_get_config_desc
-function retrieves a particular configuration descriptor from the device
-and the
-.Fn usbd_get_config_desc_full
-function retrieves a full
-.Fa wTotalLength
-length configuration descriptor, which includes all related interface
-and endpoint descriptors.
-Only one configuration may be active at a time.
-The
-.Fn usbd_set_config_index
-function activates a specified configuration.
-The configuration descriptor structure is defined in
-.In dev/usb/usb.h
-as follows:
-.Bd -literal
-typedef struct {
-	uByte		bLength;
-	uByte		bDescriptorType;
-	uWord		wTotalLength;
-	uByte		bNumInterface;
-	uByte		bConfigurationValue;
-	uByte		iConfiguration;
-	uByte		bmAttributes;
-#define UC_BUS_POWERED		0x80
-#define UC_SELF_POWERED		0x40
-#define UC_REMOTE_WAKEUP	0x20
-	uByte		bMaxPower; /* max current in 2 mA units */
-#define UC_POWER_FACTOR 2
-} UPACKED usb_config_descriptor_t;
-#define USB_CONFIG_DESCRIPTOR_SIZE 9
-.Ed
+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.
+.
+.El
 .Pp
-Each device configuration provides one or more interfaces.
-The
-.Fa bNumInterface
-field of the configuration descriptor specifies the number of
-interfaces associated with a device configuration.
-Interfaces are described by an interface descriptor, which is defined in
-.In dev/usb/usb.h
-as follows:
-.Bd -literal
-typedef struct {
-	uByte		bLength;
-	uByte		bDescriptorType;
-	uByte		bInterfaceNumber;
-	uByte		bAlternateSetting;
-	uByte		bNumEndpoints;
-	uByte		bInterfaceClass;
-	uByte		bInterfaceSubClass;
-	uByte		bInterfaceProtocol;
-	uByte		iInterface;
-} UPACKED usb_interface_descriptor_t;
-#define USB_INTERFACE_DESCRIPTOR_SIZE 9
-.Ed
+.Fa 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 interrupt pipes.
+.
+This field is mandatory.
 .Pp
-Configurations may also have alternate interfaces with the same
-.Fa bInterfaceNumber
-but different
-.Fa bAlternateSetting
-values.
-These alternate interface settings may be selected by passing a
-non-zero
-.Fa altidx
-parameter to
-.Fn usbd_set_interface .
+NOTE: For control transfers "bufsize" includes the length of the
+request structure.
+.
 .Pp
-Interfaces have zero or more endpoints, and each endpoint has an
-endpoint descriptor.
-Note that endpoint zero, which is always present, does not have an
-endpoint descriptor, and it is never included in the
-.Fa bNumEndpoints
-count of endpoints.
-The endpoint descriptor is defined in
-.In dev/usb/usb.h
-as follows:
-.Bd -literal
-typedef struct {
-	uByte		bLength;
-	uByte		bDescriptorType;
-	uByte		bEndpointAddress;
-#define UE_GET_DIR(a)	((a) & 0x80)
-#define UE_SET_DIR(a,d) ((a) | (((d)&1) << 7))
-#define UE_DIR_IN	0x80
-#define UE_DIR_OUT	0x00
-#define UE_ADDR		0x0f
-#define UE_GET_ADDR(a)	((a) & UE_ADDR)
-	uByte		bmAttributes;
-#define UE_XFERTYPE	0x03
-#define	 UE_CONTROL	0x00
-#define	 UE_ISOCHRONOUS 0x01
-#define	 UE_BULK	0x02
-#define	 UE_INTERRUPT	0x03
-#define UE_GET_XFERTYPE(a)	((a) & UE_XFERTYPE)
-#define UE_ISO_TYPE	0x0c
-#define	 UE_ISO_ASYNC	0x04
-#define	 UE_ISO_ADAPT	0x08
-#define	 UE_ISO_SYNC	0x0c
-#define UE_GET_ISO_TYPE(a)	((a) & UE_ISO_TYPE)
-	uWord		wMaxPacketSize;
-	uByte		bInterval;
-} UPACKED usb_endpoint_descriptor_t;
-#define USB_ENDPOINT_DESCRIPTOR_SIZE 7
-.Ed
-.Sh RETURN VALUES
-Many functions return a
-.Vt usbd_status
-type to indicate the outcome of the operation.
-If the operation completed successfully then
-.Dv USBD_NORMAL_COMPLETION
-is returned.
-Operations that have been started but not yet completed will return
-.Dv USBD_IN_PROGRESS .
-Other errors usually indicate a problem.
-Error codes can be converted to strings using
-.Fn usbd_errstr .
-.Sh ERRORS
-.Bl -tag -width ".Er USBD_PENDING_REQUESTS"
-.It Bq Er USBD_PENDING_REQUESTS
-A pipe could not be closed because there are active requests.
-.It Bq Er USBD_NOT_STARTED
-The transfer has not yet been started.
-.It Bq Er USBD_INVAL
-An invalid value was supplied.
-.It Bq Er USBD_NOMEM
-An attempt to allocate memory failed.
-.It Bq Er USBD_CANCELLED
-The transfer was aborted.
-.It Bq Er USBD_BAD_ADDRESS
-The specified endpoint address was not found.
-.It Bq Er USBD_IN_USE
-The endpoint is already in use, or the configuration cannot be changed
-because some of its endpoints are in use.
-.It Bq Er USBD_NO_ADDR
-No free USB devices addresses were found to assign to the device.
-.It Bq Er USBD_SET_ADDR_FAILED
-The device address could not be set.
-.It Bq Er USBD_NO_POWER
-Insufficient power was available for the device.
-.It Bq Er USBD_TOO_DEEP
-Too many levels of chained hubs were found.
-.It Bq Er USBD_IOERROR
-There was an error communicating with the device.
-.It Bq Er USBD_NOT_CONFIGURED
-An operation that requires an active configuration was attempted while
-the device was in an unconfigured state.
-.It Bq Er USBD_TIMEOUT
-A transfer timed out.
-.It Bq Er USBD_SHORT_XFER
-A transfer that disallowed short data lengths completed with less than
-the requested length transferred.
-.It Bq Er USBD_STALLED
-A transfer failed because the pipe is stalled.
-.It Bq Er USBD_INTERRUPTED
-An interruptible operation caught a signal.
-.El
+.Fa callback
+pointer sets the USB callback. This field is mandatory.
+.
+.
+.Sh USB LINUX COMPAT LAYER
+The
+.Nm usb
+module supports the Linux USB API.
+.
+.
 .Sh SEE ALSO
-.Xr usb 4
+.Xr libusb 3 ,
+.Xr usb 4 ,
+.Xr usbconfig 8
+.Sh STANDARDS
+The
+.Nm usb
+module complies with the USB 2.0 standard.
 .Sh HISTORY
-The USB driver interface first appeared in
-.Fx 3.0 .
-.Sh AUTHORS
-The USB driver was written by
-.An Lennart Augustsson
-for the
-.Nx
-project.
-.Pp
-.An -nosplit
-This manual page was written by
-.An Ian Dowse Aq iedowse@FreeBSD.org .
+The
+.Nm usb
+module has been inspired by the NetBSD USB stack initially written by
+Lennart Augustsson. The
+.Nm usb
+module was written by
+.An Hans Petter Selasky Aq hselasky@freebsd.org .