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 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 */ 72API_EXPORTED int 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(HANDLE_CTX(dev_handle)); 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(HANDLE_CTX(dev_handle)) < 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 default: 136 usbi_warn(HANDLE_CTX(dev_handle), 137 "unrecognised status code %d", transfer->status); 138 r = LIBUSB_ERROR_OTHER; 139 } 140 141 libusb_free_transfer(transfer); 142 return r; 143} 144 145static void bulk_transfer_cb(struct libusb_transfer *transfer) 146{ 147 int *completed = transfer->user_data; 148 *completed = 1; 149 usbi_dbg("actual_length=%d", transfer->actual_length); 150 /* caller interprets results and frees transfer */ 151} 152 153static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle, 154 unsigned char endpoint, unsigned char *buffer, int length, 155 int *transferred, unsigned int timeout, unsigned char type) 156{ 157 struct libusb_transfer *transfer = libusb_alloc_transfer(0); 158 int completed = 0; 159 int r; 160 161 if (!transfer) 162 return LIBUSB_ERROR_NO_MEM; 163 164 libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer, length, 165 bulk_transfer_cb, &completed, timeout); 166 transfer->type = type; 167 168 r = libusb_submit_transfer(transfer); 169 if (r < 0) { 170 libusb_free_transfer(transfer); 171 return r; 172 } 173 174 while (!completed) { 175 r = libusb_handle_events(HANDLE_CTX(dev_handle)); 176 if (r < 0) { 177 if (r == LIBUSB_ERROR_INTERRUPTED) 178 continue; 179 libusb_cancel_transfer(transfer); 180 while (!completed) 181 if (libusb_handle_events(HANDLE_CTX(dev_handle)) < 0) 182 break; 183 libusb_free_transfer(transfer); 184 return r; 185 } 186 } 187 188 *transferred = transfer->actual_length; 189 switch (transfer->status) { 190 case LIBUSB_TRANSFER_COMPLETED: 191 r = 0; 192 break; 193 case LIBUSB_TRANSFER_TIMED_OUT: 194 r = LIBUSB_ERROR_TIMEOUT; 195 break; 196 case LIBUSB_TRANSFER_STALL: 197 r = LIBUSB_ERROR_PIPE; 198 break; 199 case LIBUSB_TRANSFER_OVERFLOW: 200 r = LIBUSB_ERROR_OVERFLOW; 201 break; 202 case LIBUSB_TRANSFER_NO_DEVICE: 203 r = LIBUSB_ERROR_NO_DEVICE; 204 break; 205 default: 206 usbi_warn(HANDLE_CTX(dev_handle), 207 "unrecognised status code %d", transfer->status); 208 r = LIBUSB_ERROR_OTHER; 209 } 210 211 libusb_free_transfer(transfer); 212 return r; 213} 214 215/** \ingroup syncio 216 * Perform a USB bulk transfer. The direction of the transfer is inferred from 217 * the direction bits of the endpoint address. 218 * 219 * For bulk reads, the <tt>length</tt> field indicates the maximum length of 220 * data you are expecting to receive. If less data arrives than expected, 221 * this function will return that data, so be sure to check the 222 * <tt>transferred</tt> output parameter. 223 * 224 * You should also check the <tt>transferred</tt> parameter for bulk writes. 225 * Not all of the data may have been written. 226 * 227 * Also check <tt>transferred</tt> when dealing with a timeout error code. 228 * libusb may have to split your transfer into a number of chunks to satisfy 229 * underlying O/S requirements, meaning that the timeout may expire after 230 * the first few chunks have completed. libusb is careful not to lose any data 231 * that may have been transferred; do not assume that timeout conditions 232 * indicate a complete lack of I/O. 233 * 234 * \param dev_handle a handle for the device to communicate with 235 * \param endpoint the address of a valid endpoint to communicate with 236 * \param data a suitably-sized data buffer for either input or output 237 * (depending on endpoint) 238 * \param length for bulk writes, the number of bytes from data to be sent. for 239 * bulk reads, the maximum number of bytes to receive into the data buffer. 240 * \param transferred output location for the number of bytes actually 241 * transferred. 242 * \param timeout timeout (in millseconds) that this function should wait 243 * before giving up due to no response being received. For an unlimited 244 * timeout, use value 0. 245 * 246 * \returns 0 on success (and populates <tt>transferred</tt>) 247 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out (and populates 248 * <tt>transferred</tt>) 249 * \returns LIBUSB_ERROR_PIPE if the endpoint halted 250 * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see 251 * \ref packetoverflow 252 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 253 * \returns another LIBUSB_ERROR code on other failures 254 */ 255API_EXPORTED int libusb_bulk_transfer(struct libusb_device_handle *dev_handle, 256 unsigned char endpoint, unsigned char *data, int length, int *transferred, 257 unsigned int timeout) 258{ 259 return do_sync_bulk_transfer(dev_handle, endpoint, data, length, 260 transferred, timeout, LIBUSB_TRANSFER_TYPE_BULK); 261} 262 263/** \ingroup syncio 264 * Perform a USB interrupt transfer. The direction of the transfer is inferred 265 * from the direction bits of the endpoint address. 266 * 267 * For interrupt reads, the <tt>length</tt> field indicates the maximum length 268 * of data you are expecting to receive. If less data arrives than expected, 269 * this function will return that data, so be sure to check the 270 * <tt>transferred</tt> output parameter. 271 * 272 * You should also check the <tt>transferred</tt> parameter for interrupt 273 * writes. Not all of the data may have been written. 274 * 275 * Also check <tt>transferred</tt> when dealing with a timeout error code. 276 * libusb may have to split your transfer into a number of chunks to satisfy 277 * underlying O/S requirements, meaning that the timeout may expire after 278 * the first few chunks have completed. libusb is careful not to lose any data 279 * that may have been transferred; do not assume that timeout conditions 280 * indicate a complete lack of I/O. 281 * 282 * The default endpoint bInterval value is used as the polling interval. 283 * 284 * \param dev_handle a handle for the device to communicate with 285 * \param endpoint the address of a valid endpoint to communicate with 286 * \param data a suitably-sized data buffer for either input or output 287 * (depending on endpoint) 288 * \param length for bulk writes, the number of bytes from data to be sent. for 289 * bulk reads, the maximum number of bytes to receive into the data buffer. 290 * \param transferred output location for the number of bytes actually 291 * transferred. 292 * \param timeout timeout (in millseconds) that this function should wait 293 * before giving up due to no response being received. For an unlimited 294 * timeout, use value 0. 295 * 296 * \returns 0 on success (and populates <tt>transferred</tt>) 297 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out 298 * \returns LIBUSB_ERROR_PIPE if the endpoint halted 299 * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see 300 * \ref packetoverflow 301 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected 302 * \returns another LIBUSB_ERROR code on other error 303 */ 304API_EXPORTED int libusb_interrupt_transfer( 305 struct libusb_device_handle *dev_handle, unsigned char endpoint, 306 unsigned char *data, int length, int *transferred, unsigned int timeout) 307{ 308 return do_sync_bulk_transfer(dev_handle, endpoint, data, length, 309 transferred, timeout, LIBUSB_TRANSFER_TYPE_INTERRUPT); 310} 311 312