1 |
.\" $MidnightBSD$ |
2 |
.\" |
3 |
.\" Copyright (c) 2008 Hans Petter Selasky |
4 |
.\" |
5 |
.\" All rights reserved. |
6 |
.\" |
7 |
.\" Redistribution and use in source and binary forms, with or without |
8 |
.\" modification, are permitted provided that the following conditions |
9 |
.\" are met: |
10 |
.\" 1. Redistributions of source code must retain the above copyright |
11 |
.\" notice, this list of conditions and the following disclaimer. |
12 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
13 |
.\" notice, this list of conditions and the following disclaimer in the |
14 |
.\" documentation and/or other materials provided with the distribution. |
15 |
.\" |
16 |
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
17 |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
18 |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
19 |
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
20 |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
21 |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
22 |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
23 |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
24 |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
25 |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
26 |
.\" SUCH DAMAGE. |
27 |
.\" |
28 |
.\" $FreeBSD: stable/10/lib/libusb/libusb20.3 250582 2013-05-12 22:22:12Z joel $ |
29 |
.\" |
30 |
.Dd May 3, 2013 |
31 |
.Dt LIBUSB20 3 |
32 |
.Os |
33 |
.Sh NAME |
34 |
.Nm libusb20 |
35 |
. |
36 |
.Nd "USB access library" |
37 |
. |
38 |
. |
39 |
.Sh LIBRARY |
40 |
. |
41 |
. |
42 |
USB access library (libusb -lusb) |
43 |
. |
44 |
. |
45 |
. |
46 |
.Sh SYNOPSIS |
47 |
.In libusb20.h |
48 |
.Ft int |
49 |
.Fn libusb20_tr_close "struct libusb20_transfer *xfer" |
50 |
.Ft int |
51 |
.Fn libusb20_tr_open "struct libusb20_transfer *xfer" "uint32_t max_buf_size" "uint32_t max_frame_count" "uint8_t ep_no" |
52 |
.Fn libusb20_tr_open_stream "struct libusb20_transfer *xfer" "uint32_t max_buf_size" "uint32_t max_frame_count" "uint8_t ep_no" "uint16_t stream_id" |
53 |
.Ft struct libusb20_transfer* |
54 |
.Fn libusb20_tr_get_pointer "struct libusb20_device *pdev" "uint16_t tr_index" |
55 |
.Ft uint16_t |
56 |
.Fn libusb20_tr_get_time_complete "struct libusb20_transfer *xfer" |
57 |
.Ft uint32_t |
58 |
.Fn libusb20_tr_get_actual_frames "struct libusb20_transfer *xfer" |
59 |
.Ft uint32_t |
60 |
.Fn libusb20_tr_get_actual_length "struct libusb20_transfer *xfer" |
61 |
.Ft uint32_t |
62 |
.Fn libusb20_tr_get_max_frames "struct libusb20_transfer *xfer" |
63 |
.Ft uint32_t |
64 |
.Fn libusb20_tr_get_max_packet_length "struct libusb20_transfer *xfer" |
65 |
.Ft uint32_t |
66 |
.Fn libusb20_tr_get_max_total_length "struct libusb20_transfer *xfer" |
67 |
.Ft uint8_t |
68 |
.Fn libusb20_tr_get_status "struct libusb20_transfer *xfer" |
69 |
.Ft uint8_t |
70 |
.Fn libusb20_tr_pending "struct libusb20_transfer *xfer" |
71 |
.Ft void |
72 |
.Fn libusb20_tr_callback_wrapper "struct libusb20_transfer *xfer" |
73 |
.Ft void |
74 |
.Fn libusb20_tr_clear_stall_sync "struct libusb20_transfer *xfer" |
75 |
.Ft void |
76 |
.Fn libusb20_tr_drain "struct libusb20_transfer *xfer" |
77 |
.Ft void |
78 |
.Fn libusb20_tr_set_buffer "struct libusb20_transfer *xfer" "void *buffer" "uint16_t fr_index" |
79 |
.Ft void |
80 |
.Fn libusb20_tr_set_callback "struct libusb20_transfer *xfer" "libusb20_tr_callback_t *cb" |
81 |
.Ft void |
82 |
.Fn libusb20_tr_set_flags "struct libusb20_transfer *xfer" "uint8_t flags" |
83 |
.Ft uint32_t |
84 |
.Fn libusb20_tr_get_length "struct libusb20_transfer *xfer" "uint16_t fr_index" |
85 |
.Ft void |
86 |
.Fn libusb20_tr_set_length "struct libusb20_transfer *xfer" "uint32_t length" "uint16_t fr_index" |
87 |
.Ft void |
88 |
.Fn libusb20_tr_set_priv_sc0 "struct libusb20_transfer *xfer" "void *sc0" |
89 |
.Ft void |
90 |
.Fn libusb20_tr_set_priv_sc1 "struct libusb20_transfer *xfer" "void *sc1" |
91 |
.Ft void |
92 |
.Fn libusb20_tr_set_timeout "struct libusb20_transfer *xfer" "uint32_t timeout" |
93 |
.Ft void |
94 |
.Fn libusb20_tr_set_total_frames "struct libusb20_transfer *xfer" "uint32_t nframes" |
95 |
.Ft void |
96 |
.Fn libusb20_tr_setup_bulk "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout" |
97 |
.Ft void |
98 |
.Fn libusb20_tr_setup_control "struct libusb20_transfer *xfer" "void *psetup" "void *pbuf" "uint32_t timeout" |
99 |
.Ft void |
100 |
.Fn libusb20_tr_setup_intr "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout" |
101 |
.Ft void |
102 |
.Fn libusb20_tr_setup_isoc "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint61_t fr_index" |
103 |
.Ft uint8_t |
104 |
.Fn libusb20_tr_bulk_intr_sync "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t *pactlen" "uint32_t timeout" |
105 |
.Ft void |
106 |
.Fn libusb20_tr_start "struct libusb20_transfer *xfer" |
107 |
.Ft void |
108 |
.Fn libusb20_tr_stop "struct libusb20_transfer *xfer" |
109 |
.Ft void |
110 |
.Fn libusb20_tr_submit "struct libusb20_transfer *xfer" |
111 |
.Ft void * |
112 |
.Fn libusb20_tr_get_priv_sc0 "struct libusb20_transfer *xfer" |
113 |
.Ft void * |
114 |
.Fn libusb20_tr_get_priv_sc1 "struct libusb20_transfer *xfer" |
115 |
.Ft const char * |
116 |
.Fn libusb20_dev_get_backend_name "struct libusb20_device *" |
117 |
.Ft int |
118 |
.Fn libusb20_dev_get_port_path "struct libusb20_device *pdev" "uint8_t *buf" "uint8_t bufsize" |
119 |
.Ft int |
120 |
.Fn libusb20_dev_get_info "struct libusb20_device *pdev" "struct usb_device_info *pinfo" |
121 |
.Ft int |
122 |
.Fn libusb20_dev_get_iface_desc "struct libusb20_device *pdev" "uint8_t iface_index" "char *buf" "uint8_t len" |
123 |
.Ft const char * |
124 |
.Fn libusb20_dev_get_desc "struct libusb20_device *pdev" |
125 |
.Ft int |
126 |
.Fn libusb20_dev_close "struct libusb20_device *pdev" |
127 |
.Ft int |
128 |
.Fn libusb20_dev_detach_kernel_driver "struct libusb20_device *pdev" "uint8_t iface_index" |
129 |
.Ft int |
130 |
.Fn libusb20_dev_set_config_index "struct libusb20_device *pdev" "uint8_t configIndex" |
131 |
.Ft int |
132 |
.Fn libusb20_dev_get_debug "struct libusb20_device *pdev" |
133 |
.Ft int |
134 |
.Fn libusb20_dev_get_fd "struct libusb20_device *pdev" |
135 |
.Ft int |
136 |
.Fn libusb20_dev_kernel_driver_active "struct libusb20_device *pdev" "uint8_t iface_index" |
137 |
.Ft int |
138 |
.Fn libusb20_dev_open "struct libusb20_device *pdev" "uint16_t transfer_max" |
139 |
.Ft int |
140 |
.Fn libusb20_dev_process "struct libusb20_device *pdev" |
141 |
.Ft int |
142 |
.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" |
143 |
.Ft int |
144 |
.Fn libusb20_dev_req_string_sync "struct libusb20_device *pdev" "uint8_t index" "uint16_t langid" "void *ptr" "uint16_t len" |
145 |
.Ft int |
146 |
.Fn libusb20_dev_req_string_simple_sync "struct libusb20_device *pdev" "uint8_t index" "void *ptr" "uint16_t len" |
147 |
.Ft int |
148 |
.Fn libusb20_dev_reset "struct libusb20_device *pdev" |
149 |
.Ft int |
150 |
.Fn libusb20_dev_check_connected "struct libusb20_device *pdev" |
151 |
.Ft int |
152 |
.Fn libusb20_dev_set_power_mode "struct libusb20_device *pdev" "uint8_t power_mode" |
153 |
.Ft uint8_t |
154 |
.Fn libusb20_dev_get_power_mode "struct libusb20_device *pdev" |
155 |
.Ft uint16_t |
156 |
.Fn libusb20_dev_get_power_usage "struct libusb20_device *pdev" |
157 |
.Ft int |
158 |
.Fn libusb20_dev_set_alt_index "struct libusb20_device *pdev" "uint8_t iface_index" "uint8_t alt_index" |
159 |
.Ft struct LIBUSB20_DEVICE_DESC_DECODED * |
160 |
.Fn libusb20_dev_get_device_desc "struct libusb20_device *pdev" |
161 |
.Ft struct libusb20_config * |
162 |
.Fn libusb20_dev_alloc_config "struct libusb20_device *pdev" "uint8_t config_index" |
163 |
.Ft struct libusb20_device * |
164 |
.Fn libusb20_dev_alloc "void" |
165 |
.Ft uint8_t |
166 |
.Fn libusb20_dev_get_address "struct libusb20_device *pdev" |
167 |
.Ft uint8_t |
168 |
.Fn libusb20_dev_get_parent_address "struct libusb20_device *pdev" |
169 |
.Ft uint8_t |
170 |
.Fn libusb20_dev_get_parent_port "struct libusb20_device *pdev" |
171 |
.Ft uint8_t |
172 |
.Fn libusb20_dev_get_bus_number "struct libusb20_device *pdev" |
173 |
.Ft uint8_t |
174 |
.Fn libusb20_dev_get_mode "struct libusb20_device *pdev" |
175 |
.Ft uint8_t |
176 |
.Fn libusb20_dev_get_speed "struct libusb20_device *pdev" |
177 |
.Ft uint8_t |
178 |
.Fn libusb20_dev_get_config_index "struct libusb20_device *pdev" |
179 |
.Ft void |
180 |
.Fn libusb20_dev_free "struct libusb20_device *pdev" |
181 |
.Ft void |
182 |
.Fn libusb20_dev_set_debug "struct libusb20_device *pdev" "int debug" |
183 |
.Ft void |
184 |
.Fn libusb20_dev_wait_process "struct libusb20_device *pdev" "int timeout" |
185 |
.Ft int |
186 |
.Fn libusb20_be_get_template "struct libusb20_backend *pbe" "int *ptemp" |
187 |
.Ft int |
188 |
.Fn libusb20_be_set_template "struct libusb20_backend *pbe" "int temp" |
189 |
.Ft int |
190 |
.Fn libusb20_be_get_dev_quirk "struct libusb20_backend *pber" "uint16_t index" "struct libusb20_quirk *pq" |
191 |
.Ft int |
192 |
.Fn libusb20_be_get_quirk_name "struct libusb20_backend *pbe" "uint16_t index" "struct libusb20_quirk *pq" |
193 |
.Ft int |
194 |
.Fn libusb20_be_add_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq" |
195 |
.Ft int |
196 |
.Fn libusb20_be_remove_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq" |
197 |
.Ft struct libusb20_backend * |
198 |
.Fn libusb20_be_alloc_default "void" |
199 |
.Ft struct libusb20_backend * |
200 |
.Fn libusb20_be_alloc_freebsd "void" |
201 |
.Ft struct libusb20_backend * |
202 |
.Fn libusb20_be_alloc_linux "void" |
203 |
.Ft struct libusb20_device * |
204 |
.Fn libusb20_be_device_foreach "struct libusb20_backend *pbe" "struct libusb20_device *pdev" |
205 |
.Ft void |
206 |
.Fn libusb20_be_dequeue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev" |
207 |
.Ft void |
208 |
.Fn libusb20_be_enqueue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev" |
209 |
.Ft void |
210 |
.Fn libusb20_be_free "struct libusb20_backend *pbe" |
211 |
.Ft uint8_t |
212 |
.Fn libusb20_me_get_1 "const struct libusb20_me_struct *me" "uint16_t off" |
213 |
.Ft uint16_t |
214 |
.Fn libusb20_me_get_2 "const struct libusb20_me_struct *me" "uint16_t off" |
215 |
.Ft uint16_t |
216 |
.Fn libusb20_me_encode "void *pdata" "uint16_t len" "const void *pdecoded" |
217 |
.Ft uint16_t |
218 |
.Fn libusb20_me_decode "const void *pdata" "uint16_t len" "void *pdecoded" |
219 |
.Ft "const uint8_t *" |
220 |
.Fn libusb20_desc_foreach "const struct libusb20_me_struct *me" "const uint8_t *pdesc" |
221 |
.Ft "const char *" |
222 |
.Fn libusb20_strerror "int code" |
223 |
.Ft "const char *" |
224 |
.Fn libusb20_error_name "int code" |
225 |
. |
226 |
. |
227 |
.Sh DESCRIPTION |
228 |
. |
229 |
The |
230 |
.Nm |
231 |
library implements functions to be able to easily access and control |
232 |
USB through the USB file system interface. |
233 |
The |
234 |
.Nm |
235 |
interfaces are specific to the |
236 |
.Fx |
237 |
usb stack and are not available on other operating systems, portable |
238 |
applications should consider using |
239 |
.Xr libusb 3 . |
240 |
. |
241 |
. |
242 |
.Sh USB TRANSFER OPERATIONS |
243 |
. |
244 |
. |
245 |
.Fn libusb20_tr_close |
246 |
will release all kernel resources associated with an USB |
247 |
.Fa xfer . |
248 |
. |
249 |
This function returns zero upon success. |
250 |
. |
251 |
Non-zero return values indicate a LIBUSB20_ERROR value. |
252 |
. |
253 |
.Pp |
254 |
. |
255 |
.Fn libusb20_tr_open |
256 |
will allocate kernel buffer resources according to |
257 |
.Fa max_buf_size |
258 |
and |
259 |
.Fa max_frame_count |
260 |
associated with an USB |
261 |
.Fa pxfer |
262 |
and bind the transfer to the specified |
263 |
.Fa ep_no . |
264 |
.Fa max_buf_size |
265 |
is the minimum buffer size which the data transport layer has to support. |
266 |
If |
267 |
.Fa max_buf_size |
268 |
is zero, the |
269 |
.Nm |
270 |
library will use wMaxPacketSize to compute the buffer size. |
271 |
This can be useful for isochronous transfers. |
272 |
The actual buffer size can be greater than |
273 |
.Fa max_buf_size |
274 |
and is returned by |
275 |
.Fn libusb20_tr_get_max_total_length . |
276 |
. |
277 |
If |
278 |
.Fa max_frame_count |
279 |
is OR'ed with LIBUSB20_MAX_FRAME_PRE_SCALE the remaining part of the |
280 |
argument is converted from milliseconds into the actual number of |
281 |
frames rounded up, when this function returns. |
282 |
This flag is only valid for ISOCHRONOUS transfers and has no effect |
283 |
for other transfer types. |
284 |
The actual number of frames setup is found by calling |
285 |
.Fn libusb20_tr_get_max_frames . |
286 |
. |
287 |
This function returns zero upon success. |
288 |
. |
289 |
Non-zero return values indicate a LIBUSB20_ERROR value. |
290 |
. |
291 |
.Pp |
292 |
. |
293 |
.Fn libusb20_tr_open_stream |
294 |
is identical to |
295 |
.Fn libusb20_tr_open |
296 |
except that a stream ID can be specified for BULK endpoints having |
297 |
such a feature. |
298 |
.Fn libusb20_tr_open |
299 |
can be used to open stream ID zero. |
300 |
. |
301 |
.Pp |
302 |
. |
303 |
.Fn libusb20_tr_get_pointer |
304 |
will return a pointer to the allocated USB transfer according to the |
305 |
.Fa pdev |
306 |
and |
307 |
.Fa tr_index |
308 |
arguments. |
309 |
. |
310 |
This function returns NULL in case of failure. |
311 |
. |
312 |
.Pp |
313 |
. |
314 |
.Fn libusb20_tr_get_time_complete |
315 |
will return the completion time of an USB transfer in |
316 |
millisecond units. This function is most useful for isochronous USB |
317 |
transfers when doing echo cancelling. |
318 |
. |
319 |
.Pp |
320 |
. |
321 |
.Fn libusb20_tr_get_actual_frames |
322 |
will return the actual number of USB frames after an USB |
323 |
transfer completed. A value of zero means that no data was transferred. |
324 |
. |
325 |
.Pp |
326 |
. |
327 |
.Fn libusb20_tr_get_actual_length |
328 |
will return the sum of the actual length for all |
329 |
transferred USB frames for the given USB transfer. |
330 |
. |
331 |
.Pp |
332 |
. |
333 |
.Fn libusb20_tr_get_max_frames |
334 |
will return the maximum number of USB frames that were |
335 |
allocated when an USB transfer was setup for the given USB transfer. |
336 |
. |
337 |
.Pp |
338 |
. |
339 |
.Fn libusb20_tr_get_max_packet_length |
340 |
will return the maximum packet length in bytes |
341 |
associated with the given USB transfer. |
342 |
. |
343 |
The packet length can be used round up buffer sizes so that short USB |
344 |
packets are avoided for proxy buffers. |
345 |
. |
346 |
. |
347 |
.Pp |
348 |
. |
349 |
.Fn libusb20_tr_get_max_total_length |
350 |
will return the maximum value for the data length sum of all USB |
351 |
frames associated with an USB transfer. |
352 |
In case of control transfers the value returned does not include the |
353 |
length of the SETUP packet, 8 bytes, which is part of frame zero. |
354 |
The returned value of this function is always aligned to the maximum |
355 |
packet size, wMaxPacketSize, of the endpoint which the USB transfer is |
356 |
bound to. |
357 |
. |
358 |
.Pp |
359 |
. |
360 |
.Fn libusb20_tr_get_status |
361 |
will return the status of an USB transfer. |
362 |
. |
363 |
Status values are defined by a set of LIBUSB20_TRANSFER_XXX enums. |
364 |
. |
365 |
.Pp |
366 |
. |
367 |
.Fn libusb20_tr_pending |
368 |
will return non-zero if the given USB transfer is |
369 |
pending for completion. |
370 |
. |
371 |
Else this function returns zero. |
372 |
. |
373 |
.Pp |
374 |
. |
375 |
.Fn libusb20_tr_callback_wrapper |
376 |
This is an internal function used to wrap asynchronous USB callbacks. |
377 |
. |
378 |
.Pp |
379 |
. |
380 |
.Fn libusb20_tr_clear_stall_sync |
381 |
This is an internal function used to synchronously clear the stall on |
382 |
the given USB transfer. |
383 |
. |
384 |
Please see the USB specification for more information on stall |
385 |
clearing. |
386 |
. |
387 |
If the given USB transfer is pending when this function is called, the |
388 |
USB transfer will complete with an error after that this function has |
389 |
been called. |
390 |
. |
391 |
.Pp |
392 |
. |
393 |
.Fn libusb20_tr_drain |
394 |
will stop the given USB transfer and will not return |
395 |
until the USB transfer has been stopped in hardware. |
396 |
. |
397 |
.Pp |
398 |
. |
399 |
.Fn libusb20_tr_set_buffer |
400 |
is used to set the |
401 |
.Fa buffer |
402 |
pointer for the given USB transfer and |
403 |
.Fa fr_index . |
404 |
. |
405 |
Typically the frame index is zero. |
406 |
. |
407 |
. |
408 |
.Pp |
409 |
. |
410 |
.Fn libusb20_tr_set_callback |
411 |
is used to set the USB callback for asynchronous USB |
412 |
transfers. |
413 |
. |
414 |
The callback type is defined by libusb20_tr_callback_t. |
415 |
. |
416 |
.Pp |
417 |
. |
418 |
.Fn libusb20_tr_set_flags |
419 |
is used to set various USB flags for the given USB transfer. |
420 |
.Bl -tag -width "LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK" |
421 |
.It LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK |
422 |
Report a short frame as error. |
423 |
.It LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK |
424 |
Multiple short frames are not allowed. |
425 |
.It LIBUSB20_TRANSFER_FORCE_SHORT |
426 |
All transmitted frames are short terminated. |
427 |
.It LIBUSB20_TRANSFER_DO_CLEAR_STALL |
428 |
Will do a clear-stall before starting the transfer. |
429 |
.El |
430 |
. |
431 |
.Pp |
432 |
. |
433 |
.Fn libusb20_tr_get_length |
434 |
returns the length of the given USB frame by index. |
435 |
After an USB transfer is complete the USB frame length will get updated to the actual transferred length. |
436 |
. |
437 |
.Pp |
438 |
. |
439 |
.Fn libusb20_tr_set_length |
440 |
sets the length of the given USB frame by index. |
441 |
. |
442 |
.Pp |
443 |
. |
444 |
.Fn libusb20_tr_set_priv_sc0 |
445 |
sets private driver pointer number zero. |
446 |
. |
447 |
.Pp |
448 |
. |
449 |
.Fn libusb20_tr_set_priv_sc1 |
450 |
sets private driver pointer number one. |
451 |
. |
452 |
.Pp |
453 |
. |
454 |
.Fn libusb20_tr_set_timeout |
455 |
sets the timeout for the given USB transfer. |
456 |
. |
457 |
A timeout value of zero means no timeout. |
458 |
. |
459 |
The timeout is given in milliseconds. |
460 |
. |
461 |
.Pp |
462 |
. |
463 |
.Fn libusb20_tr_set_total_frames |
464 |
sets the total number of frames that should be executed when the USB transfer is submitted. |
465 |
. |
466 |
The total number of USB frames must be less than the maximum number of USB frames associated with the given USB transfer. |
467 |
. |
468 |
.Pp |
469 |
. |
470 |
.Fn libusb20_tr_setup_bulk |
471 |
is a helper function for setting up a single frame USB BULK transfer. |
472 |
. |
473 |
.Pp |
474 |
. |
475 |
.Fn libusb20_tr_setup_control |
476 |
is a helper function for setting up a single or dual |
477 |
frame USB CONTROL transfer depending on the control transfer length. |
478 |
. |
479 |
.Pp |
480 |
. |
481 |
.Fn libusb20_tr_setup_intr |
482 |
is a helper function for setting up a single frame USB INTERRUPT transfer. |
483 |
. |
484 |
.Pp |
485 |
. |
486 |
.Fn libusb20_tr_setup_isoc |
487 |
is a helper function for setting up a multi frame USB ISOCHRONOUS transfer. |
488 |
. |
489 |
.Pp |
490 |
. |
491 |
.Fn libusb20_tr_bulk_intr_sync |
492 |
will perform a synchronous BULK or INTERRUPT transfer having length given by the |
493 |
.Fa length |
494 |
argument and buffer pointer given by the |
495 |
.Fa pbuf |
496 |
argument on the USB transfer given by the |
497 |
.Fa xfer |
498 |
argument. |
499 |
. |
500 |
If the |
501 |
.Fa pactlen |
502 |
argument is non-NULL the actual transfer length will be stored at the given pointer destination. |
503 |
. |
504 |
If the |
505 |
.Fa timeout |
506 |
argument is non-zero the transfer will timeout after the given value in milliseconds. |
507 |
. |
508 |
This function does not change the transfer flags, like short packet not ok. |
509 |
. |
510 |
This function returns zero on success else a LIBUSB20_TRANSFER_XXX value is returned. |
511 |
. |
512 |
.Pp |
513 |
. |
514 |
.Fn libusb20_tr_start |
515 |
will get the USB transfer started, if not already |
516 |
started. |
517 |
. |
518 |
This function will not get the transfer queued in hardware. |
519 |
. |
520 |
This function is non-blocking. |
521 |
. |
522 |
.Pp |
523 |
. |
524 |
.Fn libusb20_tr_stop |
525 |
will get the USB transfer stopped, if not already stopped. |
526 |
. |
527 |
This function is non-blocking, which means that the actual stop can |
528 |
happen after the return of this function. |
529 |
. |
530 |
.Pp |
531 |
. |
532 |
.Fn libusb20_tr_submit |
533 |
will get the USB transfer queued in hardware. |
534 |
. |
535 |
. |
536 |
.Pp |
537 |
. |
538 |
.Fn libusb20_tr_get_priv_sc0 |
539 |
returns private driver pointer number zero associated |
540 |
with an USB transfer. |
541 |
. |
542 |
. |
543 |
.Pp |
544 |
. |
545 |
.Fn libusb20_tr_get_priv_sc1 |
546 |
returns private driver pointer number one associated |
547 |
with an USB transfer. |
548 |
. |
549 |
. |
550 |
.Sh USB DEVICE OPERATIONS |
551 |
. |
552 |
. |
553 |
.Fn libusb20_dev_get_backend_name |
554 |
returns a zero terminated string describing the backend used. |
555 |
. |
556 |
.Pp |
557 |
. |
558 |
.Fn libusb20_dev_get_port_path |
559 |
retrieves the list of USB port numbers which the datastream for a given USB device follows. |
560 |
The first port number is the Root HUB port number. |
561 |
Then children port numbers follow. |
562 |
The Root HUB device itself has a port path length of zero. |
563 |
Valid port numbers start at one and range until and including 255. |
564 |
Typically there should not be more than 16 levels, due to electrical and protocol limitations. |
565 |
This functions returns the number of actual port levels upon success |
566 |
else a LIBUSB20_ERROR value is returned which are always negative. |
567 |
If the actual number of port levels is greater than the maximum |
568 |
specified, a LIBUSB20_ERROR value is returned. |
569 |
. |
570 |
.Pp |
571 |
. |
572 |
.Fn libusb20_dev_get_info |
573 |
retrieves the BSD specific usb_device_info structure into the memory location given by |
574 |
.Fa pinfo . |
575 |
The USB device given by |
576 |
.Fa pdev |
577 |
must be opened before this function will succeed. |
578 |
This function returns zero on success else a LIBUSB20_ERROR value is returned. |
579 |
. |
580 |
.Pp |
581 |
. |
582 |
.Fn libusb20_dev_get_iface_desc |
583 |
retrieves the kernel interface description for the given USB |
584 |
.Fa iface_index . |
585 |
The format of the USB interface description is: "drivername<unit>: <description>" |
586 |
The description string is always zero terminated. |
587 |
A zero length string is written in case no driver is attached to the given interface. |
588 |
The USB device given by |
589 |
.Fa pdev |
590 |
must be opened before this function will succeed. |
591 |
This function returns zero on success else a LIBUSB20_ERROR value is returned. |
592 |
. |
593 |
.Pp |
594 |
. |
595 |
.Fn libusb20_dev_get_desc |
596 |
returns a zero terminated string describing the given USB device. |
597 |
The format of the string is: "drivername<unit>: <description>" |
598 |
. |
599 |
.Pp |
600 |
. |
601 |
.Fn libusb20_dev_close |
602 |
will close the given USB device. |
603 |
. |
604 |
This function returns zero on success else a LIBUSB20_ERROR value is |
605 |
returned. |
606 |
. |
607 |
.Pp |
608 |
. |
609 |
.Fn libusb20_dev_detach_kernel_driver |
610 |
will try to detach the kernel driver for the USB interface given by |
611 |
.Fa iface_index . |
612 |
. |
613 |
This function returns zero on success else a LIBUSB20_ERROR value is |
614 |
returned. |
615 |
. |
616 |
.Pp |
617 |
. |
618 |
.Fn libusb20_dev_set_config_index |
619 |
will try to set the configuration index on an USB |
620 |
device. |
621 |
. |
622 |
The first configuration index is zero. |
623 |
. |
624 |
The un-configure index is 255. |
625 |
. |
626 |
This function returns zero on success else a LIBUSB20_ERROR value is returned. |
627 |
. |
628 |
.Pp |
629 |
. |
630 |
.Fn libusb20_dev_get_debug |
631 |
returns the debug level of an USB device. |
632 |
. |
633 |
.Pp |
634 |
. |
635 |
.Fn libusb20_dev_get_fd |
636 |
returns the file descriptor of the given USB device. |
637 |
. |
638 |
A negative value is returned when no file descriptor is present. |
639 |
. |
640 |
The file descriptor can be used for polling purposes. |
641 |
. |
642 |
.Pp |
643 |
. |
644 |
.Fn libusb20_dev_kernel_driver_active |
645 |
returns zero if a kernel driver is active on the given USB interface. |
646 |
. |
647 |
Else a LIBUSB20_ERROR value is returned. |
648 |
. |
649 |
.Pp |
650 |
. |
651 |
.Fn libusb20_dev_open |
652 |
opens an USB device so that setting up USB transfers |
653 |
becomes possible. |
654 |
. |
655 |
The number of USB transfers can be zero which means only control |
656 |
transfers are allowed. |
657 |
. |
658 |
This function returns zero on success else a LIBUSB20_ERROR value is |
659 |
returned. |
660 |
. |
661 |
A return value of LIBUSB20_ERROR_BUSY means that the device is already |
662 |
opened. |
663 |
. |
664 |
.Pp |
665 |
. |
666 |
.Fn libusb20_dev_process |
667 |
is called to sync kernel USB transfers with userland USB |
668 |
transfers. |
669 |
. |
670 |
This function returns zero on success else a LIBUSB20_ERROR value is |
671 |
returned typically indicating that the given USB device has been |
672 |
detached. |
673 |
. |
674 |
.Pp |
675 |
. |
676 |
.Fn libusb20_dev_request_sync |
677 |
will perform a synchronous control request on the given |
678 |
USB device. |
679 |
. |
680 |
Before this call will succeed the USB device must be opened. |
681 |
. |
682 |
.Fa setup |
683 |
is a pointer to a decoded and host endian SETUP packet. |
684 |
.Fa data |
685 |
is a pointer to a data transfer buffer associated with the control transaction. This argument can be NULL. |
686 |
.Fa pactlen |
687 |
is a pointer to a variable that will hold the actual transfer length after the control transaction is complete. |
688 |
.Fa timeout |
689 |
is the transaction timeout given in milliseconds. |
690 |
A timeout of zero means no timeout. |
691 |
.Fa flags |
692 |
is used to specify transaction flags, for example LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK. |
693 |
. |
694 |
This function returns zero on success else a LIBUSB20_ERROR value is |
695 |
returned. |
696 |
. |
697 |
.Pp |
698 |
. |
699 |
.Fn libusb20_dev_req_string_sync |
700 |
will synchronously request an USB string by language ID |
701 |
and string index into the given buffer limited by a maximum length. |
702 |
. |
703 |
This function returns zero on success else a LIBUSB20_ERROR value is |
704 |
returned. |
705 |
. |
706 |
.Pp |
707 |
. |
708 |
.Fn libusb20_dev_req_string_simple_sync |
709 |
will synchronously request an USB string using the |
710 |
default language ID and convert the string into ASCII before storing |
711 |
the string into the given buffer limited by a maximum length which |
712 |
includes the terminating zero. |
713 |
. |
714 |
This function returns zero on success else a LIBUSB20_ERROR value is |
715 |
returned. |
716 |
. |
717 |
. |
718 |
.Pp |
719 |
. |
720 |
.Fn libusb20_dev_reset |
721 |
will try to BUS reset the given USB device and restore |
722 |
the last set USB configuration. |
723 |
. |
724 |
This function returns zero on success else a LIBUSB20_ERROR value is |
725 |
returned. |
726 |
. |
727 |
. |
728 |
.Pp |
729 |
. |
730 |
.Fn libusb20_dev_check_connected |
731 |
will check if an opened USB device is still connected. |
732 |
. |
733 |
This function returns zero if the device is still connected else a LIBUSB20_ERROR value is returned. |
734 |
. |
735 |
. |
736 |
.Pp |
737 |
. |
738 |
.Fn libusb20_dev_set_power_mode |
739 |
sets the power mode of the USB device. |
740 |
. |
741 |
Valid power modes: |
742 |
.Bl -tag -width "LIBUSB20_POWER_OFF" |
743 |
.It LIBUSB20_POWER_OFF |
744 |
.It LIBUSB20_POWER_ON |
745 |
.It LIBUSB20_POWER_SAVE |
746 |
.It LIBUSB20_POWER_SUSPEND |
747 |
.It LIBUSB20_POWER_RESUME |
748 |
.El |
749 |
.Pp |
750 |
. |
751 |
This function returns zero on success else a LIBUSB20_ERROR value is |
752 |
returned. |
753 |
. |
754 |
.Pp |
755 |
. |
756 |
.Fn libusb20_dev_get_power_mode |
757 |
returns the currently selected power mode for the given |
758 |
USB device. |
759 |
. |
760 |
.Pp |
761 |
. |
762 |
.Fn libusb20_dev_get_power_usage |
763 |
returns the reported power usage in milliamps for the given USB device. |
764 |
A power usage of zero typically means that the device is self powered. |
765 |
. |
766 |
.Pp |
767 |
. |
768 |
.Fn libusb20_dev_set_alt_index |
769 |
will try to set the given alternate index for the given |
770 |
USB interface index. |
771 |
. |
772 |
This function returns zero on success else a LIBUSB20_ERROR value is |
773 |
returned. |
774 |
. |
775 |
.Pp |
776 |
. |
777 |
.Fn libusb20_dev_get_device_desc |
778 |
returns a pointer to the decoded and host endian version |
779 |
of the device descriptor. |
780 |
. |
781 |
The USB device need not be opened when calling this function. |
782 |
. |
783 |
.Pp |
784 |
. |
785 |
.Fn libusb20_dev_alloc_config |
786 |
will read out and decode the USB config descriptor for |
787 |
the given USB device and config index. This function returns a pointer |
788 |
to the decoded configuration which must eventually be passed to |
789 |
free(). NULL is returned in case of failure. |
790 |
. |
791 |
.Pp |
792 |
. |
793 |
.Fn libusb20_dev_alloc |
794 |
is an internal function to allocate a new USB device. |
795 |
. |
796 |
.Pp |
797 |
. |
798 |
.Fn libusb20_dev_get_address |
799 |
returns the internal and not necessarily the real |
800 |
hardware address of the given USB device. |
801 |
Valid addresses start at one. |
802 |
. |
803 |
.Pp |
804 |
. |
805 |
.Fn libusb20_dev_get_parent_address |
806 |
returns the internal and not necessarily the real hardware address of |
807 |
the given parent USB HUB device. |
808 |
This value is zero for the root HUB which usually has a device address |
809 |
equal to one. |
810 |
Valid addresses start at one. |
811 |
. |
812 |
.Pp |
813 |
. |
814 |
.Fn libusb20_dev_get_parent_port |
815 |
returns the port number on the parent USB HUB device. |
816 |
This value is zero for the root HUB which usually has a device address |
817 |
equal to one. |
818 |
Valid port numbers start at one. |
819 |
. |
820 |
.Pp |
821 |
. |
822 |
.Fn libusb20_dev_get_bus_number |
823 |
returns the internal bus number which the given USB |
824 |
device belongs to. |
825 |
Valid bus numbers start at zero. |
826 |
. |
827 |
.Pp |
828 |
. |
829 |
.Fn libusb20_dev_get_mode |
830 |
returns the current operation mode of the USB entity. |
831 |
. |
832 |
Valid return values are: |
833 |
.Bl -tag -width "LIBUSB20_MODE_DEVICE" |
834 |
.It LIBUSB20_MODE_HOST |
835 |
.It LIBUSB20_MODE_DEVICE |
836 |
.El |
837 |
. |
838 |
.Pp |
839 |
. |
840 |
.Fn libusb20_dev_get_speed |
841 |
returns the current speed of the given USB device. |
842 |
. |
843 |
.Bl -tag -width "LIBUSB20_SPEED_VARIABLE" |
844 |
.It LIBUSB20_SPEED_UNKNOWN |
845 |
.It LIBUSB20_SPEED_LOW |
846 |
.It LIBUSB20_SPEED_FULL |
847 |
.It LIBUSB20_SPEED_HIGH |
848 |
.It LIBUSB20_SPEED_VARIABLE |
849 |
.It LIBUSB20_SPEED_SUPER |
850 |
.El |
851 |
. |
852 |
.Pp |
853 |
. |
854 |
.Fn libusb20_dev_get_config_index |
855 |
returns the currently selected config index for the given |
856 |
USB device. |
857 |
. |
858 |
.Pp |
859 |
. |
860 |
.Fn libusb20_dev_free |
861 |
will free the given USB device and all associated USB |
862 |
transfers. |
863 |
. |
864 |
.Pp |
865 |
. |
866 |
.Fn libusb20_dev_set_debug |
867 |
will set the debug level for the given USB device. |
868 |
. |
869 |
.Pp |
870 |
. |
871 |
.Fn libusb20_dev_wait_process |
872 |
will wait until a pending USB transfer has completed on |
873 |
the given USB device. |
874 |
. |
875 |
A timeout value can be specified which is passed on to the |
876 |
.Xr poll 2 |
877 |
function. |
878 |
. |
879 |
.Sh USB BACKEND OPERATIONS |
880 |
. |
881 |
.Fn libusb20_be_get_template |
882 |
will return the currently selected global USB device |
883 |
side mode template into the integer pointer |
884 |
.Fa ptemp . |
885 |
This function returns zero on success else a LIBUSB20_ERROR value is |
886 |
returned. |
887 |
. |
888 |
.Pp |
889 |
. |
890 |
.Fn libusb20_be_set_template |
891 |
will set the global USB device side mode template to |
892 |
.Fa temp . |
893 |
The new template is not activated until after the next USB |
894 |
enumeration. |
895 |
The template number decides how the USB device will present itself to |
896 |
the USB Host, like Mass Storage Device, USB Ethernet Device. Also see |
897 |
the |
898 |
.Xr usb2_template 4 |
899 |
module. |
900 |
This function returns zero on success else a LIBUSB20_ERROR value is |
901 |
returned. |
902 |
. |
903 |
.Pp |
904 |
. |
905 |
.Fn libusb20_be_get_dev_quirk |
906 |
will return the device quirk according to |
907 |
.Fa index |
908 |
into the libusb20_quirk structure pointed to by |
909 |
.Fa pq . |
910 |
This function returns zero on success else a LIBUSB20_ERROR value is |
911 |
returned. |
912 |
. |
913 |
If the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is |
914 |
returned. |
915 |
. |
916 |
.Pp |
917 |
. |
918 |
.Fn libusb20_be_get_quirk_name |
919 |
will return the quirk name according to |
920 |
.Fa index |
921 |
into the libusb20_quirk structure pointed to by |
922 |
.Fa pq . |
923 |
This function returns zero on success else a LIBUSB20_ERROR value is |
924 |
returned. |
925 |
. |
926 |
If the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is |
927 |
returned. |
928 |
. |
929 |
.Pp |
930 |
. |
931 |
.Fn libusb20_be_add_dev_quirk |
932 |
will add the libusb20_quirk structure pointed to by the |
933 |
.Fa pq |
934 |
argument into the device quirk list. |
935 |
. |
936 |
This function returns zero on success else a LIBUSB20_ERROR value is |
937 |
returned. |
938 |
. |
939 |
If the given quirk cannot be added LIBUSB20_ERROR_NO_MEM is |
940 |
returned. |
941 |
. |
942 |
.Pp |
943 |
. |
944 |
.Fn libusb20_be_remove_dev_quirk |
945 |
will remove the quirk matching the libusb20_quirk structure pointed to by the |
946 |
.Fa pq |
947 |
argument from the device quirk list. |
948 |
. |
949 |
This function returns zero on success else a LIBUSB20_ERROR value is |
950 |
returned. |
951 |
. |
952 |
If the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is |
953 |
returned. |
954 |
. |
955 |
.Pp |
956 |
. |
957 |
.Fn libusb20_be_alloc_default |
958 |
.Fn libusb20_be_alloc_freebsd |
959 |
.Fn libusb20_be_alloc_linux |
960 |
These functions are used to allocate a specific USB backend or the |
961 |
operating system default USB backend. Allocating a backend is a way to |
962 |
scan for currently present USB devices. |
963 |
. |
964 |
.Pp |
965 |
. |
966 |
.Fn libusb20_be_device_foreach |
967 |
is used to iterate USB devices present in a USB backend. |
968 |
. |
969 |
The starting value of |
970 |
.Fa pdev |
971 |
is NULL. |
972 |
. |
973 |
This function returns the next USB device in the list. |
974 |
. |
975 |
If NULL is returned the end of the USB device list has been reached. |
976 |
. |
977 |
.Pp |
978 |
. |
979 |
.Fn libusb20_be_dequeue_device |
980 |
will dequeue the given USB device pointer from the |
981 |
backend USB device list. |
982 |
. |
983 |
Dequeued USB devices will not be freed when the backend is freed. |
984 |
. |
985 |
.Pp |
986 |
. |
987 |
.Fn libusb20_be_enqueue_device |
988 |
will enqueue the given USB device pointer in the backend USB device list. |
989 |
. |
990 |
Enqueued USB devices will get freed when the backend is freed. |
991 |
. |
992 |
.Pp |
993 |
. |
994 |
.Fn libusb20_be_free |
995 |
will free the given backend and all USB devices in its device list. |
996 |
. |
997 |
. |
998 |
.Sh USB DESCRIPTOR PARSING |
999 |
. |
1000 |
.Fn libusb20_me_get_1 pie offset |
1001 |
This function will return a byte at the given byte offset of a message |
1002 |
entity. |
1003 |
. |
1004 |
This function is safe against invalid offsets. |
1005 |
. |
1006 |
.Pp |
1007 |
. |
1008 |
.Fn libusb20_me_get_2 pie offset |
1009 |
This function will return a little endian 16-bit value at the given byte offset of a message |
1010 |
entity. |
1011 |
. |
1012 |
This function is safe against invalid offsets. |
1013 |
. |
1014 |
.Pp |
1015 |
. |
1016 |
.Fn libusb20_me_encode pbuf len pdecoded |
1017 |
This function will encode a so-called *DECODED structure into binary |
1018 |
format. |
1019 |
. |
1020 |
The total encoded length that will fit in the given buffer is |
1021 |
returned. |
1022 |
. |
1023 |
If the buffer pointer is NULL no data will be written to the buffer |
1024 |
location. |
1025 |
. |
1026 |
.Pp |
1027 |
. |
1028 |
.Fn libusb20_me_decode pbuf len pdecoded |
1029 |
This function will decode a binary structure into a so-called *DECODED |
1030 |
structure. |
1031 |
. |
1032 |
The total decoded length is returned. |
1033 |
. |
1034 |
The buffer pointer cannot be NULL. |
1035 |
. |
1036 |
. |
1037 |
.Sh USB DEBUGGING |
1038 |
.Ft const char * |
1039 |
.Fn libusb20_strerror "int code" |
1040 |
Get the ASCII representation of the error given by the |
1041 |
.Fa code |
1042 |
argument. |
1043 |
This function does not return NULL. |
1044 |
.Pp |
1045 |
.Ft const char * |
1046 |
.Fn libusb20_error_name "int code" |
1047 |
Get the ASCII representation of the error enum given by the |
1048 |
.Fa code |
1049 |
argument. |
1050 |
This function does not return NULL. |
1051 |
. |
1052 |
.Sh FILES |
1053 |
.Bl -tag -width Pa |
1054 |
.It Pa /dev/usb |
1055 |
.El |
1056 |
.Sh SEE ALSO |
1057 |
.Xr usb 4 , |
1058 |
.Xr libusb 3 , |
1059 |
.Xr usbconfig 8 , |
1060 |
.Xr usbdump 8 |
1061 |
. |
1062 |
. |
1063 |
.Sh HISTORY |
1064 |
. |
1065 |
. |
1066 |
Some parts of the |
1067 |
.Nm |
1068 |
API derives from the libusb project at sourceforge. |