Copyright (c) 2012 Matthew R. Green
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.
3. The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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.
Copyright (c) 1999 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Lennart Augustsson.
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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.Dd May 12, 2012 .Dt USBDI 9 .Os .Sh NAME .Nm usbdi .Nd USB device drivers interface .Sh SYNOPSIS n dev/usb/usb.h n dev/usb/usbdi.h n dev/usb/usbdi_util.h .Sh DESCRIPTION Device driver access to the USB bus centers around transfers. A transfer describes a communication with a USB device. A transfer is an abstract concept that can result in several physical packets being transferred to or from a device.
p A transfer is described by a .Va usbd_xfer_handle , a largely opaque cookie. Allocated and deallocate are performed with .Fn usbd_alloc_xfer and .Fn usbd_free_xfer . The data describing the transfer is filled by either .Fn usbd_setup_default_xfer for control pipe transfers, by .Fn usbd_setup_xfer for bulk and interrupt transfers, and by .Fn usbd_setup_isoc_xfer for isochronous transfers.
p A pipe is a logical connection to a USB device. Pipes are created and destroyed by using the .Fn usbd_open_pipe , .Fn usbd_open_pipe_intr and .Fn usbd_close_pipe functions. It is common to have more than one pipe per device. Pipes are used to allocate .Va usbd_xfer_handle is required to Transfers are aborted via their parent pipe with .Fn usbd_abort_pipe . The .Fn usbd_clear_endpoint_stall and .Fn usbd_clear_endpoint_stall_async functions are used to clear endpoint halt in either a synchronous or asynchronous fashion. The .Fn usbd_bulk_transfer and .Fn usbd_intr_transfer functions are used to transfer data in either an interrupt or bulk fashion.
p A request is described by a .Va usb_device_request_t which must be initialised as necessary before calling either .Fn usbd_do_request or .Fn usbd_do_request_flags to submit the request. See the .Sx INITIALISING USB REQUESTS section for more details.
p Error handling and other return values are described in .Xr usbd_status 9 . .Sh FUNCTIONS .Ss Functions offered by usbdi.h l -tag -width indent t Dv usbd_status usbd_open_pipe(usbd_interface_handle iface, uint8_t address, uint8_t flags, usbd_pipe_handle *pipe) t Dv usbd_status usbd_close_pipe(usbd_pipe_handle pipe) t Dv usbd_status usbd_transfer(usbd_xfer_handle req) t Dv usbd_xfer_handle usbd_alloc_xfer(usbd_device_handle) t Dv usbd_status usbd_free_xfer(usbd_xfer_handle xfer) t Dv void usbd_setup_xfer(usbd_xfer_handle xfer, usbd_pipe_handle pipe, usbd_private_handle priv, void *buffer, uint32_t length, uint16_t flags, uint32_t timeout, usbd_callback) t Dv void usbd_setup_default_xfer(usbd_xfer_handle xfer, usbd_device_handle dev, usbd_private_handle priv, uint32_t timeout, usb_device_request_t *req, void *buffer, uint32_t length, uint16_t flags, usbd_callback) t Dv void usbd_setup_isoc_xfer(usbd_xfer_handle xfer, usbd_pipe_handle pipe, usbd_private_handle priv, uint16_t *frlengths, uint32_t nframes, uint16_t flags, usbd_callback) t Dv void usbd_get_xfer_status(usbd_xfer_handle xfer, usbd_private_handle *priv, void **buffer, uint32_t *count, usbd_status *status) t Dv usb_endpoint_descriptor_t *usbd_interface2endpoint_descriptor(usbd_interface_handle iface, uint8_t address) t Dv usbd_status usbd_abort_pipe(usbd_pipe_handle pipe) t Dv usbd_status usbd_clear_endpoint_stall(usbd_pipe_handle pipe) t Dv usbd_status usbd_clear_endpoint_stall_async(usbd_pipe_handle pipe) t Dv usbd_status usbd_endpoint_count(usbd_interface_handle dev, uint8_t *count) t Dv usbd_status usbd_interface_count(usbd_device_handle dev, uint8_t *count) t Dv usbd_status usbd_interface2device_handle(usbd_interface_handle iface, usbd_device_handle *dev) t Dv usbd_status usbd_device2interface_handle(usbd_device_handle dev, uint8_t ifaceno, usbd_interface_handle *iface)
p
t Dv usbd_device_handle usbd_pipe2device_handle(usbd_pipe_handle) t Dv void *usbd_alloc_buffer(usbd_xfer_handle req, uint32_t size) t Dv void usbd_free_buffer(usbd_xfer_handle req) t Dv void *usbd_get_buffer(usbd_xfer_handle xfer) t Dv usbd_status usbd_sync_transfer(usbd_xfer_handle req) t Dv usbd_status usbd_open_pipe_intr(usbd_interface_handle iface, uint8_t address, uint8_t flags, usbd_pipe_handle *pipe,
usbd_private_handle priv, void *buffer,
uint32_t length, usbd_callback)
t Dv usbd_status usbd_do_request(usbd_device_handle pipe, usb_device_request_t *req, void *data) t Dv usbd_status usbd_do_request_flags(usbd_device_handle pipe, usb_device_request_t *req, void *data, uint16_t flags, int *)
t Dv usb_interface_descriptor_t *usbd_get_interface_descriptor(usbd_interface_handle iface) t Dv usb_config_descriptor_t *usbd_get_config_descriptor(usbd_device_handle dev) t Dv usb_device_descriptor_t *usbd_get_device_descriptor(usbd_device_handle dev) t Dv usbd_status usbd_set_interface(usbd_interface_handle, int) t Dv int usbd_get_no_alts(usb_config_descriptor_t *, int) t Dv usbd_status usbd_get_interface(usbd_interface_handle iface, uint8_t *aiface) t Dv void usbd_fill_deviceinfo (usbd_device_handle dev, struct usb_device_info *di) t Dv int usbd_get_interface_altindex(usbd_interface_handle iface) t Dv usb_interface_descriptor_t *usbd_find_idesc(usb_config_descriptor_t *cd, int iindex, int ano) t Dv usb_endpoint_descriptor_t *usbd_find_edesc(usb_config_descriptor_t *cd, int ifaceidx, int altidx, int endptidx)
t Dv const char *usbd_errstr(usbd_status err) .El
.Ss Utilities from usbdi_util.h
Based on the routines in
.Dv "usbdi.h"
a number of utility functions have been defined that are accessible
through
.Dv "usbdi_util.h"
l -tag -width indent t Dv usbd_status usbd_get_desc(usbd_device_handle dev, int type, int index, int len, void *desc)
t Dv usbd_status usbd_get_config_desc(usbd_device_handle, int, usb_config_descriptor_t *)
t Dv usbd_status usbd_get_config_desc_full(usbd_device_handle, int, void *, int)
t Dv usbd_status usbd_get_device_desc(usbd_device_handle dev, usb_device_descriptor_t *d)
t Dv usbd_status usbd_set_address(usbd_device_handle dev, int addr) t Dv usbd_status usbd_get_port_status(usbd_device_handle, int, usb_port_status_t *)
t Dv usbd_status usbd_set_hub_feature(usbd_device_handle dev, int) t Dv usbd_status usbd_clear_hub_feature(usbd_device_handle, int) t Dv usbd_status usbd_set_port_feature(usbd_device_handle dev, int, int) t Dv usbd_status usbd_clear_port_feature(usbd_device_handle, int, int) t Dv usbd_status usbd_get_device_status(usbd_device_handle,usb_status_t*) t Dv usbd_status usbd_get_hub_status(usbd_device_handle dev, usb_hub_status_t *st)
t Dv usbd_status usbd_set_protocol(usbd_interface_handle dev, int report) t Dv usbd_status usbd_get_report_descriptor (usbd_device_handle dev, int ifcno, int repid, int size, void *d)
t Dv struct usb_hid_descriptor *usbd_get_hid_descriptor (usbd_interface_handle ifc)
t Dv usbd_status usbd_set_report (usbd_interface_handle iface,int type,int id,void *data,int len)
t Dv usbd_status usbd_set_report_async (usbd_interface_handle iface,int type,int id,void *data,int len)
t Dv usbd_status usbd_get_report (usbd_interface_handle iface,int type,int id,void *data,int len)
t Dv usbd_status usbd_set_idle (usbd_interface_handle iface, int duration, int id)
t Dv usbd_status usbd_alloc_report_desc (usbd_interface_handle ifc, void **descp, int *sizep, int mem)
t Dv usbd_status usbd_get_config (usbd_device_handle dev, uint8_t *conf)
t Dv usbd_status usbd_get_string_desc (usbd_device_handle dev, int sindex, int langid,
usb_string_descriptor_t *sdesc)
t Dv void usbd_delay_ms(usbd_device_handle, u_int) t Dv usbd_status usbd_set_config_no (usbd_device_handle dev, int no, int msg)
t Dv usbd_status usbd_set_config_index (usbd_device_handle dev, int index, int msg)
t Dv usbd_status usbd_bulk_transfer (usbd_xfer_handle xfer, usbd_pipe_handle pipe, uint16_t flags,
uint32_t timeout, void *buf, uint32_t *size, char *lbl)
t Dv usbd_status usbd_intr_transfer (usbd_xfer_handle xfer, usbd_pipe_handle pipe, uint16_t flags,
uint32_t timeout, void *buf, uint32_t *size, char *lbl)
these are very different in usbmp
t Dv void usb_detach_waitold(device_t) t Dv void usb_detach_wakeupold(device_t) .It Dv void usb_detach_wait(device_t dv, kcondvar_t *cv, kmutex_t *lk)
.It Dv void usb_detach_broadcast(device_t dv, kcondvar_t *cv)
.El
.Sh INITIALISING USB REQUESTS
There are 5 members of a
.Va usb_device_request_t
that must be initialised:
p l -item -offset offset -compact t .Vt uByte bmRequestType ; t .Vt uByte bRequest ; t .Vt uWord wValue ; t .Vt uWord wIndex ; t .Vt uWord wLength ; .El
p The first two are normal byte values that may be simply assigned, but the last three must be initialised with the .Dv USETW() macro.
p The .Fa bmRequestType holds the request type of this USB request, which describes the indended recipient of the request.
p This may be one of: l -tag -offset offset -compact t Dv UT_WRITE t Dv UT_READ .El
p with one of: l -tag -offset offset -compact t Dv UT_STANDARD t Dv UT_CLASS t Dv UT_VENDOR .El
p and with one of: l -tag -offset offset -compact t Dv UT_DEVICE t Dv UT_INTERFACE t Dv UT_ENDPOINT t Dv UT_OTHER .El
p These are also in combinations as: l -tag -offset offset -compact t Dv UT_READ_DEVICE t Dv UT_READ_INTERFACE t Dv UT_READ_ENDPOINT t Dv UT_WRITE_DEVICE t Dv UT_WRITE_INTERFACE t Dv UT_WRITE_ENDPOINT t Dv UT_READ_CLASS_DEVICE t Dv UT_READ_CLASS_INTERFACE t Dv UT_READ_CLASS_OTHER t Dv UT_READ_CLASS_ENDPOINT t Dv UT_WRITE_CLASS_DEVICE t Dv UT_WRITE_CLASS_INTERFACE t Dv UT_WRITE_CLASS_OTHER t Dv UT_WRITE_CLASS_ENDPOINT t Dv UT_READ_VENDOR_DEVICE t Dv UT_READ_VENDOR_INTERFACE t Dv UT_READ_VENDOR_OTHER t Dv UT_READ_VENDOR_ENDPOINT t Dv UT_WRITE_VENDOR_DEVICE t Dv UT_WRITE_VENDOR_INTERFACE t Dv UT_WRITE_VENDOR_OTHER t Dv UT_WRITE_VENDOR_ENDPOINT .El
p The .Fa bRequest describes which request is being made. The available values are: l -tag -offset offset -compact t Dv UR_GET_STATUS t Dv UR_CLEAR_FEATURE t Dv UR_SET_FEATURE t Dv UR_SET_ADDRESS t Dv UR_GET_DESCRIPTOR t Dv UR_SET_DESCRIPTOR t Dv UR_GET_CONFIG t Dv UR_SET_CONFIG t Dv UR_GET_INTERFACE t Dv UR_SET_INTERFACE t Dv UR_SYNCH_FRAME .El
p The .Fa wValue , .Fa wIndex and .Fa wLength are device-specific values and must be initialised with the .Dv USETW() macro.
p .Sh USB REQUEST TYPES AND STRUCTURES The .Dv UR_GET_STATUS request operates on a .Va usb_status_t structure, which has this member: l -item -offset offset -compact t .Vt uWord wStatus ; .El
p For device status requests, the .Fa wStatus member may have either of these bit flags set: l -tag -offset offset -compact t Dv UDS_SELF_POWERED t Dv UDS_REMOTE_WAKEUP .El
p For endpoint status requests, the .Fa wStatus member may have this bit flag set: l -tag -offset offset -compact t Dv UES_HALT .El
p The .Dv UR_CLEAR_FEATURE and .Dv UR_SET_FEATURE requests clear or set special features on USB devices. The values for .Va wValue , .Va wIndex and .Va wLength depend upon the device and device type.
p The .Dv UR_SET_ADDRESS request sets the virtual USB address of a port using the .Va wValue .
p The .Dv UR_GET_DESCRIPTOR and .Dv UR_SET_DESCRIPTOR requests operate on a .Va usb_descriptor_t structure, which has these members: l -item -offset offset -compact t .Vt uByte bLength ; t .Vt uByte bDescriptorType ; .El
p The .Fa bDescriptorType member may be one of the following values: l -tag -offset offset -compact t Dv UDESC_DEVICE t Dv UDESC_CONFIG t Dv UDESC_STRING t Dv UDESC_INTERFACE t Dv UDESC_ENDPOINT t Dv UDESC_DEVICE_QUALIFIER t Dv UDESC_OTHER_SPEED_CONFIGURATION t Dv UDESC_INTERFACE_POWER t Dv UDESC_OTG t Dv UDESC_DEBUG t Dv UDESC_INTERFACE_ASSOC t Dv UDESC_CS_DEVICE t Dv UDESC_CS_CONFIG t Dv UDESC_CS_STRING t Dv UDESC_CS_INTERFACE t Dv UDESC_CS_ENDPOINT t Dv UDESC_HUB .El
p
these have API front ends
.It Dv UR_GET_CONFIG
.It Dv UR_SET_CONFIG
.It Dv UR_GET_INTERFACE
.It Dv UR_SET_INTERFACE
this isn't supported
.It Dv UR_SYNCH_FRAME
.Sh SEE ALSO
.Xr usb 4 ,
.Xr usbd_status 9
.Sh HISTORY
This
.Nm
interface first appeared in
.Nx 1.4 .
The interface is based on an early definition from the OpenUSBDI group
within the USB organisation.
Right after this definition the OpenUSBDI development got closed for open
source developers, so this interface has not followed the further changes.
The OpenUSBDI specification is now available again, but looks different.
.Sh BUGS
This manual is under development, so its biggest shortcoming is
incompleteness.
p This manual is also out of date.