USBAudioBackend.h

Go to the documentation of this file.

#pragma once
#include <cstddef>
#include <cstdint>
 
namespace audio_tools {
 
enum class UsbDir : uint8_t { Out = 0, In = 1 };
 
enum class UsbXferType : uint8_t {
  Control = 0,
  Isochronous = 1,
  Bulk = 2,
  Interrupt = 3
};
 
enum class UsbSpeed : uint8_t { Full, High, Low, Unknown };
 
enum class UsbXferResult : uint8_t { Success, Failed, Stalled };
 
struct UsbSetupPacket {
  uint8_t bmRequestType = 0;
  uint8_t bRequest = 0;
  uint16_t wValue = 0;
  uint16_t wIndex = 0;
  uint16_t wLength = 0;
 
  enum class Type : uint8_t { Standard = 0, Class = 1, Vendor = 2 };
  enum class Recipient : uint8_t {
    Device = 0,
    Interface = 1,
    Endpoint = 2,
    Other = 3
  };
 
  Type type() const { return (Type)((bmRequestType >> 5) & 0x03); }
  UsbDir direction() const { return (UsbDir)((bmRequestType >> 7) & 0x01); }
  Recipient recipient() const { return (Recipient)(bmRequestType & 0x1F); }
};
 
enum class UsbStdRequest : uint8_t {
  ClearFeature = 1,
  GetInterface = 10,
  SetInterface = 11,
};
 
struct UsbInterfaceDescriptorView {
  uint8_t bInterfaceNumber = 0;
  uint8_t bAlternateSetting = 0;
  uint8_t bNumEndpoints = 0;
  uint8_t bInterfaceClass = 0;
  uint8_t bInterfaceSubClass = 0;
  uint8_t bInterfaceProtocol = 0;
};
 
struct UsbEndpointDescriptorView {
  uint8_t bEndpointAddress = 0;
  UsbXferType xferType = UsbXferType::Control;  // bmAttributes bits[1:0]
  uint8_t sync = 0;   // bmAttributes bits[3:2]: none/async/adaptive/sync
  uint8_t usage = 0;  // bmAttributes bits[5:4]: 0=data,1=feedback,2=implicit
  uint8_t bInterval = 0;
  uint16_t wMaxPacketSize = 0;
 
  UsbDir direction() const {
    return (bEndpointAddress & 0x80) ? UsbDir::In : UsbDir::Out;
  }
  uint16_t packetSize() const { return wMaxPacketSize & 0x7FF; }
};
 
// ── Descriptor byte-walking helpers ───────────────────────────────────────
// Pure byte arithmetic — works identically against any USB stack's raw
// descriptor buffer. Replace TinyUSB's tu_desc_next/_type/_subtype and
// tu_unaligned_read16/32.
 
inline uint8_t const* descNext(uint8_t const* p) { return p + p[0]; }
inline uint8_t descType(uint8_t const* p) { return p[1]; }
inline uint8_t descSubtype(uint8_t const* p) { return p[2]; }
 
inline uint16_t descU16(uint8_t const* p) {
  return (uint16_t)p[0] | ((uint16_t)p[1] << 8);
}
 
inline uint32_t descU32(uint8_t const* p) {
  return (uint32_t)p[0] | ((uint32_t)p[1] << 8) | ((uint32_t)p[2] << 16) |
         ((uint32_t)p[3] << 24);
}
 
inline UsbEndpointDescriptorView decodeEndpoint(uint8_t const* p) {
  UsbEndpointDescriptorView v;
  v.bEndpointAddress = p[2];
  uint8_t attr = p[3];
  v.xferType = (UsbXferType)(attr & 0x03);
  v.sync = (attr >> 2) & 0x03;
  v.usage = (attr >> 4) & 0x03;
  v.wMaxPacketSize = descU16(p + 4);
  v.bInterval = p[6];
  return v;
}
 
inline UsbInterfaceDescriptorView decodeInterface(uint8_t const* p) {
  UsbInterfaceDescriptorView v;
  v.bInterfaceNumber = p[2];
  v.bAlternateSetting = p[3];
  v.bNumEndpoints = p[4];
  v.bInterfaceClass = p[5];
  v.bInterfaceSubClass = p[6];
  v.bInterfaceProtocol = p[7];
  return v;
}
 
class USBAudioBackend {
 public:
  virtual ~USBAudioBackend() = default;
 
  // ── Endpoint lifecycle ──────────────────────────────────────────────────
  virtual bool openEndpoint(uint8_t rhport,
                            const UsbEndpointDescriptorView& ep) = 0;
  virtual bool closeEndpoint(uint8_t rhport, uint8_t ep_addr) = 0;
  virtual bool clearStall(uint8_t rhport, uint8_t ep_addr) = 0;
 
  // ── Isochronous endpoint reservation ────────────────────────────────────
  virtual bool usesIsoAlloc() const = 0;
  virtual bool isoAllocEndpoint(uint8_t rhport, uint8_t ep_addr,
                                uint16_t max_packet_size) = 0;
  virtual bool isoActivateEndpoint(uint8_t rhport,
                                   const UsbEndpointDescriptorView& ep) = 0;
  virtual bool releaseEndpoint(uint8_t rhport, uint8_t ep_addr) = 0;
  virtual bool claimEndpoint(uint8_t rhport, uint8_t ep_addr) = 0;
 
  // ── Linear-buffer data transfer ─────────────────────────────────────────
  virtual bool transfer(uint8_t rhport, uint8_t ep_addr, uint8_t* buffer,
                        uint16_t length) = 0;
 
  // ── Control endpoint (EP0) ──────────────────────────────────────────────
  virtual bool controlTransfer(uint8_t rhport, const UsbSetupPacket& request,
                               uint8_t* buffer, uint16_t length) = 0;
  virtual bool controlStatus(uint8_t rhport,
                             const UsbSetupPacket& request) = 0;
 
  // ── Device / SOF state ───────────────────────────────────────────────────
  virtual UsbSpeed speed() const = 0;
  bool isFullSpeed() const { return speed() == UsbSpeed::Full; }
  bool isHighSpeed() const { return speed() == UsbSpeed::High; }
  virtual bool mounted() const = 0;
  virtual void enableSof(uint8_t rhport, bool enable) = 0;
};
 
}  // namespace audio_tools