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