src/devices/usb/drivers/mt-musb-host/usb-transaction.h

// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef SRC_DEVICES_USB_DRIVERS_MT_MUSB_HOST_USB_TRANSACTION_H_
#define SRC_DEVICES_USB_DRIVERS_MT_MUSB_HOST_USB_TRANSACTION_H_

#include <lib/mmio/mmio.h>
#include <lib/sync/completion.h>
#include <lib/zircon-internal/thread_annotations.h>
#include <zircon/hw/usb.h>

#include <atomic>

#include <fbl/mutex.h>

namespace mt_usb_hci {

// Transactions are implemented by a state machine whose internal state is advanced through
// subsequent calls to Advance().  Upon being advanced, state machines execute until a hardware
// interrupt is required to further progress, or they enter a terminal state.
class Transaction {
 public:
  virtual ~Transaction() = default;

  // Return the actual number of bytes processed by this transaction.
  virtual size_t actual() const = 0;

  // Advance the transaction machine and return when one of the following is true:
  //   1. The machine is awaiting a hardware IRQ.
  //   2. The machine is in a terminal state.
  // If the machine is awaiting a hardware interrupt, a call to Advance with interrupt=true must
  // be made to further advance the machine's state.  This interrupt call must be made as a result
  // of receiving an endpoint interrupt corresponding to this transaction.
  //
  // If the machine is awaiting a hardware interrupt, any call to Advance(false) is a functional
  // no-op.
  virtual void Advance(bool interrupt = false) = 0;

  // True if the transaction machine has reached a successful state.
  virtual bool Ok() const = 0;

  // From any non-terminal state, cancel this transaction.
  virtual void Cancel() = 0;

  // Block and wait for this transaction to enter a terminal state.
  virtual void Wait() = 0;
};

// The states of a Control machine.  These states map to the control transaction states described in
// MUSBMHDRC section 21.2.
enum class ControlState {
  SETUP,
  SETUP_IRQ,
  IN_DATA,
  IN_DATA_IRQ,
  OUT_DATA,
  OUT_DATA_IRQ,
  IN_STATUS,
  IN_STATUS_IRQ,
  OUT_STATUS,
  OUT_STATUS_IRQ,
  SUCCESS,
  ERROR,
  CANCEL,
};

// The individual types of a Control.  See: MUSBMHDRC section 21.2.
enum class ControlType {
  ZERO,
  READ,
  WRITE,
};

// A Control transaction is a state machine capable of processing USB control-type transfers.  The
// state progression of this machine is described by MUSBMHDRC section 21.2.
class Control : public Transaction {
 public:
  Control(ControlType type, ddk::MmioView usb, const usb_setup_t& req, void* buf, size_t len,
          size_t max_pkt_sz, uint8_t faddr)
      : type_(type),
        usb_(usb),
        req_(req),
        state_(ControlState::SETUP),
        irq_wait_(false),
        terminal_(false),
        buffer_(buf),
        len_(len),
        max_pkt_sz0_(max_pkt_sz),
        actual_(0),
        faddr_(faddr) {}

  ~Control() = default;

  // Assign, copy, and move disallowed.
  Control(Control&&) = delete;
  Control& operator=(Control&&) = delete;

  size_t actual() const override { return actual_.load(); }
  ControlState state() const { return state_.load(); }

  void Advance(bool interrupt = false) override;
  bool Ok() const override { return state_.load() == ControlState::SUCCESS; }
  void Cancel() override;
  void Wait() override { __UNUSED auto _ = sync_completion_wait(&complete_, ZX_TIME_INFINITE); }

 private:
  // Abort the machine with the given state.  Endpoint-FIFOs will be flushed.
  void AbortAs(ControlState state);

  // True if the interrupt-registers indicate a bus-error event has occurred.  See: MUSBMHDRC
  // section 21.2.1.
  bool BusError();

  // Advance from the given state to the next appropriate state.
  // clang-format off
    void AdvanceSetup()        TA_REQ(lock_);
    void AdvanceSetupIrq()     TA_REQ(lock_);
    void AdvanceInData()       TA_REQ(lock_);
    void AdvanceInDataIrq()    TA_REQ(lock_);
    void AdvanceOutData()      TA_REQ(lock_);
    void AdvanceOutDataIrq()   TA_REQ(lock_);
    void AdvanceInStatus()     TA_REQ(lock_);
    void AdvanceInStatusIrq()  TA_REQ(lock_);
    void AdvanceOutStatus()    TA_REQ(lock_);
    void AdvanceOutStatusIrq() TA_REQ(lock_);
    void AdvanceSuccess()      TA_REQ(lock_);
    void AdvanceError()        TA_REQ(lock_);
    void AdvanceCancel()       TA_REQ(lock_);
  // clang-format on

  // The type of this Control.
  const ControlType type_;

  // USB register mmio.
  ddk::MmioView usb_ TA_GUARDED(lock_);

  // The USB control request header, see USB 2.0 spec. section 9.3.
  const usb_setup_t req_;

  // The current Control machine state.
  std::atomic<ControlState> state_;

  // True if the machine is currently awaiting an asynchronous interrupt (i.e. awaiting a call to
  // Advance(true)).
  std::atomic_bool irq_wait_;

  // True if the machine is in a terminal state.
  bool terminal_ TA_GUARDED(lock_);

  // The data buffer corresponding to the transaction.  For ZERO-type transactions, this data
  // buffer is not used.  For WRITE-type transactions, this buffer will be read and its data
  // written to an endpoint-FIFO.  Similarity, for a READ-type transaction, the endpoint-FIFO
  // will be read and its data written to this buffer.  This object does not assume ownership of
  // this pointer.
  void* buffer_ TA_GUARDED(lock_);

  // The buffer size.
  const size_t len_;

  // The maximum control packet size read from the device descriptor during enumeration.
  const size_t max_pkt_sz0_;

  // The actual count of bytes transfered in either a READ or WRITE-type transaction.
  std::atomic_size_t actual_;

  // A completion which is signaled when this transaction is in a terminal state.
  sync_completion_t complete_;

  // A lock used to serialize Advance() operations which are inherently thread-hostile.
  fbl::Mutex lock_;

  // The id of the device this transaction is associated with.
  const uint8_t faddr_;
};

// The states of a BulkTransaction machine.  These states map to the operation described in
// MUSBMHDRC section 22.2.
enum class BulkState {
  SETUP,
  SETUP_IN,
  SETUP_OUT,
  SEND,
  SEND_IRQ,
  RECV,
  RECV_IRQ,
  SUCCESS,
  ERROR,
  CANCEL,
};

// The endpoint's transaction direction (always from the host's perspective).
enum class BulkDirection {
  IN,
  OUT,
};

// A BulkBase transaction is an abstract state machine whose derived types are capable of processing
// bulk-like transfers (e.g. bulk, interrupt, etc...).  Concrete subclasses need to provide an
// implementation of:
//   - AdvanceSetupIn()
//   - AdvanceSetupOut()
//
// Once configured with the necessary setup logic, the transaction will proceed in a manner
// consistent with MUSBMHDRC chapter 22.
class BulkBase : public Transaction {
 public:
  BulkBase(ddk::MmioView usb, void* buf, size_t len, const usb_endpoint_descriptor_t& desc)
      : state_(BulkState::SETUP),
        ep_(usb_ep_num(&desc)),
        max_pkt_sz_(usb_ep_max_packet(&desc)),
        usb_(usb),
        dir_(usb_ep_direction(&desc) ? BulkDirection::IN : BulkDirection::OUT),
        irq_wait_(false),
        terminal_(false),
        buffer_(buf),
        len_(len),
        actual_(0) {}

  ~BulkBase() = default;

  // Assign, copy, and move disallowed.
  BulkBase(BulkBase&&) = delete;
  BulkBase& operator=(BulkBase&&) = delete;

  size_t actual() const override { return actual_.load(); }
  BulkState state() const { return state_.load(); }

  void Advance(bool interrupt = false) override;
  bool Ok() const override { return state_.load() == BulkState::SUCCESS; }
  void Cancel() override;
  void Wait() override { __UNUSED auto _ = sync_completion_wait(&complete_, ZX_TIME_INFINITE); }

 protected:
  // The current machine state.
  std::atomic<BulkState> state_;

  // The endpoint which this transaction is associated with.
  const uint8_t ep_;

  // The maximum bulk packet size read from the endpoint descriptor.
  const size_t max_pkt_sz_;

  // USB register mmio.
  ddk::MmioView usb_ TA_GUARDED(lock_);

 private:
  // Abort the machine with the given state.  All endpoint-FIFOs will be flushed.
  void AbortAs(BulkState state);

  // True if the interrupt-registers indicate a bus-error event has occurred.
  bool BusError();

  // Advance from the given state to the next appropriate state.
  // clang-format off
    void AdvanceSetup()            TA_REQ(lock_);
    virtual void AdvanceSetupIn()  TA_REQ(lock_) = 0;
    virtual void AdvanceSetupOut() TA_REQ(lock_) = 0;
    void AdvanceSend()             TA_REQ(lock_);
    void AdvanceSendIrq()          TA_REQ(lock_);
    void AdvanceRecv()             TA_REQ(lock_);
    void AdvanceRecvIrq()          TA_REQ(lock_);
    void AdvanceSuccess()          TA_REQ(lock_);
    void AdvanceError()            TA_REQ(lock_);
    void AdvanceCancel()           TA_REQ(lock_);
  // clang-format on

  // The endpoint direction for this transaction.
  const BulkDirection dir_;

  // True if the machine is currently awaiting an asynchronous interrupt (i.e. awaiting a call to
  // Advance(true)).
  std::atomic_bool irq_wait_;

  // True if the machine is in a terminal state.
  bool terminal_ TA_GUARDED(lock_);

  // The data buffer corresponding to the transaction.  For transactions corresponding to OUT-type
  // endpoints, this data will be read and transfered to the device.  Similarily, for IN-type
  // endpoints, device data will be read and written to this buffer.
  void* buffer_ TA_GUARDED(lock_);

  // The buffer size.
  const size_t len_;

  // True if a block of transferred data was aligned to the packet size.  Note that a zero-length
  // transfer is not considered packet aligned.
  bool pkt_aligned_ TA_GUARDED(lock_);

  // The actual count of bytes transfered in either an IN or OUT-type transaction.  If more than
  // max_pkt_sz_ bytes need to be read/written, this value accumulates the total count of bytes as
  // multiple packets are processed.  The total number of bytes read/written will be available
  // when the machine reaches a terminal state.
  std::atomic_size_t actual_;

  // A completion which is signaled when this transaction is in a terminal state.
  sync_completion_t complete_;

  // A lock used to serialize Advance() operations which are inherently thread-hostile.
  fbl::Mutex lock_;
};

// A Bulk transaction is a state machine capable of processing USB Bulk-type transfers.  The state
// progression of this machine is described by MUSBMHDRC chapter 22.
class Bulk : public BulkBase {
 public:
  Bulk(ddk::MmioView usb, uint8_t faddr, void* buf, size_t len,
       const usb_endpoint_descriptor_t& desc)
      : BulkBase(usb, buf, len, desc), interval_(desc.bInterval), faddr_(faddr) {}

 private:
  // Configure MUSBMHDRC for USB Bulk-type transfer.  See: MUSBMHDRC section 22.2.
  void AdvanceSetupIn() override;
  void AdvanceSetupOut() override;

  // The bulk-transfer NAK timeout window.
  const uint8_t interval_;

  // The id of the device this transaction is associated with.
  const uint8_t faddr_;
};

// An Interrupt transaction is a state machine capable of processing USB bulk-type transfers.  The
// state progression of this machine is described by MUSBMHDRC chapter 23.
class Interrupt : public BulkBase {
 public:
  Interrupt(ddk::MmioView usb, uint8_t faddr, void* buf, size_t len,
            const usb_endpoint_descriptor_t& desc)
      : BulkBase(usb, buf, len, desc), interval_(desc.bInterval), faddr_(faddr) {}

 private:
  // Configure MUSBMHDRC for USB Interrupt-type transfer.  See: MUSBMHDRC section 23.2.
  void AdvanceSetupIn() override;
  void AdvanceSetupOut() override;

  // The data transfer endpoint polling period read from the endpoint descriptor.
  const uint8_t interval_;

  // The id of the device this transaction is associated with.
  const uint8_t faddr_;
};

}  // namespace mt_usb_hci

#endif  // SRC_DEVICES_USB_DRIVERS_MT_MUSB_HOST_USB_TRANSACTION_H_