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

changeover. Needs much more content still.

1 files changed, 1 insertions, 542 deletions

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 ,