SG2002 TPU Device Driver

SG2002 TPU 设备的Rust驱动。

使用 Rust 最小化设备层实现，去除操作系统内核依赖，保留硬件操作逻辑，便于在裸机或自研RustOS上集成运行。

特性

• KernelFns 抽象层：隔离系统相关能力（日志、时间、时钟控制、缓存同步）
• 硬件操作：TDMA/TIU 寄存器访问与控制流程
• DMA 缓冲区执行：支持描述符模式和 PIO 模式
• 挂起/恢复：支持电源管理
• 结构对齐：IOCTL 结构体使用 #[repr(C)] 保证 ABI 兼容

代码结构

src/
├── lib.rs          # 库入口，类型导出，TpuError 定义
├── types.rs        # 数据类型 (DmaHeader, CpuSyncDesc, TpuConfig, TpuTdmaPioInfo)
├── device.rs       # TPU 设备核心实现 (TpuDevice)
├── kernel_fns.rs   # 内核函数抽象 trait (KernelFns)
├── platform.rs     # 平台相关结构 (TdmaReg, TpuRegBackup, 状态解析)
├── pmu.rs          # PMU 性能监控 (TpuPmu, PmuSummary)
├── registers.rs    # TDMA/TIU 硬件寄存器常量
└── ioctrl.rs       # IOCTL 参数结构定义

调用流程

本库的 API 设计参照 Linux 驱动模块的生命周期：

Linux 驱动 vs Rust 库对照

常用 ioctl 对照（用户态视角）：

在Rust OS中的调用序列

基于 YOLOv8 on StarryOS 实际运行于SG2002硬件平台的建议集成流程：

1. 系统初始化阶段

   • 创建 TpuDevice::new(...)
   • 调用 probe_setting()
   • 在设备初始化阶段调用一次 platform_init()

2. 用户态准备阶段（/dev/ion + /dev/cvi-tpu0）

   • ION_IOC_ALLOC 分配 dmabuf
   • mmap 映射 ion buffer 到用户态
   • CVITPU_DMABUF_INVLD / CVITPU_DMABUF_FLUSH 做缓存同步

3. 提交执行阶段（核心热路径）

   • CVITPU_SUBMIT_DMABUF
   • 驱动侧通过 parse_dmabuf_view() 解析 header/descs
   • 调用 run_dmabuf(paddr, header, descs)

4. 等待完成阶段

   • CVITPU_WAIT_DMABUF
   • 使用与 submit 一致的 seq_no 获取结果

5. 可选收尾

   • 继续下一帧提交（推荐）
   • 设备长时间空闲时再 platform_deinit()

适配的示例代码

// 1. 实现 KernelFns trait
struct MyKernelFns {
    // 可包含时钟控制器、复位控制器的引用
}

impl KernelFns for MyKernelFns {
    fn sleep_ms(&self, ms: u32) {
        // 实现毫秒级延时
    }
    
    fn now_us(&self) -> TimeStamp {
        // 返回微秒级单调时间戳
        0
    }
    
    fn log(&self, level: LogLevel, msg: &str) {
        // 日志输出
    }
    
    fn enable_clocks(&self) {
        // 使能 clk_tpu_axi, clk_tpu_fab
    }
    
    fn disable_clocks(&self) {
        // 关闭 TPU 时钟
    }
    
    fn reset(&self) {
        // 触发 res_tdma, res_tpu, res_tpusys 复位
    }
    
    fn dma_sync_for_device(&self, paddr: PhysAddr, size: usize) {
        // 刷新 CPU cache 到内存 (DMA_TO_DEVICE)
    }
    
    fn dma_sync_for_cpu(&self, paddr: PhysAddr, size: usize) {
        // 使 CPU cache 无效化 (DMA_FROM_DEVICE)
    }
}

// 2. 设备探测阶段 (probe)
fn tpu_probe() -> Result<TpuDevice<MyKernelFns>, TpuError> {
    // 从设备树获取寄存器地址
    let tdma_base = NonNull::new(0x0C00_0000 as *mut u8).unwrap();
    let tiu_base = NonNull::new(0x0C01_0000 as *mut u8).unwrap();
    
    let config = TpuConfig {
        pmu_buf_size: 0,      // PMU 缓冲区大小，0 表示禁用
        pmu_buf_paddr: 0,     // PMU 缓冲区物理地址
    };
    
    let kfns = MyKernelFns { /* ... */ };
    
    let mut tpu = TpuDevice::new(tdma_base, tiu_base, config, kfns);
    tpu.probe_setting();
    
    Ok(tpu)
}

// 3. 中断处理函数
fn tpu_irq_handler(tpu: &mut TpuDevice<MyKernelFns>) {
    let status = tpu.irq_handle();
    // 根据 status 处理中断
}

// 4. 执行一次 dmabuf 提交（StarryOS 驱动热路径）
fn submit_one_dmabuf(
    tpu: &mut TpuDevice<MyKernelFns>,
    dmabuf_vaddr: *const u8,
    dmabuf_len: usize,
    dmabuf_paddr: PhysAddr,
) -> Result<(), TpuError> {
    // dmabuf 结构解析已下沉到 tpu_sg2002
    let parsed = unsafe { parse_dmabuf_view(dmabuf_vaddr, dmabuf_len) }?;

    // 直接执行，header/descs 为零拷贝借用
    let result = tpu.run_dmabuf(dmabuf_paddr, parsed.header, parsed.descs);

    if let Err(TpuError::Timeout) = result {
        tpu.reset()?;
    }

    result
}

// 5. 电源管理（可选）
fn tpu_suspend(tpu: &mut TpuDevice<MyKernelFns>) -> Result<(), TpuError> {
    tpu.suspend()
}

fn tpu_resume(tpu: &mut TpuDevice<MyKernelFns>) -> Result<(), TpuError> {
    tpu.resume()
}

// 6. 用户态 ioctl 的典型顺序（伪代码）
fn user_ioctl_sequence_example() {
    // open("/dev/cvi-tpu0")
    // open("/dev/ion")
    // ION_IOC_ALLOC + mmap
    // ioctl(CVITPU_DMABUF_INVLD)
    // fill command buffer
    // ioctl(CVITPU_DMABUF_FLUSH)
    // ioctl(CVITPU_SUBMIT_DMABUF)
    // ioctl(CVITPU_WAIT_DMABUF)
}

KernelFns Trait

实现此 trait 以适配不同运行环境：

精简评估结论：

• now_us 是硬性必需（超时与轮询逻辑核心依赖）。
• enable_clocks/disable_clocks/reset 保留为可选钩子，符合不同 SoC 的电源域差异。
• dma_sync_for_device/dma_sync_for_cpu 保留为可选钩子，用于兼容有 cache 维护要求的平台。
• sleep_ms 在当前 SG2002 快路径不是必需；已调整为默认空实现，用于降低接入方实现负担。

pub trait KernelFns {
    /// 毫秒级睡眠
    fn sleep_ms(&self, _ms: u32) {}
    
    /// 获取微秒级单调时间戳
    fn now_us(&self) -> TimeStamp;
    
    /// 日志输出
    fn log(&self, level: LogLevel, msg: &str);
    
    /// 使能 TPU 时钟（可选）
    fn enable_clocks(&self) {}
    
    /// 关闭 TPU 时钟（可选）
    fn disable_clocks(&self) {}
    
    /// 复位 TPU 硬件（可选）
    fn reset(&self) {}

    // DMA 内存申请相关的函数

    /// DMA 缓存同步（可选）
    fn dma_sync_for_device(&self, _paddr: PhysAddr, _size: usize) {}
    fn dma_sync_for_cpu(&self, _paddr: PhysAddr, _size: usize) {}
}

编译

cargo build --target=riscv64gc-unknown-none-elf

参考

• 原始 C 驱动的Linux 内核版本：5.10.4
• HAL 实现：hal/mars（Mars 平台）
• 设备树兼容字符串：cvitek,tpu

SG2002 硬件信息

说明

• 需要实现 KernelFns trait 以提供平台相关功能
• run_dmabuf 实现了 hal/mars 的核心提交流程
• 该库不包含 Linux 设备模型与中断注册逻辑，由 RustOS 操作系统驱动框架提供
• 不支持 TEE (安全执行环境)