Cypress CyAPI C++ 类库编程参考手册

Cypress（原 Cypress Semiconductor，2014 版）官方 CyAPI.lib 的 C++ 编程参考，221 页。CyAPI 是 CyUsb3.sys 驱动的托管式 C++ 封装，是本项目 FX2LP/FX3 数据采集卡上位机（Windows 侧）开发的核心 API。与 Cypress-CyUSB3驱动编程参考手册（内核驱动层）和 CyUSB-NET编程参考-Cypress-NET-USB类库-FX2-FX3（C# 版）互为不同语言层的姊妹文档：CyAPI 专讲 C++ 类库。

库定位与用法模型

• CyAPI.lib 提供对 CyUsb3.sys 驱动的高级 C++ 接口，只能与绑定到该驱动的 USB 设备通信；应用无需直接调 SetupDiXxx / DeviceIoControl 等 Windows API，改用 Open / Close / XferData 等简单方法。
• 使用方式：包含 CyAPI.h 头文件 + 链接静态库 CyAPI.lib（VS2008 版本）。
• Device + EndPoints 使用模型：new CCyUSBDevice 后，一个对象同一时间通过 Open() 抽象一个设备；设备级成员如 DeviceName、VendorID、ProductID、SetAltIntfc；端点级成员（MaxPktSize、TimeOut、bIn、Reset、XferData）只能经端点成员访问。
• 构造 CCyUSBDevice 时自动注册 Windows USB 即插即用事件通知，天然支持热插拔。

类层次

• CCyUSBEndPoint（抽象基类）→ 四个子类：CCyBulkEndPoint、CCyControlEndPoint、CCyInterruptEndPoint、CCyIsocEndPoint，各自实现传输类型特化的 BeginDataXfer()。
• 端点实例通常不需要手动构造——CCyUSBDevice 打开设备时自动为所有端点建好实例（BulkInEndPt、BulkOutEndPt 及 EndPoints[] 数组）。
• 辅助类 CCyIsoPktInfo（等时传输包信息）。

同步 vs 异步传输（关键取舍）

• 常规场景直接用同步 XferData(buf, len)。
• 高性能流式采集用异步三部曲 BeginDataXfer → WaitForXfer → FinishDataXfer，可在单个端点上排队多个传输请求，实现应用层高吞吐数据流。
• 铁律：每个 BeginDataXfer 必须恰好对应一个 FinishDataXfer（Begin 分配复杂结构、Finish 释放，漏调即泄漏）。

端点枚举惯用法（手册示例）

CCyUSBDevice *USBDevice = new CCyUSBDevice(NULL);
int eptCount = USBDevice->EndPointCount();
for (int i=1; i<eptCount; i++) {
  bool bIn   = ((USBDevice->EndPoints[i]->Address & 0x80) == 0x80); // bit7=IN
  bool bBulk = (USBDevice->EndPoints[i]->Attributes == 2);          // 2=BULK
  ...
}

USB 3.0 支持（FX3 相关）

• BOS（Binary Device Object Store）描述符全套 API 在 CCyUSBDevice：GetBosDescriptor / GetBosContainerIDDescriptor / GetBosSSCapabilityDescriptor / GetBosUSB20DeviceExtensionDesc；数据结构在 USB30_def.h，类在 CyAPI.h（CCyUSBBOS 等）。
• bSuperSpeed 判断速率；SuperSpeed 端点伴随描述符字段（ssmaxburst、ssbytesperinterval 等）在 USB2.0 设备上自动置 0。
• CCyFX3Device::DownloadFw() 支持把固件二进制下载到 FX3 片上 RAM 或其外接 EEPROM；IsBootLoaderRunning() 检测引导加载态。
• 明确限制：本库不支持 USB 3.0 bulk streams 和电源管理。

CCyControlEndPoint 要点（供应商控制传输）

• 可编程 ReqType / ReqCode / Index / Value / Direction 五要素后 Read()/Write()，即标准 SETUP 包的 C++ 映射——发 FX2LP 厂商命令（如 RAM 读写、固件重载）就走这条路。

对本项目的意义

• IFLabs FX2LP 采集卡（IFLabs-USB2.0全功能核心板原理图-CY7C68013A-SRAM-FPGA总线.md、CY7C68013A中文数据手册-EZ-USB-FX2LP.md）的上位机若走 C++/Windows，本手册即工作蓝本；驱动源文件目录 library/cpp/ 内附有 CyAPI 头文件与 lib。
• 异步多缓冲流采集正是数据流式上传（FIFO 96MB/s 场景）的必要模式，配合 FX2LP 端点四重缓冲。

可行动点

• 上位机原型：Open → 校验 VendorID → 取 BulkInEndPt → 设 TimeOut → 环形 BeginDataXfer ×4。
• 若需 USB3.0 bulk streams（FX3 满速），CyAPI 不行，需 CyU3P 固件侧 + WinUSB 原生方案。

待确认：文档 221 页但正文 Part 目录只列到 Part X（索引区后为 CCyUSBDevice 大章），后部页为逐成员条目，未逐页精读。