1 /* 2 * Synchronous I/O functions for libusb 3 * Copyright 2007-2008 Daniel Drake <dsd (at) 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 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 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 */ 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 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 */ 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 */ 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
