0a9a8c2efa
USB device drivers use to talk to USB devices. This is probably still a bit rough and it does not yet include the functions specific to HID, ethernet, hubs, host controller drivers, task threads or debugging.
1254 lines
34 KiB
Groff
1254 lines
34 KiB
Groff
.\"
|
|
.\" 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 .
|