1 /* -*- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -*- */
3 * Synchronous I/O functions for libusb
4 * Copyright © 2007-2008 Daniel Drake <dsd@gentoo.org>
5 * Copyright © 2019 Nathan Hjelm <hjelmn@cs.unm.edu>
6 * Copyright © 2019 Google LLC. All rights reserved.
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
28 * @defgroup libusb_syncio Synchronous device I/O
30 * This page documents libusb's synchronous (blocking) API for USB device I/O.
31 * This interface is easy to use but has some limitations. More advanced users
32 * may wish to consider using the \ref libusb_asyncio "asynchronous I/O API" instead.
35 static void LIBUSB_CALL sync_transfer_cb(struct libusb_transfer *transfer)
37 int *completed = transfer->user_data;
39 usbi_dbg(TRANSFER_CTX(transfer), "actual_length=%d", transfer->actual_length);
40 /* caller interprets result and frees transfer */
43 static void sync_transfer_wait_for_completion(struct libusb_transfer *transfer)
45 int r, *completed = transfer->user_data;
46 struct libusb_context *ctx = HANDLE_CTX(transfer->dev_handle);
49 r = libusb_handle_events_completed(ctx, completed);
51 if (r == LIBUSB_ERROR_INTERRUPTED)
53 usbi_err(ctx, "libusb_handle_events failed: %s, cancelling transfer and retrying",
54 libusb_error_name(r));
55 libusb_cancel_transfer(transfer);
58 if (NULL == transfer->dev_handle) {
59 /* transfer completion after libusb_close() */
60 transfer->status = LIBUSB_TRANSFER_NO_DEVICE;
66 /** \ingroup libusb_syncio
67 * Perform a USB control transfer.
69 * The direction of the transfer is inferred from the bmRequestType field of
72 * The wValue, wIndex and wLength fields values should be given in host-endian
75 * \param dev_handle a handle for the device to communicate with
76 * \param bmRequestType the request type field for the setup packet
77 * \param bRequest the request field for the setup packet
78 * \param wValue the value field for the setup packet
79 * \param wIndex the index field for the setup packet
80 * \param data a suitably-sized data buffer for either input or output
81 * (depending on direction bits within bmRequestType)
82 * \param wLength the length field for the setup packet. The data buffer should
83 * be at least this size.
84 * \param timeout timeout (in milliseconds) that this function should wait
85 * before giving up due to no response being received. For an unlimited
86 * timeout, use value 0.
87 * \returns on success, the number of bytes actually transferred
88 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
89 * \returns LIBUSB_ERROR_PIPE if the control request was not supported by the
91 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
92 * \returns LIBUSB_ERROR_BUSY if called from event handling context
93 * \returns LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than
94 * the operating system and/or hardware can support (see \ref asynclimits)
95 * \returns another LIBUSB_ERROR code on other failures
97 int API_EXPORTED libusb_control_transfer(libusb_device_handle *dev_handle,
98 uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
99 unsigned char *data, uint16_t wLength, unsigned int timeout)
101 struct libusb_transfer *transfer;
102 unsigned char *buffer;
106 if (usbi_handling_events(HANDLE_CTX(dev_handle)))
107 return LIBUSB_ERROR_BUSY;
109 transfer = libusb_alloc_transfer(0);
111 return LIBUSB_ERROR_NO_MEM;
113 buffer = malloc(LIBUSB_CONTROL_SETUP_SIZE + wLength);
115 libusb_free_transfer(transfer);
116 return LIBUSB_ERROR_NO_MEM;
119 libusb_fill_control_setup(buffer, bmRequestType, bRequest, wValue, wIndex,
121 if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_OUT)
122 memcpy(buffer + LIBUSB_CONTROL_SETUP_SIZE, data, wLength);
124 libusb_fill_control_transfer(transfer, dev_handle, buffer,
125 sync_transfer_cb, &completed, timeout);
126 transfer->flags = LIBUSB_TRANSFER_FREE_BUFFER;
127 r = libusb_submit_transfer(transfer);
129 libusb_free_transfer(transfer);
133 sync_transfer_wait_for_completion(transfer);
135 if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_IN)
136 memcpy(data, libusb_control_transfer_get_data(transfer),
137 transfer->actual_length);
139 switch (transfer->status) {
140 case LIBUSB_TRANSFER_COMPLETED:
141 r = transfer->actual_length;
143 case LIBUSB_TRANSFER_TIMED_OUT:
144 r = LIBUSB_ERROR_TIMEOUT;
146 case LIBUSB_TRANSFER_STALL:
147 r = LIBUSB_ERROR_PIPE;
149 case LIBUSB_TRANSFER_NO_DEVICE:
150 r = LIBUSB_ERROR_NO_DEVICE;
152 case LIBUSB_TRANSFER_OVERFLOW:
153 r = LIBUSB_ERROR_OVERFLOW;
155 case LIBUSB_TRANSFER_ERROR:
156 case LIBUSB_TRANSFER_CANCELLED:
160 usbi_warn(HANDLE_CTX(dev_handle),
161 "unrecognised status code %d", transfer->status);
162 r = LIBUSB_ERROR_OTHER;
165 libusb_free_transfer(transfer);
169 static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle,
170 unsigned char endpoint, unsigned char *buffer, int length,
171 int *transferred, unsigned int timeout, unsigned char type)
173 struct libusb_transfer *transfer;
177 if (usbi_handling_events(HANDLE_CTX(dev_handle)))
178 return LIBUSB_ERROR_BUSY;
180 transfer = libusb_alloc_transfer(0);
182 return LIBUSB_ERROR_NO_MEM;
184 libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer, length,
185 sync_transfer_cb, &completed, timeout);
186 transfer->type = type;
188 r = libusb_submit_transfer(transfer);
190 libusb_free_transfer(transfer);
194 sync_transfer_wait_for_completion(transfer);
197 *transferred = transfer->actual_length;
199 switch (transfer->status) {
200 case LIBUSB_TRANSFER_COMPLETED:
203 case LIBUSB_TRANSFER_TIMED_OUT:
204 r = LIBUSB_ERROR_TIMEOUT;
206 case LIBUSB_TRANSFER_STALL:
207 r = LIBUSB_ERROR_PIPE;
209 case LIBUSB_TRANSFER_OVERFLOW:
210 r = LIBUSB_ERROR_OVERFLOW;
212 case LIBUSB_TRANSFER_NO_DEVICE:
213 r = LIBUSB_ERROR_NO_DEVICE;
215 case LIBUSB_TRANSFER_ERROR:
216 case LIBUSB_TRANSFER_CANCELLED:
220 usbi_warn(HANDLE_CTX(dev_handle),
221 "unrecognised status code %d", transfer->status);
222 r = LIBUSB_ERROR_OTHER;
225 libusb_free_transfer(transfer);
229 /** \ingroup libusb_syncio
230 * Perform a USB bulk transfer. The direction of the transfer is inferred from
231 * the direction bits of the endpoint address.
233 * For bulk reads, the <tt>length</tt> field indicates the maximum length of
234 * data you are expecting to receive. If less data arrives than expected,
235 * this function will return that data, so be sure to check the
236 * <tt>transferred</tt> output parameter.
238 * You should also check the <tt>transferred</tt> parameter for bulk writes.
239 * Not all of the data may have been written.
241 * Also check <tt>transferred</tt> when dealing with a timeout error code.
242 * libusb may have to split your transfer into a number of chunks to satisfy
243 * underlying O/S requirements, meaning that the timeout may expire after
244 * the first few chunks have completed. libusb is careful not to lose any data
245 * that may have been transferred; do not assume that timeout conditions
246 * indicate a complete lack of I/O. See \ref asynctimeout for more details.
248 * \param dev_handle a handle for the device to communicate with
249 * \param endpoint the address of a valid endpoint to communicate with
250 * \param data a suitably-sized data buffer for either input or output
251 * (depending on endpoint)
252 * \param length for bulk writes, the number of bytes from data to be sent. for
253 * bulk reads, the maximum number of bytes to receive into the data buffer.
254 * \param transferred output location for the number of bytes actually
255 * transferred. Since version 1.0.21 (\ref LIBUSB_API_VERSION >= 0x01000105),
256 * it is legal to pass a NULL pointer if you do not wish to receive this
258 * \param timeout timeout (in milliseconds) that this function should wait
259 * before giving up due to no response being received. For an unlimited
260 * timeout, use value 0.
262 * \returns 0 on success (and populates <tt>transferred</tt>)
263 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out (and populates
264 * <tt>transferred</tt>)
265 * \returns LIBUSB_ERROR_PIPE if the endpoint halted
266 * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
267 * \ref libusb_packetoverflow
268 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
269 * \returns LIBUSB_ERROR_BUSY if called from event handling context
270 * \returns LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than
271 * the operating system and/or hardware can support (see \ref asynclimits)
272 * \returns another LIBUSB_ERROR code on other failures
274 int API_EXPORTED libusb_bulk_transfer(libusb_device_handle *dev_handle,
275 unsigned char endpoint, unsigned char *data, int length,
276 int *transferred, unsigned int timeout)
278 return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
279 transferred, timeout, LIBUSB_TRANSFER_TYPE_BULK);
282 /** \ingroup libusb_syncio
283 * Perform a USB interrupt transfer. The direction of the transfer is inferred
284 * from the direction bits of the endpoint address.
286 * For interrupt reads, the <tt>length</tt> field indicates the maximum length
287 * of data you are expecting to receive. If less data arrives than expected,
288 * this function will return that data, so be sure to check the
289 * <tt>transferred</tt> output parameter.
291 * You should also check the <tt>transferred</tt> parameter for interrupt
292 * writes. Not all of the data may have been written.
294 * Also check <tt>transferred</tt> when dealing with a timeout error code.
295 * libusb may have to split your transfer into a number of chunks to satisfy
296 * underlying O/S requirements, meaning that the timeout may expire after
297 * the first few chunks have completed. libusb is careful not to lose any data
298 * that may have been transferred; do not assume that timeout conditions
299 * indicate a complete lack of I/O. See \ref asynctimeout for more details.
301 * The default endpoint bInterval value is used as the polling interval.
303 * \param dev_handle a handle for the device to communicate with
304 * \param endpoint the address of a valid endpoint to communicate with
305 * \param data a suitably-sized data buffer for either input or output
306 * (depending on endpoint)
307 * \param length for bulk writes, the number of bytes from data to be sent. for
308 * bulk reads, the maximum number of bytes to receive into the data buffer.
309 * \param transferred output location for the number of bytes actually
310 * transferred. Since version 1.0.21 (\ref LIBUSB_API_VERSION >= 0x01000105),
311 * it is legal to pass a NULL pointer if you do not wish to receive this
313 * \param timeout timeout (in milliseconds) that this function should wait
314 * before giving up due to no response being received. For an unlimited
315 * timeout, use value 0.
317 * \returns 0 on success (and populates <tt>transferred</tt>)
318 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
319 * \returns LIBUSB_ERROR_PIPE if the endpoint halted
320 * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
321 * \ref libusb_packetoverflow
322 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
323 * \returns LIBUSB_ERROR_BUSY if called from event handling context
324 * \returns LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than
325 * the operating system and/or hardware can support (see \ref asynclimits)
326 * \returns another LIBUSB_ERROR code on other error
328 int API_EXPORTED libusb_interrupt_transfer(libusb_device_handle *dev_handle,
329 unsigned char endpoint, unsigned char *data, int length,
330 int *transferred, unsigned int timeout)
332 return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
333 transferred, timeout, LIBUSB_TRANSFER_TYPE_INTERRUPT);