1.\" $NetBSD: usbdi.9,v 1.4 2002/02/13 08:18:53 ross Exp $ 2.\" 3.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Lennart Augustsson. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd December 3, 1999 38.Dt USBDI 9 39.Os 40.Sh NAME 41.Nm usbdi 42.Nd USB device drivers interface 43.Sh SYNOPSIS 44.Cd "#include \*[Lt]dev/usb/usb.h\*[Gt]" 45.Cd "#include \*[Lt]dev/usb/usbdi.h\*[Gt]" 46.Sh DESCRIPTION 47Device driver access to the USB bus centers around transfers. 48A transfer describes a communication with a USB device. 49A transfer is an abstract concept that can result in several 50physical packets being transferred to or from a device. 51A transfer is described by a 52.Va usbd_xfer_handle . 53It is allocated by 54.Va usbd_alloc_xfer 55and the data describing the transfer is filled by 56.Va usbd_setup_default_xfer 57for control pipe transfers, by 58.Va usbd_setup_xfer 59for bulk and interrupt transfers, and by 60.Va usbd_setup_isoc_xfer 61for isochronous transfers. 62.Pp 63describe 64.Va usbd_do_request 65.Pp 66describe pipes 67.Pp 68describe 69usbd_status 70.Ss Functions offered by usbdi 71.Bl -tag -width indent 72.It Dv usbd_status usbd_open_pipe(usbd_interface_handle iface, u_int8_t address, 73 u_int8_t flags, 74 usbd_pipe_handle *pipe) 75.It Dv usbd_status usbd_close_pipe(usbd_pipe_handle pipe) 76.It Dv usbd_status usbd_transfer(usbd_xfer_handle req) 77.It Dv usbd_xfer_handle usbd_alloc_xfer(usbd_device_handle) 78.It Dv usbd_status usbd_free_xfer(usbd_xfer_handle xfer) 79.It Dv void usbd_setup_xfer(usbd_xfer_handle xfer, usbd_pipe_handle pipe, 80 usbd_private_handle priv, void *buffer, 81 u_int32_t length, u_int16_t flags, u_int32_t timeout, 82 usbd_callback) 83.It Dv void usbd_setup_default_xfer(usbd_xfer_handle xfer, 84 usbd_device_handle dev, 85 usbd_private_handle priv, u_int32_t timeout, 86 usb_device_request_t *req, void *buffer, 87 u_int32_t length, u_int16_t flags, usbd_callback) 88.It Dv void usbd_setup_isoc_xfer(usbd_xfer_handle xfer, usbd_pipe_handle pipe, 89 usbd_private_handle priv, u_int16_t *frlengths, 90 u_int32_t nframes, u_int16_t flags, usbd_callback) 91.It Dv void usbd_get_xfer_status(usbd_xfer_handle xfer, usbd_private_handle *priv, 92 void **buffer, u_int32_t *count, usbd_status *status) 93.It Dv usb_endpoint_descriptor_t *usbd_interface2endpoint_descriptor(usbd_interface_handle iface, u_int8_t address) 94.It Dv usbd_status usbd_abort_pipe(usbd_pipe_handle pipe) 95.It Dv usbd_status usbd_clear_endpoint_stall(usbd_pipe_handle pipe) 96.It Dv usbd_status usbd_clear_endpoint_stall_async(usbd_pipe_handle pipe) 97.It Dv usbd_status usbd_endpoint_count(usbd_interface_handle dev, u_int8_t *count) 98.It Dv usbd_status usbd_interface_count(usbd_device_handle dev, u_int8_t *count) 99.It Dv usbd_status usbd_interface2device_handle(usbd_interface_handle iface, usbd_device_handle *dev) 100.It Dv usbd_status usbd_device2interface_handle(usbd_device_handle dev, u_int8_t ifaceno, usbd_interface_handle *iface) 101.Pp 102.It Dv usbd_device_handle usbd_pipe2device_handle(usbd_pipe_handle) 103.It Dv void *usbd_alloc_buffer(usbd_xfer_handle req, u_int32_t size) 104.It Dv void usbd_free_buffer(usbd_xfer_handle req) 105.It Dv void *usbd_get_buffer(usbd_xfer_handle xfer) 106.It Dv usbd_status usbd_sync_transfer(usbd_xfer_handle req) 107.It Dv usbd_status usbd_open_pipe_intr(usbd_interface_handle iface, u_int8_t address, 108 u_int8_t flags, usbd_pipe_handle *pipe, 109 usbd_private_handle priv, void *buffer, 110 u_int32_t length, usbd_callback) 111.It Dv usbd_status usbd_do_request(usbd_device_handle pipe, usb_device_request_t *req, void *data) 112.It Dv usbd_status usbd_do_request_async(usbd_device_handle pipe, usb_device_request_t *req, void *data) 113.It Dv usbd_status usbd_do_request_flags(usbd_device_handle pipe, usb_device_request_t *req, 114 void *data, u_int16_t flags, int *) 115.It Dv usb_interface_descriptor_t *usbd_get_interface_descriptor(usbd_interface_handle iface) 116.It Dv usb_config_descriptor_t *usbd_get_config_descriptor(usbd_device_handle dev) 117.It Dv usb_device_descriptor_t *usbd_get_device_descriptor(usbd_device_handle dev) 118.It Dv usbd_status usbd_set_interface(usbd_interface_handle, int) 119.It Dv int usbd_get_no_alts(usb_config_descriptor_t *, int) 120.It Dv usbd_status usbd_get_interface(usbd_interface_handle iface, u_int8_t *aiface) 121.It Dv void usbd_fill_deviceinfo (usbd_device_handle dev, struct usb_device_info *di) 122.It Dv int usbd_get_interface_altindex(usbd_interface_handle iface) 123.It Dv usb_interface_descriptor_t *usbd_find_idesc(usb_config_descriptor_t *cd, int iindex, int ano) 124.It Dv usb_endpoint_descriptor_t *usbd_find_edesc(usb_config_descriptor_t *cd, int ifaceidx, int altidx, 125 int endptidx) 126.It Dv const char *usbd_errstr(usbd_status err) 127.El 128.Ss Utilities from usbdi_util.h 129Based on the routines in 130.Dv "usbdi.h" 131a number of utility functions have been defined that are accessible 132through 133.Dv "usbdi_util.h" 134.Bl -tag -width indent 135.It Dv usbd_status usbd_get_desc(usbd_device_handle dev, int type, 136 int index, int len, void *desc) 137.It Dv usbd_status usbd_get_config_desc(usbd_device_handle, int, 138 usb_config_descriptor_t *) 139.It Dv usbd_status usbd_get_config_desc_full(usbd_device_handle, int, 140 void *, int) 141.It Dv usbd_status usbd_get_device_desc(usbd_device_handle dev, 142 usb_device_descriptor_t *d) 143.It Dv usbd_status usbd_set_address(usbd_device_handle dev, int addr) 144.It Dv usbd_status usbd_get_port_status(usbd_device_handle, 145 int, usb_port_status_t *) 146.It Dv usbd_status usbd_set_hub_feature(usbd_device_handle dev, int) 147.It Dv usbd_status usbd_clear_hub_feature(usbd_device_handle, int) 148.It Dv usbd_status usbd_set_port_feature(usbd_device_handle dev, int, int) 149.It Dv usbd_status usbd_clear_port_feature(usbd_device_handle, int, int) 150.It Dv usbd_status usbd_get_device_status(usbd_device_handle,usb_status_t*) 151.It Dv usbd_status usbd_get_hub_status(usbd_device_handle dev, 152 usb_hub_status_t *st) 153.It Dv usbd_status usbd_set_protocol(usbd_interface_handle dev, int report) 154.It Dv usbd_status usbd_get_report_descriptor 155(usbd_device_handle dev, int ifcno, int repid, int size, void *d) 156.It Dv struct usb_hid_descriptor *usbd_get_hid_descriptor 157(usbd_interface_handle ifc) 158.It Dv usbd_status usbd_set_report 159(usbd_interface_handle iface,int type,int id,void *data,int len) 160.It Dv usbd_status usbd_set_report_async 161(usbd_interface_handle iface,int type,int id,void *data,int len) 162.It Dv usbd_status usbd_get_report 163(usbd_interface_handle iface,int type,int id,void *data,int len) 164.It Dv usbd_status usbd_set_idle 165(usbd_interface_handle iface, int duration, int id) 166.It Dv usbd_status usbd_alloc_report_desc 167(usbd_interface_handle ifc, void **descp, int *sizep, int mem) 168.It Dv usbd_status usbd_get_config 169(usbd_device_handle dev, u_int8_t *conf) 170.It Dv usbd_status usbd_get_string_desc 171(usbd_device_handle dev, int sindex, int langid, 172 usb_string_descriptor_t *sdesc) 173.It Dv void usbd_delay_ms(usbd_device_handle, u_int) 174.It Dv usbd_status usbd_set_config_no 175(usbd_device_handle dev, int no, int msg) 176.It Dv usbd_status usbd_set_config_index 177(usbd_device_handle dev, int index, int msg) 178.It Dv usbd_status usbd_bulk_transfer 179(usbd_xfer_handle xfer, usbd_pipe_handle pipe, u_int16_t flags, 180 u_int32_t timeout, void *buf, u_int32_t *size, char *lbl) 181.It Dv void usb_detach_wait(device_ptr_t) 182.It Dv void usb_detach_wakeup(device_ptr_t) 183.El 184.Sh SEE ALSO 185.Xr usb 4 186.Sh HISTORY 187This 188.Nm 189interface first appeared in 190.Nx 1.4 . 191The interface is based on an early definition from the OpenUSBDI group 192within the USB organisation. Right after this definition the OpenUSBDI 193development got closed for open source developers, so this interface 194has not followed the further changes. 195The OpenUSBDI specification is now available again, but looks different. 196.Sh BUGS 197This man page is under development, so its biggest shortcoming is 198incompleteness. 199