libusb/sync.c

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