libusb/sync.c

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