知识库

Cypress CyUSB3.sys 驱动编程参考手册

6分钟阅读

Cypress CyUSB3.sys 驱动编程参考手册

来源：Cypress Semiconductor 官方文档（2012），CyUSB3.sys Windows 通用 USB 驱动程序员参考，59 页。 背景：该文档属于液相芯片项目数据采集卡（Cypress CY7C6013A / FX2LP 系列）开发资料包，是 Windows 端上位机通过 USB 与采集卡通信的核心驱动接口文档。

一句话定位

CyUSB3.sys 是 Cypress 提供的 WDF 兼容通用 USB 驱动，应用层通过 DeviceIoControl() + 一组 IOCTL_ADAPT_* 控制码直接操作 USB 设备端点，实现 Bulk/Interrupt/Isochronous/Control 四类传输，无需自写内核驱动。

核心架构

  • 驱动模型：Windows Driver Foundation (WDF) 兼容，支持 USB 2.0 通用设备和 Cypress USB 3.0 设备。
  • 应用接口：用户态程序通过 DeviceIoControl(hDevice, IOCTL_xxx, ...) 与驱动通信；IOCTL 定义在 cyioctl.h。
  • 句柄获取两种方式：
    1. 简单方式：用 CyAPI 类库，new CCyUSBDevice() 自动建立句柄，DeviceHandle() 取出。
    2. 原生方式：SetupDiGetClassDevs() 按驱动 GUID（默认 {AE18AA60-7F6A-11d4-97DD-00010229B959}）枚举设备 → CreateFile(DevicePath) 打开句柄。

INF 配置要点（部署关键）

  • 把自有设备的 VID/PID 加进 CyUSB3.INF 的 [Device]/[Device.NT]/[Device.Ntx86]/[Device.Ntamd64] 各节，去掉注释分号，替换 VID_XXXX&PID_XXXX；同步改 [Strings] 节描述。
  • 修改 INF 后驱动签名失效：32/64 位 Windows 均允许带警告安装未签名驱动；产品化后可做 WHQL 认证。
  • 多厂商共存：不同厂商可用同一 CYUSB3.SYS 但各自定义 GUID（GUIDGEN 生成），互不冲突。
  • CyScript 特性：INF 可配置枚举时自动播放 .SPT 脚本（典型用途：设备上电自动下载固件）。注意固件下载后若以相同 VID/PID 重新枚举会死循环——第二人格必须用不同 VID/PID。禁用方法：注册表删除 DriverEXECSCRIPT 键。
  • 重装同 VID/PID 驱动前，删掉 C:\WINDOWS\inf\ 下旧的 oemXX.inf/pnf 备份，避免 Windows 误用旧 INF。

IOCTL 接口清单（核心 API 面）

设备信息类

IOCTL功能
GET_ADDRESS取设备 USB 地址（1字节）
GET_DEVICE_NAME取 Product 字符串描述符
GET_FRIENDLY_NAME取 INF [Strings] 中的友好名
GET_DEVICE_SPEED取速度：UNKNOWN/LOW_FULL/HIGH(0x02)/SUPER(0x04)
GET_DRIVER_VERSION / GET_USBDI_VERSION驱动/主控制器驱动版本
GET_NUMBER_ENDPOINTS当前接口设置的端点数
GET_ALT_INTERFACE_SETTING取备用接口设置
GET_CURRENT_FRAME取主控制器当前帧号

传输类（最重要）

IOCTL功能
SEND_EP0_CONTROL_TRANSFER向默认控制端点0发控制请求（含厂商请求），传入 SINGLE_TRANSFER + 数据缓冲两段式结构
SEND_NON_EP0_TRANSFERBulk/Interrupt/ISOC 传输，SINGLE_TRANSFER 结构后紧跟数据缓冲
SEND_NON_EP0_DIRECT同上，但 BufferOffset/BufferLength 置 0，数据放第二个独立缓冲（零拷贝风格）

控制/恢复类

IOCTL功能
ABORT_PIPE取消指定端点挂起的 IO
RESET_PIPE复位端点，清除 stall/错误（不取消挂起传输）
RESET_PARENT_PORT复位上游端口，配置和句柄保持有效
CYCLE_PORT端口断电重连（设备意外移除再枚举）
SELECT_INTERFACE切换备用接口设置

已废弃（仅为兼容保留）

GET/SET_DEVICE_POWER_STATE、GET/SET_TRANSFER_SIZE——WDF 内部管理电源与传输尺寸。驱动固化的传输上限：Bulk/Interrupt 4MB；全速 ISOC 256 帧；高速/超高速 ISOC 1024 帧。

关键数据结构（cyioctl.h）

typedef struct _SINGLE_TRANSFER {
    union { SETUP_PACKET SetupPacket; ISO_ADV_PARAMS IsoParams; };
    UCHAR  Reserved;
    UCHAR  ucEndpointAddress;   // 目标端点地址
    ULONG  NtStatus;            // 驱动返回
    ULONG  UsbdStatus;          // 主控制器返回
    ULONG  IsoPacketOffset;     // ISOC 包列表偏移
    ULONG  IsoPacketLength;
    ULONG  BufferOffset;        // 数据缓冲偏移
    ULONG  BufferLength;
} SINGLE_TRANSFER, *PSINGLE_TRANSFER;
  • SETUP_PACKET：标准 8 字节 USB 请求（bmRequest/bRequest/wValue/wIndex/wLength）+ ulTimeOut。
  • ISO_ADV_PARAMS：ISOC 调度控制——USB_ISO_CMD_ASAP（排队即发）、USB_ISO_CMD_CURRENT_FRAME（当前帧+偏移）、USB_ISO_CMD_SET_FRAME（指定帧）。
  • ISOC 约束：缓冲长度必须是 MaxPacketSize 的整数倍；高速/超高速还须是 MaxPacketSize×8 的倍数；超高速需按 MaxBurst 计算单微帧包长。

已知限制（Part 7）

  • 不支持 SET ADDRESS、SYNC FRAME（无法经控制端点实现）。
  • 不支持 USB 3.0 Bulk streaming。
  • USB3.0 复合设备下 EP0 取配置描述符会返回两个接口的合集（USBDI 总线接口限制）。

ezusb.sys → CyUSB3.sys 迁移映射（对 FX2 项目直接有用）

旧 EZ-USB 驱动的每个操作一个 IOCTL，新驱动收敛为三类：

  • IOCTL_Ezusb_RESETPIPE/ABORTPIPE/RESET → IOCTL_ADAPT_RESET_PIPE/ABORT_PIPE/RESET_PARENT_PORT（一一对应）
  • 所有 BULK_READ/WRITE、ISO_READ/WRITE → 统一映射到 SEND_NON_EP0_TRANSFER 或 SEND_NON_EP0_DIRECT（方向由端点地址决定）
  • 所有控制类（GET_DEVICE_DESCRIPTOR、VENDOR_REQUEST、GET_STRING 等）→ 统一 SEND_EP0_CONTROL_TRANSFER 自己填 SETUP_PACKET
  • GET_LAST_ERROR → 直接用 Win32 GetLastError()
  • START/STOP_ISO_STREAM 无等价物：CYUSB3 不在驱动层做 ISOC 流式缓冲，靠应用自己连续提交

可行动点

  • 若为 FX2LP/CY7C6013A 采集卡写 Windows 上位机：优先用 CyAPI（CCyUSBDevice/CCyBulkEndPoint）省掉 SetupDi 样板代码；追求极致吞吐用 SEND_NON_EP0_DIRECT + OVERLAPPED 异步。
  • 数据采集卡的 Bulk IN 高吞吐场景注意 4MB 单次传输上限，超过需分片。
  • 端点错误恢复标准流程：ABORT_PIPE（取消挂起）→ RESET_PIPE（清 stall）→ 重传。

关联

  • 同目录资源：CY7C6013A 实例源代码（FX2SlaveFIFOASYNC 等从属端固件示例）
  • 流式细胞仪概要设计 —— 同一液相芯片项目体系的软件设计文档
  • FX2 固件侧的 FIFO 模式配置见 Cypress FX2 TRM（不在本盘该文档内，待确认）

关系图谱

反向链接