diff options
Diffstat (limited to 'static/netbsd/man9/usbdi.9')
| -rw-r--r-- | static/netbsd/man9/usbdi.9 | 987 |
1 files changed, 987 insertions, 0 deletions
diff --git a/static/netbsd/man9/usbdi.9 b/static/netbsd/man9/usbdi.9 new file mode 100644 index 00000000..3441acc8 --- /dev/null +++ b/static/netbsd/man9/usbdi.9 @@ -0,0 +1,987 @@ +.\" $NetBSD: usbdi.9,v 1.37 2022/08/14 19:12:23 skrll Exp $ +.\" +.\" 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. +.\" +.\" 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, 2016 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson and Nick Hudson. +.\" +.\" 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 April 24, 2016 +.Dt USBDI 9 +.Os +.Sh NAME +.Nm usbdi +.Nd USB device drivers interface +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.In dev/usb/usbdi_util.h +.Ss Functions offered by usbdi.h +.Ft usbd_status +.Fn usbd_open_pipe "struct usbd_interface *iface" "uint8_t address" \ + "uint8_t flags" "struct usbd_pipe **pipe" +.Ft usbd_status +.Fn usbd_close_pipe "struct usbd_pipe *pipe" +.Ft usbd_status +.Fn usbd_transfer "struct usbd_xfer *xfer" +.Ft struct usbd_xfer * +.Fn usbd_setup_xfer "struct usbd_xfer *xfer" \ + "void *priv" "void *buffer" "uint32_t length" \ + "uint16_t flags" "uint32_t timeout" "usbd_callback" +.Ft void +.Fn usbd_setup_default_xfer "struct usbd_xfer *xfer" \ + "struct usbd_device *dev" "void *priv" \ + "uint32_t timeout" "usb_device_request_t *req" " void *buffer" \ + "uint32_t length" "uint16_t flags" "usbd_callback" +.Ft void +.Fn usbd_setup_isoc_xfer "struct usbd_xfer *xfer" \ + "void *priv" "uint16_t *frlengths" \ + "uint32_t nframes" "uint16_t flags" "usbd_callback" +.Ft void +.Fn usbd_get_xfer_status "struct usbd_xfer *xfer" "void **priv" \ + "void **buffer" "uint32_t *count" "usbd_status *status" +.Ft usb_endpoint_descriptor_t * +.Fn usbd_interface2endpoint_descriptor "struct usbd_interface *iface" \ + "uint8_t address" +.Ft usbd_status +.Fn usbd_abort_pipe "struct usbd_pipe *pipe" +.Ft usbd_status +.Fn usbd_abort_default_pipe "struct usbd_device *dev" +.Ft usbd_status +.Fn usbd_clear_endpoint_stall "struct usbd_pipe *pipe" +.Ft usbd_status +.Fn usbd_clear_endpoint_stall_async "struct usbd_pipe *pipe" +.Ft void +.Fn usbd_clear_endpoint_toggle "struct usbd_pipe *pipe" +.Ft usbd_status +.Fn usbd_endpoint_count "struct usbd_interface *dev" "uint8_t *count" +.Ft usbd_status +.Fn usbd_interface_count "struct usbd_device *dev" "uint8_t *count" +.Ft usbd_status +.Fn usbd_interface2device_handle "struct usbd_interface *iface" "struct usbd_device **dev" +.Ft usbd_status +.Fn usbd_device2interface_handle "struct usbd_device *dev" "uint8_t ifaceno" "struct usbd_interface **iface" +.Pp +.Ft struct usbd_device * +.Fn usbd_pipe2device_handle "struct usbd_pipe *pipe" +.Ft int +.Fn usbd_create_xfer "struct usbd_pipe *pipe" "size_t len" \ +"unsigned int flags" "unsigned int nframes" "struct usbd_xfer **xp" +.Ft void +.Fn usbd_destroy_xfer "struct usbd_xfer *xfer" +.Ft void * +.Fn usbd_get_buffer "struct usbd_xfer *xfer" +.Ft usbd_status +.Fn usbd_sync_transfer "struct usbd_xfer *req" +.Ft usbd_status +.Fn usbd_sync_transfer_sig "struct usbd_xfer *req" +.Ft usbd_status +.Fn usbd_open_pipe_intr "struct usbd_interface *iface" "uint8_t address" \ + "uint8_t flags" "struct usbd_pipe **pipe" \ + "void *priv" "void *buffer" \ + "uint32_t length" "usbd_callback callback" "int interval" +.Ft usbd_status +.Fn usbd_do_request "struct usbd_device *dev" "usb_device_request_t *req" \ + "void *data" +.Ft usbd_status +.Fn usbd_do_request_flags "struct usbd_device *dev" \ + "usb_device_request_t *req" "void *data" "uint16_t flags" "int *actlen" \ + "uint32_t timo" +.Ft usb_interface_descriptor_t * +.Fn usbd_get_interface_descriptor "struct usbd_interface *iface" +.Ft usb_config_descriptor_t * +.Fn usbd_get_config_descriptor "struct usbd_device *dev" +.Ft usb_device_descriptor_t * +.Fn usbd_get_device_descriptor "struct usbd_device *dev" +.Ft usbd_status +.Fn usbd_set_interface "struct usbd_interface *iface" "int altidx" +.Ft int +.Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno" +.Ft usbd_status +.\" unused, delete? +.\" .Fn usbd_get_interface "struct usbd_interface *iface" "uint8_t *aiface" +.\" .Ft void +.Fn usbd_fill_deviceinfo "struct usbd_device *dev" "struct usb_device_info *di" +.Ft int +.Fn usbd_get_interface_altindex "struct usbd_interface *iface" +.Ft usb_endpoint_descriptor_t * +.Fn usbd_get_endpoint_descriptor "struct usbd_interface *dev" \ + "uint8_t address" +.Ft usb_interface_descriptor_t * +.Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" +.Ft usb_endpoint_descriptor_t * +.Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ + "int endptidx" +.Ft void +.Fn usbd_dopoll "struct usbd_interface *iface" +.Ft void +.Fn usbd_set_polling "struct usbd_device *iface" "int val" +.Ft const char * +.Fn usbd_errstr "usbd_status err" +.Ft void +.Fn usbd_add_dev_event "int type" "struct usbd_device *iface" +.Ft void +.Fn usbd_add_drv_event "int type" "struct usbd_device *iface" "device_t dv" +.Ft char * +.Fn usbd_devinfo_alloc "struct usbd_device *iface" "int showclass" +.Ft void +.Fn usbd_devinfo_free "char *str" +.Ft const struct usbd_quirks * +.Fn usbd_get_quirks "struct usbd_device *iface" +.Ft usbd_status +.Fn usbd_reload_device_desc "struct usbd_device *iface" +.Ft int +.Fn usbd_ratecheck "struct timeval *tv" +.Ft usbd_status +.Fn usbd_get_string "struct usbd_device *iface" "int si" "char *buf" +.Ft usbd_status +.Fn usbd_get_string0 "struct usbd_device *iface" "int si" "char *buf" \ + "int unicode" +.Ft void +.Fn usb_desc_iter_init "struct usbd_device *iface" "usbd_desc_iter_t *iter" +.Ft const usb_descriptor_t * +.Fn usb_desc_iter_next "usbd_desc_iter_t *iter" +.Ft void +.Fn usb_add_task "struct usbd_device *iface" "struct usb_task *task" \ + "int queue" +.Ft void +.Fn usb_rem_task "struct usbd_device *iface" "struct usb_task *task" +.Ft void +.Fn usb_init_task "struct usb_task *task" "void (*func)(void *)" \ + "void *arg" uint8_t flags +.Ft const struct usb_devno * +.Fn usb_lookup "const struct usb_devno *tbl" \ + "uint16_t vendor" "uint16_t product" +.Ss Obsolete functions +The following functions have been obsoleted from +.Dv usbdi.h . +.Ft void * +.Fn usbd_alloc_buffer "struct usbd_xfer *xfer" "uint32_t size" +.Ft void +.Fn usbd_free_buffer "struct usbd_xfer *xfer" +.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 . +.Ft usbd_status +.Fn usbd_get_desc "struct usbd_device *dev" "int type" "int index" \ + "int len" "void *desc" +.Ft usbd_status +.Fn usbd_get_config_desc "struct usbd_device *dev" "int confidx" \ + "usb_config_descriptor_t *d" +.Ft usbd_status +.Fn usbd_get_config_desc_full "struct usbd_device *" "int dev" "void *d" "int size" +.Ft usbd_status +.Fn usbd_get_device_desc "struct usbd_device *dev" \ + "usb_device_descriptor_t *d" +.Ft usbd_status +.Fn usbd_set_address "struct usbd_device *dev" "int addr" +.Ft usbd_status +.Fn usbd_get_port_status "struct usbd_device *dev" "int port" "usb_port_status_t *ps" +.Ft usbd_status +.Fn usbd_set_hub_feature "struct usbd_device *dev" "int sel" +.Ft usbd_status +.Fn usbd_clear_hub_feature "struct usbd_device *dev" "int sel" +.Ft usbd_status +.Fn usbd_set_port_feature "struct usbd_device *dev" "int port" "int sel" +.Ft usbd_status +.Fn usbd_clear_port_feature "struct usbd_device *dev" "int port" "int sel" +.Ft usbd_status +.Fn usbd_get_device_status "struct usbd_device *dev" "usb_status_t *st" +.Ft usbd_status +.Fn usbd_get_hub_status "struct usbd_device *dev" "usb_hub_status_t *st" +.Ft usbd_status +.Fn usbd_set_protocol "struct usbd_interface *dev" "int report" +.Ft usbd_status +.Fn usbd_get_report_descriptor "struct usbd_device *dev" "int ifcno" "int repid" "int size" "void *d" +.Ft struct usb_hid_descriptor * +.Fn usbd_get_hid_descriptor "struct usbd_interface *ifc" +.Ft usbd_status +.Fn usbd_set_report "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.Ft usbd_status +.Fn usbd_set_report_async "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.Ft usbd_status +.Fn usbd_get_report "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.Ft usbd_status +.Fn usbd_set_idle "struct usbd_interface *iface" "int duration" "int id" +.Ft usbd_status +.Fn usbd_alloc_report_desc "struct usbd_interface *ifc" "void **descp" \ + "int *sizep" "int mem" +.\" private API between ugen(4) and usbdi(9) +.\" .Ft usbd_status +.\" .Fn usbd_get_config "struct usbd_device *dev" "uint8_t *conf" +.Ft usbd_status +.Fn usbd_get_string_desc "struct usbd_device *dev" "int sindex" "int langid" \ + "usb_string_descriptor_t *sdesc" +.Ft void +.Fn usbd_delay_ms "struct usbd_device *dev" "u_int ms" +.Ft usbd_status +.Fn usbd_set_config_no "struct usbd_device *dev" "int no" "int msg" +.Ft usbd_status +.Fn usbd_set_config_index "struct usbd_device *dev" "int index" "int msg" +.Ft usbd_status +.Fn usbd_bulk_transfer "struct usbd_xfer *xfer" "struct usbd_pipe *pipe" \ + "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" +.Ft usbd_status +.Fn usbd_intr_transfer "struct usbd_xfer *xfer" "struct usbd_pipe *pipe" \ + "uint16_t flags" "uint32_t timeout" "void *buf" "uint32_t *size" +.Ft void +.Fn usb_detach_waitold "device_t dv" +.Ft void +.Fn usb_detach_wakeupold "device_t dv" +.Ft void +.Fn usb_detach_wait "device_t dv" "kcondvar_t *cv" "kmutex_t *lk" +.Ft void +.Fn usb_detach_broadcast "device_t dv" "kcondvar_t *cv" +.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. +A transfer is described by the +.Va struct usbd_xfer * +cookie. +A pipe is a logical connection to a USB device. +It is described by the +.Va struct usbd_pipe * +cookie. +See the +.Sx TRANSFERS +and +.Sx PIPES +sections for more details. +.Pp +There are a number of functions to obtain a handle, descriptor +or resource count: +.Bl -tag -width 10n +.It Fn usbd_device2interface_handle dev ifaceno iface +Fills in +.Fa iface +with the +.Ft struct usbd_interface * +for the USB device +.Fa dev +on interface number +.Fa ifaceno . +.It Fn usbd_interface2device_handle iface dev +Fills in +.Fa dev +with the +.Ft struct usbd_device * +pointer for interface +.Fa iface . +.\" usbd_pipe2device_handle is unused; remove from usbdi? +.It Fn usbd_pipe2device_handle pipe +Returns the +.Ft struct usbd_device * +associated with +.Fa pipe . +.It Fn usbd_interface2endpoint_descriptor iface address +Returns the +.Ft usb_endpoint_descriptor_t * +for the particular interface +.Fa iface +at address +.Fa address . +.\" XXX describe what a .Ft usb_endpoint_descriptor_t is. +.It Fn usbd_endpoint_count dev count +.It Fn usbd_interface_count dev count +Fills in +.Fa count +with the number of endpoint or interfaces the USB device +.Fa dev +has. +.El +.Pp +Error handling and other return values are described in +.Xr usbd_status 9 . +.Pp +Additional comments on particular functions: +.Bl -tag -width 10n +.It Fn usbd_errstr err +Returns the string associated with +.Fa err . +.It Fn usbd_add_dev_event type iface +The +.Ar type +must be one of +.Dv USB_EVENT_CTRLR_ATTACH , +.Dv USB_EVENT_CTRLR_DETACH , +.Dv USB_EVENT_DEVICE_ATTACH +and +.Dv USB_EVENT_DEVICE_DETACH . +.It Fn usbd_add_drv_event type iface dv +The +.Fa type +must be one of +.Dv USB_EVENT_DRIVER_ATTACH +and +.Dv USB_EVENT_DRIVER_DETACH . +The +.Fa dv +corresponds with the +.Ft device_t +associated with the device attached or detached. +.It Fn usb_lookup tbl vendor product +Lookup a USB device. +The returned +.Va struct usb_devno +pointer has these members: +.Bl -item -offset offset -compact +.It +.Vt uint16_t ud_vendor ; +.It +.Vt uint16_t ud_product ; +.El +The +.Dv USB_PRODUCT_ANY +macro can be used to match any USB product by a particular vendor. +.El +.\" +.\" XXX functions missing descriptions in usbdi.h XXX +.\" +.\" .Fn usbd_get_interface_descriptor "struct usbd_interface *iface" +.\" .Fn usbd_get_config_descriptor "struct usbd_device *dev" +.\" .Fn usbd_get_device_descriptor "struct usbd_device *dev" +.\" .Fn usbd_get_no_alts "usb_config_descriptor_t *iface" "int ifaceno" +.\" unused, delete? +.\" .Fn usbd_get_interface "struct usbd_interface *iface" "uint8_t *aiface" +.\" .Fn usbd_fill_deviceinfo "struct usbd_device *dev" "struct usb_device_info *di" +.\" .Fn usbd_get_interface_altindex "struct usbd_interface *iface" +.\" .Fn usbd_get_endpoint_descriptor "struct usbd_interface *dev" \ +.\" "uint8_t address" +.\" .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int iindex" "int ano" +.\" .Fn usbd_find_edesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx" \ +.\" "int endptidx" +.\" .Fn usbd_dopoll "struct usbd_interface *iface" +.\" .Fn usbd_set_polling" struct usbd_device *iface" "int val" +.\" +.\" .Fn usbd_add_dev_event "int type" "struct usbd_device *iface" +.\" .Fn usbd_add_drv_event "int type" "struct usbd_device *iface" "device_t dv" +.\" +.\" .Fn usbd_devinfo_alloc "struct usbd_device *iface" "int showclass" +.\" .Fn usbd_devinfo_free "char *str" +.\" +.\" .Fn usbd_get_quirks "struct usbd_device *iface" +.\" .Fn usbd_reload_device_desc "struct usbd_device *iface" +.\" .Fn usbd_ratecheck "struct timeval *tv" +.\" .Fn usbd_get_string "struct usbd_device *iface" "int si" "char *buf" +.\" .Fn usbd_get_string0 "struct usbd_device *iface" "int" si "char *buf" \ +.\" "int unicode" +.\" +.\" .Fn usb_desc_iter_init "struct usbd_device *iface" "usbd_desc_iter_t *iter" +.\" .Fn usb_desc_iter_next "usbd_desc_iter_t *iter" +.\" +.\" XXX functions missing descriptions in usbdi.h XXX +.\" +.\" .Dv usbdi_util.h . +.\" .Ft usbd_status +.\" .Fn usbd_get_desc "struct usbd_device *dev" "int type" "int index" \ +.\" "int len" "void *desc" +.\" .Ft usbd_status +.\" .Fn usbd_get_config_desc "struct usbd_device *dev" "int confidx" \ +.\" "usb_config_descriptor_t *d" +.\" .Ft usbd_status +.\" .Fn usbd_get_config_desc_full "struct usbd_device *" "int dev" "void *d" "int size" +.\" .Ft usbd_status +.\" .Fn usbd_get_device_desc "struct usbd_device *dev" \ +.\" "usb_device_descriptor_t *d" +.\" .Ft usbd_status +.\" .Fn usbd_set_address "struct usbd_device *dev" "int addr" +.\" .Ft usbd_status +.\" .Fn usbd_get_port_status "struct usbd_device *dev" "intp ort" "usb_port_status_t *ps" +.\" .Ft usbd_status +.\" .Fn usbd_set_hub_feature "struct usbd_device *dev" "int sel" +.\" .Ft usbd_status +.\" .Fn usbd_clear_hub_feature "struct usbd_device *dev" "int sel" +.\" .Ft usbd_status +.\" .Fn usbd_set_port_feature "struct usbd_device *dev" "int port" "int sel" +.\" .Ft usbd_status +.\" .Fn usbd_clear_port_feature "struct usbd_device *dev" "int port" "int sel" +.\" .Ft usbd_status +.\" .Fn usbd_get_device_status "struct usbd_device *dev" "usb_status_t *st" +.\" .Ft usbd_status +.\" .Fn usbd_get_hub_status "struct usbd_device *dev" "usb_hub_status_t *st" +.\" .Ft usbd_status +.\" .Fn usbd_set_protocol "struct usbd_interface *dev" "int report" +.\" .Ft usbd_status +.\" .Fn usbd_get_report_descriptor "struct usbd_device *dev" "int ifcno" "int repid" "int size" "void *d" +.\" .Ft struct usb_hid_descriptor * +.\" .Fn usbd_get_hid_descriptor "struct usbd_interface *ifc" +.\" .Ft usbd_status +.\" .Fn usbd_set_report "struct usbd_interface *iface" "nt type" "int id" "void *data" "int len" +.\" .Ft usbd_status +.\" .Fn usbd_set_report_async "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.\" .Ft usbd_status +.\" .Fn usbd_get_report "struct usbd_interface *iface" "int type" "int id" "void *data" "int len" +.\" .Ft usbd_status +.\" .Fn usbd_set_idle "struct usbd_interface *iface" "int duration" "int id" +.\" .Ft usbd_status +.\" .Fn usbd_alloc_report_desc "struct usbd_interface *ifc" "void **descp" \ +.\" "int *sizep" "int mem" +.\" .Ft usbd_status +.\" .Fn usbd_get_string_desc "struct usbd_device *dev" "int sindex" "int langid" \ +.\" "usb_string_descriptor_t *sdesc" +.\" .Ft void +.\" .Fn usbd_delay_ms "struct usbd_device *dev" "u_int ms" +.\" .Ft usbd_status +.\" .Fn usbd_set_config_no "struct usbd_device *dev" "int no" "int msg" +.\" .Ft usbd_status +.\" .Fn usbd_set_config_index "struct usbd_device *dev" "int index" "int msg" +.\" .Ft usbd_status +.\" +.Sh PIPES +Pipes are created and destroyed by using the +.Fn usbd_open_pipe , +.Fn usbd_open_pipe_intr +and +.Fn usbd_close_pipe +functions. +The open functions take the interface handle +.Fa iface , +the +.Fa address +of this pipe and +.Fa flags +for this pipe which currently may be 0, or a combination of +.Dv USBD_EXCLUSIVE_USE , +to enable exclusive access to this interface and address, and +.Dv USBD_MPSAFE , +to allow running transfer callbacks on this pipe without first acquiring +.Dv kernel_lock . +The +.Fn usbd_open_pipe_intr +takes additional arguments +.Fa priv +to set the default private handle. +.Fa buffer +and +.Fa len +to describe the buffer to be used, +.Fa callback +for the function to call at interrupt time, and finally the +.Fa interval +for interrupts to be delivered in milliseconds. +The +.Fa interval +may be set to +.Dv USBD_DEFAULT_INTERVAL +use the default interval, specified by the ep. description. +It is common to have more than one pipe per device. +.Sh TRANSFERS +Transfers are created and destroyed with +.Fn usbd_create_xfer +and +.Fn usbd_destroy_xfer , +respectively, and are associated with a pipe at their creation time. +The create function takes the pipe handle +.Fa pipe , +the length of the largest transfer possible +.Fa len , +possible transfer flags +.Fa flags , +the number of isochronous frames (or 0) in +.Fa nframes . +.Pp +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. +Private data may be passed between setup and completion or status +calls using the +.Ft void *priv +argument. +.Pp +Arguments to the setup functions include the newly allocated +.Fa xfer , +the private data +.Fa priv , +the +.Fa timeout +in milliseconds, +for control, bulk and interrupt transfers +.Fa buffer +the data to transfer and its +.Fa length +and for isochronous transfers the frame length +.Fa frlengths +and number of frames +.Fa nframes , +and for default transfers a USB request structure +.Fa req +must be presented. +See the +.Sx INITIALISING USB REQUESTS +section for more details on USB requests. +.Pp +The transfer specific +.Fa flags +that can be set are: +.Bl -tag -width 10n +.It Dv USBD_SYNCHRONOUS +Wait for completion +.It Dv USBD_SYNCHRONOUS_SIG +When waiting for completion, allow signals to trigger wake up. +.It Dv USBD_SHORT_XFER_OK +Short reads are not an error +.It Dv USBD_FORCE_SHORT_XFER +Force last short packet on write +.El +.Pp +The +.Fn usbd_get_buffer +function returns the current kernel address for the buffer suitable for +transfer in +.Fa xfer . +.Pp +The +.Fn usbd_open_pipe , +.Fn usbd_open_pipe_intr , +.Fn usbd_close_pipe , +.Fn usbd_alloc_xfer , +and +.Fn usbd_free_xfer +can all sleep and should not be called from interrupt context as a result. +.Pp +Upon completion the +.Fa callback +function is called, which takes the completed +.Fa xfer , +the private data +.Fa priv +originally associated with this transfer, and +.Fa status +the status of this transfer. +.Pp +Transfers are initiated by calling +.Fn usbd_transfer , +and their results made be later obtained by calling +.Fa usbd_get_xfer_status , +which fills in the private data +.Fa priv , +original buffer location +.Fa buffer , +the length +.Fa length , +and the +.Fa status +of this request. +.Pp +The +.Fn usbd_bulk_transfer +and +.Fn usbd_intr_transfer +functions are used to transfer data in either an interrupt or +bulk fashion, and are front-ends to the +.Fn usbd_setup_xfer , +.Fn usbd_transfer +and +.Fn usbd_get_xfer_status , +as well as associated error handling. +The +.Fn usbd_sync_transfer +is identical to +.Fn usbd_transfer +with the +.Dv USBD_SYNCHRONOUS +flag set. +The +.Fn usbd_sync_transfer_sig +is identical to +.Fn usbd_transfer +with the +.Dv USBD_SYNCHRONOUS +and +.Dv USBD_SYNCHRONOUS_SIG +flags set. +.Pp +Transfers are aborted via this pipe with +.Fn usbd_abort_pipe +and +.Fn usbd_abort_default_pipe . +.Pp +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. +To clear the toggle state of an endpoint the +.Fn usbd_clear_endpoint_toggle +function should be used. +.Pp +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. +For both these functions +.Fa dev +is the handle of the USB device the request is for, +.Fa req +is the USB request, as described in the +.Sx INITIALISING USB REQUESTS +section, and then +.Fa data +is a buffer containing the data +.\" (if any)???? +for the request. +For the +.Fn usbd_do_request_flags +function there are additional +.Fa flags +passed to the +.Fa usbd_setup +function, +.Fa actlen +a pointer to fill in with the actual length of this request, and +.Fa timo , +the number of milliseconds to wait before timing out this request. +.Sh INITIALISING USB REQUESTS +There are 5 members of a +.Va usb_device_request_t +that must be initialised: +.Pp +.Bl -item -offset offset -compact +.It +.Vt uByte bmRequestType ; +.It +.Vt uByte bRequest ; +.It +.Vt uWord wValue ; +.It +.Vt uWord wIndex ; +.It +.Vt uWord wLength ; +.El +.Pp +The first two are normal byte values that may be simply assigned, +but the last three must be initialised with the +.Fn USETW +macro. +.Pp +The +.Fa bmRequestType +holds the request type of this USB request, which describes the +intended recipient of the request. +.Pp +This may be one of: +.Bl -tag -width UT_WRITEXX -offset offset -compact +.It Dv UT_WRITE +.It Dv UT_READ +.El +.Pp +with one of: +.Bl -tag -width UT_STANDARDXX -offset offset -compact +.It Dv UT_STANDARD +.It Dv UT_CLASS +.It Dv UT_VENDOR +.El +.Pp +and with one of: +.Bl -tag -width UT_INTERFACEXX -offset offset -compact +.It Dv UT_DEVICE +.It Dv UT_INTERFACE +.It Dv UT_ENDPOINT +.It Dv UT_OTHER +.El +.Pp +These are also in combinations as: +.Bl -tag -width UT_WRITE_VENDOR_INTERFACEXX -offset offset -compact +.It Dv UT_READ_DEVICE +.It Dv UT_READ_INTERFACE +.It Dv UT_READ_ENDPOINT +.It Dv UT_WRITE_DEVICE +.It Dv UT_WRITE_INTERFACE +.It Dv UT_WRITE_ENDPOINT +.It Dv UT_READ_CLASS_DEVICE +.It Dv UT_READ_CLASS_INTERFACE +.It Dv UT_READ_CLASS_OTHER +.It Dv UT_READ_CLASS_ENDPOINT +.It Dv UT_WRITE_CLASS_DEVICE +.It Dv UT_WRITE_CLASS_INTERFACE +.It Dv UT_WRITE_CLASS_OTHER +.It Dv UT_WRITE_CLASS_ENDPOINT +.It Dv UT_READ_VENDOR_DEVICE +.It Dv UT_READ_VENDOR_INTERFACE +.It Dv UT_READ_VENDOR_OTHER +.It Dv UT_READ_VENDOR_ENDPOINT +.It Dv UT_WRITE_VENDOR_DEVICE +.It Dv UT_WRITE_VENDOR_INTERFACE +.It Dv UT_WRITE_VENDOR_OTHER +.It Dv UT_WRITE_VENDOR_ENDPOINT +.El +.Pp +The +.Fa bRequest +describes which request is being made. +The available values are: +.Bl -tag -width UR_GET_DESCRIPTORXX -offset offset -compact +.It Dv UR_GET_STATUS +.It Dv UR_CLEAR_FEATURE +.It Dv UR_SET_FEATURE +.It Dv UR_SET_ADDRESS +.It Dv UR_GET_DESCRIPTOR +.It Dv UR_SET_DESCRIPTOR +.\" these have API front ends +.\" .It Dv UR_GET_CONFIG +.\" api usbd_get_config() (ugen private) +.\" .It Dv UR_SET_CONFIG +.\" static api usbd_set_config() (usb_subr private) +.\" .It Dv UR_GET_INTERFACE +.\" .It Dv UR_SET_INTERFACE +.\" this isn't supported +.\" .It Dv UR_SYNCH_FRAME +.El +.Pp +The +.Fa wValue , +.Fa wIndex +and +.Fa wLength +are device-specific values and must be initialised with the +.Fn USETW +macro. +.Sh USB REQUEST TYPES AND STRUCTURES +The +.Dv UR_GET_STATUS +request operates on a +.Va usb_status_t +structure, which has this member: +.Bl -item -offset offset -compact +.It +.Vt uWord wStatus ; +.El +.Pp +For device status requests the +.Fa wStatus +member may have either of these bit flags set: +.Bl -tag -width UDS_REMOTE_WAKEUPXX -offset offset -compact +.It Dv UDS_SELF_POWERED +.It Dv UDS_REMOTE_WAKEUP +.El +.Pp +For endpoint status requests the +.Fa wStatus +member may have this bit flag set: +.Bl -tag -width UES_HALTXX -offset offset -compact +.It Dv UES_HALT +.El +.Pp +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. +.Pp +The +.Dv UR_SET_ADDRESS +request sets the virtual USB address of a port using the +.Va wValue . +.Pp +The +.Dv UR_GET_DESCRIPTOR +and +.Dv UR_SET_DESCRIPTOR +requests operate on a +.Va usb_descriptor_t +structure, which has these members: +.Bl -item -offset offset -compact +.It +.Vt uByte bLength ; +.It +.Vt uByte bDescriptorType ; +.El +.Pp +The +.Fa bDescriptorType +member may be one of the following values: +.Bl -tag -width UDESC_OTHER_SPEED_CONFIGURATIONXX -offset offset -compact +.It Dv UDESC_DEVICE +.It Dv UDESC_CONFIG +.It Dv UDESC_STRING +.It Dv UDESC_INTERFACE +.It Dv UDESC_ENDPOINT +.It Dv UDESC_DEVICE_QUALIFIER +.It Dv UDESC_OTHER_SPEED_CONFIGURATION +.It Dv UDESC_INTERFACE_POWER +.It Dv UDESC_OTG +.It Dv UDESC_DEBUG +.It Dv UDESC_INTERFACE_ASSOC +.It Dv UDESC_CS_DEVICE +.It Dv UDESC_CS_CONFIG +.It Dv UDESC_CS_STRING +.It Dv UDESC_CS_INTERFACE +.It Dv UDESC_CS_ENDPOINT +.It Dv UDESC_HUB +.El +.Pp +The +.\" XXXMRG is the below even remotely valid? +.Fn usbd_set_interface +function can be used to change the index used for transfers on this +interface as obtained via +.Fn usbd_device2interface_handle . +.Sh USB DEVICE DETACHMENT +There are two functions available to ease the detach of active devices. +Typically a reference count is maintained on syscall activity. +When a USB device is to be detached, the reference count should be +decremented and if it is greater or equal to zero, +.Fn usb_detach_wait +should be called on the +.Ft dv +associated with this USB device and, typically, a device-specific +condition variable +.Fa cv . +and mutex +.Fa lk +protecting this reference count state. +At the end of each syscall function, if the reference count is decremented +to less than zero, then +.Fn usb_detach_broadcast +must be called on the +.Ft dv +and +.Fa cv +that is being waited on with +.Fn usb_detach_wait . +.Pp +The are another pair of functions with similar functionality that do not +use a condition variable or mutex and should be avoided in new code. +The +.Fn usb_detach_waitold +function works like +.Fn usb_detach_wait , +and the +.Fn usb_detach_wakeupold +function works like +.Fn usb_detach_broadcast . +.\" XXX add an actual code example. +.Sh USB TASK MANAGEMENT +The USB stack provides a task management framework to execute tasks +in a thread context at the soonest opportunity. +Typically this is used by network drivers to handle periodic updates +or status change requests, or other operations that need to run in +a normal context. +.Pp +The +.Fn usb_init_task +function takes a pointer to a +.Ft struct usb_task +that will be initialised, a function to call for this task +.Fa func , +the argument to pass to +.Fa func , +.Fa arg , +and the task flags +.Fa flags . +If the +.Fa flags +argument is +.Dv USB_TASKQ_MPSAFE , +the +.Fa func +function will be called without first acquiring +.Dv kernel_lock . +.Pp +To invoke the task callback the +.Fn usb_add_task +function should be called with the +.Fa iface +associated with this device, the task structure +.Fa task , +and the +.Fa queue +to run against, either +.Dv USB_TASKQ_HC +for operations initiated by host controllers or +.Dv USB_TASKQ_DRIVER +for operations initiated by USB drivers. +.Pp +To deschedule a potentially running task the +.Fn usb_rem_task +function should be called. +.Pp +The driver using these facilities is expected to provide the +necessary serialisation between +.Fn usb_init_task , +.Fn usb_add_task +and +.Fn usb_rem_task +for each specific +.Ft struct usb_task . +.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. |