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