src/jtag/drivers/libusb_helper.h

   1 /***************************************************************************
   2  *   Copyright (C) 2009 by Zachary T Welch <zw@superlucidity.net>          *
   3  *                                                                         *
   4  *   Copyright (C) 2011 by Mauro Gamba <maurillo71@gmail.com>              *
   5  *                                                                         *
   6  *   This program is free software; you can redistribute it and/or modify  *
   7  *   it under the terms of the GNU General Public License as published by  *
   8  *   the Free Software Foundation; either version 2 of the License, or     *
   9  *   (at your option) any later version.                                   *
  10  *                                                                         *
  11  *   This program is distributed in the hope that it will be useful,       *
  12  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  14  *   GNU General Public License for more details.                          *
  15  *                                                                         *
  16  *   You should have received a copy of the GNU General Public License     *
  17  *   along with this program.  If not, see <http://www.gnu.org/licenses/>. *
  18  ***************************************************************************/
  19
  20 #ifndef OPENOCD_JTAG_DRIVERS_LIBUSB_HELPER_H
  21 #define OPENOCD_JTAG_DRIVERS_LIBUSB_HELPER_H
  22
  23 #include <libusb.h>
  24
  25 /* When we debug a target that works as a USB device, halting the target causes the
  26  * USB communication with the USB host to become unresponsive. The host will try
  27  * to reconnect/reset/setup the unresponsive device during which communication
  28  * with other devices on the same USB bus can get stalled for several seconds.
  29  * If the JTAG adapter is on the same bus, we need to make sure openOCD will wait
  30  * for packets at least as long as the host USB stack. Otherwise the USB stack
  31  * might deliver a valid packet, but openOCD would ignore it due to the timeout.
  32  * The xHCI spec uses 5 sec timeouts, so let's use that in openOCD with some margin.
  33  *
  34  * Use this value in all libusb calls. HID API might have a libusb backend and
  35  * would probably be victim to the same bug, so it should use this timeout, too.
  36  */
  37 #define LIBUSB_TIMEOUT_MS       (6000)
  38
  39 /* this callback should return a non NULL value only when the serial could not
  40  * be retrieved by the standard 'libusb_get_string_descriptor_ascii' */
  41 typedef char * (*adapter_get_alternate_serial_fn)(struct libusb_device_handle *device,
  42                 struct libusb_device_descriptor *dev_desc);
  43
  44 int jtag_libusb_open(const uint16_t vids[], const uint16_t pids[],
  45                 struct libusb_device_handle **out,
  46                 adapter_get_alternate_serial_fn adapter_get_alternate_serial);
  47 void jtag_libusb_close(struct libusb_device_handle *dev);
  48 int jtag_libusb_control_transfer(struct libusb_device_handle *dev,
  49                 uint8_t request_type, uint8_t request, uint16_t value,
  50                 uint16_t index, char *bytes, uint16_t size, unsigned int timeout);
  51 int jtag_libusb_bulk_write(struct libusb_device_handle *dev, int ep,
  52                 char *bytes, int size, int timeout, int *transferred);
  53 int jtag_libusb_bulk_read(struct libusb_device_handle *dev, int ep,
  54                 char *bytes, int size, int timeout, int *transferred);
  55 int jtag_libusb_set_configuration(struct libusb_device_handle *devh,
  56                 int configuration);
  57 /**
  58  * Find the first interface optionally matching class, subclass and
  59  * protocol and claim it.
  60  * @param devh _libusb_ device handle.
  61  * @param usb_read_ep A pointer to a variable where the _IN_ endpoint
  62  *      number will be stored.
  63  * @param usb_write_ep A pointer to a variable where the _OUT_ endpoint
  64  *      number will be stored.
  65  * @param bclass `bInterfaceClass` to match, or -1 to ignore this field.
  66  * @param subclass `bInterfaceSubClass` to match, or -1 to ignore this field.
  67  * @param protocol `bInterfaceProtocol` to match, or -1 to ignore this field.
  68  * @param trans_type `bmAttributes Bits 0..1 Transfer type` to match, or -1 to ignore this field.
  69  * @returns Returns ERROR_OK on success, ERROR_FAIL otherwise.
  70  */
  71 int jtag_libusb_choose_interface(struct libusb_device_handle *devh,
  72                 unsigned int *usb_read_ep,
  73                 unsigned int *usb_write_ep,
  74                 int bclass, int subclass, int protocol, int trans_type);
  75 int jtag_libusb_get_pid(struct libusb_device *dev, uint16_t *pid);
  76 int jtag_libusb_handle_events_completed(int *completed);
  77
  78 #endif /* OPENOCD_JTAG_DRIVERS_LIBUSB_HELPER_H */