xref: /freebsd/share/man/man9/usbdi.9 (revision 0a9a8c2efa2d9fd61a61dd0dc118f445dd8054d2)

.\"
.\" Copyright (c) 2005 Ian Dowse <iedowse@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	$FreeBSD$
.Dd December 30, 2005
.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 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
.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 .
.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.
.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 .
.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.
.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
}
.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 approx 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 */
};
.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;
.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.
.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.
.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.
.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.
.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
.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
.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
.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 .
.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
.Sh SEE ALSO
.Xr usb 4
.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 .