hid.hpp

#pragma once
#include <cstring>
 
#include "dev_core.hpp"
#include "libxr_mem.hpp"
#include "usb/core/desc_cfg.hpp"
 
namespace LibXR::USB
{
 
template <size_t REPORT_DESC_LEN, size_t TX_REPORT_LEN, size_t RX_REPORT_LEN = 0>
class HID : public DeviceClass
{
 public:
  // 暴露单接口的 HID 功能默认使用这个接口字符串。
  // Default interface string for HID functions that expose one interface.
  static constexpr const char* DEFAULT_INTERFACE_STRING = "XRUSB HID";
 
  enum class HIDDescriptorType : uint8_t
  {
    HID = 0x21,      
    REPORT = 0x22,   
    PHYSICAL = 0x23  
  };
 
  enum class ClassRequest : uint8_t
  {
    GET_REPORT = 0x01,    
    GET_IDLE = 0x02,      
    GET_PROTOCOL = 0x03,  
    SET_REPORT = 0x09,    
    SET_IDLE = 0x0A,      
    SET_PROTOCOL = 0x0B   
  };
 
  enum class Protocol : uint8_t
  {
    BOOT = 0x00,   
    REPORT = 0x01  
  };
 
  enum class ReportType : uint8_t
  {
    INPUT = 1,   
    OUTPUT = 2,  
    FEATURE = 3  
  };
 
#pragma pack(push, 1)
  struct HIDDescriptor
  {
    uint8_t bLength;                    
    HIDDescriptorType bDescriptorType;  
    uint16_t bcdHID;                    
    uint8_t bCountryCode;               
    uint8_t bNumDescriptors;  
    HIDDescriptorType
        bReportDescriptorType;         
    uint16_t wReportDescriptorLength;  
  };
 
  struct HIDDescBlockIN
  {
    InterfaceDescriptor intf;  
    HIDDescriptor hid;         
    EndpointDescriptor ep_in;  
  };
 
  struct HIDDescBlockINOUT
  {
    InterfaceDescriptor intf;   
    HIDDescriptor hid;          
    EndpointDescriptor ep_in;   
    EndpointDescriptor ep_out;  
  };
#pragma pack(pop)
 
  HID(bool enable_out_endpoint = false, uint8_t in_ep_interval = 10,
      uint8_t out_ep_interval = 10,
      Endpoint::EPNumber in_ep_num = Endpoint::EPNumber::EP_AUTO,
      Endpoint::EPNumber out_ep_num = Endpoint::EPNumber::EP_AUTO,
      const char* interface_string = DEFAULT_INTERFACE_STRING)
      : in_ep_interval_(in_ep_interval),
        out_ep_interval_(out_ep_interval),
        in_ep_num_(in_ep_num),
        out_ep_num_(out_ep_num),
        enable_out_endpoint_(enable_out_endpoint),
        interface_string_(interface_string)
  {
  }
 
  const char* GetInterfaceString(size_t local_interface_index) const override
  {
    // HID 只暴露一个接口。
    // HID contributes exactly one interface.
    return (local_interface_index == 0u) ? interface_string_ : nullptr;
  }
 
 protected:
  void BindEndpoints(EndpointPool& endpoint_pool, uint8_t start_itf_num, bool) override
  {
    inited_ = false;
    itf_num_ = start_itf_num;
    ep_in_ = nullptr;
    ep_out_ = nullptr;
 
    // 获取IN端点
    auto ans = endpoint_pool.Get(ep_in_, Endpoint::Direction::IN, in_ep_num_);
    ASSERT(ans == ErrorCode::OK);
    ep_in_->Configure(
        {Endpoint::Direction::IN, Endpoint::Type::INTERRUPT, TX_REPORT_LEN});
 
    if (enable_out_endpoint_)
    {
      ans = endpoint_pool.Get(ep_out_, Endpoint::Direction::OUT, out_ep_num_);
      ASSERT(ans == ErrorCode::OK);
      ep_out_->Configure(
          {Endpoint::Direction::OUT, Endpoint::Type::INTERRUPT, RX_REPORT_LEN});
    }
 
    // 填充接口描述符
    desc_.intf = {
        9,                                                   // bLength
        static_cast<uint8_t>(DescriptorType::INTERFACE),     // bDescriptorType
        static_cast<uint8_t>(itf_num_),                      // bInterfaceNumber
        0,                                                   // bAlternateSetting
        static_cast<uint8_t>(enable_out_endpoint_ ? 2 : 1),  // bNumEndpoints
        0x03,                                                // bInterfaceClass (HID)
        0x00,                                                // bInterfaceSubClass
        0x00,                        // bInterfaceProtocol (可选键盘/鼠标设置1/2)
        GetInterfaceStringIndex(0u)  // iInterface
    };
 
    // 填充HID描述符
    desc_.hid = {9,
                 HIDDescriptorType::HID,
                 0x0111,  // HID v1.11
                 0x00,    // 国家码
                 0x01,    // 只有一个后续描述符（Report Desc）
                 HIDDescriptorType::REPORT,
                 REPORT_DESC_LEN};
 
    // 填充IN端点描述符
    desc_.ep_in = {
        7,
        static_cast<uint8_t>(DescriptorType::ENDPOINT),
        ep_in_->GetAddress(),
        static_cast<uint8_t>(Endpoint::Type::INTERRUPT),
        TX_REPORT_LEN,
        in_ep_interval_  // 轮询间隔ms
    };
 
    // 填充OUT端点描述符（如启用）
    if (enable_out_endpoint_)
    {
      desc_.ep_out = {7,
                      static_cast<uint8_t>(DescriptorType::ENDPOINT),
                      ep_out_->GetAddress(),
                      static_cast<uint8_t>(Endpoint::Type::INTERRUPT),
                      RX_REPORT_LEN,
                      out_ep_interval_};
    }
 
    // 设置最终数据指针
    if (enable_out_endpoint_)
    {
      SetData(RawData{reinterpret_cast<uint8_t*>(&desc_), sizeof(HIDDescBlockINOUT)});
    }
    else
    {
      SetData(RawData{reinterpret_cast<uint8_t*>(&desc_), sizeof(HIDDescBlockIN)});
    }
 
    ep_in_->SetOnTransferCompleteCallback(on_data_in_complete_cb_);
 
    if (enable_out_endpoint_)
    {
      ep_out_->SetOnTransferCompleteCallback(on_data_out_complete_cb_);
      ep_out_->Transfer(RX_REPORT_LEN);
    }
 
    inited_ = true;
  }
 
  static void OnDataOutCompleteStatic(bool in_isr, HID* self, LibXR::ConstRawData& data)
  {
    if (self == nullptr || !self->inited_ || self->ep_out_ == nullptr)
    {
      return;
    }
    self->OnDataOutComplete(in_isr, data);
    self->ep_out_->Transfer(RX_REPORT_LEN);
  }
 
  static void OnDataInCompleteStatic(bool in_isr, HID* self, LibXR::ConstRawData& data)
  {
    if (self == nullptr || !self->inited_ || self->ep_in_ == nullptr)
    {
      return;
    }
    self->OnDataInComplete(in_isr, data);
  }
 
  virtual void OnDataOutComplete(bool in_isr, LibXR::ConstRawData& data)
  {
    UNUSED(in_isr);
    UNUSED(data);
  }
 
  virtual void OnDataInComplete(bool in_isr, LibXR::ConstRawData& data)
  {
    UNUSED(in_isr);
    UNUSED(data);
  }
 
  void UnbindEndpoints(EndpointPool& endpoint_pool, bool) override
  {
    inited_ = false;
    if (ep_in_)
    {
      ep_in_->Close();
      endpoint_pool.Release(ep_in_);
      ep_in_ = nullptr;
    }
    if (ep_out_)
    {
      ep_out_->Close();
      endpoint_pool.Release(ep_out_);
      ep_out_ = nullptr;
    }
  }
 
  size_t GetInterfaceCount() override { return 1; }
 
  bool HasIAD() override { return false; }
 
  bool OwnsEndpoint(uint8_t ep_addr) const override
  {
    if (!inited_)
    {
      return false;
    }
 
    return ep_in_->GetAddress() == ep_addr ||
           (enable_out_endpoint_ && ep_out_->GetAddress() == ep_addr);
  }
 
  size_t GetMaxConfigSize() override
  {
    return enable_out_endpoint_ ? sizeof(HIDDescBlockINOUT) : sizeof(HIDDescBlockIN);
  }
 
  ErrorCode OnGetDescriptor(bool in_isr, uint8_t bRequest, uint16_t wValue,
                            uint16_t wLength, ConstRawData& need_write) override
  {
    UNUSED(in_isr);
    UNUSED(bRequest);
 
    uint8_t desc_type = (wValue >> 8) & 0xFF;
    // uint8_t desc_index = wValue & 0xFF; // 一般为0，暂不需要
 
    switch (desc_type)
    {
      case static_cast<uint8_t>(HIDDescriptorType::HID):  // 0x21
      {
        // 返回 HID 描述符
        ConstRawData desc = GetHIDDesc();
        need_write.addr_ = desc.addr_;
        need_write.size_ = (wLength < desc.size_) ? wLength : desc.size_;
        return ErrorCode::OK;
      }
      case static_cast<uint8_t>(HIDDescriptorType::REPORT):  // 0x22
      {
        // 返回 Report Descriptor
        ConstRawData desc = GetReportDesc();
        need_write.addr_ = desc.addr_;
        need_write.size_ = (wLength < desc.size_) ? wLength : desc.size_;
        return ErrorCode::OK;
      }
      case static_cast<uint8_t>(HIDDescriptorType::PHYSICAL):
        // 物理描述符（很少用，未实现）
      default:
        return ErrorCode::NOT_SUPPORT;
    }
  }
 
  ErrorCode OnClassRequest(bool in_isr, uint8_t bRequest, uint16_t wValue,
                           uint16_t wLength, uint16_t wIndex,
                           DeviceClass::ControlTransferResult& result) override
  {
    UNUSED(in_isr);
    UNUSED(wIndex);
 
    uint8_t report_id = wValue & 0xFF;
 
    switch (static_cast<ClassRequest>(bRequest))
    {
      case ClassRequest::GET_REPORT:
      {
        ReportType report_type = static_cast<ReportType>((wValue >> 8) & 0xFF);
        switch (report_type)
        {
          case ReportType::INPUT:
            // 查找或生成 Input Report（按你的设备实际逻辑）
            return OnGetInputReport(report_id, result);
          case ReportType::OUTPUT:
            // 查找或返回最近收到的 Output Report（通常很少实现GET Output）
            return OnGetLastOutputReport(report_id, result);
          case ReportType::FEATURE:
            // 查找或生成 Feature Report
            return OnGetFeatureReport(report_id, result);
          default:
            return OnCustomClassRequest(in_isr, bRequest, wValue, wLength, result);
        }
      }
 
      case ClassRequest::SET_REPORT:
        if (wLength == 0)
        {
          return ErrorCode::ARG_ERR;
        }
        // 由OnClassData阶段接收
        return OnSetReport(report_id, result);
 
      case ClassRequest::GET_IDLE:
        // 仅支持一个Idle rate
        if (wLength != 1 || report_id != 0)
        {
          return ErrorCode::ARG_ERR;
        }
        result.write_data = ConstRawData{&idle_rate_, 1};
        return ErrorCode::OK;
 
      case ClassRequest::SET_IDLE:
        if (report_id != 0)
        {
          return ErrorCode::ARG_ERR;
        }
        idle_rate_ = wValue >> 8;
        result.write_zlp = true;
        return ErrorCode::OK;
 
      case ClassRequest::GET_PROTOCOL:
        result.write_data = ConstRawData{reinterpret_cast<uint8_t*>(&protocol_), 1};
        return ErrorCode::OK;
 
      case ClassRequest::SET_PROTOCOL:
        protocol_ = static_cast<Protocol>(wValue & 0xFF);
        result.write_zlp = true;
        return ErrorCode::OK;
 
      default:
        return ErrorCode::NOT_SUPPORT;
    }
  }
 
  ErrorCode OnClassData(bool in_isr, uint8_t bRequest, LibXR::ConstRawData& data) override
  {
    UNUSED(in_isr);
 
    switch (static_cast<ClassRequest>(bRequest))
    {
      case ClassRequest::SET_REPORT:
      {
        // 通常为 Output Report 或 Feature Report
        // 你可以区分是 Output 还是 Feature，也可以统一交给
        // OnSetReportData（推荐如下写法）
        auto ans = OnSetReportData(in_isr, data);
        if (ans == ErrorCode::OK)
        {
          // 可选：记录最近一次 report id（假定第一个字节是 report id，没有 report id
          // 就写0）
          last_output_report_id_ =
              (data.size_ > 0) ? reinterpret_cast<const uint8_t*>(data.addr_)[0] : 0;
        }
        return ans;
      }
      default:
        return OnCustomClassData(in_isr, bRequest, data);
    }
  }
 
  uint8_t GetLastOutputReportID() const { return last_output_report_id_; }
 
  virtual ConstRawData GetReportDesc() = 0;
 
  virtual ConstRawData GetHIDDesc()
  {
    return ConstRawData{&desc_.hid, sizeof(HIDDescriptor)};
  }
 
  virtual ErrorCode OnGetInputReport(uint8_t report_id,
                                     DeviceClass::ControlTransferResult& result)
  {
    UNUSED(report_id);
    result.write_data = ConstRawData{nullptr, 0};
    return ErrorCode::OK;
  }
 
  virtual ErrorCode OnGetLastOutputReport(uint8_t report_id,
                                          DeviceClass::ControlTransferResult& result)
  {
    UNUSED(report_id);
    result.write_data = ConstRawData{nullptr, 0};
    return ErrorCode::OK;
  }
 
  virtual ErrorCode OnGetFeatureReport(uint8_t report_id,
                                       DeviceClass::ControlTransferResult& result)
  {
    UNUSED(report_id);
    result.write_data = ConstRawData{nullptr, 0};
    return ErrorCode::OK;
  }
 
  virtual ErrorCode OnCustomClassRequest(bool in_isr, uint8_t bRequest, uint16_t wValue,
                                         uint16_t wLength,
                                         DeviceClass::ControlTransferResult& result)
  {
    UNUSED(in_isr);
    UNUSED(bRequest);
    UNUSED(wValue);
    UNUSED(wLength);
    UNUSED(result);
    return ErrorCode::NOT_SUPPORT;
  }
 
  virtual ErrorCode OnCustomClassData(bool in_isr, uint8_t bRequest, ConstRawData& data)
  {
    UNUSED(in_isr);
    UNUSED(bRequest);
    UNUSED(data);
    return ErrorCode::NOT_SUPPORT;
  }
 
  virtual ErrorCode OnSetReport(uint8_t report_id,
                                DeviceClass::ControlTransferResult& result)
  {
    UNUSED(report_id);
    UNUSED(result);
 
    return ErrorCode::NOT_SUPPORT;
  }
 
  virtual ErrorCode OnSetReportData(bool in_isr, ConstRawData& data)
  {
    UNUSED(in_isr);
    UNUSED(data);
 
    return ErrorCode::OK;
  }
 
  ErrorCode SendInputReport(ConstRawData report)
  {
    if (!inited_ || !ep_in_)
    {
      return ErrorCode::FAILED;
    }
    if (!report.addr_ || report.size_ == 0 || report.size_ > TX_REPORT_LEN)
    {
      return ErrorCode::ARG_ERR;
    }
 
    if (ep_in_->GetState() != Endpoint::State::IDLE)
    {
      return ErrorCode::BUSY;
    }
 
    // 数据拷贝到端点缓冲区
    auto buf = ep_in_->GetBuffer();
    if (report.size_ > buf.size_)
    {
      return ErrorCode::NO_BUFF;
    }
 
    LibXR::Memory::FastCopy(buf.addr_, report.addr_, report.size_);
 
    // 启动端点传输
    return ep_in_->Transfer(report.size_);
  }
 
  uint8_t GetIDLERate() const { return idle_rate_; }
 
  Endpoint* GetInEndpoint() { return ep_in_; }
 
  Endpoint* GetOutEndpoint() { return ep_out_; }
 
  bool HasOutEndpoint() const { return enable_out_endpoint_; }
 
 private:
  uint8_t in_ep_interval_;         
  uint8_t out_ep_interval_;        
  HIDDescBlockINOUT desc_;         
  Endpoint::EPNumber in_ep_num_;   
  Endpoint::EPNumber out_ep_num_;  
  Endpoint* ep_in_ = nullptr;      
  Endpoint* ep_out_ = nullptr;     
  bool enable_out_endpoint_;  
  bool inited_ = false;       
  size_t itf_num_;            
  const char* interface_string_ = nullptr;  
 
  Protocol protocol_ = Protocol::REPORT;  
  uint8_t idle_rate_ = 0;                 
  uint8_t last_output_report_id_ =
      0;  
 
  LibXR::Callback<LibXR::ConstRawData&> on_data_out_complete_cb_ =
      LibXR::Callback<LibXR::ConstRawData&>::Create(OnDataOutCompleteStatic, this);
 
  LibXR::Callback<LibXR::ConstRawData&> on_data_in_complete_cb_ =
      LibXR::Callback<LibXR::ConstRawData&>::Create(OnDataInCompleteStatic, this);
};
 
}  // namespace LibXR::USB