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