share/man/man9/usbdi.9

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