14eaae44dSAndrew Thompson.\" 24eaae44dSAndrew Thompson.\" Copyright (c) 2008 Hans Petter Selasky 34eaae44dSAndrew Thompson.\" 44eaae44dSAndrew Thompson.\" All rights reserved. 54eaae44dSAndrew Thompson.\" 64eaae44dSAndrew Thompson.\" Redistribution and use in source and binary forms, with or without 74eaae44dSAndrew Thompson.\" modification, are permitted provided that the following conditions 84eaae44dSAndrew Thompson.\" are met: 94eaae44dSAndrew Thompson.\" 1. Redistributions of source code must retain the above copyright 104eaae44dSAndrew Thompson.\" notice, this list of conditions and the following disclaimer. 114eaae44dSAndrew Thompson.\" 2. Redistributions in binary form must reproduce the above copyright 124eaae44dSAndrew Thompson.\" notice, this list of conditions and the following disclaimer in the 134eaae44dSAndrew Thompson.\" documentation and/or other materials provided with the distribution. 144eaae44dSAndrew Thompson.\" 154eaae44dSAndrew Thompson.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 164eaae44dSAndrew Thompson.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 174eaae44dSAndrew Thompson.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 184eaae44dSAndrew Thompson.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 194eaae44dSAndrew Thompson.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 204eaae44dSAndrew Thompson.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 214eaae44dSAndrew Thompson.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 224eaae44dSAndrew Thompson.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 234eaae44dSAndrew Thompson.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 244eaae44dSAndrew Thompson.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 254eaae44dSAndrew Thompson.\" SUCH DAMAGE. 264eaae44dSAndrew Thompson.\" 274eaae44dSAndrew Thompson.\" $FreeBSD$ 284eaae44dSAndrew Thompson.\" 29c54c1f7cSAndrew Thompson.Dd May 21, 2009 304eaae44dSAndrew Thompson.Dt LIBUSB 3 314eaae44dSAndrew Thompson.Os 324eaae44dSAndrew Thompson.Sh NAME 334eaae44dSAndrew Thompson.Nm libusb 344eaae44dSAndrew Thompson. 354eaae44dSAndrew Thompson.Nd "USB access library" 364eaae44dSAndrew Thompson. 374eaae44dSAndrew Thompson. 384eaae44dSAndrew Thompson.Sh LIBRARY 394eaae44dSAndrew Thompson. 404eaae44dSAndrew Thompson. 414eaae44dSAndrew ThompsonUSB access library (libusb -lusb) 424eaae44dSAndrew Thompson. 434eaae44dSAndrew Thompson. 444eaae44dSAndrew Thompson. 454eaae44dSAndrew Thompson.Sh SYNOPSIS 464eaae44dSAndrew Thompson.In libusb20.h 47dc8f21bcSAndrew Thompson.Ft int 48dc8f21bcSAndrew Thompson.Fn libusb20_tr_close "struct libusb20_transfer *xfer" 49dc8f21bcSAndrew Thompson.Ft int 50dc8f21bcSAndrew Thompson.Fn libusb20_tr_open "struct libusb20_transfer *xfer" "uint32_t max_buf_size" "uint32_t max_frame_count" "uint8_t ep_no" 51dc8f21bcSAndrew Thompson.Ft struct libusb20_transfer* 52dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_pointer "struct libusb20_device *pdev" "uint16_t tr_index" 53dc8f21bcSAndrew Thompson.Ft uint16_t 54dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_time_complete "struct libusb20_transfer *xfer" 55dc8f21bcSAndrew Thompson.Ft uint32_t 56dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_actual_frames "struct libusb20_transfer *xfer" 57dc8f21bcSAndrew Thompson.Ft uint32_t 58dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_actual_length "struct libusb20_transfer *xfer" 59dc8f21bcSAndrew Thompson.Ft uint32_t 60dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_max_frames "struct libusb20_transfer *xfer" 61dc8f21bcSAndrew Thompson.Ft uint32_t 62dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_max_packet_length "struct libusb20_transfer *xfer" 63dc8f21bcSAndrew Thompson.Ft uint32_t 64dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_max_total_length "struct libusb20_transfer *xfer" 65dc8f21bcSAndrew Thompson.Ft uint8_t 66dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_status "struct libusb20_transfer *xfer" 67dc8f21bcSAndrew Thompson.Ft uint8_t 68dc8f21bcSAndrew Thompson.Fn libusb20_tr_pending "struct libusb20_transfer *xfer" 69dc8f21bcSAndrew Thompson.Ft void 70dc8f21bcSAndrew Thompson.Fn libusb20_tr_callback_wrapper "struct libusb20_transfer *xfer" 71dc8f21bcSAndrew Thompson.Ft void 72dc8f21bcSAndrew Thompson.Fn libusb20_tr_clear_stall_sync "struct libusb20_transfer *xfer" 73dc8f21bcSAndrew Thompson.Ft void 74dc8f21bcSAndrew Thompson.Fn libusb20_tr_drain "struct libusb20_transfer *xfer" 75dc8f21bcSAndrew Thompson.Ft void 76dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_buffer "struct libusb20_transfer *xfer" "void *buffer" "uint16_t fr_index" 77dc8f21bcSAndrew Thompson.Ft void 78dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_callback "struct libusb20_transfer *xfer" "libusb20_tr_callback_t *cb" 79dc8f21bcSAndrew Thompson.Ft void 80dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_flags "struct libusb20_transfer *xfer" "uint8_t flags" 81dc8f21bcSAndrew Thompson.Ft void 82dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_length "struct libusb20_transfer *xfer" "uint32_t length" "uint16_t fr_index" 83dc8f21bcSAndrew Thompson.Ft void 84dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_priv_sc0 "struct libusb20_transfer *xfer" "void *sc0" 85dc8f21bcSAndrew Thompson.Ft void 86dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_priv_sc1 "struct libusb20_transfer *xfer" "void *sc1" 87dc8f21bcSAndrew Thompson.Ft void 88dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_timeout "struct libusb20_transfer *xfer" "uint32_t timeout" 89dc8f21bcSAndrew Thompson.Ft void 90dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_total_frames "struct libusb20_transfer *xfer" "uint32_t nframes" 91dc8f21bcSAndrew Thompson.Ft void 92dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_bulk "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout" 93dc8f21bcSAndrew Thompson.Ft void 94dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_control "struct libusb20_transfer *xfer" "void *psetup" "void *pbuf" "uint32_t timeout" 95dc8f21bcSAndrew Thompson.Ft void 96dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_intr "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout" 97dc8f21bcSAndrew Thompson.Ft void 98dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_isoc "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint61_t fr_index" 99dc8f21bcSAndrew Thompson.Ft void 100dc8f21bcSAndrew Thompson.Fn libusb20_tr_start "struct libusb20_transfer *xfer" 101dc8f21bcSAndrew Thompson.Ft void 102dc8f21bcSAndrew Thompson.Fn libusb20_tr_stop "struct libusb20_transfer *xfer" 103dc8f21bcSAndrew Thompson.Ft void 104dc8f21bcSAndrew Thompson.Fn libusb20_tr_submit "struct libusb20_transfer *xfer" 105dc8f21bcSAndrew Thompson.Ft void * 106dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_priv_sc0 "struct libusb20_transfer *xfer" 107dc8f21bcSAndrew Thompson.Ft void * 108dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_priv_sc1 "struct libusb20_transfer *xfer" 109dc8f21bcSAndrew Thompson.Ft const char * 110dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_backend_name "struct libusb20_device *" 111dc8f21bcSAndrew Thompson.Ft int 112dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_info "struct libusb20_device *pdev" "struct usb2_device_info *pinfo" 113dc8f21bcSAndrew Thompson.Ft int 114dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_iface_desc "struct libusb20_device *pdev" "uint8_t iface_index" "char *buf" "uint8_t len" 115dc8f21bcSAndrew Thompson.Ft const char * 116dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_desc "struct libusb20_device *pdev" 117dc8f21bcSAndrew Thompson.Ft int 118dc8f21bcSAndrew Thompson.Fn libusb20_dev_claim_interface "struct libusb20_device *pdev" "uint8_t iface_index" 119dc8f21bcSAndrew Thompson.Ft int 120dc8f21bcSAndrew Thompson.Fn libusb20_dev_close "struct libusb20_device *pdev" 121dc8f21bcSAndrew Thompson.Ft int 122dc8f21bcSAndrew Thompson.Fn libusb20_dev_detach_kernel_driver "struct libusb20_device *pdev" "uint8_t iface_index" 123dc8f21bcSAndrew Thompson.Ft int 124dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_config_index "struct libusb20_device *pdev" "uint8_t configIndex" 125dc8f21bcSAndrew Thompson.Ft int 126dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_debug "struct libusb20_device *pdev" 127dc8f21bcSAndrew Thompson.Ft int 128dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_fd "struct libusb20_device *pdev" 129dc8f21bcSAndrew Thompson.Ft int 130dc8f21bcSAndrew Thompson.Fn libusb20_dev_kernel_driver_active "struct libusb20_device *pdev" "uint8_t iface_index" 131dc8f21bcSAndrew Thompson.Ft int 132dc8f21bcSAndrew Thompson.Fn libusb20_dev_open "struct libusb20_device *pdev" "uint16_t transfer_max" 133dc8f21bcSAndrew Thompson.Ft int 134dc8f21bcSAndrew Thompson.Fn libusb20_dev_process "struct libusb20_device *pdev" 135dc8f21bcSAndrew Thompson.Ft int 136dc8f21bcSAndrew Thompson.Fn libusb20_dev_release_interface "struct libusb20_device *pdev" "uint8_t iface_index" 137dc8f21bcSAndrew Thompson.Ft int 138dc8f21bcSAndrew Thompson.Fn libusb20_dev_request_sync "struct libusb20_device *pdev" "struct LIBUSB20_CONTROL_SETUP_DECODED *setup" "void *data" "uint16_t *pactlen" "uint32_t timeout" "uint8_t flags" 139dc8f21bcSAndrew Thompson.Ft int 140dc8f21bcSAndrew Thompson.Fn libusb20_dev_req_string_sync "struct libusb20_device *pdev" "uint8_t index" "uint16_t langid" "void *ptr" "uint16_t len" 141dc8f21bcSAndrew Thompson.Ft int 142dc8f21bcSAndrew Thompson.Fn libusb20_dev_req_string_simple_sync "struct libusb20_device *pdev" "uint8_t index" "void *ptr" "uint16_t len" 143dc8f21bcSAndrew Thompson.Ft int 144dc8f21bcSAndrew Thompson.Fn libusb20_dev_reset "struct libusb20_device *pdev" 145dc8f21bcSAndrew Thompson.Ft int 146dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_power_mode "struct libusb20_device *pdev" "uint8_t power_mode" 147dc8f21bcSAndrew Thompson.Ft uint8_t 148dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_power_mode "struct libusb20_device *pdev" 149dc8f21bcSAndrew Thompson.Ft int 150dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_alt_index "struct libusb20_device *pdev" "uint8_t iface_index" "uint8_t alt_index" 151c54c1f7cSAndrew Thompson.Ft struct LIBUSB20_DEVICE_DESC_DECODED * 152c54c1f7cSAndrew Thompson.Fn libusb20_dev_get_device_desc "struct libusb20_device *pdev" 153dc8f21bcSAndrew Thompson.Ft struct libusb20_config * 154dc8f21bcSAndrew Thompson.Fn libusb20_dev_alloc_config "struct libusb20_device *pdev" "uint8_t config_index" 155dc8f21bcSAndrew Thompson.Ft struct libusb20_device * 156dc8f21bcSAndrew Thompson.Fn libusb20_dev_alloc "void" 157dc8f21bcSAndrew Thompson.Ft uint8_t 158dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_address "struct libusb20_device *pdev" 159dc8f21bcSAndrew Thompson.Ft uint8_t 160dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_bus_number "struct libusb20_device *pdev" 161dc8f21bcSAndrew Thompson.Ft uint8_t 162dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_mode "struct libusb20_device *pdev" 163dc8f21bcSAndrew Thompson.Ft uint8_t 164dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_speed "struct libusb20_device *pdev" 165dc8f21bcSAndrew Thompson.Ft uint8_t 166dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_config_index "struct libusb20_device *pdev" 167dc8f21bcSAndrew Thompson.Ft void 168dc8f21bcSAndrew Thompson.Fn libusb20_dev_free "struct libusb20_device *pdev" 169dc8f21bcSAndrew Thompson.Ft void 170dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_debug "struct libusb20_device *pdev" "int debug" 171dc8f21bcSAndrew Thompson.Ft void 172dc8f21bcSAndrew Thompson.Fn libusb20_dev_wait_process "struct libusb20_device *pdev" "int timeout" 173dc8f21bcSAndrew Thompson.Ft int 174dc8f21bcSAndrew Thompson.Fn libusb20_be_get_template "struct libusb20_backend *pbe" "int *ptemp" 175dc8f21bcSAndrew Thompson.Ft int 176dc8f21bcSAndrew Thompson.Fn libusb20_be_set_template "struct libusb20_backend *pbe" "int temp" 177dc8f21bcSAndrew Thompson.Ft int 178dc8f21bcSAndrew Thompson.Fn libusb20_be_get_dev_quirk "struct libusb20_backend *pber", "uint16_t index" "struct libusb20_quirk *pq" 179dc8f21bcSAndrew Thompson.Ft int 180dc8f21bcSAndrew Thompson.Fn libusb20_be_get_quirk_name "struct libusb20_backend *pbe" "uint16_t index" "struct libusb20_quirk *pq" 181dc8f21bcSAndrew Thompson.Ft int 182dc8f21bcSAndrew Thompson.Fn libusb20_be_add_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq" 183dc8f21bcSAndrew Thompson.Ft int 184dc8f21bcSAndrew Thompson.Fn libusb20_be_remove_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq" 185dc8f21bcSAndrew Thompson.Ft struct libusb20_backend * 186dc8f21bcSAndrew Thompson.Fn libusb20_be_alloc_linux "void" 187dc8f21bcSAndrew Thompson.Ft struct libusb20_device * 188dc8f21bcSAndrew Thompson.Fn libusb20_be_device_foreach "struct libusb20_backend *pbe" "struct libusb20_device *pdev" 189dc8f21bcSAndrew Thompson.Ft void 190dc8f21bcSAndrew Thompson.Fn libusb20_be_dequeue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev" 191dc8f21bcSAndrew Thompson.Ft void 192dc8f21bcSAndrew Thompson.Fn libusb20_be_enqueue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev" 193dc8f21bcSAndrew Thompson.Ft void 194dc8f21bcSAndrew Thompson.Fn libusb20_be_free "struct libusb20_backend *pbe" 195dc8f21bcSAndrew Thompson.Ft uint8_t 196dc8f21bcSAndrew Thompson.Fn libusb20_me_get_1 "const struct libusb20_me_struct *me" "uint16_t off" 197dc8f21bcSAndrew Thompson.Ft uint16_t 198dc8f21bcSAndrew Thompson.Fn libusb20_me_get_2 "const struct libusb20_me_struct *me" "uint16_t off" 199dc8f21bcSAndrew Thompson.Ft uint16_t 200dc8f21bcSAndrew Thompson.Fn libusb20_me_encode "void *pdata" "uint16_t len" "const void *pdecoded" 201dc8f21bcSAndrew Thompson.Ft uint16_t 202dc8f21bcSAndrew Thompson.Fn libusb20_me_decode "const void *pdata" "uint16_t len" "void *pdecoded" 203dc8f21bcSAndrew Thompson.Ft "const uint8_t *" 204dc8f21bcSAndrew Thompson.Fn libusb20_desc_foreach "const struct libusb20_me_struct *me" "const uint8_t *pdesc" 2054eaae44dSAndrew Thompson. 2064eaae44dSAndrew Thompson. 2074eaae44dSAndrew Thompson.Sh DESCRIPTION 2084eaae44dSAndrew Thompson. 2094eaae44dSAndrew ThompsonThe 2104eaae44dSAndrew Thompson.Nm 2114eaae44dSAndrew Thompsonlibrary implements functions to be able to easily access and control 2124eaae44dSAndrew ThompsonUSB through the USB file system interface. 2134eaae44dSAndrew Thompson. 2144eaae44dSAndrew Thompson. 2154eaae44dSAndrew Thompson.Sh USB TRANSFER OPERATIONS 2164eaae44dSAndrew Thompson. 2174eaae44dSAndrew Thompson.Pp 2184eaae44dSAndrew Thompson. 219dc8f21bcSAndrew Thompson.Fn libusb20_tr_close 220dc8f21bcSAndrew Thompsonwill release all kernel resources associated with an USB 221dc8f21bcSAndrew Thompson.Fa xfer . 2224eaae44dSAndrew Thompson. 2234eaae44dSAndrew ThompsonThis function returns zero upon success. 2244eaae44dSAndrew Thompson. 2254eaae44dSAndrew ThompsonNon-zero return values indicate a LIBUSB20_ERROR value. 2264eaae44dSAndrew Thompson. 2274eaae44dSAndrew Thompson.Pp 2284eaae44dSAndrew Thompson. 229dc8f21bcSAndrew Thompson.Fn libusb20_tr_open 230dc8f21bcSAndrew Thompsonwill allocate kernel resources like 2314eaae44dSAndrew Thompson.Fa max_buf_size 2324eaae44dSAndrew Thompsonand 2334eaae44dSAndrew Thompson.Fa max_frame_count 2344eaae44dSAndrew Thompsonassociated with an USB 2354eaae44dSAndrew Thompson.Fa pxfer 2364eaae44dSAndrew Thompsonand bind the transfer to the specified 2374eaae44dSAndrew Thompson.Fa ep_no . 2384eaae44dSAndrew Thompson. 2394eaae44dSAndrew ThompsonThis function returns zero upon success. 2404eaae44dSAndrew Thompson. 2414eaae44dSAndrew ThompsonNon-zero return values indicate a LIBUSB20_ERROR value. 2424eaae44dSAndrew Thompson. 2434eaae44dSAndrew Thompson.Pp 2444eaae44dSAndrew Thompson. 245dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_pointer 246dc8f21bcSAndrew Thompsonwill return a pointer to the allocated USB transfer according to the 2474eaae44dSAndrew Thompson.Fa pdev 2484eaae44dSAndrew Thompsonand 2494eaae44dSAndrew Thompson.Fa tr_index 2504eaae44dSAndrew Thompsonarguments. 2514eaae44dSAndrew Thompson. 2524eaae44dSAndrew ThompsonThis function returns NULL in case of failure. 2534eaae44dSAndrew Thompson. 2544eaae44dSAndrew Thompson.Pp 2554eaae44dSAndrew Thompson. 256dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_time_complete 257dc8f21bcSAndrew Thompsonwill return the completion time of an USB transfer in 2584eaae44dSAndrew Thompsonmillisecond units. This function is most useful for isochronous USB 2594eaae44dSAndrew Thompsontransfers when doing echo cancelling. 2604eaae44dSAndrew Thompson. 2614eaae44dSAndrew Thompson.Pp 2624eaae44dSAndrew Thompson. 263dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_actual_frames 264dc8f21bcSAndrew Thompsonwill return the actual number of USB frames after an USB 2654eaae44dSAndrew Thompsontransfer completed. A value of zero means that no data was transferred. 2664eaae44dSAndrew Thompson. 2674eaae44dSAndrew Thompson.Pp 2684eaae44dSAndrew Thompson. 269dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_actual_length 270dc8f21bcSAndrew Thompsonwill return the sum of the actual length for all 2714eaae44dSAndrew Thompsontransferred USB frames for the given USB transfer. 2724eaae44dSAndrew Thompson. 2734eaae44dSAndrew Thompson.Pp 2744eaae44dSAndrew Thompson. 275dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_max_frames 276dc8f21bcSAndrew Thompsonwill return the maximum number of USB frames that were 2774eaae44dSAndrew Thompsonallocated when an USB transfer was setup for the given USB transfer. 2784eaae44dSAndrew Thompson. 2794eaae44dSAndrew Thompson.Pp 2804eaae44dSAndrew Thompson. 281dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_max_packet_length 282dc8f21bcSAndrew Thompsonwill return the maximum packet length in bytes 2834eaae44dSAndrew Thompsonassociated with the given USB transfer. 2844eaae44dSAndrew Thompson. 2854eaae44dSAndrew ThompsonThe packet length can be used round up buffer sizes so that short USB 2864eaae44dSAndrew Thompsonpackets are avoided for proxy buffers. 2874eaae44dSAndrew Thompson. 2884eaae44dSAndrew Thompson. 2894eaae44dSAndrew Thompson.Pp 2904eaae44dSAndrew Thompson. 291dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_max_total_length 292dc8f21bcSAndrew Thompsonfunction will return the maximum value for the length sum of all 2934eaae44dSAndrew ThompsonUSB frames associated with an USB transfer. 2944eaae44dSAndrew Thompson. 2954eaae44dSAndrew Thompson.Pp 2964eaae44dSAndrew Thompson. 297dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_status 298dc8f21bcSAndrew Thompsonwill return the status of an USB transfer. 2994eaae44dSAndrew Thompson. 3004eaae44dSAndrew ThompsonStatus values are defined by a set of LIBUSB20_TRANSFER_XXX enums. 3014eaae44dSAndrew Thompson. 3024eaae44dSAndrew Thompson.Pp 3034eaae44dSAndrew Thompson. 304dc8f21bcSAndrew Thompson.Fn libusb20_tr_pending 305dc8f21bcSAndrew Thompsonwill return non-zero if the given USB transfer is 3064eaae44dSAndrew Thompsonpending for completion. 3074eaae44dSAndrew Thompson. 3084eaae44dSAndrew ThompsonElse this function returns zero. 3094eaae44dSAndrew Thompson. 3104eaae44dSAndrew Thompson.Pp 3114eaae44dSAndrew Thompson. 312dc8f21bcSAndrew Thompson.Fn libusb20_tr_callback_wrapper 3134eaae44dSAndrew ThompsonThis is an internal function used to wrap asynchronous USB callbacks. 3144eaae44dSAndrew Thompson. 3154eaae44dSAndrew Thompson.Pp 3164eaae44dSAndrew Thompson. 317dc8f21bcSAndrew Thompson.Fn libusb20_tr_clear_stall_sync 3184eaae44dSAndrew ThompsonThis is an internal function used to synchronously clear the stall on 3194eaae44dSAndrew Thompsonthe given USB transfer. 3204eaae44dSAndrew Thompson. 3214eaae44dSAndrew ThompsonPlease see the USB specification for more information on stall 3224eaae44dSAndrew Thompsonclearing. 3234eaae44dSAndrew Thompson. 3244eaae44dSAndrew ThompsonIf the given USB transfer is pending when this function is called, the 3254eaae44dSAndrew ThompsonUSB transfer will complete with an error after that this function has 3264eaae44dSAndrew Thompsonbeen called. 3274eaae44dSAndrew Thompson. 3284eaae44dSAndrew Thompson.Pp 3294eaae44dSAndrew Thompson. 330dc8f21bcSAndrew Thompson.Fn libusb20_tr_drain 331dc8f21bcSAndrew Thompsonwill stop the given USB transfer and will not return 3324eaae44dSAndrew Thompsonuntil the USB transfer has been stopped in hardware. 3334eaae44dSAndrew Thompson. 3344eaae44dSAndrew Thompson.Pp 3354eaae44dSAndrew Thompson. 336dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_buffer 337dc8f21bcSAndrew Thompsonis used to set the 3384eaae44dSAndrew Thompson.Fa buffer 3394eaae44dSAndrew Thompsonpointer for the given USB transfer and 3404eaae44dSAndrew Thompson.Fa fr_index . 3414eaae44dSAndrew Thompson. 3424eaae44dSAndrew ThompsonTypically the frame index is zero. 3434eaae44dSAndrew Thompson. 3444eaae44dSAndrew Thompson. 3454eaae44dSAndrew Thompson.Pp 3464eaae44dSAndrew Thompson. 347dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_callback 348dc8f21bcSAndrew Thompsonis used to set the USB callback for asynchronous USB 3494eaae44dSAndrew Thompsontransfers. 3504eaae44dSAndrew Thompson. 3514eaae44dSAndrew ThompsonThe callback type is defined by libusb20_tr_callback_t. 3524eaae44dSAndrew Thompson. 3534eaae44dSAndrew Thompson.Pp 3544eaae44dSAndrew Thompson. 355dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_flags 356dc8f21bcSAndrew Thompsonis used to set various USB flags for the given USB transfer. 3574eaae44dSAndrew Thompson.Bl -tag 3584eaae44dSAndrew Thompson.It LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK 3594eaae44dSAndrew ThompsonReport a short frame as error. 3604eaae44dSAndrew Thompson.It LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK 3614eaae44dSAndrew ThompsonMultiple short frames are not allowed. 3624eaae44dSAndrew Thompson.It LIBUSB20_TRANSFER_FORCE_SHORT 3634eaae44dSAndrew ThompsonAll transmitted frames are short terminated. 3644eaae44dSAndrew Thompson.It LIBUSB20_TRANSFER_DO_CLEAR_STALL 3654eaae44dSAndrew ThompsonWill do a clear-stall before starting the transfer. 3664eaae44dSAndrew Thompson.El 3674eaae44dSAndrew Thompson. 3684eaae44dSAndrew Thompson.Pp 3694eaae44dSAndrew Thompson. 370dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_length 371dc8f21bcSAndrew Thompsonsets the length of a given USB transfer and frame index. 3724eaae44dSAndrew Thompson. 3734eaae44dSAndrew Thompson.Pp 3744eaae44dSAndrew Thompson. 375dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_priv_sc0 376dc8f21bcSAndrew Thompsonsets private driver pointer number zero. 3774eaae44dSAndrew Thompson. 3784eaae44dSAndrew Thompson.Pp 3794eaae44dSAndrew Thompson. 380dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_priv_sc1 381dc8f21bcSAndrew Thompsonsets private driver pointer number one. 3824eaae44dSAndrew Thompson. 3834eaae44dSAndrew Thompson.Pp 3844eaae44dSAndrew Thompson. 385dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_timeout 386dc8f21bcSAndrew Thompsonsets the timeout for the given USB transfer. 3874eaae44dSAndrew Thompson. 3884eaae44dSAndrew ThompsonA timeout value of zero means no timeout. 3894eaae44dSAndrew Thompson. 3904eaae44dSAndrew ThompsonThe timeout is given in milliseconds. 3914eaae44dSAndrew Thompson. 3924eaae44dSAndrew Thompson.Pp 3934eaae44dSAndrew Thompson. 394dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_total_frames 395dc8f21bcSAndrew Thompsonsets the total number of frames that should be executed when the USB transfer is submitted. 3964eaae44dSAndrew Thompson. 3974eaae44dSAndrew ThompsonThe total number of USB frames must be less than the maximum number of USB frames associated with the given USB transfer. 3984eaae44dSAndrew Thompson. 3994eaae44dSAndrew Thompson.Pp 4004eaae44dSAndrew Thompson. 401dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_bulk 402dc8f21bcSAndrew Thompsonis a helper function for setting up a single frame USB BULK transfer. 4034eaae44dSAndrew Thompson. 4044eaae44dSAndrew Thompson.Pp 4054eaae44dSAndrew Thompson. 406dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_control 407dc8f21bcSAndrew Thompsonis a helper function for setting up a single or dual 4084eaae44dSAndrew Thompsonframe USB CONTROL transfer depending on the control transfer length. 4094eaae44dSAndrew Thompson. 4104eaae44dSAndrew Thompson.Pp 4114eaae44dSAndrew Thompson. 412dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_intr 413dc8f21bcSAndrew Thompsonis a helper function for setting up a single frame USB INTERRUPT transfer. 4144eaae44dSAndrew Thompson. 4154eaae44dSAndrew Thompson.Pp 4164eaae44dSAndrew Thompson. 417dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_isoc 418dc8f21bcSAndrew Thompsonis a helper function for setting up a multi frame USB ISOCHRONOUS transfer. 4194eaae44dSAndrew Thompson. 4204eaae44dSAndrew Thompson.Pp 4214eaae44dSAndrew Thompson. 422dc8f21bcSAndrew Thompson.Fn libusb20_tr_start 423dc8f21bcSAndrew Thompsonwill get the USB transfer started, if not already 4244eaae44dSAndrew Thompsonstarted. 4254eaae44dSAndrew Thompson. 4264eaae44dSAndrew ThompsonThis function will not get the transfer queued in hardware. 4274eaae44dSAndrew Thompson. 4284eaae44dSAndrew ThompsonThis function is non-blocking. 4294eaae44dSAndrew Thompson. 4304eaae44dSAndrew Thompson.Pp 4314eaae44dSAndrew Thompson. 432dc8f21bcSAndrew Thompson.Fn libusb20_tr_stop 433dc8f21bcSAndrew Thompsonwill get the USB transfer stopped, if not already stopped. 4344eaae44dSAndrew Thompson. 4354eaae44dSAndrew ThompsonThis function is non-blocking, which means that the actual stop can 4364eaae44dSAndrew Thompsonhappen after the return of this function. 4374eaae44dSAndrew Thompson. 4384eaae44dSAndrew Thompson.Pp 4394eaae44dSAndrew Thompson. 440dc8f21bcSAndrew Thompson.Fn libusb20_tr_submit 441dc8f21bcSAndrew Thompsonwill get the USB transfer queued in hardware. 4424eaae44dSAndrew Thompson. 4434eaae44dSAndrew Thompson. 4444eaae44dSAndrew Thompson.Pp 4454eaae44dSAndrew Thompson. 446dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_priv_sc0 447dc8f21bcSAndrew Thompsonreturns private driver pointer number zero associated 4484eaae44dSAndrew Thompsonwith an USB transfer. 4494eaae44dSAndrew Thompson. 4504eaae44dSAndrew Thompson. 4514eaae44dSAndrew Thompson.Pp 4524eaae44dSAndrew Thompson. 453dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_priv_sc1 454dc8f21bcSAndrew Thompsonreturns private driver pointer number one associated 4554eaae44dSAndrew Thompsonwith an USB transfer. 4564eaae44dSAndrew Thompson. 4574eaae44dSAndrew Thompson. 4584eaae44dSAndrew Thompson.Sh USB DEVICE OPERATIONS 4594eaae44dSAndrew Thompson. 4604eaae44dSAndrew Thompson.Pp 4614eaae44dSAndrew Thompson. 462dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_backend_name 463dc8f21bcSAndrew Thompsonreturns a zero terminated string describing the backend used. 4644eaae44dSAndrew Thompson. 4654eaae44dSAndrew Thompson.Pp 4664eaae44dSAndrew Thompson. 467dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_info 468dc8f21bcSAndrew Thompsonretrives the BSD specific usb2_device_info structure into the memory location given by 4694eaae44dSAndrew Thompson.Fa pinfo . 4704eaae44dSAndrew ThompsonThe USB device given by 4714eaae44dSAndrew Thompson.Fa pdev 4724eaae44dSAndrew Thompsonmust be opened before this function will succeed. 4734eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is returned. 4744eaae44dSAndrew Thompson. 4754eaae44dSAndrew Thompson.Pp 4764eaae44dSAndrew Thompson. 477dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_iface_desc 478dc8f21bcSAndrew Thompsonretrieves the kernel interface description for the given USB 4794eaae44dSAndrew Thompson.Fa iface_index . 4804eaae44dSAndrew ThompsonThe format of the USB interface description is: "drivername<unit>: <description>" 4814eaae44dSAndrew ThompsonThe description string is always zero terminated. 4824eaae44dSAndrew ThompsonA zero length string is written in case no driver is attached to the given interface. 4834eaae44dSAndrew ThompsonThe USB device given by 4844eaae44dSAndrew Thompson.Fa pdev 4854eaae44dSAndrew Thompsonmust be opened before this function will succeed. 4864eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is returned. 4874eaae44dSAndrew Thompson. 4884eaae44dSAndrew Thompson.Pp 4894eaae44dSAndrew Thompson. 490dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_desc 491dc8f21bcSAndrew Thompsonreturns a zero terminated string describing the given USB device. 4924eaae44dSAndrew ThompsonThe format of the string is: "drivername<unit>: <description>" 4934eaae44dSAndrew Thompson. 4944eaae44dSAndrew Thompson.Pp 4954eaae44dSAndrew Thompson. 496dc8f21bcSAndrew Thompson.Fn libusb20_dev_claim_interface 4974eaae44dSAndrew ThompsonThis function will try to claim the given USB interface given by 4984eaae44dSAndrew Thompson.Fa iface_index . 4994eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 5004eaae44dSAndrew Thompsonreturned. 5014eaae44dSAndrew Thompson. 5024eaae44dSAndrew Thompson.Pp 5034eaae44dSAndrew Thompson. 504dc8f21bcSAndrew Thompson.Fn libusb20_dev_close 505dc8f21bcSAndrew Thompsonwill close the given USB device. 5064eaae44dSAndrew Thompson. 5074eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 5084eaae44dSAndrew Thompsonreturned. 5094eaae44dSAndrew Thompson. 5104eaae44dSAndrew Thompson.Pp 5114eaae44dSAndrew Thompson. 512dc8f21bcSAndrew Thompson.Fn libusb20_dev_detach_kernel_driver 513dc8f21bcSAndrew Thompsonwill try to detach the kernel driver for the USB interface given by 5144eaae44dSAndrew Thompson.Fa iface_index . 5154eaae44dSAndrew Thompson. 5164eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 5174eaae44dSAndrew Thompsonreturned. 5184eaae44dSAndrew Thompson. 5194eaae44dSAndrew Thompson.Pp 5204eaae44dSAndrew Thompson. 521dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_config_index 522dc8f21bcSAndrew Thompsonwill try to set the configuration index on an USB 5234eaae44dSAndrew Thompsondevice. 5244eaae44dSAndrew Thompson. 5254eaae44dSAndrew ThompsonThe first configuration index is zero. 5264eaae44dSAndrew Thompson. 5274eaae44dSAndrew ThompsonThe un-configure index is 255. 5284eaae44dSAndrew Thompson. 5294eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is returned. 5304eaae44dSAndrew Thompson. 5314eaae44dSAndrew Thompson.Pp 5324eaae44dSAndrew Thompson. 533dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_debug 534dc8f21bcSAndrew Thompsonreturns the debug level of an USB device. 5354eaae44dSAndrew Thompson. 5364eaae44dSAndrew Thompson.Pp 5374eaae44dSAndrew Thompson. 538dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_fd 539dc8f21bcSAndrew Thompsonreturns the file descriptor of the given USB device. 5404eaae44dSAndrew Thompson. 5414eaae44dSAndrew ThompsonA negative value is returned when no file descriptor is present. 5424eaae44dSAndrew Thompson. 5434eaae44dSAndrew ThompsonThe file descriptor can be used for polling purposes. 5444eaae44dSAndrew Thompson. 5454eaae44dSAndrew Thompson.Pp 5464eaae44dSAndrew Thompson. 547dc8f21bcSAndrew Thompson.Fn libusb20_dev_kernel_driver_active 548dc8f21bcSAndrew Thompsonreturns a non-zero value if a kernel driver is active on 5494eaae44dSAndrew Thompsonthe given USB interface. 5504eaae44dSAndrew Thompson. 5514eaae44dSAndrew ThompsonElse zero is returned. 5524eaae44dSAndrew Thompson. 5534eaae44dSAndrew Thompson.Pp 5544eaae44dSAndrew Thompson. 555dc8f21bcSAndrew Thompson.Fn libusb20_dev_open 556dc8f21bcSAndrew Thompsonopens an USB device so that setting up USB transfers 5574eaae44dSAndrew Thompsonbecomes possible. 5584eaae44dSAndrew Thompson. 5594eaae44dSAndrew ThompsonThe number of USB transfers can be zero which means only control 5604eaae44dSAndrew Thompsontransfers are allowed. 5614eaae44dSAndrew Thompson. 5624eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 5634eaae44dSAndrew Thompsonreturned. 5644eaae44dSAndrew Thompson. 5654eaae44dSAndrew ThompsonA return value of LIBUSB20_ERROR_BUSY means that the device is already 5664eaae44dSAndrew Thompsonopened. 5674eaae44dSAndrew Thompson. 5684eaae44dSAndrew Thompson.Pp 5694eaae44dSAndrew Thompson. 570dc8f21bcSAndrew Thompson.Fn libusb20_dev_process 571dc8f21bcSAndrew Thompsonis called to sync kernel USB transfers with userland USB 5724eaae44dSAndrew Thompsontransfers. 5734eaae44dSAndrew Thompson. 5744eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 5754eaae44dSAndrew Thompsonreturned typically indicating that the given USB device has been 5764eaae44dSAndrew Thompsondetached. 5774eaae44dSAndrew Thompson. 5784eaae44dSAndrew Thompson.Pp 5794eaae44dSAndrew Thompson. 580dc8f21bcSAndrew Thompson.Fn libusb20_dev_release_interface 581dc8f21bcSAndrew Thompsonwill try to release a claimed USB interface for the specified USB device. 5824eaae44dSAndrew Thompson. 5834eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 5844eaae44dSAndrew Thompsonreturned. 5854eaae44dSAndrew Thompson. 5864eaae44dSAndrew Thompson.Pp 5874eaae44dSAndrew Thompson. 588dc8f21bcSAndrew Thompson.Fn libusb20_dev_request_sync 589dc8f21bcSAndrew Thompsonwill perform a synchronous control request on the given 5904eaae44dSAndrew ThompsonUSB device. 5914eaae44dSAndrew Thompson. 5924eaae44dSAndrew ThompsonBefore this call will succeed the USB device must be opened. 5934eaae44dSAndrew Thompson. 5944eaae44dSAndrew Thompson.Fa setup 5954eaae44dSAndrew Thompsonis a pointer to a decoded and host endian SETUP packet. 5964eaae44dSAndrew Thompson.Fa data 5974eaae44dSAndrew Thompsonis a pointer to a data transfer buffer associated with the control transaction. This argument can be NULL. 5984eaae44dSAndrew Thompson.Fa pactlen 5994eaae44dSAndrew Thompsonis a pointer to a variable that will hold the actual transfer length after the control transaction is complete. 6004eaae44dSAndrew Thompson.Fa timeout 6014eaae44dSAndrew Thompsonis the transaction timeout given in milliseconds. 6024eaae44dSAndrew ThompsonA timeout of zero means no timeout. 6034eaae44dSAndrew Thompson.Fa flags 6044eaae44dSAndrew Thompsonis used to specify transaction flags, for example LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK. 6054eaae44dSAndrew Thompson. 6064eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 6074eaae44dSAndrew Thompsonreturned. 6084eaae44dSAndrew Thompson. 6094eaae44dSAndrew Thompson.Pp 6104eaae44dSAndrew Thompson. 611dc8f21bcSAndrew Thompson.Fn libusb20_dev_req_string_sync 612dc8f21bcSAndrew Thompsonwill synchronously request an USB string by language ID 6134eaae44dSAndrew Thompsonand string index into the given buffer limited by a maximum length. 6144eaae44dSAndrew Thompson. 6154eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 6164eaae44dSAndrew Thompsonreturned. 6174eaae44dSAndrew Thompson. 6184eaae44dSAndrew Thompson.Pp 6194eaae44dSAndrew Thompson. 620dc8f21bcSAndrew Thompson.Fn libusb20_dev_req_string_simple_sync 621dc8f21bcSAndrew Thompsonwill synchronously request an USB string using the 6224eaae44dSAndrew Thompsondefault language ID and convert the string into ASCII before storing 6234eaae44dSAndrew Thompsonthe string into the given buffer limited by a maximum length which 6244eaae44dSAndrew Thompsonincludes the terminating zero. 6254eaae44dSAndrew Thompson. 6264eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 6274eaae44dSAndrew Thompsonreturned. 6284eaae44dSAndrew Thompson. 6294eaae44dSAndrew Thompson. 6304eaae44dSAndrew Thompson.Pp 6314eaae44dSAndrew Thompson. 632dc8f21bcSAndrew Thompson.Fn libusb20_dev_reset 633dc8f21bcSAndrew Thompsonwill try to BUS reset the given USB device and restore 6344eaae44dSAndrew Thompsonthe last set USB configuration. 6354eaae44dSAndrew Thompson. 6364eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 6374eaae44dSAndrew Thompsonreturned. 6384eaae44dSAndrew Thompson. 6394eaae44dSAndrew Thompson.Pp 6404eaae44dSAndrew Thompson. 641dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_power_mode 642dc8f21bcSAndrew Thompsonsets the power mode of the USB device. 6434eaae44dSAndrew Thompson. 6444eaae44dSAndrew ThompsonValid power modes: 6454eaae44dSAndrew Thompson.Bl -tag 6464eaae44dSAndrew Thompson.It LIBUSB20_POWER_OFF 6474eaae44dSAndrew Thompson.It LIBUSB20_POWER_ON 6484eaae44dSAndrew Thompson.It LIBUSB20_POWER_SAVE 6494eaae44dSAndrew Thompson.It LIBUSB20_POWER_SUSPEND 6504eaae44dSAndrew Thompson.It LIBUSB20_POWER_RESUME 6514eaae44dSAndrew Thompson.El 6524eaae44dSAndrew Thompson. 6534eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 6544eaae44dSAndrew Thompsonreturned. 6554eaae44dSAndrew Thompson. 6564eaae44dSAndrew Thompson.Pp 6574eaae44dSAndrew Thompson. 658dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_power_mode 659dc8f21bcSAndrew Thompsonreturns the currently selected power mode for the given 6604eaae44dSAndrew ThompsonUSB device. 6614eaae44dSAndrew Thompson. 6624eaae44dSAndrew Thompson.Pp 6634eaae44dSAndrew Thompson. 664dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_alt_index 665dc8f21bcSAndrew Thompsonwill try to set the given alternate index for the given 6664eaae44dSAndrew ThompsonUSB interface index. 6674eaae44dSAndrew Thompson. 6684eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 6694eaae44dSAndrew Thompsonreturned. 6704eaae44dSAndrew Thompson. 6714eaae44dSAndrew Thompson.Pp 6724eaae44dSAndrew Thompson. 673dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_device_desc 674dc8f21bcSAndrew Thompsonreturns a pointer to the decoded and host endian version 6754eaae44dSAndrew Thompsonof the device descriptor. 6764eaae44dSAndrew Thompson. 6774eaae44dSAndrew ThompsonThe USB device need not be opened when calling this function. 6784eaae44dSAndrew Thompson. 6794eaae44dSAndrew Thompson.Pp 6804eaae44dSAndrew Thompson. 681dc8f21bcSAndrew Thompson.Fn libusb20_dev_alloc_config 682dc8f21bcSAndrew Thompsonwill read out and decode the USB config descriptor for 6834eaae44dSAndrew Thompsonthe given USB device and config index. This function returns a pointer 6844eaae44dSAndrew Thompsonto the decoded configuration which must eventually be passed to 6854eaae44dSAndrew Thompsonfree(). NULL is returned in case of failure. 6864eaae44dSAndrew Thompson. 6874eaae44dSAndrew Thompson.Pp 6884eaae44dSAndrew Thompson. 689dc8f21bcSAndrew Thompson.Fn libusb20_dev_alloc 690dc8f21bcSAndrew Thompsonis an internal function to allocate a new USB device. 6914eaae44dSAndrew Thompson. 6924eaae44dSAndrew Thompson.Pp 6934eaae44dSAndrew Thompson. 694dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_address 695dc8f21bcSAndrew Thompsonreturns the internal and not necessarily the real 6964eaae44dSAndrew Thompsonhardware address of the given USB device. 6974eaae44dSAndrew Thompson. 6984eaae44dSAndrew Thompson.Pp 6994eaae44dSAndrew Thompson. 700dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_bus_number 701dc8f21bcSAndrew Thompsonreturns the internal bus number which the given USB 7024eaae44dSAndrew Thompsondevice belongs to. 7034eaae44dSAndrew Thompson. 7044eaae44dSAndrew Thompson.Pp 7054eaae44dSAndrew Thompson. 706dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_mode 707dc8f21bcSAndrew Thompsonreturns the current operation mode of the USB entity. 7084eaae44dSAndrew Thompson. 7094eaae44dSAndrew ThompsonValid return values are: 7104eaae44dSAndrew Thompson.Bl -tag 7114eaae44dSAndrew Thompson.It LIBUSB20_MODE_HOST 7124eaae44dSAndrew Thompson.It LIBUSB20_MODE_DEVICE 7134eaae44dSAndrew Thompson.El 7144eaae44dSAndrew Thompson. 7154eaae44dSAndrew Thompson.Pp 7164eaae44dSAndrew Thompson. 717dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_speed 718dc8f21bcSAndrew Thompsonreturns the current speed of the given USB device. 7194eaae44dSAndrew Thompson. 7204eaae44dSAndrew Thompson.Bl -tag 7214eaae44dSAndrew Thompson.It LIBUSB20_SPEED_UNKNOWN 7224eaae44dSAndrew Thompson.It LIBUSB20_SPEED_LOW 7234eaae44dSAndrew Thompson.It LIBUSB20_SPEED_FULL 7244eaae44dSAndrew Thompson.It LIBUSB20_SPEED_HIGH 7254eaae44dSAndrew Thompson.It LIBUSB20_SPEED_VARIABLE 7264eaae44dSAndrew Thompson.It LIBUSB20_SPEED_SUPER 7274eaae44dSAndrew Thompson.El 7284eaae44dSAndrew Thompson. 7294eaae44dSAndrew Thompson.Pp 7304eaae44dSAndrew Thompson. 731dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_config_index 7324eaae44dSAndrew ThompsonThis function returns the currently select config index for the given 7334eaae44dSAndrew ThompsonUSB device. 7344eaae44dSAndrew Thompson. 7354eaae44dSAndrew Thompson.Pp 7364eaae44dSAndrew Thompson. 737dc8f21bcSAndrew Thompson.Fn libusb20_dev_free 738dc8f21bcSAndrew Thompsonwill free the given USB device and all associated USB 7394eaae44dSAndrew Thompsontransfers. 7404eaae44dSAndrew Thompson. 7414eaae44dSAndrew Thompson.Pp 7424eaae44dSAndrew Thompson. 743dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_debug 744dc8f21bcSAndrew Thompsonwill set the debug level for the given USB device. 7454eaae44dSAndrew Thompson. 7464eaae44dSAndrew Thompson.Pp 7474eaae44dSAndrew Thompson. 748dc8f21bcSAndrew Thompson.Fn libusb20_dev_wait_process 749dc8f21bcSAndrew Thompsonfunction will wait until a pending USB transfer has completed on 7504eaae44dSAndrew Thompsonthe given USB device. 7514eaae44dSAndrew Thompson. 7524eaae44dSAndrew ThompsonA timeout value can be specified which is passed on to the 7534eaae44dSAndrew Thompson.Xr 2 poll 7544eaae44dSAndrew Thompsonfunction. 7554eaae44dSAndrew Thompson. 7564eaae44dSAndrew Thompson.Sh USB BACKEND OPERATIONS 7574eaae44dSAndrew Thompson. 758dc8f21bcSAndrew Thompson.Fn libusb20_be_get_template 759dc8f21bcSAndrew Thompsonwill return the currently selected global USB device 7604eaae44dSAndrew Thompsonside mode template into the integer pointer 7614eaae44dSAndrew Thompson.Fa ptemp . 7624eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 7634eaae44dSAndrew Thompsonreturned. 7644eaae44dSAndrew Thompson. 7654eaae44dSAndrew Thompson.Pp 7664eaae44dSAndrew Thompson. 767dc8f21bcSAndrew Thompson.Fn libusb20_be_set_template 768dc8f21bcSAndrew Thompsonwill set the global USB device side mode template to 7694eaae44dSAndrew Thompson.Fa temp . 7704eaae44dSAndrew ThompsonThe new template is not activated until after the next USB 7714eaae44dSAndrew Thompsonenumeration. 7724eaae44dSAndrew ThompsonThe template number decides how the USB device will present itself to 7734eaae44dSAndrew Thompsonthe USB Host, like Mass Storage Device, USB Ethernet Device. Also see 7744eaae44dSAndrew Thompsonthe 7754eaae44dSAndrew Thompson.Xr usb2_template 4 7764eaae44dSAndrew Thompsonmodule. 7774eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 7784eaae44dSAndrew Thompsonreturned. 7794eaae44dSAndrew Thompson. 7804eaae44dSAndrew Thompson.Pp 7814eaae44dSAndrew Thompson. 782dc8f21bcSAndrew Thompson.Fn libusb20_be_get_dev_quirk 7834eaae44dSAndrew ThompsonThis function will return the device quirk according to 7844eaae44dSAndrew Thompson.Fa index 7854eaae44dSAndrew Thompsoninto the libusb20_quirk structure pointed to by 7864eaae44dSAndrew Thompson.Fa pq . 7874eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 7884eaae44dSAndrew Thompsonreturned. 7894eaae44dSAndrew Thompson. 7904eaae44dSAndrew ThompsonIf the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is 7914eaae44dSAndrew Thompsonreturned. 7924eaae44dSAndrew Thompson. 7934eaae44dSAndrew Thompson.Pp 7944eaae44dSAndrew Thompson. 795dc8f21bcSAndrew Thompson.Fn libusb20_be_get_quirk_name 796dc8f21bcSAndrew Thompsonwill return the quirk name according to 7974eaae44dSAndrew Thompson.Fa index 7984eaae44dSAndrew Thompsoninto the libusb20_quirk structure pointed to by 7994eaae44dSAndrew Thompson.Fa pq . 8004eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 8014eaae44dSAndrew Thompsonreturned. 8024eaae44dSAndrew Thompson. 8034eaae44dSAndrew ThompsonIf the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is 8044eaae44dSAndrew Thompsonreturned. 8054eaae44dSAndrew Thompson. 8064eaae44dSAndrew Thompson.Pp 8074eaae44dSAndrew Thompson. 808dc8f21bcSAndrew Thompson.Fn libusb20_be_add_dev_quirk 809dc8f21bcSAndrew Thompsonwill add the libusb20_quirk structure pointed to by the 8104eaae44dSAndrew Thompson.Fa pq 8114eaae44dSAndrew Thompsonargument into the device quirk list. 8124eaae44dSAndrew Thompson. 8134eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 8144eaae44dSAndrew Thompsonreturned. 8154eaae44dSAndrew Thompson. 8164eaae44dSAndrew ThompsonIf the given quirk cannot be added LIBUSB20_ERROR_NO_MEM is 8174eaae44dSAndrew Thompsonreturned. 8184eaae44dSAndrew Thompson. 8194eaae44dSAndrew Thompson.Pp 8204eaae44dSAndrew Thompson. 821dc8f21bcSAndrew Thompson.Fn libusb20_be_remove_dev_quirk 822dc8f21bcSAndrew Thompsonwill remove the quirk matching the libusb20_quirk structure pointed to by the 8234eaae44dSAndrew Thompson.Fa pq 8244eaae44dSAndrew Thompsonargument from the device quirk list. 8254eaae44dSAndrew Thompson. 8264eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is 8274eaae44dSAndrew Thompsonreturned. 8284eaae44dSAndrew Thompson. 8294eaae44dSAndrew ThompsonIf the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is 8304eaae44dSAndrew Thompsonreturned. 8314eaae44dSAndrew Thompson. 832dc8f21bcSAndrew Thompson.Fn libusb20_be_alloc_linux 8334eaae44dSAndrew ThompsonThese functions are used to allocate a specific USB backend or the 8344eaae44dSAndrew Thompsonoperating system default USB backend. Allocating a backend is a way to 8354eaae44dSAndrew Thompsonscan for currently present USB devices. 8364eaae44dSAndrew Thompson. 8374eaae44dSAndrew Thompson.Pp 8384eaae44dSAndrew Thompson. 839dc8f21bcSAndrew Thompson.Fn libusb20_be_device_foreach 840dc8f21bcSAndrew Thompsonis used to iterate USB devices present in a USB backend. 8414eaae44dSAndrew Thompson. 8424eaae44dSAndrew ThompsonThe starting value of 8434eaae44dSAndrew Thompson.Fa pdev 8444eaae44dSAndrew Thompsonis NULL. 8454eaae44dSAndrew Thompson. 8464eaae44dSAndrew ThompsonThis function returns the next USB device in the list. 8474eaae44dSAndrew Thompson. 8484eaae44dSAndrew ThompsonIf NULL is returned the end of the USB device list has been reached. 8494eaae44dSAndrew Thompson. 8504eaae44dSAndrew Thompson.Pp 8514eaae44dSAndrew Thompson. 852dc8f21bcSAndrew Thompson.Fn libusb20_be_dequeue_device 853dc8f21bcSAndrew Thompsonwill dequeue the given USB device pointer from the 8544eaae44dSAndrew Thompsonbackend USB device list. 8554eaae44dSAndrew Thompson. 8564eaae44dSAndrew ThompsonDequeued USB devices will not be freed when the backend is freed. 8574eaae44dSAndrew Thompson. 8584eaae44dSAndrew Thompson.Pp 8594eaae44dSAndrew Thompson. 860dc8f21bcSAndrew Thompson.Fn libusb20_be_enqueue_device 8614eaae44dSAndrew ThompsonThis function will enqueue the given USB device pointer in the backend USB device list. 8624eaae44dSAndrew Thompson. 8634eaae44dSAndrew ThompsonEnqueued USB devices will get freed when the backend is freed. 8644eaae44dSAndrew Thompson. 8654eaae44dSAndrew Thompson.Pp 8664eaae44dSAndrew Thompson. 867dc8f21bcSAndrew Thompson.Fn libusb20_be_free 868dc8f21bcSAndrew Thompsonwill free the given backend and all USB devices in its device list. 8694eaae44dSAndrew Thompson. 8704eaae44dSAndrew Thompson. 8714eaae44dSAndrew Thompson.Sh USB DESCRIPTOR PARSING 8724eaae44dSAndrew Thompson. 8734eaae44dSAndrew Thompson.Fn libusb20_me_get_1 pie offset 8744eaae44dSAndrew ThompsonThis function will return a byte at the given byte offset of a message 8754eaae44dSAndrew Thompsonentity. 8764eaae44dSAndrew Thompson. 8774eaae44dSAndrew ThompsonThis function is safe against invalid offsets. 8784eaae44dSAndrew Thompson. 8794eaae44dSAndrew Thompson.Pp 8804eaae44dSAndrew Thompson. 8814eaae44dSAndrew Thompson.Fn libusb20_me_get_2 pie offset 8824eaae44dSAndrew ThompsonThis function will return a little endian 16-bit value at the given byte offset of a message 8834eaae44dSAndrew Thompsonentity. 8844eaae44dSAndrew Thompson. 8854eaae44dSAndrew ThompsonThis function is safe against invalid offsets. 8864eaae44dSAndrew Thompson. 8874eaae44dSAndrew Thompson.Pp 8884eaae44dSAndrew Thompson. 8894eaae44dSAndrew Thompson.Fn libusb20_me_encode pbuf len pdecoded 8904eaae44dSAndrew ThompsonThis function will encode a so-called *DECODED structure into binary 8914eaae44dSAndrew Thompsonformat. 8924eaae44dSAndrew Thompson. 8934eaae44dSAndrew ThompsonThe total encoded length that will fit in the given buffer is 8944eaae44dSAndrew Thompsonreturned. 8954eaae44dSAndrew Thompson. 8964eaae44dSAndrew ThompsonIf the buffer pointer is NULL no data will be written to the buffer 8974eaae44dSAndrew Thompsonlocation. 8984eaae44dSAndrew Thompson. 8994eaae44dSAndrew Thompson.Pp 9004eaae44dSAndrew Thompson. 9014eaae44dSAndrew Thompson.Fn libusb20_me_decode pbuf len pdecoded 9024eaae44dSAndrew ThompsonThis function will decode a binary structure into a so-called *DECODED 9034eaae44dSAndrew Thompsonstructure. 9044eaae44dSAndrew Thompson. 9054eaae44dSAndrew ThompsonThe total decoded length is returned. 9064eaae44dSAndrew Thompson. 9074eaae44dSAndrew ThompsonThe buffer pointer cannot be NULL. 9084eaae44dSAndrew Thompson. 9094eaae44dSAndrew Thompson. 9104eaae44dSAndrew Thompson.Sh LIBUSB VERSION 0.1 COMPATIBILITY 9114eaae44dSAndrew Thompson. 9124eaae44dSAndrew Thompson.Fn usb_open 9134eaae44dSAndrew Thompson.Fn usb_close 9144eaae44dSAndrew Thompson.Fn usb_get_string 9154eaae44dSAndrew Thompson.Fn usb_get_string_simple 9164eaae44dSAndrew Thompson.Fn usb_get_descriptor_by_endpoint 9174eaae44dSAndrew Thompson.Fn usb_get_descriptor 9184eaae44dSAndrew Thompson.Fn usb_parse_descriptor 9194eaae44dSAndrew Thompson.Fn usb_parse_configuration 9204eaae44dSAndrew Thompson.Fn usb_destroy_configuration 9214eaae44dSAndrew Thompson.Fn usb_fetch_and_parse_descriptors 9224eaae44dSAndrew Thompson.Fn usb_bulk_write 9234eaae44dSAndrew Thompson.Fn usb_bulk_read 9244eaae44dSAndrew Thompson.Fn usb_interrupt_write 9254eaae44dSAndrew Thompson.Fn usb_interrupt_read 9264eaae44dSAndrew Thompson.Fn usb_control_msg 9274eaae44dSAndrew Thompson.Fn usb_set_configuration 9284eaae44dSAndrew Thompson.Fn usb_claim_interface 9294eaae44dSAndrew Thompson.Fn usb_release_interface 9304eaae44dSAndrew Thompson.Fn usb_set_altinterface 9314eaae44dSAndrew Thompson.Fn usb_resetep 9324eaae44dSAndrew Thompson.Fn usb_clear_halt 9334eaae44dSAndrew Thompson.Fn usb_reset 9344eaae44dSAndrew Thompson.Fn usb_strerror 9354eaae44dSAndrew Thompson.Fn usb_init 9364eaae44dSAndrew Thompson.Fn usb_set_debug 9374eaae44dSAndrew Thompson.Fn usb_find_busses 9384eaae44dSAndrew Thompson.Fn usb_find_devices 9394eaae44dSAndrew Thompson.Fn usb_device 9404eaae44dSAndrew Thompson.Fn usb_get_busses 9414eaae44dSAndrew ThompsonThese functions are compliant with LibUSB version 0.1.12. 9424eaae44dSAndrew Thompson. 9434eaae44dSAndrew Thompson.Sh FILES 9444eaae44dSAndrew Thompson. 9454eaae44dSAndrew Thompson. 9464eaae44dSAndrew Thompson/dev/usb 9474eaae44dSAndrew Thompson.Sh SEE ALSO 948c54c1f7cSAndrew Thompson.Xr usb 4 , 9494eaae44dSAndrew Thompson.Xr usbconfig 8 9504eaae44dSAndrew Thompson. 9514eaae44dSAndrew Thompson. 9524eaae44dSAndrew Thompson.Sh HISTORY 9534eaae44dSAndrew Thompson. 9544eaae44dSAndrew Thompson. 9554eaae44dSAndrew ThompsonSome parts of the 9564eaae44dSAndrew Thompson.Nm 9574eaae44dSAndrew ThompsonAPI derives from the libusb project at sourceforge. 958