usb_device.h

// Copyright lowRISC contributors (OpenTitan project).
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
#ifndef OPENTITAN_SW_HOST_TESTS_USBDEV_USBDEV_STREAM_USB_DEVICE_H_
#define OPENTITAN_SW_HOST_TESTS_USBDEV_USBDEV_STREAM_USB_DEVICE_H_
#include <iostream>
 
// The 'usbdev_serial' class may be used on platforms where libusb support is
// not available; libusb is required to exercise Isochronous streams, Interrupt
// streams and Control Transfers.
#if STREAMTEST_LIBUSB
#include <libusb-1.0/libusb.h>
#endif
 
class USBDevice {
 public:
#if STREAMTEST_LIBUSB
  USBDevice(bool verbose = false, bool manual = false)
      : verbose_(verbose),
        manual_(manual),
        state_(StateStreaming),
        ctx_(nullptr),
        devh_(nullptr) {}
#else
  USBDevice(bool verbose = false, bool manual = false)
      : verbose_(verbose),
        manual_(manual),
        state_(StateStreaming),
        devh_(false) {}
#endif
 
  // Device states.
  enum USBDevState {
    StateStreaming,
    StateSuspending,
    StateSuspended,
    StateResuming
  };
 
  /**
   * Test phases; named according to the event that we are expecting to occur.
   */
  typedef enum {
    /**
     * First test phase just tests regular Suspend/Resume signaling; after we've
     * resumed, we expect a Bus Reset from the DPI/Host.
     */
    kSuspendPhaseSuspend = 0u,
    /**
     * This test phase instructs the DPI model to put the DUT into Suspend long
     * enough that this software will attempt to put the device into its Normal
     * Sleep state and exercise the AON/Wakeup module, stopping the clocks but
     * not powering down.
     */
    kSuspendPhaseSleepResume,
    /*
     * The AON/Wakeup module will cause us to awaken in response to a bus reset.
     */
    kSuspendPhaseSleepReset,
    /**
     * As above, but this time we're expecting a VBUS/SENSE loss.
     */
    kSuspendPhaseSleepDisconnect,
    /**
     * Mirrors Resume detection for normal sleep, but this time we enter Deep
     * Sleep and the power is removed too.
     */
    kSuspendPhaseDeepResume,
    /**
     * Mirrors Bus Reset detection for normal sleep, but this time we enter Deep
     * Sleep and the power is removed too.
     */
    kSuspendPhaseDeepReset,
    /**
     * As above, but this time we're expecting a VBUS/SENSE loss.
     */
    kSuspendPhaseDeepDisconnect,
    /**
     * Final phase; shut down.
     */
    kSuspendPhaseShutdown,
  } usbdev_suspend_phase_t;
 
  // DPI test numbers.
  typedef enum usb_testutils_test_number {
    kUsbTestNumberSmoke = 0,
    kUsbTestNumberStreams,
    kUsbTestNumberIso,
    kUsbTestNumberMixed,
    kUsbTestNumberSuspend,
    kUsbTestNumberExc,
  } usb_testutils_test_number_t;
 
  // Test/stream flags; these are common with device-side software.
  typedef enum {
    /**
     * Mask for extracting the stream ID number.
     */
    kUsbdevStreamFlagID = 0x0FU,
    /**
     * Host shall retrieve IN data from the device for this stream.
     */
    kUsbdevStreamFlagRetrieve = 0x10U,
    /**
     * Host shall check that IN data matches as expected.
     */
    kUsbdevStreamFlagCheck = 0x20U,
    /**
     * DPI model (or Host) shall retry IN data fetches, where possible.
     */
    kUsbdevStreamFlagRetry = 0x40U,
    /**
     * Host shall send OUT data to the device for this stream.
     */
    kUsbdevStreamFlagSend = 0x80U,
    /**
     * Default stream flags; for non-libusb builds.
     */
    kUsbdevStreamFlagsDefault = kUsbdevStreamFlagRetrieve |
                                kUsbdevStreamFlagCheck |
                                kUsbdevStreamFlagRetry | kUsbdevStreamFlagSend
  } usbdev_stream_flags_t;
 
  // Vendor-Specific requests.
  static constexpr uint8_t kVendorGetData = 0x7du;
  static constexpr uint8_t kVendorPutData = 0x7fu;
 
  // Maximum packet size of 64 bytes is used for Control, Interrupt and Bulk
  // Transfers.
  static constexpr unsigned kDevDataMaxPacketSize = 0x40U;
 
  // Our USB device has a maximum packet size of just 64 bytes even for
  // Isochronous transfers; this may one day be increased.
  static constexpr unsigned kDevIsoMaxPacketSize = 0x40U;
 
  /**
   * Initialize USB device before test; called once at startup.
   *
   * @param  vendorID   Vendor ID code of the USB device.
   * @param  productID  Product ID code of the USB device.
   * @param  devAddress Device address (0 for first accessible device).
   * @param  busNumber  Bus number (if devAddress non-zero).
   * @return true iff initialization was successful.
   */
  bool Init(uint16_t productID, uint16_t vendorID, uint8_t devAddress = 0u,
            uint8_t busNumber = 0u);
  /**
   * Finalize USB device before completing test.
   *
   * @return true iff finalization was successful.
   */
  bool Fin();
  /**
   * (Re)open the device. If the device is already open, this function just
   * returns immediately.
   *
   * @return true iff opening was successful, or the device was already open.
   */
  bool Open();
  /**
   * Close the device, if open. If the device is already closed, this function
   * just returns immediately.
   *
   * @return true iff closing was successful, or the device was already closed.
   */
  bool Close();
  /**
   * Service the device; keep libusb transfers being processed.
   *
   * @return true iff the device is still operational.
   */
  bool Service();
 
#if STREAMTEST_LIBUSB
  /**
   * Claim an interface on the device.
   *
   * @param interface The interface number of the interface to be claimed.
   * @return The result of the operation.
   */
  int ClaimInterface(unsigned interface) const {
    return libusb_claim_interface(devh_, (int)interface);
  }
  /**
   * Release an interface on the device.
   *
   * @param interface The interface number of the interface to be claimed.
   * @return The result of the operation.
   */
  int ReleaseInterface(unsigned interface) const {
    return libusb_release_interface(devh_, (int)interface);
  }
  /**
   * Emit a textual report of an error returned by libusb.
   *
   * @param  rc      Return code from libusb function.
   * @return false as a convenience for indicating failure to caller.
   */
  inline bool ErrorUSB(const char *prefix, int rc) {
    std::cerr << prefix << " (" << rc << ", " << libusb_error_name(rc) << ")"
              << std::endl;
    return false;
  }
  /**
   * Retrieve libusb device handle.
   *
   * @return The device handle, or nullptr if none eg. device not open.
   */
  libusb_device_handle *DeviceHandle() const { return devh_; }
  /**
   * Fill Control Transfer descriptor.
   */
  void FillControlTransfer(struct libusb_transfer *xfr, uint8_t ep,
                           uint8_t *buffer, libusb_transfer_cb_fn callback,
                           void *user_data, unsigned timeout_ms) {
    libusb_fill_control_transfer(xfr, devh_, buffer, callback, user_data,
                                 timeout_ms);
    // Complete the endpoint number because we're _not_ always targeting
    // Endpoint Zero.
    xfr->endpoint = ep;
  }
  /**
   * Fill Bulk Transfer descriptor.
   */
  void FillBulkTransfer(struct libusb_transfer *xfr, uint8_t ep,
                        uint8_t *buffer, size_t len,
                        libusb_transfer_cb_fn callback, void *user_data,
                        unsigned timeout_ms) const {
    libusb_fill_bulk_transfer(xfr, devh_, ep, buffer, len, callback, user_data,
                              timeout_ms);
  }
  /**
   * Fill Interrupt Transfer descriptor.
   */
  void FillIntTransfer(struct libusb_transfer *xfr, uint8_t ep, uint8_t *buffer,
                       size_t len, libusb_transfer_cb_fn callback,
                       void *user_data, unsigned timeout_ms) const {
    libusb_fill_interrupt_transfer(xfr, devh_, ep, buffer, len, callback,
                                   user_data, timeout_ms);
  }
  /**
   * Fill Isochronous transfer descriptor,
   */
  void FillIsoTransfer(struct libusb_transfer *xfr, uint8_t ep, uint8_t *buffer,
                       size_t len, unsigned num_iso_packets,
                       libusb_transfer_cb_fn callback, void *user_data,
                       unsigned timeout_ms) const {
    libusb_fill_iso_transfer(xfr, devh_, ep, buffer, len, num_iso_packets,
                             callback, user_data, timeout_ms);
  }
  /**
   * Complete the lengths of the packets in this Isochronous transfer, assuming
   * that packets are of uniform size.
   *
   * @param  xfr     Isochronous transfer to be completed.
   * @param  len     Total length of all packets within the transfer.
   */
  void SetIsoPacketLengths(struct libusb_transfer *xfr, unsigned len) const {
    libusb_set_iso_packet_lengths(xfr, len);
  }
  /**
   * Allocate a transfer descriptor to be completed by the caller.
   *
   * @return  Pointer to transfer transcript, or NULL if allocation failed.
   */
  struct libusb_transfer *AllocTransfer(unsigned iso_packets) const {
    return libusb_alloc_transfer((int)iso_packets);
  }
  /**
   * Free an allocated transfer descriptor.
   *
   * @param  xfr     The transfer descriptor to be freed.
   */
  void FreeTransfer(struct libusb_transfer *xfr) const {
    return libusb_free_transfer(xfr);
  }
  /**
   * Submit a transfer for processing.
   *
   * @param  xfr     The transfer to be submitted.
   */
  int SubmitTransfer(struct libusb_transfer *xfr) const {
    return libusb_submit_transfer(xfr);
  }
  /**
   * Cancel a pending transfer.
   *
   * @param  xfr     The transfer to be cancelled.
   */
  int CancelTransfer(struct libusb_transfer *xfr) const {
    return libusb_cancel_transfer(xfr);
  }
#endif
  /**
   * Is test progress being directed/controlled manually?
   */
  inline bool ManualControl() const { return manual_; }
  /**
   * Returns the current phase of the test
   */
  inline usbdev_suspend_phase_t TestPhase() const { return testPhase_; }
  /**
   * Returns microseconds corresponding to the given number of bus frame delays.
   */
  static inline uint32_t TimeFrames(unsigned frames) { return frames * 1000u; }
  /**
   * Delay for at least the requested number of microseconds (wall time);
   * this is important in ensuring the appropriate time intervals (eg. Resume
   * Signaling) are met.
   *
   * For verbose reporting, the also indicates whether traffic is expected, and
   * may be visually paired up with any device-side logging or logic analyzer
   * traces.
   *
   * @param time_us      Minimum time delay, in microseconds.
   * @param with_traffic Indicates whether USB traffic is expected during this
   * time.
   * @return true iff delayed without error
   */
  bool Delay(uint32_t time_us, bool with_traffic = true);
  /**
   * Read Test Descriptor from the DUT using a Vendor-Specific command.
   *
   * @return true iff the operation was successful.
   */
  bool ReadTestDesc();
  /**
   * Return the test number from the test descriptor.
   *
   * @return test number
   */
  uint8_t TestNumber() const { return testNumber_; }
  /**
   * Return the specified test argument from the test descriptor.
   *
   * @param  arg     Argument number.
   * @return test argument
   */
  uint8_t TestArg(unsigned arg) const {
    // Presently all defined tests support up to 4 arguments.
    return (arg < 4U) ? testArg_[arg] : 0U;
  }
  /**
   * Reset and Reconfigure the DUT.
   *
   * @return true iff the operation was successful.
   */
  bool Reset();
  /**
   * Suspend device.
   *
   * @return true iff the operation was successful.
   */
  bool Suspend();
  /**
   * Resume operation of suspended device.
   */
  bool Resume();
  /**
   * Connect device to the USB.
   *
   * @param true iff the operation was succesful.
   */
  bool Connect();
  /**
   * Disconnect device from the USB.
   *
   * @param true iff the operation was succesful.
   */
  bool Disconnect();
  /**
   * Return the textual name of the specified test phase.
   *
   * @param  phase     Test phase.
   * @return           Textual name.
   */
  static const char *PhaseName(usbdev_suspend_phase_t phase);
  /**
   * Returns the current state of the device.
   *
   * @return current state.
   */
  USBDevState CurrentState() const { return state_; }
  /**
   * Sets the current state of the device in the Suspend/Resume signaling.
   *
   * @param  state   The current state of the device.
   */
  void SetState(USBDevState state) { state_ = state; }
 
 private:
  // Verbose logging/reporting.
  bool verbose_;
 
  // Test phases/behavior are being directed/controlled manually.
  bool manual_;
 
  // Current device state.
  USBDevState state_;
 
  // Vendor ID of USB device.
  uint16_t vendorID_;
  // Product ID of USB device.
  uint16_t productID_;
 
  // Specified bus number.
  uint8_t busSpec_;
  // Specified device address.
  uint8_t addrSpec_;
 
  // Bus number of the device we're using.
  uint8_t busNumber_;
  // (Bus-local) device address of the device we're using.
  uint8_t devAddress_;
 
#if STREAMTEST_LIBUSB
  // Context information for libusb.
  libusb_context *ctx_;
 
  // Device handle.
  libusb_device_handle *devh_;
 
  // Parent device handler.
  libusb_device_handle *parenth_;
  int portNumber_;
 
  // Device descriptor.
  libusb_device_descriptor devDesc_;
#else
  // Device handle; just retain whether open/closed.
  bool devh_;
#endif
 
  // Device path (bus number - ports numbers).
  std::string devPath_;
 
  // Current phase within the Suspend-Sleep-Wakeup-Resume testing sequence.
  usbdev_suspend_phase_t testPhase_;
 
  usb_testutils_test_number_t testNumber_;
 
  uint8_t testArg_[4];
 
  // TODO: We should introduce a timeout on libusb Control Transfers.
  static const unsigned kControlTransferTimeout = 0u;
 
  // Vendor-Specific Commands.
  static const uint8_t kVendorTestConfig = 0x7cu;
  static const uint8_t kVendorTestStatus = 0x7eu;
};
 
#endif  // OPENTITAN_SW_HOST_TESTS_USBDEV_USBDEV_STREAM_USB_DEVICE_H_