xref: /freebsd/lib/libusb/libusb.3 (revision 545b01ad3a7ded3fc7bcf82749757641b66e4b73) 
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.\"
29545b01adSAndrew Thompson.Dd May 28, 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"
81545b01adSAndrew Thompson.Ft uint32_t
82545b01adSAndrew Thompson.Fn libusb20_tr_get_length "struct libusb20_transfer *xfer" "uint16_t fr_index"
83dc8f21bcSAndrew Thompson.Ft void
84dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_length "struct libusb20_transfer *xfer" "uint32_t length" "uint16_t fr_index"
85dc8f21bcSAndrew Thompson.Ft void
86dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_priv_sc0 "struct libusb20_transfer *xfer" "void *sc0"
87dc8f21bcSAndrew Thompson.Ft void
88dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_priv_sc1 "struct libusb20_transfer *xfer" "void *sc1"
89dc8f21bcSAndrew Thompson.Ft void
90dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_timeout "struct libusb20_transfer *xfer" "uint32_t timeout"
91dc8f21bcSAndrew Thompson.Ft void
92dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_total_frames "struct libusb20_transfer *xfer" "uint32_t nframes"
93dc8f21bcSAndrew Thompson.Ft void
94dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_bulk "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout"
95dc8f21bcSAndrew Thompson.Ft void
96dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_control "struct libusb20_transfer *xfer" "void *psetup" "void *pbuf" "uint32_t timeout"
97dc8f21bcSAndrew Thompson.Ft void
98dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_intr "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout"
99dc8f21bcSAndrew Thompson.Ft void
100dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_isoc "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint61_t fr_index"
101dc8f21bcSAndrew Thompson.Ft void
102dc8f21bcSAndrew Thompson.Fn libusb20_tr_start "struct libusb20_transfer *xfer"
103dc8f21bcSAndrew Thompson.Ft void
104dc8f21bcSAndrew Thompson.Fn libusb20_tr_stop "struct libusb20_transfer *xfer"
105dc8f21bcSAndrew Thompson.Ft void
106dc8f21bcSAndrew Thompson.Fn libusb20_tr_submit "struct libusb20_transfer *xfer"
107dc8f21bcSAndrew Thompson.Ft void *
108dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_priv_sc0 "struct libusb20_transfer *xfer"
109dc8f21bcSAndrew Thompson.Ft void *
110dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_priv_sc1 "struct libusb20_transfer *xfer"
111dc8f21bcSAndrew Thompson.Ft const char *
112dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_backend_name "struct libusb20_device *"
113dc8f21bcSAndrew Thompson.Ft int
114760bc48eSAndrew Thompson.Fn libusb20_dev_get_info "struct libusb20_device *pdev" "struct usb_device_info *pinfo"
115dc8f21bcSAndrew Thompson.Ft int
116dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_iface_desc "struct libusb20_device *pdev" "uint8_t iface_index" "char *buf" "uint8_t len"
117dc8f21bcSAndrew Thompson.Ft const char *
118dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_desc "struct libusb20_device *pdev"
119dc8f21bcSAndrew Thompson.Ft int
120dc8f21bcSAndrew Thompson.Fn libusb20_dev_claim_interface "struct libusb20_device *pdev" "uint8_t iface_index"
121dc8f21bcSAndrew Thompson.Ft int
122dc8f21bcSAndrew Thompson.Fn libusb20_dev_close "struct libusb20_device *pdev"
123dc8f21bcSAndrew Thompson.Ft int
124dc8f21bcSAndrew Thompson.Fn libusb20_dev_detach_kernel_driver "struct libusb20_device *pdev" "uint8_t iface_index"
125dc8f21bcSAndrew Thompson.Ft int
126dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_config_index "struct libusb20_device *pdev" "uint8_t configIndex"
127dc8f21bcSAndrew Thompson.Ft int
128dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_debug "struct libusb20_device *pdev"
129dc8f21bcSAndrew Thompson.Ft int
130dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_fd "struct libusb20_device *pdev"
131dc8f21bcSAndrew Thompson.Ft int
132dc8f21bcSAndrew Thompson.Fn libusb20_dev_kernel_driver_active "struct libusb20_device *pdev" "uint8_t iface_index"
133dc8f21bcSAndrew Thompson.Ft int
134dc8f21bcSAndrew Thompson.Fn libusb20_dev_open "struct libusb20_device *pdev" "uint16_t transfer_max"
135dc8f21bcSAndrew Thompson.Ft int
136dc8f21bcSAndrew Thompson.Fn libusb20_dev_process "struct libusb20_device *pdev"
137dc8f21bcSAndrew Thompson.Ft int
138dc8f21bcSAndrew Thompson.Fn libusb20_dev_release_interface "struct libusb20_device *pdev" "uint8_t iface_index"
139dc8f21bcSAndrew Thompson.Ft int
140dc8f21bcSAndrew 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"
141dc8f21bcSAndrew Thompson.Ft int
142dc8f21bcSAndrew Thompson.Fn libusb20_dev_req_string_sync "struct libusb20_device *pdev" "uint8_t index" "uint16_t langid" "void *ptr" "uint16_t len"
143dc8f21bcSAndrew Thompson.Ft int
144dc8f21bcSAndrew Thompson.Fn libusb20_dev_req_string_simple_sync "struct libusb20_device *pdev" "uint8_t index" "void *ptr" "uint16_t len"
145dc8f21bcSAndrew Thompson.Ft int
146dc8f21bcSAndrew Thompson.Fn libusb20_dev_reset "struct libusb20_device *pdev"
147dc8f21bcSAndrew Thompson.Ft int
148dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_power_mode "struct libusb20_device *pdev" "uint8_t power_mode"
149dc8f21bcSAndrew Thompson.Ft uint8_t
150dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_power_mode "struct libusb20_device *pdev"
151dc8f21bcSAndrew Thompson.Ft int
152dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_alt_index "struct libusb20_device *pdev" "uint8_t iface_index" "uint8_t alt_index"
153c54c1f7cSAndrew Thompson.Ft struct LIBUSB20_DEVICE_DESC_DECODED *
154c54c1f7cSAndrew Thompson.Fn libusb20_dev_get_device_desc "struct libusb20_device *pdev"
155dc8f21bcSAndrew Thompson.Ft struct libusb20_config *
156dc8f21bcSAndrew Thompson.Fn libusb20_dev_alloc_config "struct libusb20_device *pdev" "uint8_t config_index"
157dc8f21bcSAndrew Thompson.Ft struct libusb20_device *
158dc8f21bcSAndrew Thompson.Fn libusb20_dev_alloc "void"
159dc8f21bcSAndrew Thompson.Ft uint8_t
160dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_address "struct libusb20_device *pdev"
161dc8f21bcSAndrew Thompson.Ft uint8_t
162dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_bus_number "struct libusb20_device *pdev"
163dc8f21bcSAndrew Thompson.Ft uint8_t
164dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_mode "struct libusb20_device *pdev"
165dc8f21bcSAndrew Thompson.Ft uint8_t
166dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_speed "struct libusb20_device *pdev"
167dc8f21bcSAndrew Thompson.Ft uint8_t
168dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_config_index "struct libusb20_device *pdev"
169dc8f21bcSAndrew Thompson.Ft void
170dc8f21bcSAndrew Thompson.Fn libusb20_dev_free "struct libusb20_device *pdev"
171dc8f21bcSAndrew Thompson.Ft void
172dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_debug "struct libusb20_device *pdev" "int debug"
173dc8f21bcSAndrew Thompson.Ft void
174dc8f21bcSAndrew Thompson.Fn libusb20_dev_wait_process "struct libusb20_device *pdev" "int timeout"
175dc8f21bcSAndrew Thompson.Ft int
176dc8f21bcSAndrew Thompson.Fn libusb20_be_get_template "struct libusb20_backend *pbe" "int *ptemp"
177dc8f21bcSAndrew Thompson.Ft int
178dc8f21bcSAndrew Thompson.Fn libusb20_be_set_template "struct libusb20_backend *pbe" "int temp"
179dc8f21bcSAndrew Thompson.Ft int
180dc8f21bcSAndrew Thompson.Fn libusb20_be_get_dev_quirk "struct libusb20_backend *pber", "uint16_t index" "struct libusb20_quirk *pq"
181dc8f21bcSAndrew Thompson.Ft int
182dc8f21bcSAndrew Thompson.Fn libusb20_be_get_quirk_name "struct libusb20_backend *pbe" "uint16_t index" "struct libusb20_quirk *pq"
183dc8f21bcSAndrew Thompson.Ft int
184dc8f21bcSAndrew Thompson.Fn libusb20_be_add_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq"
185dc8f21bcSAndrew Thompson.Ft int
186dc8f21bcSAndrew Thompson.Fn libusb20_be_remove_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq"
187dc8f21bcSAndrew Thompson.Ft struct libusb20_backend *
188545b01adSAndrew Thompson.Fn libusb20_be_alloc_default "void"
189545b01adSAndrew Thompson.Ft struct libusb20_backend *
190545b01adSAndrew Thompson.Fn libusb20_be_alloc_freebsd "void"
191545b01adSAndrew Thompson.Ft struct libusb20_backend *
192dc8f21bcSAndrew Thompson.Fn libusb20_be_alloc_linux "void"
193dc8f21bcSAndrew Thompson.Ft struct libusb20_device *
194dc8f21bcSAndrew Thompson.Fn libusb20_be_device_foreach  "struct libusb20_backend *pbe" "struct libusb20_device *pdev"
195dc8f21bcSAndrew Thompson.Ft void
196dc8f21bcSAndrew Thompson.Fn libusb20_be_dequeue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev"
197dc8f21bcSAndrew Thompson.Ft void
198dc8f21bcSAndrew Thompson.Fn libusb20_be_enqueue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev"
199dc8f21bcSAndrew Thompson.Ft void
200dc8f21bcSAndrew Thompson.Fn libusb20_be_free "struct libusb20_backend *pbe"
201dc8f21bcSAndrew Thompson.Ft uint8_t
202dc8f21bcSAndrew Thompson.Fn libusb20_me_get_1 "const struct libusb20_me_struct *me" "uint16_t off"
203dc8f21bcSAndrew Thompson.Ft uint16_t
204dc8f21bcSAndrew Thompson.Fn libusb20_me_get_2 "const struct libusb20_me_struct *me" "uint16_t off"
205dc8f21bcSAndrew Thompson.Ft uint16_t
206dc8f21bcSAndrew Thompson.Fn libusb20_me_encode "void *pdata" "uint16_t len" "const void *pdecoded"
207dc8f21bcSAndrew Thompson.Ft uint16_t
208dc8f21bcSAndrew Thompson.Fn libusb20_me_decode "const void *pdata" "uint16_t len" "void *pdecoded"
209dc8f21bcSAndrew Thompson.Ft "const uint8_t *"
210dc8f21bcSAndrew Thompson.Fn libusb20_desc_foreach "const struct libusb20_me_struct *me" "const uint8_t *pdesc"
2114eaae44dSAndrew Thompson.
2124eaae44dSAndrew Thompson.
2134eaae44dSAndrew Thompson.Sh DESCRIPTION
2144eaae44dSAndrew Thompson.
2154eaae44dSAndrew ThompsonThe
2164eaae44dSAndrew Thompson.Nm
2174eaae44dSAndrew Thompsonlibrary implements functions to be able to easily access and control
2184eaae44dSAndrew ThompsonUSB through the USB file system interface.
2194eaae44dSAndrew Thompson.
2204eaae44dSAndrew Thompson.
2214eaae44dSAndrew Thompson.Sh USB TRANSFER OPERATIONS
2224eaae44dSAndrew Thompson.
2234eaae44dSAndrew Thompson.Pp
2244eaae44dSAndrew Thompson.
225dc8f21bcSAndrew Thompson.Fn libusb20_tr_close
226dc8f21bcSAndrew Thompsonwill release all kernel resources associated with an USB
227dc8f21bcSAndrew Thompson.Fa xfer .
2284eaae44dSAndrew Thompson.
2294eaae44dSAndrew ThompsonThis function returns zero upon success.
2304eaae44dSAndrew Thompson.
2314eaae44dSAndrew ThompsonNon-zero return values indicate a LIBUSB20_ERROR value.
2324eaae44dSAndrew Thompson.
2334eaae44dSAndrew Thompson.Pp
2344eaae44dSAndrew Thompson.
235dc8f21bcSAndrew Thompson.Fn libusb20_tr_open
236545b01adSAndrew Thompsonwill allocate kernel buffer resources according to
2374eaae44dSAndrew Thompson.Fa max_buf_size
2384eaae44dSAndrew Thompsonand
2394eaae44dSAndrew Thompson.Fa max_frame_count
2404eaae44dSAndrew Thompsonassociated with an USB
2414eaae44dSAndrew Thompson.Fa pxfer
2424eaae44dSAndrew Thompsonand bind the transfer to the specified
2434eaae44dSAndrew Thompson.Fa ep_no .
244545b01adSAndrew Thompson.Fa max_buf_size
245545b01adSAndrew Thompsonis the minimum buffer size which the data transport layer has to support.
246545b01adSAndrew ThompsonIf
247545b01adSAndrew Thompson.Fa max_buf_size
248545b01adSAndrew Thompsonis zero, the
249545b01adSAndrew Thompson.Nm
250545b01adSAndrew Thompsonlibrary will use wMaxPacketSize to compute the buffer size.
251545b01adSAndrew ThompsonThis can be useful for isochronous transfers.
252545b01adSAndrew ThompsonThe actual buffer size can be greater than
253545b01adSAndrew Thompson.Fa max_buf_size
254545b01adSAndrew Thompsonand is returned by
255545b01adSAndrew Thompson.Fn libusb20_tr_get_max_total_length .
2564eaae44dSAndrew Thompson.
2574eaae44dSAndrew ThompsonThis function returns zero upon success.
2584eaae44dSAndrew Thompson.
2594eaae44dSAndrew ThompsonNon-zero return values indicate a LIBUSB20_ERROR value.
2604eaae44dSAndrew Thompson.
2614eaae44dSAndrew Thompson.Pp
2624eaae44dSAndrew Thompson.
263dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_pointer
264dc8f21bcSAndrew Thompsonwill return a pointer to the allocated USB transfer according to the
2654eaae44dSAndrew Thompson.Fa pdev
2664eaae44dSAndrew Thompsonand
2674eaae44dSAndrew Thompson.Fa tr_index
2684eaae44dSAndrew Thompsonarguments.
2694eaae44dSAndrew Thompson.
2704eaae44dSAndrew ThompsonThis function returns NULL in case of failure.
2714eaae44dSAndrew Thompson.
2724eaae44dSAndrew Thompson.Pp
2734eaae44dSAndrew Thompson.
274dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_time_complete
275dc8f21bcSAndrew Thompsonwill return the completion time of an USB transfer in
2764eaae44dSAndrew Thompsonmillisecond units. This function is most useful for isochronous USB
2774eaae44dSAndrew Thompsontransfers when doing echo cancelling.
2784eaae44dSAndrew Thompson.
2794eaae44dSAndrew Thompson.Pp
2804eaae44dSAndrew Thompson.
281dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_actual_frames
282dc8f21bcSAndrew Thompsonwill return the actual number of USB frames after an USB
2834eaae44dSAndrew Thompsontransfer completed. A value of zero means that no data was transferred.
2844eaae44dSAndrew Thompson.
2854eaae44dSAndrew Thompson.Pp
2864eaae44dSAndrew Thompson.
287dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_actual_length
288dc8f21bcSAndrew Thompsonwill return the sum of the actual length for all
2894eaae44dSAndrew Thompsontransferred USB frames for the given USB transfer.
2904eaae44dSAndrew Thompson.
2914eaae44dSAndrew Thompson.Pp
2924eaae44dSAndrew Thompson.
293dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_max_frames
294dc8f21bcSAndrew Thompsonwill return the maximum number of USB frames that were
2954eaae44dSAndrew Thompsonallocated when an USB transfer was setup for the given USB transfer.
2964eaae44dSAndrew Thompson.
2974eaae44dSAndrew Thompson.Pp
2984eaae44dSAndrew Thompson.
299dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_max_packet_length
300dc8f21bcSAndrew Thompsonwill return the maximum packet length in bytes
3014eaae44dSAndrew Thompsonassociated with the given USB transfer.
3024eaae44dSAndrew Thompson.
3034eaae44dSAndrew ThompsonThe packet length can be used round up buffer sizes so that short USB
3044eaae44dSAndrew Thompsonpackets are avoided for proxy buffers.
3054eaae44dSAndrew Thompson.
3064eaae44dSAndrew Thompson.
3074eaae44dSAndrew Thompson.Pp
3084eaae44dSAndrew Thompson.
309dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_max_total_length
310dc8f21bcSAndrew Thompsonfunction will return the maximum value for the length sum of all
3114eaae44dSAndrew ThompsonUSB frames associated with an USB transfer.
3124eaae44dSAndrew Thompson.
3134eaae44dSAndrew Thompson.Pp
3144eaae44dSAndrew Thompson.
315dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_status
316dc8f21bcSAndrew Thompsonwill return the status of an USB transfer.
3174eaae44dSAndrew Thompson.
3184eaae44dSAndrew ThompsonStatus values are defined by a set of LIBUSB20_TRANSFER_XXX enums.
3194eaae44dSAndrew Thompson.
3204eaae44dSAndrew Thompson.Pp
3214eaae44dSAndrew Thompson.
322dc8f21bcSAndrew Thompson.Fn libusb20_tr_pending
323dc8f21bcSAndrew Thompsonwill return non-zero if the given USB transfer is
3244eaae44dSAndrew Thompsonpending for completion.
3254eaae44dSAndrew Thompson.
3264eaae44dSAndrew ThompsonElse this function returns zero.
3274eaae44dSAndrew Thompson.
3284eaae44dSAndrew Thompson.Pp
3294eaae44dSAndrew Thompson.
330dc8f21bcSAndrew Thompson.Fn libusb20_tr_callback_wrapper
3314eaae44dSAndrew ThompsonThis is an internal function used to wrap asynchronous USB callbacks.
3324eaae44dSAndrew Thompson.
3334eaae44dSAndrew Thompson.Pp
3344eaae44dSAndrew Thompson.
335dc8f21bcSAndrew Thompson.Fn libusb20_tr_clear_stall_sync
3364eaae44dSAndrew ThompsonThis is an internal function used to synchronously clear the stall on
3374eaae44dSAndrew Thompsonthe given USB transfer.
3384eaae44dSAndrew Thompson.
3394eaae44dSAndrew ThompsonPlease see the USB specification for more information on stall
3404eaae44dSAndrew Thompsonclearing.
3414eaae44dSAndrew Thompson.
3424eaae44dSAndrew ThompsonIf the given USB transfer is pending when this function is called, the
3434eaae44dSAndrew ThompsonUSB transfer will complete with an error after that this function has
3444eaae44dSAndrew Thompsonbeen called.
3454eaae44dSAndrew Thompson.
3464eaae44dSAndrew Thompson.Pp
3474eaae44dSAndrew Thompson.
348dc8f21bcSAndrew Thompson.Fn libusb20_tr_drain
349dc8f21bcSAndrew Thompsonwill stop the given USB transfer and will not return
3504eaae44dSAndrew Thompsonuntil the USB transfer has been stopped in hardware.
3514eaae44dSAndrew Thompson.
3524eaae44dSAndrew Thompson.Pp
3534eaae44dSAndrew Thompson.
354dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_buffer
355dc8f21bcSAndrew Thompsonis used to set the
3564eaae44dSAndrew Thompson.Fa buffer
3574eaae44dSAndrew Thompsonpointer for the given USB transfer and
3584eaae44dSAndrew Thompson.Fa fr_index .
3594eaae44dSAndrew Thompson.
3604eaae44dSAndrew ThompsonTypically the frame index is zero.
3614eaae44dSAndrew Thompson.
3624eaae44dSAndrew Thompson.
3634eaae44dSAndrew Thompson.Pp
3644eaae44dSAndrew Thompson.
365dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_callback
366dc8f21bcSAndrew Thompsonis used to set the USB callback for asynchronous USB
3674eaae44dSAndrew Thompsontransfers.
3684eaae44dSAndrew Thompson.
3694eaae44dSAndrew ThompsonThe callback type is defined by libusb20_tr_callback_t.
3704eaae44dSAndrew Thompson.
3714eaae44dSAndrew Thompson.Pp
3724eaae44dSAndrew Thompson.
373dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_flags
374dc8f21bcSAndrew Thompsonis used to set various USB flags for the given USB transfer.
3754eaae44dSAndrew Thompson.Bl -tag
3764eaae44dSAndrew Thompson.It LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK
3774eaae44dSAndrew ThompsonReport a short frame as error.
3784eaae44dSAndrew Thompson.It LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK
3794eaae44dSAndrew ThompsonMultiple short frames are not allowed.
3804eaae44dSAndrew Thompson.It LIBUSB20_TRANSFER_FORCE_SHORT
3814eaae44dSAndrew ThompsonAll transmitted frames are short terminated.
3824eaae44dSAndrew Thompson.It LIBUSB20_TRANSFER_DO_CLEAR_STALL
3834eaae44dSAndrew ThompsonWill do a clear-stall before starting the transfer.
3844eaae44dSAndrew Thompson.El
3854eaae44dSAndrew Thompson.
3864eaae44dSAndrew Thompson.Pp
3874eaae44dSAndrew Thompson.
388545b01adSAndrew Thompson.Fn libusb20_tr_get_length
389545b01adSAndrew Thompsonreturns the length of the given USB frame by index.
390545b01adSAndrew ThompsonAfter an USB transfer is complete the USB frame length will get updated to the actual transferred length.
391545b01adSAndrew Thompson.
392545b01adSAndrew Thompson.Pp
393545b01adSAndrew Thompson.
394dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_length
395545b01adSAndrew Thompsonsets the length of the given USB frame by index.
3964eaae44dSAndrew Thompson.
3974eaae44dSAndrew Thompson.Pp
3984eaae44dSAndrew Thompson.
399dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_priv_sc0
400dc8f21bcSAndrew Thompsonsets private driver pointer number zero.
4014eaae44dSAndrew Thompson.
4024eaae44dSAndrew Thompson.Pp
4034eaae44dSAndrew Thompson.
404dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_priv_sc1
405dc8f21bcSAndrew Thompsonsets private driver pointer number one.
4064eaae44dSAndrew Thompson.
4074eaae44dSAndrew Thompson.Pp
4084eaae44dSAndrew Thompson.
409dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_timeout
410dc8f21bcSAndrew Thompsonsets the timeout for the given USB transfer.
4114eaae44dSAndrew Thompson.
4124eaae44dSAndrew ThompsonA timeout value of zero means no timeout.
4134eaae44dSAndrew Thompson.
4144eaae44dSAndrew ThompsonThe timeout is given in milliseconds.
4154eaae44dSAndrew Thompson.
4164eaae44dSAndrew Thompson.Pp
4174eaae44dSAndrew Thompson.
418dc8f21bcSAndrew Thompson.Fn libusb20_tr_set_total_frames
419dc8f21bcSAndrew Thompsonsets the total number of frames that should be executed when the USB transfer is submitted.
4204eaae44dSAndrew Thompson.
4214eaae44dSAndrew ThompsonThe total number of USB frames must be less than the maximum number of USB frames associated with the given USB transfer.
4224eaae44dSAndrew Thompson.
4234eaae44dSAndrew Thompson.Pp
4244eaae44dSAndrew Thompson.
425dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_bulk
426dc8f21bcSAndrew Thompsonis a helper function for setting up a single frame USB BULK transfer.
4274eaae44dSAndrew Thompson.
4284eaae44dSAndrew Thompson.Pp
4294eaae44dSAndrew Thompson.
430dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_control
431dc8f21bcSAndrew Thompsonis a helper function for setting up a single or dual
4324eaae44dSAndrew Thompsonframe USB CONTROL transfer depending on the control transfer length.
4334eaae44dSAndrew Thompson.
4344eaae44dSAndrew Thompson.Pp
4354eaae44dSAndrew Thompson.
436dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_intr
437dc8f21bcSAndrew Thompsonis a helper function for setting up a single frame USB INTERRUPT transfer.
4384eaae44dSAndrew Thompson.
4394eaae44dSAndrew Thompson.Pp
4404eaae44dSAndrew Thompson.
441dc8f21bcSAndrew Thompson.Fn libusb20_tr_setup_isoc
442dc8f21bcSAndrew Thompsonis a helper function for setting up a multi frame USB ISOCHRONOUS transfer.
4434eaae44dSAndrew Thompson.
4444eaae44dSAndrew Thompson.Pp
4454eaae44dSAndrew Thompson.
446dc8f21bcSAndrew Thompson.Fn libusb20_tr_start
447dc8f21bcSAndrew Thompsonwill get the USB transfer started, if not already
4484eaae44dSAndrew Thompsonstarted.
4494eaae44dSAndrew Thompson.
4504eaae44dSAndrew ThompsonThis function will not get the transfer queued in hardware.
4514eaae44dSAndrew Thompson.
4524eaae44dSAndrew ThompsonThis function is non-blocking.
4534eaae44dSAndrew Thompson.
4544eaae44dSAndrew Thompson.Pp
4554eaae44dSAndrew Thompson.
456dc8f21bcSAndrew Thompson.Fn libusb20_tr_stop
457dc8f21bcSAndrew Thompsonwill get the USB transfer stopped, if not already stopped.
4584eaae44dSAndrew Thompson.
4594eaae44dSAndrew ThompsonThis function is non-blocking, which means that the actual stop can
4604eaae44dSAndrew Thompsonhappen after the return of this function.
4614eaae44dSAndrew Thompson.
4624eaae44dSAndrew Thompson.Pp
4634eaae44dSAndrew Thompson.
464dc8f21bcSAndrew Thompson.Fn libusb20_tr_submit
465dc8f21bcSAndrew Thompsonwill get the USB transfer queued in hardware.
4664eaae44dSAndrew Thompson.
4674eaae44dSAndrew Thompson.
4684eaae44dSAndrew Thompson.Pp
4694eaae44dSAndrew Thompson.
470dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_priv_sc0
471dc8f21bcSAndrew Thompsonreturns private driver pointer number zero associated
4724eaae44dSAndrew Thompsonwith an USB transfer.
4734eaae44dSAndrew Thompson.
4744eaae44dSAndrew Thompson.
4754eaae44dSAndrew Thompson.Pp
4764eaae44dSAndrew Thompson.
477dc8f21bcSAndrew Thompson.Fn libusb20_tr_get_priv_sc1
478dc8f21bcSAndrew Thompsonreturns private driver pointer number one associated
4794eaae44dSAndrew Thompsonwith an USB transfer.
4804eaae44dSAndrew Thompson.
4814eaae44dSAndrew Thompson.
4824eaae44dSAndrew Thompson.Sh USB DEVICE OPERATIONS
4834eaae44dSAndrew Thompson.
4844eaae44dSAndrew Thompson.Pp
4854eaae44dSAndrew Thompson.
486dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_backend_name
487dc8f21bcSAndrew Thompsonreturns a zero terminated string describing the backend used.
4884eaae44dSAndrew Thompson.
4894eaae44dSAndrew Thompson.Pp
4904eaae44dSAndrew Thompson.
491dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_info
492760bc48eSAndrew Thompsonretrives the BSD specific usb_device_info structure into the memory location given by
4934eaae44dSAndrew Thompson.Fa pinfo .
4944eaae44dSAndrew ThompsonThe USB device given by
4954eaae44dSAndrew Thompson.Fa pdev
4964eaae44dSAndrew Thompsonmust be opened before this function will succeed.
4974eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is returned.
4984eaae44dSAndrew Thompson.
4994eaae44dSAndrew Thompson.Pp
5004eaae44dSAndrew Thompson.
501dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_iface_desc
502dc8f21bcSAndrew Thompsonretrieves the kernel interface description for the given USB
5034eaae44dSAndrew Thompson.Fa iface_index .
5044eaae44dSAndrew ThompsonThe format of the USB interface description is: "drivername<unit>: <description>"
5054eaae44dSAndrew ThompsonThe description string is always zero terminated.
5064eaae44dSAndrew ThompsonA zero length string is written in case no driver is attached to the given interface.
5074eaae44dSAndrew ThompsonThe USB device given by
5084eaae44dSAndrew Thompson.Fa pdev
5094eaae44dSAndrew Thompsonmust be opened before this function will succeed.
5104eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is returned.
5114eaae44dSAndrew Thompson.
5124eaae44dSAndrew Thompson.Pp
5134eaae44dSAndrew Thompson.
514dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_desc
515dc8f21bcSAndrew Thompsonreturns a zero terminated string describing the given USB device.
5164eaae44dSAndrew ThompsonThe format of the string is: "drivername<unit>: <description>"
5174eaae44dSAndrew Thompson.
5184eaae44dSAndrew Thompson.Pp
5194eaae44dSAndrew Thompson.
520dc8f21bcSAndrew Thompson.Fn libusb20_dev_claim_interface
5214eaae44dSAndrew ThompsonThis function will try to claim the given USB interface given by
5224eaae44dSAndrew Thompson.Fa iface_index .
5234eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
5244eaae44dSAndrew Thompsonreturned.
5254eaae44dSAndrew Thompson.
5264eaae44dSAndrew Thompson.Pp
5274eaae44dSAndrew Thompson.
528dc8f21bcSAndrew Thompson.Fn libusb20_dev_close
529dc8f21bcSAndrew Thompsonwill close the given USB device.
5304eaae44dSAndrew Thompson.
5314eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
5324eaae44dSAndrew Thompsonreturned.
5334eaae44dSAndrew Thompson.
5344eaae44dSAndrew Thompson.Pp
5354eaae44dSAndrew Thompson.
536dc8f21bcSAndrew Thompson.Fn libusb20_dev_detach_kernel_driver
537dc8f21bcSAndrew Thompsonwill try to detach the kernel driver for the USB interface given by
5384eaae44dSAndrew Thompson.Fa iface_index .
5394eaae44dSAndrew Thompson.
5404eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
5414eaae44dSAndrew Thompsonreturned.
5424eaae44dSAndrew Thompson.
5434eaae44dSAndrew Thompson.Pp
5444eaae44dSAndrew Thompson.
545dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_config_index
546dc8f21bcSAndrew Thompsonwill try to set the configuration index on an USB
5474eaae44dSAndrew Thompsondevice.
5484eaae44dSAndrew Thompson.
5494eaae44dSAndrew ThompsonThe first configuration index is zero.
5504eaae44dSAndrew Thompson.
5514eaae44dSAndrew ThompsonThe un-configure index is 255.
5524eaae44dSAndrew Thompson.
5534eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is returned.
5544eaae44dSAndrew Thompson.
5554eaae44dSAndrew Thompson.Pp
5564eaae44dSAndrew Thompson.
557dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_debug
558dc8f21bcSAndrew Thompsonreturns the debug level of an USB device.
5594eaae44dSAndrew Thompson.
5604eaae44dSAndrew Thompson.Pp
5614eaae44dSAndrew Thompson.
562dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_fd
563dc8f21bcSAndrew Thompsonreturns the file descriptor of the given USB device.
5644eaae44dSAndrew Thompson.
5654eaae44dSAndrew ThompsonA negative value is returned when no file descriptor is present.
5664eaae44dSAndrew Thompson.
5674eaae44dSAndrew ThompsonThe file descriptor can be used for polling purposes.
5684eaae44dSAndrew Thompson.
5694eaae44dSAndrew Thompson.Pp
5704eaae44dSAndrew Thompson.
571dc8f21bcSAndrew Thompson.Fn libusb20_dev_kernel_driver_active
572dc8f21bcSAndrew Thompsonreturns a non-zero value if a kernel driver is active on
5734eaae44dSAndrew Thompsonthe given USB interface.
5744eaae44dSAndrew Thompson.
5754eaae44dSAndrew ThompsonElse zero is returned.
5764eaae44dSAndrew Thompson.
5774eaae44dSAndrew Thompson.Pp
5784eaae44dSAndrew Thompson.
579dc8f21bcSAndrew Thompson.Fn libusb20_dev_open
580dc8f21bcSAndrew Thompsonopens an USB device so that setting up USB transfers
5814eaae44dSAndrew Thompsonbecomes possible.
5824eaae44dSAndrew Thompson.
5834eaae44dSAndrew ThompsonThe number of USB transfers can be zero which means only control
5844eaae44dSAndrew Thompsontransfers are allowed.
5854eaae44dSAndrew Thompson.
5864eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
5874eaae44dSAndrew Thompsonreturned.
5884eaae44dSAndrew Thompson.
5894eaae44dSAndrew ThompsonA return value of LIBUSB20_ERROR_BUSY means that the device is already
5904eaae44dSAndrew Thompsonopened.
5914eaae44dSAndrew Thompson.
5924eaae44dSAndrew Thompson.Pp
5934eaae44dSAndrew Thompson.
594dc8f21bcSAndrew Thompson.Fn libusb20_dev_process
595dc8f21bcSAndrew Thompsonis called to sync kernel USB transfers with userland USB
5964eaae44dSAndrew Thompsontransfers.
5974eaae44dSAndrew Thompson.
5984eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
5994eaae44dSAndrew Thompsonreturned typically indicating that the given USB device has been
6004eaae44dSAndrew Thompsondetached.
6014eaae44dSAndrew Thompson.
6024eaae44dSAndrew Thompson.Pp
6034eaae44dSAndrew Thompson.
604dc8f21bcSAndrew Thompson.Fn libusb20_dev_release_interface
605dc8f21bcSAndrew Thompsonwill try to release a claimed USB interface for the specified USB device.
6064eaae44dSAndrew Thompson.
6074eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
6084eaae44dSAndrew Thompsonreturned.
6094eaae44dSAndrew Thompson.
6104eaae44dSAndrew Thompson.Pp
6114eaae44dSAndrew Thompson.
612dc8f21bcSAndrew Thompson.Fn libusb20_dev_request_sync
613dc8f21bcSAndrew Thompsonwill perform a synchronous control request on the given
6144eaae44dSAndrew ThompsonUSB device.
6154eaae44dSAndrew Thompson.
6164eaae44dSAndrew ThompsonBefore this call will succeed the USB device must be opened.
6174eaae44dSAndrew Thompson.
6184eaae44dSAndrew Thompson.Fa setup
6194eaae44dSAndrew Thompsonis a pointer to a decoded and host endian SETUP packet.
6204eaae44dSAndrew Thompson.Fa data
6214eaae44dSAndrew Thompsonis a pointer to a data transfer buffer associated with the control transaction. This argument can be NULL.
6224eaae44dSAndrew Thompson.Fa pactlen
6234eaae44dSAndrew Thompsonis a pointer to a variable that will hold the actual transfer length after the control transaction is complete.
6244eaae44dSAndrew Thompson.Fa timeout
6254eaae44dSAndrew Thompsonis the transaction timeout given in milliseconds.
6264eaae44dSAndrew ThompsonA timeout of zero means no timeout.
6274eaae44dSAndrew Thompson.Fa flags
6284eaae44dSAndrew Thompsonis used to specify transaction flags, for example LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK.
6294eaae44dSAndrew Thompson.
6304eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
6314eaae44dSAndrew Thompsonreturned.
6324eaae44dSAndrew Thompson.
6334eaae44dSAndrew Thompson.Pp
6344eaae44dSAndrew Thompson.
635dc8f21bcSAndrew Thompson.Fn libusb20_dev_req_string_sync
636dc8f21bcSAndrew Thompsonwill synchronously request an USB string by language ID
6374eaae44dSAndrew Thompsonand string index into the given buffer limited by a maximum length.
6384eaae44dSAndrew Thompson.
6394eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
6404eaae44dSAndrew Thompsonreturned.
6414eaae44dSAndrew Thompson.
6424eaae44dSAndrew Thompson.Pp
6434eaae44dSAndrew Thompson.
644dc8f21bcSAndrew Thompson.Fn libusb20_dev_req_string_simple_sync
645dc8f21bcSAndrew Thompsonwill synchronously request an USB string using the
6464eaae44dSAndrew Thompsondefault language ID and convert the string into ASCII before storing
6474eaae44dSAndrew Thompsonthe string into the given buffer limited by a maximum length which
6484eaae44dSAndrew Thompsonincludes the terminating zero.
6494eaae44dSAndrew Thompson.
6504eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
6514eaae44dSAndrew Thompsonreturned.
6524eaae44dSAndrew Thompson.
6534eaae44dSAndrew Thompson.
6544eaae44dSAndrew Thompson.Pp
6554eaae44dSAndrew Thompson.
656dc8f21bcSAndrew Thompson.Fn libusb20_dev_reset
657dc8f21bcSAndrew Thompsonwill try to BUS reset the given USB device and restore
6584eaae44dSAndrew Thompsonthe last set USB configuration.
6594eaae44dSAndrew Thompson.
6604eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
6614eaae44dSAndrew Thompsonreturned.
6624eaae44dSAndrew Thompson.
6634eaae44dSAndrew Thompson.Pp
6644eaae44dSAndrew Thompson.
665dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_power_mode
666dc8f21bcSAndrew Thompsonsets the power mode of the USB device.
6674eaae44dSAndrew Thompson.
6684eaae44dSAndrew ThompsonValid power modes:
6694eaae44dSAndrew Thompson.Bl -tag
6704eaae44dSAndrew Thompson.It LIBUSB20_POWER_OFF
6714eaae44dSAndrew Thompson.It LIBUSB20_POWER_ON
6724eaae44dSAndrew Thompson.It LIBUSB20_POWER_SAVE
6734eaae44dSAndrew Thompson.It LIBUSB20_POWER_SUSPEND
6744eaae44dSAndrew Thompson.It LIBUSB20_POWER_RESUME
6754eaae44dSAndrew Thompson.El
6764eaae44dSAndrew Thompson.
6774eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
6784eaae44dSAndrew Thompsonreturned.
6794eaae44dSAndrew Thompson.
6804eaae44dSAndrew Thompson.Pp
6814eaae44dSAndrew Thompson.
682dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_power_mode
683dc8f21bcSAndrew Thompsonreturns the currently selected power mode for the given
6844eaae44dSAndrew ThompsonUSB device.
6854eaae44dSAndrew Thompson.
6864eaae44dSAndrew Thompson.Pp
6874eaae44dSAndrew Thompson.
688dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_alt_index
689dc8f21bcSAndrew Thompsonwill try to set the given alternate index for the given
6904eaae44dSAndrew ThompsonUSB interface index.
6914eaae44dSAndrew Thompson.
6924eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
6934eaae44dSAndrew Thompsonreturned.
6944eaae44dSAndrew Thompson.
6954eaae44dSAndrew Thompson.Pp
6964eaae44dSAndrew Thompson.
697dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_device_desc
698dc8f21bcSAndrew Thompsonreturns a pointer to the decoded and host endian version
6994eaae44dSAndrew Thompsonof the device descriptor.
7004eaae44dSAndrew Thompson.
7014eaae44dSAndrew ThompsonThe USB device need not be opened when calling this function.
7024eaae44dSAndrew Thompson.
7034eaae44dSAndrew Thompson.Pp
7044eaae44dSAndrew Thompson.
705dc8f21bcSAndrew Thompson.Fn libusb20_dev_alloc_config
706dc8f21bcSAndrew Thompsonwill read out and decode the USB config descriptor for
7074eaae44dSAndrew Thompsonthe given USB device and config index. This function returns a pointer
7084eaae44dSAndrew Thompsonto the decoded configuration which must eventually be passed to
7094eaae44dSAndrew Thompsonfree(). NULL is returned in case of failure.
7104eaae44dSAndrew Thompson.
7114eaae44dSAndrew Thompson.Pp
7124eaae44dSAndrew Thompson.
713dc8f21bcSAndrew Thompson.Fn libusb20_dev_alloc
714dc8f21bcSAndrew Thompsonis an internal function to allocate a new USB device.
7154eaae44dSAndrew Thompson.
7164eaae44dSAndrew Thompson.Pp
7174eaae44dSAndrew Thompson.
718dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_address
719dc8f21bcSAndrew Thompsonreturns the internal and not necessarily the real
7204eaae44dSAndrew Thompsonhardware address of the given USB device.
7214eaae44dSAndrew Thompson.
7224eaae44dSAndrew Thompson.Pp
7234eaae44dSAndrew Thompson.
724dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_bus_number
725dc8f21bcSAndrew Thompsonreturns the internal bus number which the given USB
7264eaae44dSAndrew Thompsondevice belongs to.
7274eaae44dSAndrew Thompson.
7284eaae44dSAndrew Thompson.Pp
7294eaae44dSAndrew Thompson.
730dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_mode
731dc8f21bcSAndrew Thompsonreturns the current operation mode of the USB entity.
7324eaae44dSAndrew Thompson.
7334eaae44dSAndrew ThompsonValid return values are:
7344eaae44dSAndrew Thompson.Bl -tag
7354eaae44dSAndrew Thompson.It LIBUSB20_MODE_HOST
7364eaae44dSAndrew Thompson.It LIBUSB20_MODE_DEVICE
7374eaae44dSAndrew Thompson.El
7384eaae44dSAndrew Thompson.
7394eaae44dSAndrew Thompson.Pp
7404eaae44dSAndrew Thompson.
741dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_speed
742dc8f21bcSAndrew Thompsonreturns the current speed of the given USB device.
7434eaae44dSAndrew Thompson.
7444eaae44dSAndrew Thompson.Bl -tag
7454eaae44dSAndrew Thompson.It LIBUSB20_SPEED_UNKNOWN
7464eaae44dSAndrew Thompson.It LIBUSB20_SPEED_LOW
7474eaae44dSAndrew Thompson.It LIBUSB20_SPEED_FULL
7484eaae44dSAndrew Thompson.It LIBUSB20_SPEED_HIGH
7494eaae44dSAndrew Thompson.It LIBUSB20_SPEED_VARIABLE
7504eaae44dSAndrew Thompson.It LIBUSB20_SPEED_SUPER
7514eaae44dSAndrew Thompson.El
7524eaae44dSAndrew Thompson.
7534eaae44dSAndrew Thompson.Pp
7544eaae44dSAndrew Thompson.
755dc8f21bcSAndrew Thompson.Fn libusb20_dev_get_config_index
7564eaae44dSAndrew ThompsonThis function returns the currently select config index for the given
7574eaae44dSAndrew ThompsonUSB device.
7584eaae44dSAndrew Thompson.
7594eaae44dSAndrew Thompson.Pp
7604eaae44dSAndrew Thompson.
761dc8f21bcSAndrew Thompson.Fn libusb20_dev_free
762dc8f21bcSAndrew Thompsonwill free the given USB device and all associated USB
7634eaae44dSAndrew Thompsontransfers.
7644eaae44dSAndrew Thompson.
7654eaae44dSAndrew Thompson.Pp
7664eaae44dSAndrew Thompson.
767dc8f21bcSAndrew Thompson.Fn libusb20_dev_set_debug
768dc8f21bcSAndrew Thompsonwill set the debug level for the given USB device.
7694eaae44dSAndrew Thompson.
7704eaae44dSAndrew Thompson.Pp
7714eaae44dSAndrew Thompson.
772dc8f21bcSAndrew Thompson.Fn libusb20_dev_wait_process
773dc8f21bcSAndrew Thompsonfunction will wait until a pending USB transfer has completed on
7744eaae44dSAndrew Thompsonthe given USB device.
7754eaae44dSAndrew Thompson.
7764eaae44dSAndrew ThompsonA timeout value can be specified which is passed on to the
777545b01adSAndrew Thompson.Xr poll 2
7784eaae44dSAndrew Thompsonfunction.
7794eaae44dSAndrew Thompson.
7804eaae44dSAndrew Thompson.Sh USB BACKEND OPERATIONS
7814eaae44dSAndrew Thompson.
782dc8f21bcSAndrew Thompson.Fn libusb20_be_get_template
783dc8f21bcSAndrew Thompsonwill return the currently selected global USB device
7844eaae44dSAndrew Thompsonside mode template into the integer pointer
7854eaae44dSAndrew Thompson.Fa ptemp .
7864eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
7874eaae44dSAndrew Thompsonreturned.
7884eaae44dSAndrew Thompson.
7894eaae44dSAndrew Thompson.Pp
7904eaae44dSAndrew Thompson.
791dc8f21bcSAndrew Thompson.Fn libusb20_be_set_template
792dc8f21bcSAndrew Thompsonwill set the global USB device side mode template to
7934eaae44dSAndrew Thompson.Fa temp .
7944eaae44dSAndrew ThompsonThe new template is not activated until after the next USB
7954eaae44dSAndrew Thompsonenumeration.
7964eaae44dSAndrew ThompsonThe template number decides how the USB device will present itself to
7974eaae44dSAndrew Thompsonthe USB Host, like Mass Storage Device, USB Ethernet Device. Also see
7984eaae44dSAndrew Thompsonthe
7994eaae44dSAndrew Thompson.Xr usb2_template 4
8004eaae44dSAndrew Thompsonmodule.
8014eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
8024eaae44dSAndrew Thompsonreturned.
8034eaae44dSAndrew Thompson.
8044eaae44dSAndrew Thompson.Pp
8054eaae44dSAndrew Thompson.
806dc8f21bcSAndrew Thompson.Fn libusb20_be_get_dev_quirk
8074eaae44dSAndrew ThompsonThis function will return the device quirk according to
8084eaae44dSAndrew Thompson.Fa index
8094eaae44dSAndrew Thompsoninto the libusb20_quirk structure pointed to by
8104eaae44dSAndrew Thompson.Fa pq .
8114eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
8124eaae44dSAndrew Thompsonreturned.
8134eaae44dSAndrew Thompson.
8144eaae44dSAndrew ThompsonIf the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is
8154eaae44dSAndrew Thompsonreturned.
8164eaae44dSAndrew Thompson.
8174eaae44dSAndrew Thompson.Pp
8184eaae44dSAndrew Thompson.
819dc8f21bcSAndrew Thompson.Fn libusb20_be_get_quirk_name
820dc8f21bcSAndrew Thompsonwill return the quirk name according to
8214eaae44dSAndrew Thompson.Fa index
8224eaae44dSAndrew Thompsoninto the libusb20_quirk structure pointed to by
8234eaae44dSAndrew Thompson.Fa pq .
8244eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
8254eaae44dSAndrew Thompsonreturned.
8264eaae44dSAndrew Thompson.
8274eaae44dSAndrew ThompsonIf the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is
8284eaae44dSAndrew Thompsonreturned.
8294eaae44dSAndrew Thompson.
8304eaae44dSAndrew Thompson.Pp
8314eaae44dSAndrew Thompson.
832dc8f21bcSAndrew Thompson.Fn libusb20_be_add_dev_quirk
833dc8f21bcSAndrew Thompsonwill add the libusb20_quirk structure pointed to by the
8344eaae44dSAndrew Thompson.Fa pq
8354eaae44dSAndrew Thompsonargument into the device quirk list.
8364eaae44dSAndrew Thompson.
8374eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
8384eaae44dSAndrew Thompsonreturned.
8394eaae44dSAndrew Thompson.
8404eaae44dSAndrew ThompsonIf the given quirk cannot be added LIBUSB20_ERROR_NO_MEM is
8414eaae44dSAndrew Thompsonreturned.
8424eaae44dSAndrew Thompson.
8434eaae44dSAndrew Thompson.Pp
8444eaae44dSAndrew Thompson.
845dc8f21bcSAndrew Thompson.Fn libusb20_be_remove_dev_quirk
846dc8f21bcSAndrew Thompsonwill remove the quirk matching the libusb20_quirk structure pointed to by the
8474eaae44dSAndrew Thompson.Fa pq
8484eaae44dSAndrew Thompsonargument from the device quirk list.
8494eaae44dSAndrew Thompson.
8504eaae44dSAndrew ThompsonThis function returns zero on success else a LIBUSB20_ERROR value is
8514eaae44dSAndrew Thompsonreturned.
8524eaae44dSAndrew Thompson.
8534eaae44dSAndrew ThompsonIf the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is
8544eaae44dSAndrew Thompsonreturned.
8554eaae44dSAndrew Thompson.
856545b01adSAndrew Thompson.Pp
857545b01adSAndrew Thompson.
858545b01adSAndrew Thompson.Fn libusb20_be_alloc_default
859545b01adSAndrew Thompson.Fn libusb20_be_alloc_freebsd
860dc8f21bcSAndrew Thompson.Fn libusb20_be_alloc_linux
8614eaae44dSAndrew ThompsonThese functions are used to allocate a specific USB backend or the
8624eaae44dSAndrew Thompsonoperating system default USB backend. Allocating a backend is a way to
8634eaae44dSAndrew Thompsonscan for currently present USB devices.
8644eaae44dSAndrew Thompson.
8654eaae44dSAndrew Thompson.Pp
8664eaae44dSAndrew Thompson.
867dc8f21bcSAndrew Thompson.Fn libusb20_be_device_foreach
868dc8f21bcSAndrew Thompsonis used to iterate USB devices present in a USB backend.
8694eaae44dSAndrew Thompson.
8704eaae44dSAndrew ThompsonThe starting value of
8714eaae44dSAndrew Thompson.Fa pdev
8724eaae44dSAndrew Thompsonis NULL.
8734eaae44dSAndrew Thompson.
8744eaae44dSAndrew ThompsonThis function returns the next USB device in the list.
8754eaae44dSAndrew Thompson.
8764eaae44dSAndrew ThompsonIf NULL is returned the end of the USB device list has been reached.
8774eaae44dSAndrew Thompson.
8784eaae44dSAndrew Thompson.Pp
8794eaae44dSAndrew Thompson.
880dc8f21bcSAndrew Thompson.Fn libusb20_be_dequeue_device
881dc8f21bcSAndrew Thompsonwill dequeue the given USB device pointer from the
8824eaae44dSAndrew Thompsonbackend USB device list.
8834eaae44dSAndrew Thompson.
8844eaae44dSAndrew ThompsonDequeued USB devices will not be freed when the backend is freed.
8854eaae44dSAndrew Thompson.
8864eaae44dSAndrew Thompson.Pp
8874eaae44dSAndrew Thompson.
888dc8f21bcSAndrew Thompson.Fn libusb20_be_enqueue_device
8894eaae44dSAndrew ThompsonThis function will enqueue the given USB device pointer in the backend USB device list.
8904eaae44dSAndrew Thompson.
8914eaae44dSAndrew ThompsonEnqueued USB devices will get freed when the backend is freed.
8924eaae44dSAndrew Thompson.
8934eaae44dSAndrew Thompson.Pp
8944eaae44dSAndrew Thompson.
895dc8f21bcSAndrew Thompson.Fn libusb20_be_free
896dc8f21bcSAndrew Thompsonwill free the given backend and all USB devices in its device list.
8974eaae44dSAndrew Thompson.
8984eaae44dSAndrew Thompson.
8994eaae44dSAndrew Thompson.Sh USB DESCRIPTOR PARSING
9004eaae44dSAndrew Thompson.
9014eaae44dSAndrew Thompson.Fn libusb20_me_get_1 pie offset
9024eaae44dSAndrew ThompsonThis function will return a byte at the given byte offset of a message
9034eaae44dSAndrew Thompsonentity.
9044eaae44dSAndrew Thompson.
9054eaae44dSAndrew ThompsonThis function is safe against invalid offsets.
9064eaae44dSAndrew Thompson.
9074eaae44dSAndrew Thompson.Pp
9084eaae44dSAndrew Thompson.
9094eaae44dSAndrew Thompson.Fn libusb20_me_get_2 pie offset
9104eaae44dSAndrew ThompsonThis function will return a little endian 16-bit value at the given byte offset of a message
9114eaae44dSAndrew Thompsonentity.
9124eaae44dSAndrew Thompson.
9134eaae44dSAndrew ThompsonThis function is safe against invalid offsets.
9144eaae44dSAndrew Thompson.
9154eaae44dSAndrew Thompson.Pp
9164eaae44dSAndrew Thompson.
9174eaae44dSAndrew Thompson.Fn libusb20_me_encode pbuf len pdecoded
9184eaae44dSAndrew ThompsonThis function will encode a so-called *DECODED structure into binary
9194eaae44dSAndrew Thompsonformat.
9204eaae44dSAndrew Thompson.
9214eaae44dSAndrew ThompsonThe total encoded length that will fit in the given buffer is
9224eaae44dSAndrew Thompsonreturned.
9234eaae44dSAndrew Thompson.
9244eaae44dSAndrew ThompsonIf the buffer pointer is NULL no data will be written to the buffer
9254eaae44dSAndrew Thompsonlocation.
9264eaae44dSAndrew Thompson.
9274eaae44dSAndrew Thompson.Pp
9284eaae44dSAndrew Thompson.
9294eaae44dSAndrew Thompson.Fn libusb20_me_decode pbuf len pdecoded
9304eaae44dSAndrew ThompsonThis function will decode a binary structure into a so-called *DECODED
9314eaae44dSAndrew Thompsonstructure.
9324eaae44dSAndrew Thompson.
9334eaae44dSAndrew ThompsonThe total decoded length is returned.
9344eaae44dSAndrew Thompson.
9354eaae44dSAndrew ThompsonThe buffer pointer cannot be NULL.
9364eaae44dSAndrew Thompson.
9374eaae44dSAndrew Thompson.
9384eaae44dSAndrew Thompson.Sh LIBUSB VERSION 0.1 COMPATIBILITY
9394eaae44dSAndrew Thompson.
9404eaae44dSAndrew Thompson.Fn usb_open
9414eaae44dSAndrew Thompson.Fn usb_close
9424eaae44dSAndrew Thompson.Fn usb_get_string
9434eaae44dSAndrew Thompson.Fn usb_get_string_simple
9444eaae44dSAndrew Thompson.Fn usb_get_descriptor_by_endpoint
9454eaae44dSAndrew Thompson.Fn usb_get_descriptor
9464eaae44dSAndrew Thompson.Fn usb_parse_descriptor
9474eaae44dSAndrew Thompson.Fn usb_parse_configuration
9484eaae44dSAndrew Thompson.Fn usb_destroy_configuration
9494eaae44dSAndrew Thompson.Fn usb_fetch_and_parse_descriptors
9504eaae44dSAndrew Thompson.Fn usb_bulk_write
9514eaae44dSAndrew Thompson.Fn usb_bulk_read
9524eaae44dSAndrew Thompson.Fn usb_interrupt_write
9534eaae44dSAndrew Thompson.Fn usb_interrupt_read
9544eaae44dSAndrew Thompson.Fn usb_control_msg
9554eaae44dSAndrew Thompson.Fn usb_set_configuration
9564eaae44dSAndrew Thompson.Fn usb_claim_interface
9574eaae44dSAndrew Thompson.Fn usb_release_interface
9584eaae44dSAndrew Thompson.Fn usb_set_altinterface
9594eaae44dSAndrew Thompson.Fn usb_resetep
9604eaae44dSAndrew Thompson.Fn usb_clear_halt
9614eaae44dSAndrew Thompson.Fn usb_reset
9624eaae44dSAndrew Thompson.Fn usb_strerror
9634eaae44dSAndrew Thompson.Fn usb_init
9644eaae44dSAndrew Thompson.Fn usb_set_debug
9654eaae44dSAndrew Thompson.Fn usb_find_busses
9664eaae44dSAndrew Thompson.Fn usb_find_devices
9674eaae44dSAndrew Thompson.Fn usb_device
9684eaae44dSAndrew Thompson.Fn usb_get_busses
9694eaae44dSAndrew ThompsonThese functions are compliant with LibUSB version 0.1.12.
9704eaae44dSAndrew Thompson.
9714eaae44dSAndrew Thompson.Sh FILES
9724eaae44dSAndrew Thompson.
9734eaae44dSAndrew Thompson.
9744eaae44dSAndrew Thompson/dev/usb
9754eaae44dSAndrew Thompson.Sh SEE ALSO
976c54c1f7cSAndrew Thompson.Xr usb 4 ,
9774eaae44dSAndrew Thompson.Xr usbconfig 8
9784eaae44dSAndrew Thompson.
9794eaae44dSAndrew Thompson.
9804eaae44dSAndrew Thompson.Sh HISTORY
9814eaae44dSAndrew Thompson.
9824eaae44dSAndrew Thompson.
9834eaae44dSAndrew ThompsonSome parts of the
9844eaae44dSAndrew Thompson.Nm
9854eaae44dSAndrew ThompsonAPI derives from the libusb project at sourceforge.
986