src/jtag/drivers/libusb_helper.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2
   3 /***************************************************************************
   4  *   Copyright (C) 2009 by Zachary T Welch <zw@superlucidity.net>          *
   5  *                                                                         *
   6  *   Copyright (C) 2011 by Mauro Gamba <maurillo71@gmail.com>              *
   7  ***************************************************************************/
   8
   9 #ifndef OPENOCD_JTAG_DRIVERS_LIBUSB_HELPER_H
  10 #define OPENOCD_JTAG_DRIVERS_LIBUSB_HELPER_H
  11
  12 #include <libusb.h>
  13
  14 /* When we debug a target that works as a USB device, halting the target causes the
  15  * USB communication with the USB host to become unresponsive. The host will try
  16  * to reconnect/reset/setup the unresponsive device during which communication
  17  * with other devices on the same USB bus can get stalled for several seconds.
  18  * If the JTAG adapter is on the same bus, we need to make sure openOCD will wait
  19  * for packets at least as long as the host USB stack. Otherwise the USB stack
  20  * might deliver a valid packet, but openOCD would ignore it due to the timeout.
  21  * The xHCI spec uses 5 sec timeouts, so let's use that in openOCD with some margin.
  22  *
  23  * Use this value in all libusb calls. HID API might have a libusb backend and
  24  * would probably be victim to the same bug, so it should use this timeout, too.
  25  */
  26 #define LIBUSB_TIMEOUT_MS       (6000)
  27
  28 /* this callback should return a non NULL value only when the serial could not
  29  * be retrieved by the standard 'libusb_get_string_descriptor_ascii' */
  30 typedef char * (*adapter_get_alternate_serial_fn)(struct libusb_device_handle *device,
  31                 struct libusb_device_descriptor *dev_desc);
  32
  33 bool jtag_libusb_match_ids(struct libusb_device_descriptor *dev_desc,
  34                 const uint16_t vids[], const uint16_t pids[]);
  35 int jtag_libusb_open(const uint16_t vids[], const uint16_t pids[],
  36                 const char *product, struct libusb_device_handle **out,
  37                 adapter_get_alternate_serial_fn adapter_get_alternate_serial);
  38 void jtag_libusb_close(struct libusb_device_handle *dev);
  39 int jtag_libusb_control_transfer(struct libusb_device_handle *dev,
  40                 uint8_t request_type, uint8_t request, uint16_t value,
  41                 uint16_t index, char *bytes, uint16_t size, unsigned int timeout,
  42                 int *transferred);
  43 int jtag_libusb_bulk_write(struct libusb_device_handle *dev, int ep,
  44                 char *bytes, int size, int timeout, int *transferred);
  45 int jtag_libusb_bulk_read(struct libusb_device_handle *dev, int ep,
  46                 char *bytes, int size, int timeout, int *transferred);
  47 int jtag_libusb_set_configuration(struct libusb_device_handle *devh,
  48                 int configuration);
  49 /**
  50  * Find the first interface optionally matching class, subclass and
  51  * protocol and claim it.
  52  * @param devh _libusb_ device handle.
  53  * @param usb_read_ep A pointer to a variable where the _IN_ endpoint
  54  *      number will be stored.
  55  * @param usb_write_ep A pointer to a variable where the _OUT_ endpoint
  56  *      number will be stored.
  57  * @param bclass `bInterfaceClass` to match, or -1 to ignore this field.
  58  * @param subclass `bInterfaceSubClass` to match, or -1 to ignore this field.
  59  * @param protocol `bInterfaceProtocol` to match, or -1 to ignore this field.
  60  * @param trans_type `bmAttributes Bits 0..1 Transfer type` to match, or -1 to ignore this field.
  61  * @returns Returns ERROR_OK on success, ERROR_FAIL otherwise.
  62  */
  63 int jtag_libusb_choose_interface(struct libusb_device_handle *devh,
  64                 unsigned int *usb_read_ep,
  65                 unsigned int *usb_write_ep,
  66                 int bclass, int subclass, int protocol, int trans_type);
  67 int jtag_libusb_get_pid(struct libusb_device *dev, uint16_t *pid);
  68 int jtag_libusb_handle_events_completed(int *completed);
  69
  70 /**
  71  * Attempts to allocate a block of persistent DMA memory suitable for transfers
  72  * against the USB device. Fall-back to the ordinary heap malloc()
  73  * if the first libusb_dev_mem_alloc() call fails.
  74  * @param devh _libusb_ device handle.
  75  * @param length size of desired data buffer
  76  * @returns a pointer to the newly allocated memory, or NULL on failure
  77  */
  78 uint8_t *oocd_libusb_dev_mem_alloc(libusb_device_handle *devh,
  79                         size_t length);
  80
  81 /**
  82  * Free device memory allocated with oocd_libusb_dev_mem_alloc().
  83  * Uses either libusb_dev_mem_free() or free() consistently with
  84  * the used method of allocation.
  85  * @param devh _libusb_ device handle.
  86  * @param buffer pointer to the previously allocated memory
  87  * @param length size of desired data buffer
  88  * @returns Returns ERROR_OK on success, ERROR_FAIL otherwise.
  89  */
  90 int oocd_libusb_dev_mem_free(libusb_device_handle *devh,
  91                         uint8_t *buffer, size_t length);
  92
  93 #endif /* OPENOCD_JTAG_DRIVERS_LIBUSB_HELPER_H */