• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Synchronous I/O functions for libusb
3  * Copyright © 2007-2008 Daniel Drake <dsd@gentoo.org>
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18  */
19 
20 #include <config.h>
21 
22 #include <errno.h>
23 #include <stdint.h>
24 #include <stdlib.h>
25 #include <string.h>
26 
27 #include "libusbi.h"
28 
29 /**
30  * @defgroup libusb_syncio Synchronous device I/O
31  *
32  * This page documents libusb's synchronous (blocking) API for USB device I/O.
33  * This interface is easy to use but has some limitations. More advanced users
34  * may wish to consider using the \ref libusb_asyncio "asynchronous I/O API" instead.
35  */
36 
sync_transfer_cb(struct libusb_transfer * transfer)37 static void LIBUSB_CALL sync_transfer_cb(struct libusb_transfer *transfer)
38 {
39 	int *completed = transfer->user_data;
40 	*completed = 1;
41 	usbi_dbg("actual_length=%d", transfer->actual_length);
42 	/* caller interprets result and frees transfer */
43 }
44 
sync_transfer_wait_for_completion(struct libusb_transfer * transfer)45 static void sync_transfer_wait_for_completion(struct libusb_transfer *transfer)
46 {
47 	int r, *completed = transfer->user_data;
48 	struct libusb_context *ctx = HANDLE_CTX(transfer->dev_handle);
49 
50 	while (!*completed) {
51 		r = libusb_handle_events_completed(ctx, completed);
52 		if (r < 0) {
53 			if (r == LIBUSB_ERROR_INTERRUPTED)
54 				continue;
55 			usbi_err(ctx, "libusb_handle_events failed: %s, cancelling transfer and retrying",
56 				 libusb_error_name(r));
57 			libusb_cancel_transfer(transfer);
58 			continue;
59 		}
60 	}
61 }
62 
63 /** \ingroup libusb_syncio
64  * Perform a USB control transfer.
65  *
66  * The direction of the transfer is inferred from the bmRequestType field of
67  * the setup packet.
68  *
69  * The wValue, wIndex and wLength fields values should be given in host-endian
70  * byte order.
71  *
72  * \param dev_handle a handle for the device to communicate with
73  * \param bmRequestType the request type field for the setup packet
74  * \param bRequest the request field for the setup packet
75  * \param wValue the value field for the setup packet
76  * \param wIndex the index field for the setup packet
77  * \param data a suitably-sized data buffer for either input or output
78  * (depending on direction bits within bmRequestType)
79  * \param wLength the length field for the setup packet. The data buffer should
80  * be at least this size.
81  * \param timeout timeout (in millseconds) that this function should wait
82  * before giving up due to no response being received. For an unlimited
83  * timeout, use value 0.
84  * \returns on success, the number of bytes actually transferred
85  * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
86  * \returns LIBUSB_ERROR_PIPE if the control request was not supported by the
87  * device
88  * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
89  * \returns LIBUSB_ERROR_BUSY if called from event handling context
90  * \returns LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than
91  * the operating system and/or hardware can support
92  * \returns another LIBUSB_ERROR code on other failures
93  */
libusb_control_transfer(libusb_device_handle * dev_handle,uint8_t bmRequestType,uint8_t bRequest,uint16_t wValue,uint16_t wIndex,unsigned char * data,uint16_t wLength,unsigned int timeout)94 int API_EXPORTED libusb_control_transfer(libusb_device_handle *dev_handle,
95 	uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
96 	unsigned char *data, uint16_t wLength, unsigned int timeout)
97 {
98 	struct libusb_transfer *transfer;
99 	unsigned char *buffer;
100 	int completed = 0;
101 	int r;
102 
103 	if (usbi_handling_events(HANDLE_CTX(dev_handle)))
104 		return LIBUSB_ERROR_BUSY;
105 
106 	transfer = libusb_alloc_transfer(0);
107 	if (!transfer)
108 		return LIBUSB_ERROR_NO_MEM;
109 
110 	buffer = (unsigned char*) malloc(LIBUSB_CONTROL_SETUP_SIZE + wLength);
111 	if (!buffer) {
112 		libusb_free_transfer(transfer);
113 		return LIBUSB_ERROR_NO_MEM;
114 	}
115 
116 	libusb_fill_control_setup(buffer, bmRequestType, bRequest, wValue, wIndex,
117 		wLength);
118 	if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_OUT)
119 		memcpy(buffer + LIBUSB_CONTROL_SETUP_SIZE, data, wLength);
120 
121 	libusb_fill_control_transfer(transfer, dev_handle, buffer,
122 		sync_transfer_cb, &completed, timeout);
123 	transfer->flags = LIBUSB_TRANSFER_FREE_BUFFER;
124 	r = libusb_submit_transfer(transfer);
125 	if (r < 0) {
126 		libusb_free_transfer(transfer);
127 		return r;
128 	}
129 
130 	sync_transfer_wait_for_completion(transfer);
131 
132 	if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_IN)
133 		memcpy(data, libusb_control_transfer_get_data(transfer),
134 			transfer->actual_length);
135 
136 	switch (transfer->status) {
137 	case LIBUSB_TRANSFER_COMPLETED:
138 		r = transfer->actual_length;
139 		break;
140 	case LIBUSB_TRANSFER_TIMED_OUT:
141 		r = LIBUSB_ERROR_TIMEOUT;
142 		break;
143 	case LIBUSB_TRANSFER_STALL:
144 		r = LIBUSB_ERROR_PIPE;
145 		break;
146 	case LIBUSB_TRANSFER_NO_DEVICE:
147 		r = LIBUSB_ERROR_NO_DEVICE;
148 		break;
149 	case LIBUSB_TRANSFER_OVERFLOW:
150 		r = LIBUSB_ERROR_OVERFLOW;
151 		break;
152 	case LIBUSB_TRANSFER_ERROR:
153 	case LIBUSB_TRANSFER_CANCELLED:
154 		r = LIBUSB_ERROR_IO;
155 		break;
156 	default:
157 		usbi_warn(HANDLE_CTX(dev_handle),
158 			"unrecognised status code %d", transfer->status);
159 		r = LIBUSB_ERROR_OTHER;
160 	}
161 
162 	libusb_free_transfer(transfer);
163 	return r;
164 }
165 
do_sync_bulk_transfer(struct libusb_device_handle * dev_handle,unsigned char endpoint,unsigned char * buffer,int length,int * transferred,unsigned int timeout,unsigned char type)166 static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle,
167 	unsigned char endpoint, unsigned char *buffer, int length,
168 	int *transferred, unsigned int timeout, unsigned char type)
169 {
170 	struct libusb_transfer *transfer;
171 	int completed = 0;
172 	int r;
173 
174 	if (usbi_handling_events(HANDLE_CTX(dev_handle)))
175 		return LIBUSB_ERROR_BUSY;
176 
177 	transfer = libusb_alloc_transfer(0);
178 	if (!transfer)
179 		return LIBUSB_ERROR_NO_MEM;
180 
181 	libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer, length,
182 		sync_transfer_cb, &completed, timeout);
183 	transfer->type = type;
184 
185 	r = libusb_submit_transfer(transfer);
186 	if (r < 0) {
187 		libusb_free_transfer(transfer);
188 		return r;
189 	}
190 
191 	sync_transfer_wait_for_completion(transfer);
192 
193 	if (transferred)
194 		*transferred = transfer->actual_length;
195 
196 	switch (transfer->status) {
197 	case LIBUSB_TRANSFER_COMPLETED:
198 		r = 0;
199 		break;
200 	case LIBUSB_TRANSFER_TIMED_OUT:
201 		r = LIBUSB_ERROR_TIMEOUT;
202 		break;
203 	case LIBUSB_TRANSFER_STALL:
204 		r = LIBUSB_ERROR_PIPE;
205 		break;
206 	case LIBUSB_TRANSFER_OVERFLOW:
207 		r = LIBUSB_ERROR_OVERFLOW;
208 		break;
209 	case LIBUSB_TRANSFER_NO_DEVICE:
210 		r = LIBUSB_ERROR_NO_DEVICE;
211 		break;
212 	case LIBUSB_TRANSFER_ERROR:
213 	case LIBUSB_TRANSFER_CANCELLED:
214 		r = LIBUSB_ERROR_IO;
215 		break;
216 	default:
217 		usbi_warn(HANDLE_CTX(dev_handle),
218 			"unrecognised status code %d", transfer->status);
219 		r = LIBUSB_ERROR_OTHER;
220 	}
221 
222 	libusb_free_transfer(transfer);
223 	return r;
224 }
225 
226 /** \ingroup libusb_syncio
227  * Perform a USB bulk transfer. The direction of the transfer is inferred from
228  * the direction bits of the endpoint address.
229  *
230  * For bulk reads, the <tt>length</tt> field indicates the maximum length of
231  * data you are expecting to receive. If less data arrives than expected,
232  * this function will return that data, so be sure to check the
233  * <tt>transferred</tt> output parameter.
234  *
235  * You should also check the <tt>transferred</tt> parameter for bulk writes.
236  * Not all of the data may have been written.
237  *
238  * Also check <tt>transferred</tt> when dealing with a timeout error code.
239  * libusb may have to split your transfer into a number of chunks to satisfy
240  * underlying O/S requirements, meaning that the timeout may expire after
241  * the first few chunks have completed. libusb is careful not to lose any data
242  * that may have been transferred; do not assume that timeout conditions
243  * indicate a complete lack of I/O.
244  *
245  * \param dev_handle a handle for the device to communicate with
246  * \param endpoint the address of a valid endpoint to communicate with
247  * \param data a suitably-sized data buffer for either input or output
248  * (depending on endpoint)
249  * \param length for bulk writes, the number of bytes from data to be sent. for
250  * bulk reads, the maximum number of bytes to receive into the data buffer.
251  * \param transferred output location for the number of bytes actually
252  * transferred. Since version 1.0.21 (\ref LIBUSB_API_VERSION >= 0x01000105),
253  * it is legal to pass a NULL pointer if you do not wish to receive this
254  * information.
255  * \param timeout timeout (in millseconds) that this function should wait
256  * before giving up due to no response being received. For an unlimited
257  * timeout, use value 0.
258  *
259  * \returns 0 on success (and populates <tt>transferred</tt>)
260  * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out (and populates
261  * <tt>transferred</tt>)
262  * \returns LIBUSB_ERROR_PIPE if the endpoint halted
263  * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
264  * \ref libusb_packetoverflow
265  * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
266  * \returns LIBUSB_ERROR_BUSY if called from event handling context
267  * \returns another LIBUSB_ERROR code on other failures
268  */
libusb_bulk_transfer(struct libusb_device_handle * dev_handle,unsigned char endpoint,unsigned char * data,int length,int * transferred,unsigned int timeout)269 int API_EXPORTED libusb_bulk_transfer(struct libusb_device_handle *dev_handle,
270 	unsigned char endpoint, unsigned char *data, int length, int *transferred,
271 	unsigned int timeout)
272 {
273 	return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
274 		transferred, timeout, LIBUSB_TRANSFER_TYPE_BULK);
275 }
276 
277 /** \ingroup libusb_syncio
278  * Perform a USB interrupt transfer. The direction of the transfer is inferred
279  * from the direction bits of the endpoint address.
280  *
281  * For interrupt reads, the <tt>length</tt> field indicates the maximum length
282  * of data you are expecting to receive. If less data arrives than expected,
283  * this function will return that data, so be sure to check the
284  * <tt>transferred</tt> output parameter.
285  *
286  * You should also check the <tt>transferred</tt> parameter for interrupt
287  * writes. Not all of the data may have been written.
288  *
289  * Also check <tt>transferred</tt> when dealing with a timeout error code.
290  * libusb may have to split your transfer into a number of chunks to satisfy
291  * underlying O/S requirements, meaning that the timeout may expire after
292  * the first few chunks have completed. libusb is careful not to lose any data
293  * that may have been transferred; do not assume that timeout conditions
294  * indicate a complete lack of I/O.
295  *
296  * The default endpoint bInterval value is used as the polling interval.
297  *
298  * \param dev_handle a handle for the device to communicate with
299  * \param endpoint the address of a valid endpoint to communicate with
300  * \param data a suitably-sized data buffer for either input or output
301  * (depending on endpoint)
302  * \param length for bulk writes, the number of bytes from data to be sent. for
303  * bulk reads, the maximum number of bytes to receive into the data buffer.
304  * \param transferred output location for the number of bytes actually
305  * transferred. Since version 1.0.21 (\ref LIBUSB_API_VERSION >= 0x01000105),
306  * it is legal to pass a NULL pointer if you do not wish to receive this
307  * information.
308  * \param timeout timeout (in millseconds) that this function should wait
309  * before giving up due to no response being received. For an unlimited
310  * timeout, use value 0.
311  *
312  * \returns 0 on success (and populates <tt>transferred</tt>)
313  * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
314  * \returns LIBUSB_ERROR_PIPE if the endpoint halted
315  * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
316  * \ref libusb_packetoverflow
317  * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
318  * \returns LIBUSB_ERROR_BUSY if called from event handling context
319  * \returns another LIBUSB_ERROR code on other error
320  */
libusb_interrupt_transfer(struct libusb_device_handle * dev_handle,unsigned char endpoint,unsigned char * data,int length,int * transferred,unsigned int timeout)321 int API_EXPORTED libusb_interrupt_transfer(
322 	struct libusb_device_handle *dev_handle, unsigned char endpoint,
323 	unsigned char *data, int length, int *transferred, unsigned int timeout)
324 {
325 	return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
326 		transferred, timeout, LIBUSB_TRANSFER_TYPE_INTERRUPT);
327 }
328